DigitalOcean integration: operations for AI agents
DigitalOcean connects to Type.com as an integration. This page lists the 858 operations documented for Claude and Codex in Type.com: 453 read, 257 write, 148 destructive.
About DigitalOcean
Official DigitalOcean API references with actual operation descriptions, vendor scopes and distinct control-plane, agent and inference hosts. Configure the connection for the required host and grant the scopes required by each operation.
Categories: Developer Tools & IT
How to connect DigitalOcean to Type.com
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
858 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
858 operations listed.
Action Gateway
- Read
Get an Actor's Limits
Returns the per-minute limits set for the actor and the limits in effect, each the lower of your team's limit and the actor's override. Returns 404 when the actor has no sessions, connections, or limit overrides.
GET /v2/action-gateway/actors/{actor_id}/limits - Read
List Connections
Returns the connections you can see, excluding revoked ones. Offset-paged with page and `per_page`; filter by provider, `user_id`, and status.
GET /v2/action-gateway/connections - Read
Get a Connection
Returns the connection and, while it is pending, the authorization the user still has to complete. Reading a pending connection picks up a completed authorization, and marks the connection expired once its link has lapsed. Returns 404 for an unknown connection or one you cannot see.
GET /v2/action-gateway/connections/{id} - Read
List MCP Servers
Returns every MCP server your team has registered, sorted by `serverRef`.
GET /v2/action-gateway/mcp-servers - Read
Get an MCP Server
Returns one of your team's MCP servers, or 404 when your team has none with this `serverRef`.
GET /v2/action-gateway/mcp-servers/{server_ref} - Read
List an MCP Server's Tools
Returns every tool discovered on the server, sorted by name, with whether each is enabled. Tools that have since disappeared from the server stay listed.
GET /v2/action-gateway/mcp-servers/{server_ref}/tools - Read
List Output Views
Returns the output views your team can use: views DigitalOcean publishes to every team, plus your team's own. Cursor-paged with `page_size` and `page_token`; no total is reported.
GET /v2/action-gateway/output-views - Read
Preview an Output View
Validates a projection exactly as create does and returns the view it would produce, including `output_schema`, without storing anything. name and description are optional here; name uniqueness and the per-tool-version limit are not checked.
POST /v2/action-gateway/output-views/preview - Read
Get an Output View
Returns one of your team's views, or a published view on a tool version your catalog exposes. Returns 404 when the view does not exist, was deleted, or belongs to another team.
GET /v2/action-gateway/output-views/{view_id} - Read
List Sessions
Returns the sessions you can see, newest first. Offset-paged with page and `per_page`; `end_user_id` filters to one actor.
GET /v2/action-gateway/sessions - Read
Search Sessions
Returns the sessions you can see whose name, `actor_id`, `session_urn`, or `agentName` contains query, case-insensitively, ranked across the whole result set. Cursor-paged with `page_size` and `page_token`; no total is reported.
GET /v2/action-gateway/sessions/search - Read
List Toolbelts
Returns your team's toolbelts, one entry per name describing its latest version, sorted by name. Offset-paged with page and `per_page`; pagination reports the total.
GET /v2/action-gateway/toolbelts - Read
Search Toolbelts
Returns your team's toolbelts whose name, display name, or description contains query, case-insensitively, sorted by name. Cursor-paged with `page_size` and `page_token`; no total is reported.
GET /v2/action-gateway/toolbelts/search - Read
Get a Toolbelt
Returns the latest version of the named toolbelt, or the version requested, with catalog metadata for one page of its members in `tool_details`. A deleted toolbelt returns 404 unless a version is requested.
GET /v2/action-gateway/toolbelts/{name} - Read
List the Providers in a Toolbelt
Returns the distinct providers of the toolbelt's members, each with its member count, sorted by provider ID. List one provider's members with `GET .../toolbelts/{name}/providers/{provider}/tools`.
GET /v2/action-gateway/toolbelts/{name}/providers - Read
List a Toolbelt's Tools from One Provider
Returns a page of catalog metadata for the toolbelt's members from the named provider, sorted by tool slug. An unknown provider returns an empty page.
GET /v2/action-gateway/toolbelts/{name}/providers/{provider}/tools - Read
List Tools
Returns one page of the tools your team can use: released catalog tools plus the enabled tools of your team's MCP servers. definitions[i] describes tools[i]. Offset-paged with page and `per_page`; an unknown `toolkitId` returns an empty page.
GET /v2/action-gateway/tools - Read
List Tool Health
Returns availability and latency for each catalog tool over the requested window, sorted by provider and then tool slug. A tool with no calls in the window is listed with `data_status` `HEALTH_DATA_STATUS_NO_DATA`. Metrics are aggregated across all customers; request volumes are not reported. Tools of your team's MCP servers are not included. Offset-paged with page and `per_page`.
GET /v2/action-gateway/tools/health - Read
List Provider Health
Returns availability and latency for each catalog provider over the requested window, sorted by provider ID. Metrics are aggregated across all customers; request volumes are not reported. Tools of your team's MCP servers are not included. Offset-paged with page and `per_page`.
GET /v2/action-gateway/tools/health/providers - Read
Get Tool Health
Returns availability and latency for one catalog tool over the requested window, optionally with a history series. Metrics are aggregated across all customers; request volumes are not reported. Returns 404 when `tool_slug` is not a catalog tool.
GET /v2/action-gateway/tools/health/tools/{tool_slug} - Read
List Providers
Returns the active catalog providers with at least one released tool, sorted by display name, with the credential kinds each accepts and the parameters a connection or team credential needs. Your team's MCP servers are listed separately under `/v2/action-gateway/mcp-servers`.
GET /v2/action-gateway/tools/providers - Read
Search Providers
Returns the providers of `GET /v2/action-gateway/tools/providers` whose name, display name, or description contains query, case-insensitively, sorted by name. Cursor-paged with `page_size` and `page_token`; no total is reported.
GET /v2/action-gateway/tools/providers/search - Read
Search Tools
Returns the tools your team can use that match query, optionally restricted to some providers or to the members of one of your toolbelts. Results are ranked across the whole result set: exact tool name matches first, then name or title prefixes, then name or title substrings, then other matches. Cursor-paged with `page_size` and `page_token`; no total is reported.
GET /v2/action-gateway/tools/search - Read
List Toolkits
Returns the providers (toolkits) whose tools your team can use: catalog providers with at least one released tool, plus your team's registered MCP servers.
GET /v2/action-gateway/tools/toolkits - Read
List Users
Returns the user IDs known for your team: session `actor_id` values, the `user_id` of connections that are not revoked, and actors with limit overrides. Only sessions and connections you can see count. Offset-paged with page and `per_page`.
GET /v2/action-gateway/users - Read
Get a User
Returns the sessions and non-revoked connections of one user ID. Returns 404 when the user has none you can see and no limit overrides.
GET /v2/action-gateway/users/{user_id} - Write
Set an Actor's Limits
Sets per-minute limits for the listed categories and leaves the others unchanged. A limit may not exceed your team's current limit for the category (400 otherwise), and 0 blocks every call in the category. The actor does not need to exist yet.
POST /v2/action-gateway/actors/{actor_id}/limits:set - Write
Create a Connection
Connects one of your users, identified by `user_id`, to a provider so tools can act on their account. An OAuth connection starts pending, and authorization carries the URL to send the user to; read the connection until it is active or expired. A connection through a team API-key credential is active immediately. There is one connection per provider and `user_id` for each DigitalOcean user who creates connections. Repeating the request returns the existing connection when its scopes cover the request, reusing a pending connection's link, and restarts an expired or revoked connection under the same ID. Requesting scopes beyond an existing connection's, or a different credential, returns 400 until that connection is deleted.
POST /v2/action-gateway/connections - Write
Register an MCP Server
Registers a remote MCP server for your team, using the streamable HTTP transport. The server starts with `syncStatus` pending and no tools: discover its tools with `POST .../mcp-servers/{server_ref}/resync`, then choose which to enable with `PUT .../mcp-servers/{server_ref}/tools`. The endpoint must be HTTPS and resolve only to public IP addresses. The number of servers per team is limited (10 by default); registering beyond it returns 429. Returns 409 when `serverRef` is already in use.
POST /v2/action-gateway/mcp-servers - Write
Update an MCP Server
Changes the server's description, which is shown on its catalog card immediately. The endpoint and credentials cannot be changed; to change them, delete the server and register it again.
PATCH /v2/action-gateway/mcp-servers/{server_ref} - Write
Discover an MCP Server's Tools
Connects to the server, lists its tools, and records them. Discovered tools are not callable until you enable them. When discovery finishes in time, returns 200 with the server and its tools; a discovery failure is reported in `syncStatus` and `syncError` rather than as an error. Otherwise returns 202 with pending set while discovery continues: poll `GET .../mcp-servers/{server_ref}` until `lastSyncedAt` or `syncError` changes (`syncStatus` is not reset while discovery runs). For a server registered with `credentialRefSource` connection, `user_id` is required; if that user has not authorized the server yet, the response carries authorization with the URL to send them to. Resyncs are rate limited per team, and a team can run only a few discoveries at once; either limit returns 429.
POST /v2/action-gateway/mcp-servers/{server_ref}/resync - Write
Create an Output View
An output view is a named projection of one tool version's output: tool calls that use it return only the listed fields, and its `output_schema` describes the result. The view is bound to the tool version your catalog currently releases. Returns 409 when your team already has a view with this name on the tool version, and 429 when your team already has the maximum of 20 views on it.
POST /v2/action-gateway/output-views - Write
Create a Session
Creates a session owned by your team, with a new session URN, and returns the MCP URL an agent connects to. tools selects the tools and toolbelts the session exposes, and policy decides which calls run, need approval, or are refused.
POST /v2/action-gateway/sessions - Write
Create a Toolbelt
A toolbelt is a named set of tools, each pinned to a version, that your team can attach to sessions as `toolbelt:<name>@<version>`. The first version is 1 unless version is set. Returns 409 if an active toolbelt with the same name exists. The name of a deleted toolbelt can be reused; its versions start again from the initial version.
POST /v2/action-gateway/toolbelts - Write
Add Tools to a Toolbelt
Adds the listed tools and returns the toolbelt. When membership changes, this creates a new version that keeps the display name and description. Tools already in the toolbelt are left as they are, so a request that adds nothing new returns the current version unchanged. Returns 400 when a tool is not an active catalog tool, when a pin differs from the tool's current released version or from the version the toolbelt already holds, or when the toolbelt would exceed 500 tools. Returns 404 for an unknown or deleted toolbelt.
POST /v2/action-gateway/toolbelts/{name}/tools/add - Destructive
Clear an Actor's Limits
Removes the actor's overrides for the listed categories, which then follow your team's limits again. Clearing a category without an override succeeds.
POST /v2/action-gateway/actors/{actor_id}/limits:clear - Destructive
Delete a Connection
Marks the connection revoked and returns it; for an OAuth connection, its stored tokens are deleted first. Creating a connection for the same provider and `user_id` later reuses the same ID. Only the user who created the connection can delete it; for anyone else it is 404.
DELETE /v2/action-gateway/connections/{id} - Destructive
Delete an MCP Server
Disables all of the server's tools, removes them from your team's catalog, and deletes the server. An `api_key` supplied at registration is deleted; a `credentialRef` you supplied is left untouched. For a server registered with `credentialRefSource` connection, every user connection made through its OAuth client is revoked. Returns the deleted server, or 404 when it does not exist.
DELETE /v2/action-gateway/mcp-servers/{server_ref} - Destructive
Set Which of an MCP Server's Tools Are Enabled
`enabledToolSlugs` is the complete set to enable; every other tool of the server is disabled. An enabled tool is added to your team's catalog at its latest discovered version, and a disabled one is removed from it. Repeating the same set changes nothing. Before changing anything, each tool being enabled, re-enabled, or moved to a newer discovered version is verified against the live server: it must still be listed there, with the same input schema as when it was discovered. If any check fails or the server cannot be reached, the request fails with 400 and nothing changes; resync and try again. An unknown tool slug is also rejected with 400. A request that needs verification counts against the resync rate limit (429). Returns the server's full tool list.
PUT /v2/action-gateway/mcp-servers/{server_ref}/tools - Destructive
Delete an Output View
Deletes one of your team's views and returns it with audit.deleted_at set; it can no longer be used. Published views cannot be deleted. Returns 404 when the view does not exist, is already deleted, or is not your team's.
DELETE /v2/action-gateway/output-views/{view_id} - Destructive
Delete a Session
Deletes the session and its policy. Succeeds without deleting anything when the session does not exist or you cannot delete it, so repeating a delete also succeeds. A malformed `session_urn` is rejected with 400.
DELETE /v2/action-gateway/sessions/{session_urn} - Destructive
Delete a Toolbelt
Marks the toolbelt deleted and returns its latest version with status deprecated. Its versions stay readable by explicit version until the name is reused. The name is free to reuse immediately; a new toolbelt with it starts a fresh version history. Returns 404 when the toolbelt does not exist or is already deleted.
DELETE /v2/action-gateway/toolbelts/{name} - Destructive
Remove Tools from a Toolbelt
Removes the listed tools and returns the toolbelt. When membership changes, this creates a new version that keeps the display name and description. Tools that are not members are ignored, and removing every tool is allowed; deleting the toolbelt itself is a separate DELETE. Returns 400 when a pin differs from the version the toolbelt holds, and 404 for an unknown or deleted toolbelt.
POST /v2/action-gateway/toolbelts/{name}/tools/remove
Action Gateway Data Plane
- Read
List Session Tools
Lists the catalog tools that a session can call, ordered by name. The list applies the session's `tools` selection and omits tools that its policy always denies. Each page includes an `ETag` header. Send it in `If-None-Match` to receive `304 Not Modified` while the page is unchanged.
GET /tools - Read
Search Session Tools
Finds the catalog tools that fit one or more use cases. This is the REST form of the `action_search` MCP tool. Each query is searched independently and returns its own result group, so you can see which tools serve which goal. Results include each tool's `inputSchema`, so you can call a tool with `POST /tools/invoke` without another lookup. Results include only tools that the session can call. If the session policy requires approval for `action_search`, the response is a failed result with `_meta.status` set to `requires_approval`.
POST /tools/search - Write
Decide a Pending Approval
Approves or denies a tool call that is waiting for approval. A tool result returns `_meta.status` set to `requires_approval` when the session policy sets `ask` for the call, and its `_meta.decide` gives this request's path. Send the decision with the session owner's token. Approval is a separate control request, not a tool, so an agent cannot approve its own calls. After approving, repeat the original call with the same arguments before `expires_at`. An approval applies only to that session, tool version, and set of arguments, and is used once. To ask again after a denial or expiry, repeat the tool call.
POST /approvals/session/{session_id}/{approval_id} - Write
Decide a Pending Approval by Session Header
Approves or denies a tool call that is waiting for approval, identifying the session with the `X-Session-Id` header. It behaves the same as `POST /approvals/session/{session_id}/{approval_id}`, which is the path returned in a result's `_meta.decide`.
POST /approvals/{approval_id} - Destructive
Invoke Session Tools
Runs 1 to 10 tool calls in parallel and returns one result per call, in request order. This is the REST form of the `action_invoke` MCP tool. Each call is checked against the session's tool selection and policy, uses the session actor's connections, and applies any output view bound to the tool in the session. A well-formed request returns `200` even when some calls fail. Check each item's `result.status`, and use `success_count` and `error_count` to branch without scanning every item. A call whose policy requires approval fails with `_meta.status` set to `requires_approval`. Have the session's owner approve it, then repeat the call with the same arguments. A call that needs the end user to connect a provider fails with `_meta.status` set to `requires_authorization` or `requires_connection_configuration`.
POST /tools/invoke - Destructive
Execute Code
Runs Python code in an ephemeral sandbox and returns its `stdout`, `stderr`, and `exit_code`. This is the REST form of the `action_code` MCP tool. Use it for computation, parsing, and data processing, or to chain several catalog tools in one request. The sandbox provides `invoke_digitalocean_tool(name, arguments)`, which calls a catalog tool and returns a tool result. Those calls follow the session's tool selection and policy. Each request runs in a fresh sandbox, so state is not kept between requests. Execution, including tool calls, is time limited. Code that runs too long fails with a `timeout` error. A nonzero exit code is still a `succeeded` result; check `output.exit_code`. If the session policy requires approval for `action_code`, the response is a failed result with `_meta.status` set to `requires_approval`.
POST /code/execute
1-Click Applications
- Read
List 1-Click Applications
To list all available 1-Click applications, send a GET request to `/v2/1-clicks`. The `type` may be provided as query paramater in order to restrict results to a certain type of 1-Click, for example: `/v2/1-clicks?type=droplet`. Current supported types are `kubernetes` and `droplet`. The response will be a JSON object with a key called `1_clicks`. This will be set to an array of 1-Click application data, each of which will contain the the slug and type for the 1-Click.
GET /v2/1-clicks - Write
Install Kubernetes 1-Click Applications
To install a Kubernetes 1-Click application on a cluster, send a POST request to `/v2/1-clicks/kubernetes`. The `addon_slugs` and `cluster_uuid` must be provided as body parameter in order to specify which 1-Click application(s) to install. To list all available 1-Click Kubernetes applications, send a request to `/v2/1-clicks?type=kubernetes`.
POST /v2/1-clicks/kubernetes
Account
- Read
Get User Information
To show information about the current user account, send a GET request to `/v2/account`.
GET /v2/account
SSH Keys
- Read
List All SSH Keys
To list all of the keys in your account, send a GET request to `/v2/account/keys`. The response will be a JSON object with a key set to `ssh_keys`. The value of this will be an array of ssh_key objects, each of which contains the standard ssh_key attributes.
GET /v2/account/keys - Read
Retrieve an Existing SSH Key
To get information about a key, send a GET request to `/v2/account/keys/$KEY_ID` or `/v2/account/keys/$KEY_FINGERPRINT`. The response will be a JSON object with the key `ssh_key` and value an ssh_key object which contains the standard ssh_key attributes.
GET /v2/account/keys/{ssh_key_identifier} - Write
Create a New SSH Key
To add a new SSH public key to your DigitalOcean account, send a POST request to `/v2/account/keys`. Set the `name` attribute to the name you wish to use and the `public_key` attribute to the full public key you are adding.
POST /v2/account/keys - Write
Update an SSH Key's Name
To update the name of an SSH key, send a PUT request to either `/v2/account/keys/$SSH_KEY_ID` or `/v2/account/keys/$SSH_KEY_FINGERPRINT`. Set the `name` attribute to the new name you want to use.
PUT /v2/account/keys/{ssh_key_identifier} - Destructive
Delete an SSH Key
To destroy a public SSH key that you have in your account, send a DELETE request to `/v2/account/keys/$KEY_ID` or `/v2/account/keys/$KEY_FINGERPRINT`. A 204 status will be returned, indicating that the action was successful and that the response body is empty.
DELETE /v2/account/keys/{ssh_key_identifier}
Actions
- Read
List All Actions
This will be the entire list of actions taken on your account, so it will be quite large. As with any large collection returned by the API, the results will be paginated with only 20 on each page by default.
GET /v2/actions - Read
Retrieve an Existing Action
To retrieve a specific action object, send a GET request to `/v2/actions/$ACTION_ID`.
GET /v2/actions/{action_id}
Add-Ons
- Read
List Available Add-On Applications
To fetch details of all available Add-On Applications, send a GET request to `/v2/add-ons/apps`.
GET /v2/add-ons/apps - Read
Get Metadata for an Add-On Application
To find out what metadata is required for a specific add-on, send a GET request to `/v2/add-ons/apps/{app_slug}/metadata`. Metadata varies by application.
GET /v2/add-ons/apps/{app_slug}/metadata - Read
List all Add-On Resources
To fetch all Add-On Resources under your team, send a GET request to `/v2/add-ons/saas`.
GET /v2/add-ons/saas - Read
Get details on an Add-On Resource
To fetch details of a specific Add-On Resource, send a GET request to `/v2/add-ons/saas/{resource_uuid}`. Replace `{resource_uuid}` with the UUID of the resource you want to retrieve.
GET /v2/add-ons/saas/{resource_uuid} - Write
Create/Provision a New Add-on Resource
To create an add-on resource, send a POST request to `/v2/add-ons/saas` with required parameters. Some add-ons require additional metadata to be provided in the request body. To find out what metadata is required for a specific add-on, send a GET request to `/v2/add-ons/apps/{app_slug}/metadata`.
POST /v2/add-ons/saas - Write
Update the name for an Add-On Resource
To change the name of an Add-On Resource, send a PATCH request to `/v2/add-ons/saas/{resource_uuid}`. Replace `{resource_uuid}` with the UUID of the resource for which you want to change the name.
PATCH /v2/add-ons/saas/{resource_uuid} - Write
Update the plan for an Add-On Resource
To change the plan associated with an Add-On Resource, send a PATCH request to `/v2/add-ons/saas/{resource_uuid}/plan`. Replace `{resource_uuid}` with the UUID of the resource for which you want to change the plan.
PATCH /v2/add-ons/saas/{resource_uuid}/plan - Destructive
Delete/Deprovision an Add-on Resource
To delete an add-on resource, send a DELETE request to `/v2/add-ons/saas/{resource_uuid}` with the UUID of the resource to delete. You cannot retrieve the resource after it has been deleted. The response indicates a request was sent to the 3rd party add-on provider to delete the resource. You will no longer be billed for this resource.
DELETE /v2/add-ons/saas/{resource_uuid}
Harness Runtime
- Read
List active Environment Configs for the caller's team.
Returns lightweight team-scoped config metadata without loading or returning environment-spec JSON. Soft-deleted configs are excluded.
GET /v2/agents/configs - Read
Get an active Environment Config and its environment spec.
Returns one team-scoped Environment Config including the sanitized environment spec and redacted credential slot metadata. Secret values are never returned.
GET /v2/agents/configs/{config_id} - Read
List the sessions created from one Environment Config.
Enumerates the caller's team sessions whose session was created from this durable Environment Config. Keyset-paginated on an opaque cursor, newest first, same shape and status semantics as GET /v2/agents/sessions.
GET /v2/agents/configs/{config_id}/sessions - Read
ListSessions enumerates sessions for the caller's tenant.
Keyset-paginated on an opaque cursor. Results are scoped to the authenticated team. Destroyed and failed sessions are omitted by default (matching the Cloud Console); pass `status=SESSION_STATUS_ALL` to list every session regardless of status, or an explicit status such as `status=SESSION_STATUS_FAILED` or `status=SESSION_STATUS_DESTROYED` to list only those.
GET /v2/agents/sessions - Read
ValidatePolicy checks a manifest's tool-permission policy against the agent's capabilities without creating a session.
Stateless preflight: parses the same environment spec as CreateSession and runs the identical resolve + validate pipeline against the capability descriptor stamped on the selected template's image (resolved per-request via the sandbox, not a separate registry). Returns per-rule verdicts. Nothing is provisioned or persisted. Each rule is validated against the descriptor for the (agent, version) the template resolves to and gets a verdict: `exact`, `degraded`, `unsupported`, or `unverified`. `ok` is false when any strict rule is unsupported or unverified — i.e. CreateSession would reject the policy for that agent. An empty `spec.permissions` returns `ok: true` with no verdicts. Because it shares the create path's descriptor lookup, the verdicts match what CreateSession would compute.
POST /v2/agents/sessions/policy/validate - Read
ListSandboxSizes returns the customer-selectable sandbox (microVM) size catalog.
Read-only catalog the UI (and other clients) render as the size picker, instead of hardcoding the list. The set is the single source of truth shared with create-time validation and the default-size fallback, so every `slug` returned here is accepted by CreateSession as spec.sandbox.sizeSlug. Sizes are returned smallest-to-largest. Static and safe to cache; independent of team/session; no pagination.
GET /v2/agents/sessions/sandbox/sizes - Read
GetSession returns the current snapshot of a session.
GetSession returns the current snapshot of a session.
GET /v2/agents/sessions/{session_id} - Read
ListCheckpoints enumerates a session's checkpoints, newest first.
Keyset-paginated on an opaque cursor, like ListSessions.
GET /v2/agents/sessions/{session_id}/checkpoints - Read
GetCheckpoint returns the current snapshot of a checkpoint.
GetCheckpoint returns the current snapshot of a checkpoint.
GET /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id} - Read
Download a file or tar archive from the session's sandbox workspace.
Streams the workspace payload back as `application/octet-stream` using chunked transfer encoding, followed by a fixed integrity footer. Response body layout: `<payload>` + `<footer>`, where the footer is exactly 73 bytes: `DOWSSHA1` (8 bytes) + 64-char lowercase SHA-256 hex + `\n`. The client MUST strip the trailing 73 bytes before saving, verify SHA-256(payload) equals the footer digest, and treat a tail that does not match this shape (magic + 64 hex + newline) as a failed (truncated/corrupt) transfer. Other metadata: - `X-Workspace-Is-Archive: true` when the payload is a tar archive. - `X-Workspace-Size-Bytes` is a progress hint (not Content-Length) and excludes the footer. - The `X-Content-Sha256` trailer also carries the digest but is best-effort: edge proxies may strip HTTP trailers, so the body footer is authoritative. Concurrent transfers (upload + download) are capped server-side; over the cap the request blocks and may return 503.
GET /v2/agents/sessions/{session_id}/workspace/download - Read
Get the status of a staged workspace transfer.
Returns the current transfer state. For a completed download the response also carries a freshly minted presigned GET `download_url` (its TTL starts at poll time) and the payload `sha256` for client-side verification.
GET /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id} - Read
StreamSessionEvents opens the session's Server-Sent Events feed.
Opens a `text/event-stream` of the session's canonical events, served by the MARS data plane (OHP). Each frame is `event: <type>` plus a `data:` line holding a JSON event envelope; comment lines (`: keepalive`) arrive about every 15s and must be ignored. Decode every `data:` with one envelope parser and dispatch on the envelope's `type`. Every stream opens with a `stream.state` control frame (its `data` is a `stream_state`). Delivery is at-least-once: clients MUST de-duplicate and order by `event_id` (a ULID), never by `seq`. The same path serves two modes: - live attach (default): recent context, then an open stream that stays live until the client disconnects. Pass `Last-Event-ID` (or `cursor`) to resume strictly after the last event the client already rendered, suppressing the last-N context floor. - finite replay (`replay_only=true`): writes a bounded slice of the stored transcript and closes. This is what `doctl agents logs` uses; paginate it with `replay_from`. OHP serves recent history only (bounded by Kafka retention and an event window); it is not an archive. OHP's own errors (404/429/500/503) use the DO-standard JSON `{id, message, request_id}` envelope (cthulhu#179797 / MARSOHS-2065); the 401 comes from the edge.
GET /v2/agents/sessions/{session_id}/events - Read
PortForwardSession opens a WebSocket tunnel to a guest TCP port.
Upgrades the request to a WebSocket and bridges it to one TCP connection on the session sandbox's guest `port`. Binary frames carry the opaque byte stream in both directions; the server closes with a descriptive WebSocket close code when the tunnel ends. This is the raw TCP tunnel; browser clients reaching the in-guest OpenHands Agent Server use the ingress URL (`GET /v2/agents/sessions/{session_id}/ingress`), which has replaced this bridge for them. WebSocket is not expressible in OpenAPI; this documents the GET that initiates the upgrade handshake (HTTP 101 Switching Protocols). The handler dials the guest before upgrading, so a PAUSED session is woken and served rather than rejected. `port` must be between 1024 and 65535. A request without the WebSocket upgrade headers is answered 400 by the handshake layer.
GET /v2/agents/sessions/{session_id}/port-forward/{port} - Read
GetIngressURL returns the public HTTPS URL of the session's OpenHands Agent Server.
Publishes the URL on first call and returns it. Idempotent while the session runs: the same URL is returned until the session is paused, locked or rolled back, after which the next call returns a new hostname (pause and lock revoke the URL; rollback moves the session to a new sandbox, so re-fetch after resume, unlock or rollback). The URL fronts guest port 8000 (the OpenHands Agent Server, HTTP + WebSocket) and replaces the port-forward bridge for browser clients. Requests to the URL carry the caller's DO token as a Bearer header. Poll until `state` is INGRESS_URL_STATE_READY; there is no failed state. Only OpenHands sessions support ingress, and it is gated per team.
GET /v2/agents/sessions/{session_id}/ingress - Read
ListTeamTemplates returns the caller's team custom templates.
team_id is stamped from the authenticated principal; never accepted from the client.
GET /v2/agents/templates - Read
GetTemplate returns a team custom template by public id.
GetTemplate returns a team custom template by public id.
GET /v2/agents/templates/{template_id} - Read
ListTemplateBuilds returns build history for a template.
ListTemplateBuilds returns build history for a template.
GET /v2/agents/templates/{template_id}/builds - Read
GetTemplateBuild returns a single template build.
GetTemplateBuild returns a single template build.
GET /v2/agents/templates/{template_id}/builds/{build_id} - Read
ListTriggers enumerates the calling team's triggers.
Keyset-paginated on an opaque cursor. Excludes soft-deleted triggers. Scoped to the authenticated team.
GET /v2/agents/triggers - Read
GetTriggerBySession reverse-looks-up the trigger that produced or binds a session.
Returns the trigger that produced (fresh) or binds (reuse) the given session. Resolves to the row even after the trigger is soft-deleted.
GET /v2/agents/triggers/by-session/{session_id} - Read
ListReusableSessions lists the team's PAUSED sessions for the reuse picker.
Returns the team's sessions in status PAUSED, for binding a session_mode=reuse trigger. The item shape is the hosted-agents Session, so `agent_kind` and `status` use the AGENT_KIND_* / SESSION_STATUS_* spelling; `status` is always SESSION_STATUS_PAUSED here.
GET /v2/agents/triggers/reusable-sessions - Read
GetTrigger returns a single trigger by id.
GetTrigger returns a single trigger by id. Write-only fields (webhook secret, output destination, session_template env values) are never included.
GET /v2/agents/triggers/{trigger_id} - Read
ListTriggerExecutions returns a trigger's execution history.
Keyset-paginated. The large `payload` field is omitted from list items; fetch a single execution to read it.
GET /v2/agents/triggers/{trigger_id}/executions - Read
GetTriggerExecution returns a single execution, including its payload.
Returns the full execution row, including the `payload`, `output_text`, and `output_truncated` fields omitted from list items.
GET /v2/agents/triggers/{trigger_id}/executions/{execution_id} - Read
ListWebhookProviders lists supported webhook providers for the create-trigger UI.
A static, code-defined registry (not a database table), webhook-only. Cron triggers have no provider and never call this. Used to populate the provider dropdown with display name, docs link, paste hint, and the signature scheme.
GET /v2/agents/webhook-providers - Write
Create an Environment Config (environment spec + optional Insights opt-in).
Accepts name, environment-spec YAML text, and optional Insights telemetry opt-in. Tenant secrets are declared inside the environment spec (write-only values), not as sibling request fields. Responses never echo secret values; GET/create may include credential slot metadata (name/source/provider only). Configs are immutable after create.
POST /v2/agents/configs - Write
Clone an Environment Config under a new name.
Copies the source config's sanitized manifest to a new UUID. Source and clone are independent (no lineage). Credential bindings are never copied: if the manifest declares secret slots, supply secrets/oauth_assignments again (write-only). content_hash matches the source when the manifest is unchanged.
POST /v2/agents/configs/{config_id}/clone - Write
CreateSession provisions a sandbox and starts a Harness Runtime session.
Returns once the session row is allocated. Sandbox boot completes asynchronously. Two mutually exclusive request forms are selected by Content-Type (same contract as harness-api `harness.swagger.json`): - YAML (`application/x-yaml`, `application/yaml`, `text/yaml`, `text/x-yaml`): the environment spec. Two environment-spec formats are accepted during the dual-format transition: the flat format (primary) and the legacy `agents.digitalocean.com/v1alpha1` envelope (deprecated). A top-level `apiVersion` key selects the legacy parser; its absence selects flat. Internally persists a durable Environment Config, then creates the session. - JSON (`application/json`): `{name, config_id}` loads the config, resolves its credentials from Secrets Manager at the version pinned when the config was created, and creates the session. The OpenAPI `requestBody` schemas the JSON form for client generation (Autorest cannot emit a multi–content-type body). The live API still accepts the YAML forms listed above. Successful responses may include `config_id` on the session. `X-Device-UUID` (if present) is persisted on the session row. Query parameters `openai_session_id` and `resume_on_topoff` apply to both forms; when both the JSON body field and `?resume_on_topoff=` are present, the query parameter wins.
POST /v2/agents/sessions - Write
PatchSession updates session-scoped settings on an existing session.
Partial update of session-scoped settings (not the agent manifest / config). The body must include at least one recognized patchable property; an empty object {} is 400. Only properties listed on PatchSessionRequest are accepted — any other top-level JSON key is rejected with 400. Omitted properties are left unchanged. Today the only patchable field is resume_on_topoff; more session settings may be added over time. Terminal sessions (DESTROYED, FAILED) cannot be patched.
PATCH /v2/agents/sessions/{session_id} - Write
CreateCheckpoint captures the session's live sandbox state as a durable checkpoint.
Synchronous: blocks until the capture reaches READY and returns the terminal Checkpoint — clients never see PENDING on this endpoint and need no poll loop. The checkpoint binds the machine-state capture to the event-log cursor at the cut, so it can later seed forks (POST .../fork) and rollback. Checkpoints are taken between turns; a session with an active turn in flight returns 409.
POST /v2/agents/sessions/{session_id}/checkpoints - Write
ForkSession creates child sessions from a checkpoint of this session.
Each child boots a fresh sandbox from the checkpoint's machine-state capture and is drivable exactly like any other session (input, HITL), with parent_session_id and fork_id set for lineage. When from_checkpoint_id is omitted, an implicit checkpoint of the session "now" is captured first and the children fork from that. All-or-nothing: on failure nothing is left running.
POST /v2/agents/sessions/{session_id}/fork - Write
ResolveHITL records the user's decision on a pending HITL request.
harness-api forwards the decision into the owning microVM via the inbound runtime.v1.OHR.ResolveHITL RPC (dialed through the guest-fronting proxy), which unblocks the gated agent action. The resolution is also echoed to all attached clients as a HITLResolved event on StreamSession. Returns 204 No Content on success.
POST /v2/agents/sessions/{session_id}/hitl/{request_id} - Write
SendInput delivers a user chat message into the session.
The agent observes it on its next turn and emits subsequent events via StreamSession. The input is forwarded to the owning microVM's OHR inbound surface, which attributes it to a run and returns the run id.
POST /v2/agents/sessions/{session_id}/input - Write
PauseSession freezes the session's microVM sandbox.
Supported on microvm-substrate sessions only; dewdrop/docker sessions return 501 Not Implemented. Paused sessions count against quota. Clients learn state via GetSession/ListSessions; no live session.updated event is emitted.
POST /v2/agents/sessions/{session_id}/pause - Write
ResumeSession explicitly thaws a PAUSED session's microVM sandbox.
Only valid for microvm-substrate sessions; dewdrop/docker sessions return 501 Not Implemented. Implicit resume also occurs when SendInput or ResolveHITL is called on a paused session. Returns synchronously once the sandbox is ready.
POST /v2/agents/sessions/{session_id}/resume - Write
Start a staged (large-file) workspace transfer.
Creates an asynchronous, object-storage-backed transfer for payloads larger than the streaming path supports (> ~50 MiB). Bulk bytes never traverse harness-api: the client PUTs/GETs presigned DO Spaces URLs directly. Set `direction` to `upload` or `download`. - `upload`: responds 201 with `transfer_id` + `part_size`; the client then requests per-part presigned PUT URLs, uploads them to Spaces, and calls `commit`. - `download`: responds 202 with `transfer_id`; the client polls GET until `completed` and then fetches `download_url` from Spaces. Upload and cancel currently return 501 until the sandbox backend RPCs ship; download is live.
POST /v2/agents/sessions/{session_id}/workspace/transfers - Write
Finalize a staged upload.
Upload only. Call once, after all parts have been uploaded. Completes the multipart upload and starts the asynchronous import into the workspace. Responds 202; poll the transfer until `completed` or `failed`.
POST /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/commit - Write
Mint presigned PUT URLs for one or more multipart upload parts.
Upload only. Pass one or more 1-based `part_numbers`; the response returns a presigned `upload_url` per part (all sharing one `expires_at`), so a client can drive parallel part uploads without a round trip per part. PUT each part's bytes directly to its URL (bypassing harness-api). If URLs expire before the PUT, request them again.
POST /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/part-upload-urls - Write
Upload a file or tar archive into the session's sandbox workspace.
Streams the raw request body to a path inside the sandbox workspace. Concurrent transfers (upload + download) are capped server-side; over the cap the request blocks and may return 503. The optional `X-Content-Sha256` request header carries a hex digest the guest verifies after the full payload is written.
POST /v2/agents/sessions/{session_id}/workspace/upload - Write
CreateTemplate creates a team custom template and kicks a build.
Creates a team-owned template from a customer OCI ref rebased onto a base template. team_id is stamped from the authenticated principal.
POST /v2/agents/templates - Write
UpdateTemplate updates a team template's source and kicks a new build.
UpdateTemplate updates a team template's source and kicks a new build.
PUT /v2/agents/templates/{template_id} - Write
CreateTrigger creates a webhook or cron trigger.
Validation is synchronous, so a mistake is a 400/409 at creation, not a silent miss at the first fire. Exactly one of `webhook` / `cron` must be present and match `kind`. kind=cron forbids a `webhook` block and requires a parseable `cron.cron_expr` and a valid IANA `cron.timezone`. session_mode=fresh requires `session_template` (a well-formed agents.yaml Agent manifest) and forbids `bound_session_id`; session_mode=reuse requires `bound_session_id` (an existing team-owned session) and forbids `session_template`. `output.mode` selects the destination block (email/slack), which is stored encrypted. `name` must be unique per team among non-deleted triggers. For webhook triggers the response includes `webhook_secret` exactly ONCE - it is never returned again. Cron triggers return no secret and carry a computed `trigger.cron.next_run_at`. The team and user identity are taken from the authenticated principal, never the body.
POST /v2/agents/triggers - Write
UpdateTrigger updates, pauses, or re-enables a trigger.
Partial update: only the supplied fields change. `kind` and `webhook.provider` are immutable (409 on change). Mutable: `name` (409 on duplicate), `status` (active<->paused), `prompt_template`, `output`, `session_template` (fresh), `bound_session_id` (reuse), `cron.cron_expr` / `cron.timezone` (recomputes next_run_at). Re-enabling never produces a catch-up run. PATCHing session_template is a full replacement, so every spec.secrets slot value the new manifest declares must be resupplied (secret values are never echoed back), or the request is a 400.
PATCH /v2/agents/triggers/{trigger_id} - Write
RotateTriggerSecret issues a new webhook secret.
Webhook triggers only (409 for cron). Issues a new secret (shown once) and moves the old value to the previous slot, where it keeps verifying deliveries until previous_secret_expires_at. Default grace is 5 minutes when grace_period_seconds is omitted, so deliveries already in flight (signed with the old value) still succeed while the customer updates their external system. After that instant the old value is refused with 401. Pass grace_period_seconds=0 to retire the old secret on this call (breach response), or a positive value (up to the server max, default 1 hour) for a custom window; above the max is 400.
POST /v2/agents/triggers/{trigger_id}/rotate-secret - Write
ReceiveTriggerWebhook accepts a signed delivery from an external system.
The one public, un-team-authenticated endpoint. There is NO DO bearer token: the caller is the customer's external system. Authentication is the per-trigger HMAC secret, verified on every delivery; edge rate-limiting is mandatory. The request body is the provider's RAW body, forwarded verbatim (the HMAC is computed over the exact bytes received); Content-Type is provider-defined and passed through. The signature header depends on the trigger's provider: - github: `X-Hub-Signature-256: sha256=<hex>` (HMAC-SHA256 of the raw body) - gitlab: `X-Gitlab-Token: <token>` (plaintext token equality; GitLab does not sign) - custom: `X-DigitalOcean-Signature: t=<unix>,v1=<hex>` (HMAC-SHA256 of `{unix}.{raw body}`; `do-signature` is also accepted as a transitional alias) On success (including a provider retry that dedupes to an existing firing) it returns 202 with the execution_id. A delivery to a paused trigger returns 202 with no body and queues nothing (deliberately not 409, so providers do not auto-disable the webhook after repeated non-2xx).
POST /v2/agents/triggers/{trigger_id}/webhook - Destructive
Soft-delete an Environment Config.
Releases the active team-scoped name; the config row is retained (soft delete), so sessions created from it keep a resolvable config_id.
DELETE /v2/agents/configs/{config_id} - Destructive
DestroySession tears down the sandbox and marks the session DESTROYED.
Persistent workspace contents are retained per tenant policy. Returns 204 No Content on success.
DELETE /v2/agents/sessions/{session_id} - Destructive
DeleteCheckpoint removes a checkpoint and its underlying machine-state capture.
Idempotent: deleting an already-gone checkpoint still returns 200. Removes the DB row and the substrate checkpoint.
DELETE /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id} - Destructive
RollbackToCheckpoint rewinds a session to a checkpoint.
In-place restore: boots a fresh sandbox from the checkpoint and atomically swaps the session's sandbox pointer to it, so the session keeps its same session_id; the old sandbox is then torn down.
POST /v2/agents/sessions/{session_id}/checkpoints/{checkpoint_id}/rollback - Destructive
ExecInSandbox runs a one-shot command inside the session's sandbox.
Runs `argv` directly in the guest (no shell). Stdout/stderr are buffered and capped at 1 MiB each; truncation is indicated via response headers when present. A non-zero exit code is still HTTP 200.
POST /v2/agents/sessions/{session_id}/sandbox/exec - Destructive
Cancel a staged workspace transfer.
Aborts an in-flight transfer. Idempotent: cancelling an already-terminal transfer returns `aborted: false` with the current status. The request body is optional.
POST /v2/agents/sessions/{session_id}/workspace/transfers/{transfer_id}/cancel - Destructive
DeleteTemplate deletes a team custom template.
Global templates cannot be deleted via this API.
DELETE /v2/agents/templates/{template_id} - Destructive
DeleteTrigger soft-deletes a trigger.
Marks the trigger deleted, fails any pending executions, and purges the webhook secret / cron schedule. A fresh trigger owns no session; a reuse trigger only UNBINDS - it never destroys the customer's session. Execution history and by-session lookups continue to resolve to the deleted row. Returns 204 No Content on success.
DELETE /v2/agents/triggers/{trigger_id} - Destructive
CancelExecution ends a running execution and frees the trigger's in-flight slot.
Fails the execution and frees the trigger's in-flight slot. A fresh-mode session is destroyed outright. A reuse-mode session is only paused, not stopped - harness has no run-interrupt call, so the agent's turn may still be in flight server-side; this frees the queue, not necessarily the agent's work. A non-running execution is a no-op that still returns 200.
POST /v2/agents/triggers/{trigger_id}/executions/{execution_id}/cancel
Apps
- Read
List All Apps
List all apps on your account. Information about the current active deployment as well as any in progress ones will also be included for each app.
GET /v2/apps - Read
Retrieve an Existing App
Retrieve details about an existing app by either its ID or name. To retrieve an app by its name, do not include an ID in the request path. Information about the current active deployment as well as any in progress ones will also be included in the response.
GET /v2/apps/{id} - Read
Retrieve Active Deployment Logs
Retrieve the logs of the active deployment if one exists. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment. Note log_type=BUILD logs will return logs associated with the current active deployment (being served). To view build logs associated with in-progress build, the query must explicitly reference the deployment id.
GET /v2/apps/{app_id}/components/{component_name}/logs - Read
Retrieve Exec URL
Returns a websocket URL that allows sending/receiving console input and output to a component of the active deployment if one exists.
GET /v2/apps/{app_id}/components/{component_name}/exec - Read
Retrieve App Instances
Retrieve the list of running instances for a given application, including instance names and component types. Please note that these instances are ephemeral and may change over time. It is recommended not to make persistent changes or develop scripts that rely on their persistence.
GET /v2/apps/{app_id}/instances - Read
List App Deployments
List all deployments of an app.
GET /v2/apps/{app_id}/deployments - Read
Retrieve an App Deployment
Retrieve information about an app deployment.
GET /v2/apps/{app_id}/deployments/{deployment_id} - Read
Retrieve Deployment Logs
Retrieve the logs of a past, in-progress, or active deployment. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.
GET /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs - Read
Retrieve Aggregate Deployment Logs
Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.
GET /v2/apps/{app_id}/deployments/{deployment_id}/logs - Read
Retrieve Exec URL for Deployment
Returns a websocket URL that allows sending/receiving console input and output to a component of the specified deployment if one exists. Optionally, the instance_name parameter can be provided to retrieve the exec URL for a specific instance. Note that instances are ephemeral; therefore, we recommended to avoid making persistent changes or such scripting around them.
GET /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec - Read
Retrieve Active Deployment Aggregate Logs
Retrieve the logs of the active deployment if one exists. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment. Note log_type=BUILD logs will return logs associated with the current active deployment (being served). To view build logs associated with in-progress build, the query must explicitly reference the deployment id.
GET /v2/apps/{app_id}/logs - Read
List Job Invocations
List all job invocations for an app.
GET /v2/apps/{app_id}/job-invocations - Read
Get Job Invocations
Get a specific job invocation for an app.
GET /v2/apps/{app_id}/job-invocations/{job_invocation_id} - Read
Retrieve Job Invocation Logs
Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. If deployment is omitted the active deployment will be selected (if available). The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.
GET /v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs - Read
List App Events
List all events for an app, including deployments and autoscaling events.
GET /v2/apps/{app_id}/events - Read
Get an Event
Get a single event for an app.
GET /v2/apps/{app_id}/events/{event_id} - Read
Retrieve Event Logs
Retrieve the logs of an autoscaling event for an app.
GET /v2/apps/{app_id}/events/{event_id}/logs - Read
List Instance Sizes
List all instance sizes for `service`, `worker`, and `job` components.
GET /v2/apps/tiers/instance_sizes - Read
Retrieve an Instance Size
Retrieve information about a specific instance size for `service`, `worker`, and `job` components.
GET /v2/apps/tiers/instance_sizes/{slug} - Read
List App Regions
List all regions supported by App Platform.
GET /v2/apps/regions - Read
Propose an App Spec
To propose and validate a spec for a new or existing app, send a POST request to the `/v2/apps/propose` endpoint. The request returns some information about the proposed app, including app cost and upgrade cost. If an existing app ID is specified, the app spec is treated as a proposed update to the existing app.
POST /v2/apps/propose - Read
List all app alerts
List alerts associated to the app and any components. This includes configuration information about the alerts including emails, slack webhooks, and triggering events or conditions.
GET /v2/apps/{app_id}/alerts - Read
Validate App Rollback
Check whether an app can be rolled back to a specific deployment. This endpoint can also be used to check if there are any warnings or validation conditions that will cause the rollback to proceed under unideal circumstances. For example, if a component must be rebuilt as part of the rollback causing it to take longer than usual.
POST /v2/apps/{app_id}/rollback/validate - Read
Retrieve App Daily Bandwidth Metrics
Retrieve daily bandwidth usage metrics for a single app.
GET /v2/apps/{app_id}/metrics/bandwidth_daily - Read
Retrieve Multiple Apps' Daily Bandwidth Metrics
Retrieve daily bandwidth usage metrics for multiple apps.
POST /v2/apps/metrics/bandwidth_daily - Read
Retrieve App Health
Retrieve information like health status, cpu and memory utilization of app components.
GET /v2/apps/{app_id}/health - Write
Create a New App
Create a new app by submitting an app specification. For documentation on app specifications (`AppSpec` objects), please refer to [the product documentation](https://docs.digitalocean.com/products/app-platform/reference/app-spec/).
POST /v2/apps - Write
Update an App
Update an existing app by submitting a new app specification. For documentation on app specifications (`AppSpec` objects), please refer to [the product documentation](https://docs.digitalocean.com/products/app-platform/reference/app-spec/).
PUT /v2/apps/{id} - Write
Restart an App
Perform a rolling restart of all or specific components in an app.
POST /v2/apps/{app_id}/restart - Write
Create an App Deployment
Creating an app deployment will pull the latest changes from your repository and schedule a new deployment for your app.
POST /v2/apps/{app_id}/deployments - Write
Update destinations for alerts
Updates the emails and slack webhook destinations for app alerts. Emails must be associated to a user with access to the app.
POST /v2/apps/{app_id}/alerts/{alert_id}/destinations - Destructive
Delete an App
Delete an existing app. Once deleted, all active deployments will be permanently shut down and the app deleted. If needed, be sure to back up your app specification so that you may re-create it at a later time.
DELETE /v2/apps/{id} - Destructive
Cancel a Deployment
Immediately cancel an in-progress deployment.
POST /v2/apps/{app_id}/deployments/{deployment_id}/cancel - Destructive
Cancel Job Invocation
Cancel a specific job invocation for an app.
POST /v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel - Destructive
Cancel an Event
Cancel an in-progress autoscaling event.
POST /v2/apps/{app_id}/events/{event_id}/cancel - Destructive
Rollback App
Rollback an app to a previous deployment. A new deployment will be created to perform the rollback. The app will be pinned to the rollback deployment preventing any new deployments from being created, either manually or through Auto Deploy on Push webhooks. To resume deployments, the rollback must be either committed or reverted. It is recommended to use the Validate App Rollback endpoint to double check if the rollback is valid and if there are any warnings.
POST /v2/apps/{app_id}/rollback - Destructive
Commit App Rollback
Commit an app rollback. This action permanently applies the rollback and unpins the app to resume new deployments.
POST /v2/apps/{app_id}/rollback/commit - Destructive
Revert App Rollback
Revert an app rollback. This action reverts the active rollback by creating a new deployment from the latest app spec prior to the rollback and unpins the app to resume new deployments.
POST /v2/apps/{app_id}/rollback/revert
CDN Endpoints
- Read
List All CDN Endpoints
To list all of the CDN endpoints available on your account, send a GET request to `/v2/cdn/endpoints`.
GET /v2/cdn/endpoints - Read
Retrieve an Existing CDN Endpoint
To show information about an existing CDN endpoint, send a GET request to `/v2/cdn/endpoints/$ENDPOINT_ID`.
GET /v2/cdn/endpoints/{cdn_id} - Write
Create a New CDN Endpoint
To create a new CDN endpoint, send a POST request to `/v2/cdn/endpoints`. The origin attribute must be set to the fully qualified domain name (FQDN) of a DigitalOcean Space. Optionally, the TTL may be configured by setting the `ttl` attribute. A custom subdomain may be configured by specifying the `custom_domain` and `certificate_id` attributes.
POST /v2/cdn/endpoints - Write
Update a CDN Endpoint
To update the TTL, certificate ID, or the FQDN of the custom subdomain for an existing CDN endpoint, send a PUT request to `/v2/cdn/endpoints/$ENDPOINT_ID`.
PUT /v2/cdn/endpoints/{cdn_id} - Destructive
Delete a CDN Endpoint
To delete a specific CDN endpoint, send a DELETE request to `/v2/cdn/endpoints/$ENDPOINT_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/cdn/endpoints/{cdn_id} - Destructive
Purge the Cache for an Existing CDN Endpoint
To purge cached content from a CDN endpoint, send a DELETE request to `/v2/cdn/endpoints/$ENDPOINT_ID/cache`. The body of the request should include a `files` attribute containing a list of cached file paths to be purged. A path may be for a single file or may contain a wildcard (`*`) to recursively purge all files under a directory. When only a wildcard is provided, all cached files will be purged. There is a rate limit of 50 files per 20 seconds that can be purged. CDN endpoints have a rate limit of 5 requests per 10 seconds. Purging files using a wildcard path counts as a single request against the API's rate limit. Two identical purge requests cannot be sent at the same time.
DELETE /v2/cdn/endpoints/{cdn_id}/cache
Certificates
- Read
List All Certificates
To list all of the certificates available on your account, send a GET request to `/v2/certificates`.
GET /v2/certificates - Read
Retrieve an Existing Certificate
To show information about an existing certificate, send a GET request to `/v2/certificates/$CERTIFICATE_ID`.
GET /v2/certificates/{certificate_id} - Write
Create a New Certificate
To upload new SSL certificate which you have previously generated, send a POST request to `/v2/certificates`. When uploading a user-generated certificate, the `private_key`, `leaf_certificate`, and optionally the `certificate_chain` attributes should be provided. The type must be set to `custom`. When using Let's Encrypt to create a certificate, the `dns_names` attribute must be provided, and the type must be set to `lets_encrypt`.
POST /v2/certificates - Destructive
Delete a Certificate
To delete a specific certificate, send a DELETE request to `/v2/certificates/$CERTIFICATE_ID`.
DELETE /v2/certificates/{certificate_id}
Billing
- Read
Get Customer Balance
To retrieve the balances on a customer's account, send a GET request to `/v2/customers/my/balance`.
GET /v2/customers/my/balance - Read
Get Customer Prepayment Configuration
To retrieve the prepayment configuration and current prepayment status for a customer's account, send a GET request to `/v2/customers/my/prepayment_config`.
GET /v2/customers/my/prepayment_config - Read
Get Customer Prepayment Status
To retrieve the prepayment gate status and balances for a customer's account, send a GET request to `/v2/customers/my/prepayment_status`.
GET /v2/customers/my/prepayment_status - Read
List Billing History
To retrieve a list of all billing history entries, send a GET request to `/v2/customers/my/billing_history`.
GET /v2/customers/my/billing_history - Read
List All Invoices
To retrieve a list of all invoices, send a GET request to `/v2/customers/my/invoices`.
GET /v2/customers/my/invoices - Read
Retrieve an Invoice by UUID
To retrieve the invoice items for an invoice, send a GET request to `/v2/customers/my/invoices/$INVOICE_UUID`.
GET /v2/customers/my/invoices/{invoice_uuid} - Read
Retrieve an Invoice CSV by UUID
To retrieve a CSV for an invoice, send a GET request to `/v2/customers/my/invoices/$INVOICE_UUID/csv`.
GET /v2/customers/my/invoices/{invoice_uuid}/csv - Read
Retrieve an Invoice PDF by UUID
To retrieve a PDF for an invoice, send a GET request to `/v2/customers/my/invoices/$INVOICE_UUID/pdf`.
GET /v2/customers/my/invoices/{invoice_uuid}/pdf - Read
Retrieve an Invoice Summary by UUID
To retrieve a summary for an invoice, send a GET request to `/v2/customers/my/invoices/$INVOICE_UUID/summary`.
GET /v2/customers/my/invoices/{invoice_uuid}/summary - Read
List Billing Insights
This endpoint returns day-over-day changes in billing resource usage based on nightly invoice items, including total amount, region, SKU, and description for a specified date range. It is important to note that the daily resource usage may not reflect month-end billing totals when totaled for a given month as nightly invoice item estimates do not necessarily encompass all invoicing factors for the entire month.
GET /v2/billing/{account_urn}/insights/{start_date}/{end_date}
Databases
- Read
List Database Options
To list all of the options available for the offered database engines, send a GET request to `/v2/databases/options`. The result will be a JSON object with an `options` key.
GET /v2/databases/options - Read
List All Database Clusters
To list all of the database clusters available on your account, send a GET request to `/v2/databases`. To limit the results to database clusters with a specific tag, include the `tag_name` query parameter set to the name of the tag. For example, `/v2/databases?tag_name=$TAG_NAME`. The result will be a JSON object with a `databases` key. This will be set to an array of database objects, each of which will contain the standard database attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects will contain the information needed to connect to the cluster's standby node(s). The embedded `maintenance_window` object will contain information about any scheduled maintenance for the database cluster.
GET /v2/databases - Read
Retrieve an Existing Database Cluster
To show information about an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID`. The response will be a JSON object with a database key. This will be set to an object containing the standard database cluster attributes. The embedded `connection` and `private_connection` objects will contain the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster.
GET /v2/databases/{database_cluster_uuid} - Read
Retrieve an Existing Database Cluster Configuration
Shows configuration parameters for an existing database cluster by sending a GET request to `/v2/databases/$DATABASE_ID/config`. The response is a JSON object with a `config` key, which is set to an object containing any database configuration parameters.
GET /v2/databases/{database_cluster_uuid}/config - Read
Retrieve the Public Certificate
To retrieve the public certificate used to secure the connection to the database cluster send a GET request to `/v2/databases/$DATABASE_ID/ca`. The response will be a JSON object with a `ca` key. This will be set to an object containing the base64 encoding of the public key certificate.
GET /v2/databases/{database_cluster_uuid}/ca - Read
Retrieve the Status of an Online Migration
To retrieve the status of the most recent online migration, send a GET request to `/v2/databases/$DATABASE_ID/online-migration`.
GET /v2/databases/{database_cluster_uuid}/online-migration - Read
List Firewall Rules (Trusted Sources) for a Database Cluster
To list all of a database cluster's firewall rules (known as "trusted sources" in the control panel), send a GET request to `/v2/databases/$DATABASE_ID/firewall`. The result will be a JSON object with a `rules` key.
GET /v2/databases/{database_cluster_uuid}/firewall - Read
Retrieve DO Settings for a Database Cluster
To retrieve the DigitalOcean-specific settings for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/do_settings`. The response will include the current `service_cnames` configuration.
GET /v2/databases/{database_cluster_uuid}/do_settings - Read
List Backups for a Database Cluster
To list all of the available backups of a PostgreSQL or MySQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/backups`. **Note**: Backups are not supported for Caching or Valkey clusters. The result will be a JSON object with a `backups key`. This will be set to an array of backup objects, each of which will contain the size of the backup and the timestamp at which it was created.
GET /v2/databases/{database_cluster_uuid}/backups - Read
List All Read-only Replicas
To list all of the read-only replicas associated with a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/replicas`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The result will be a JSON object with a `replicas` key. This will be set to an array of database replica objects, each of which will contain the standard database replica attributes.
GET /v2/databases/{database_cluster_uuid}/replicas - Read
List all Events Logs
To list all of the cluster events, send a GET request to `/v2/databases/$DATABASE_ID/events`. The result will be a JSON object with a `events` key.
GET /v2/databases/{database_cluster_uuid}/events - Read
Retrieve an Existing Read-only Replica
To show information about an existing database replica, send a GET request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a `replica key`. This will be set to an object containing the standard database replica attributes.
GET /v2/databases/{database_cluster_uuid}/replicas/{replica_name} - Read
List all Database Users
To list all of the users for your database cluster, send a GET request to `/v2/databases/$DATABASE_ID/users`. Note: User management is not supported for Caching or Valkey clusters. The result will be a JSON object with a `users` key. This will be set to an array of database user objects, each of which will contain the standard database user attributes. User passwords will not show without the `database:view_credentials` scope. For MySQL clusters, additional options will be contained in the mysql_settings object. For PostgreSQL clusters, additional options will be contained in the `settings` object (for example, `pg_allow_replication`). For Kafka clusters, additional options will be contained in the `settings` object. For MongoDB clusters, additional information will be contained in the mongo_user_settings object
GET /v2/databases/{database_cluster_uuid}/users - Read
Retrieve an Existing Database User
To show information about an existing database user, send a GET request to `/v2/databases/$DATABASE_ID/users/$USERNAME`. Note: User management is not supported for Caching or Valkey clusters. The response will be a JSON object with a `user` key. This will be set to an object containing the standard database user attributes. The user's password will not show up unless the `database:view_credentials` scope is present. For MySQL clusters, additional options will be contained in the `mysql_settings` object. For PostgreSQL clusters, additional options will be contained in the `settings` object (for example, `pg_allow_replication`). For Kafka clusters, additional options will be contained in the `settings` object. For MongoDB clusters, additional information will be contained in the mongo_user_settings object
GET /v2/databases/{database_cluster_uuid}/users/{username} - Read
List All Databases
To list all of the databases in a clusters, send a GET request to `/v2/databases/$DATABASE_ID/dbs`. The result will be a JSON object with a `dbs` key. This will be set to an array of database objects, each of which will contain the standard database attributes. Note: Database management is not supported for Caching or Valkey clusters.
GET /v2/databases/{database_cluster_uuid}/dbs - Read
Retrieve an Existing Database
To show information about an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID/dbs/$DB_NAME`. Note: Database management is not supported for Caching or Valkey clusters. The response will be a JSON object with a `db` key. This will be set to an object containing the standard database attributes.
GET /v2/databases/{database_cluster_uuid}/dbs/{database_name} - Read
List Connection Pools (PostgreSQL)
To list all of the connection pools available to a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools`. The result will be a JSON object with a `pools` key. This will be set to an array of connection pool objects.
GET /v2/databases/{database_cluster_uuid}/pools - Read
Retrieve Existing Connection Pool (PostgreSQL)
To show information about an existing connection pool for a PostgreSQL database cluster, send a GET request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. The response will be a JSON object with a `pool` key.
GET /v2/databases/{database_cluster_uuid}/pools/{pool_name} - Read
Retrieve the Eviction Policy for a Caching or Valkey Cluster
To retrieve the configured eviction policy for an existing Caching or Valkey cluster, send a GET request to `/v2/databases/$DATABASE_ID/eviction_policy`. The response will be a JSON object with an `eviction_policy` key. This will be set to a string representing the eviction policy.
GET /v2/databases/{database_cluster_uuid}/eviction_policy - Read
Retrieve the SQL Modes for a MySQL Cluster
To retrieve the configured SQL modes for an existing MySQL cluster, send a GET request to `/v2/databases/$DATABASE_ID/sql_mode`. The response will be a JSON object with a `sql_mode` key. This will be set to a string representing the configured SQL modes.
GET /v2/databases/{database_cluster_uuid}/sql_mode - Read
Retrieve Autoscale Configuration for a Database Cluster
To retrieve the autoscale configuration for an existing database cluster, send a GET request to `/v2/databases/$DATABASE_ID/autoscale`. The response will be a JSON object with autoscaling configuration details.
GET /v2/databases/{database_cluster_uuid}/autoscale - Read
List Topics for a Kafka Cluster
To list all of a Kafka cluster's topics, send a GET request to `/v2/databases/$DATABASE_ID/topics`. The result will be a JSON object with a `topics` key.
GET /v2/databases/{database_cluster_uuid}/topics - Read
Get Topic for a Kafka Cluster
To retrieve a given topic by name from the set of a Kafka cluster's topics, send a GET request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. The result will be a JSON object with a `topic` key.
GET /v2/databases/{database_cluster_uuid}/topics/{topic_name} - Read
List Logsinks for a Database Cluster
To list logsinks for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/logsink`.
GET /v2/databases/{database_cluster_uuid}/logsink - Read
Get Logsink for a Database Cluster
To get a logsink for a database cluster, send a GET request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`.
GET /v2/databases/{database_cluster_uuid}/logsink/{logsink_id} - Read
List Schemas for Kafka Cluster
To list all schemas for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry`.
GET /v2/databases/{database_cluster_uuid}/schema-registry - Read
Get a Kafka Schema by Subject Name
To get a specific schema by subject name for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME`.
GET /v2/databases/{database_cluster_uuid}/schema-registry/{subject_name} - Read
Get Kafka Schema by Subject Version
To get a specific schema by subject name for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME/versions/$VERSION`.
GET /v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}/versions/{version} - Read
Retrieve Schema Registry Configuration for a kafka Cluster
To retrieve the Schema Registry configuration for a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/config`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters.
GET /v2/databases/{database_cluster_uuid}/schema-registry/config - Read
Retrieve Schema Registry Configuration for a Subject of kafka Cluster
To retrieve the Schema Registry configuration for a Subject of a Kafka cluster, send a GET request to `/v2/databases/$DATABASE_ID/schema-registry/config/$SUBJECT_NAME`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters.
GET /v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name} - Read
Retrieve Database Clusters' Metrics Endpoint Credentials
To show the credentials for all database clusters' metrics endpoints, send a GET request to `/v2/databases/metrics/credentials`. The result will be a JSON object with a `credentials` key.
GET /v2/databases/metrics/credentials - Read
List Indexes for a OpenSearch Cluster
To list all of a OpenSearch cluster's indexes, send a GET request to `/v2/databases/$DATABASE_ID/indexes`. The result will be a JSON object with a `indexes` key.
GET /v2/databases/{database_cluster_uuid}/indexes - Write
Create a New Database Cluster
To create a database cluster, send a POST request to `/v2/databases`. To see a list of options for each engine, such as available regions, size slugs, and versions, send a GET request to the `/v2/databases/options` endpoint. The available sizes for the `storage_size_mib` field depends on the cluster's size. To see a list of available sizes, see [Managed Database Pricing](https://www.digitalocean.com/pricing/managed-databases). The create response returns a JSON object with a key called `database`. The value of this is an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's `status` attribute is `creating`. When the cluster is ready to receive traffic, this changes to `online`. The embedded `connection` and `private_connection` objects contains the information needed to access the database cluster. For multi-node clusters, the `standby_connection` and `standby_private_connection` objects contain the information needed to connect to the cluster's standby node(s). DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an existing cluster, send a POST request to `/v2/databases`. In addition to the standard database cluster attributes, the JSON body must include a key named `backup_restore` with the name of the original database cluster and the timestamp of the backup to be restored. Creating a database from a backup is the same as forking a database in the control panel. PostgreSQL and MySQL Advanced Edition clusters can be provisioned by setting `engine` to `advanced_pg` or `advanced_mysql`. Advanced Edition clusters are currently in public preview and target highly available workloads. `advanced_pg` supports 1-, 2-, and 3-node deployments; `advanced_mysql` only supports 1- and 3-node deployments. See the [PostgreSQL Advanced Edition](https://docs.digitalocean.com/products/databases/postgresql/how-to/use-advanced-edition-clusters/) and [MySQL Advanced Edition](https://docs.digitalocean.com/products/databases/mysql/how-to/use-advanced-edition-clusters/) documentation for the feature differences vs. Standard Edition and current preview limitations. Note: Caching cluster creates are no longer supported as of 2025-04-30T00:00:00Z. Backups are also not supported for Caching or Valkey clusters.
POST /v2/databases - Write
Update the Database Configuration for an Existing Database
To update the configuration for an existing database cluster, send a PATCH request to `/v2/databases/$DATABASE_ID/config`.
PATCH /v2/databases/{database_cluster_uuid}/config - Write
Start an Online Migration
To start an online migration, send a PUT request to `/v2/databases/$DATABASE_ID/online-migration` endpoint. Migrating a cluster establishes a connection with an existing cluster and replicates its contents to the target cluster. Online migration is only available for MySQL, PostgreSQL, Caching, and Valkey clusters. If the existing database is continuously being written to, the migration process will continue for up to two weeks unless it is manually stopped. Online migration is only available for [MySQL](https://docs.digitalocean.com/products/databases/mysql/how-to/migrate/#:~:text=To%20migrate%20a%20MySQL%20database,then%20select%20Set%20Up%20Migration), [PostgreSQL](https://docs.digitalocean.com/products/databases/postgresql/how-to/migrate/), [Caching](https://docs.digitalocean.com/products/databases/redis/how-to/migrate/), and [Valkey](https://docs.digitalocean.com/products/databases/valkey/how-to/migrate/) clusters.
PUT /v2/databases/{database_cluster_uuid}/online-migration - Write
Migrate a Database Cluster to a New Region
To migrate a database cluster to a new region, send a `PUT` request to `/v2/databases/$DATABASE_ID/migrate`. The body of the request must specify a `region` attribute. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its `status` attribute will now be set to `migrating`. This will transition back to `online` when the migration has completed.
PUT /v2/databases/{database_cluster_uuid}/migrate - Write
Resize a Database Cluster
To resize a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/resize`. The body of the request must specify both the size and num_nodes attributes. A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to resizing. This will transition back to online when the resize operation has completed.
PUT /v2/databases/{database_cluster_uuid}/resize - Write
Update Firewall Rules (Trusted Sources) for a Database
To update a database cluster's firewall rules (known as "trusted sources" in the control panel), send a PUT request to `/v2/databases/$DATABASE_ID/firewall` specifying which resources should be able to open connections to the database. You may limit connections to specific Droplets, Kubernetes clusters, or IP addresses. When a tag is provided, any Droplet or Kubernetes node with that tag applied to it will have access. The firewall is limited to 100 rules (or trusted sources). You cannot add IPv6 addresses as trusted sources. For additional limits, see your database engine's limits page. When possible, we recommend [placing your databases into a VPC network](https://docs.digitalocean.com/products/networking/vpc/) to limit access to them instead of using a firewall. A successful request returns a 204 status code with no content.
PUT /v2/databases/{database_cluster_uuid}/firewall - Write
Update DO Settings for a Database Cluster
To update the DigitalOcean-specific settings for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/do_settings`. Currently, the only supported setting is `service_cnames`, which allows you to specify custom DNS names (CNAMEs) to be included in the TLS certificate Subject Alternative Names (SANs) for the database cluster nodes. This enables TLS verification when connecting via a custom hostname. After updating, the database nodes will be replaced to apply the new certificate. This process is performed as a rolling replacement and does not cause downtime. To clear all custom CNAMEs, send an empty array or omit the field.
PUT /v2/databases/{database_cluster_uuid}/do_settings - Write
Configure a Database Cluster's Maintenance Window
To configure the window when automatic maintenance should be performed for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/maintenance`. A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/{database_cluster_uuid}/maintenance - Write
Start Database Maintenance
To start the installation of updates for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/install_update`. A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/{database_cluster_uuid}/install_update - Write
Create a Read-only Replica
To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to `/v2/databases/$DATABASE_ID/replicas` specifying the name it should be given, the size of the node to be used, and the region where it will be located. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. The response will be a JSON object with a key called `replica`. The value of this will be an object that contains the standard attributes associated with a database replica. The initial value of the read-only replica's `status` attribute will be `forking`. When the replica is ready to receive traffic, this will transition to `active`.
POST /v2/databases/{database_cluster_uuid}/replicas - Write
Promote a Read-only Replica to become a Primary Cluster
To promote a specific read-only replica, send a PUT request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME/promote`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
PUT /v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote - Write
Add a Database User
To add a new database user, send a POST request to `/v2/databases/$DATABASE_ID/users` with the desired username. Note: User management is not supported for Caching or Valkey clusters. When adding a user to a MySQL cluster, additional options can be configured in the `mysql_settings` object. When adding a user to a PostgreSQL cluster, additional options can be configured in the `settings` object (for example, `pg_allow_replication`). When `pg_allow_replication` is omitted, it defaults to `false`. When adding a user to a Kafka cluster, additional options can be configured in the `settings` object. When adding a user to a MongoDB cluster, additional options can be configured in the `settings.mongo_user_settings` object. The response will be a JSON object with a key called `user`. The value of this will be an object that contains the standard attributes associated with a database user including its randomly generated password.
POST /v2/databases/{database_cluster_uuid}/users - Write
Update a Database User
To update an existing database user, send a PUT request to `/v2/databases/$DATABASE_ID/users/$USERNAME` with the desired settings. **Note**: only `settings` can be updated via this type of request. If you wish to change the name of a user, you must recreate a new user. For PostgreSQL clusters, you can update `settings.pg_allow_replication` to enable or disable replication privileges for the user. When omitted, the value defaults to `false`. For Kafka and OpenSearch clusters, additional options can be configured in the `settings` object (for example, topic or index ACLs). Updating users is supported for PostgreSQL, Kafka, and OpenSearch clusters. For other engines, the request returns a 422. MongoDB roles and database access are set with `settings.mongo_user_settings` when creating a user and cannot be changed afterward; recreate the user to apply different roles or databases. The response will be a JSON object with a key called `user`. The value of this will be an object that contains the name of the updated database user, along with the `settings` object that has been updated.
PUT /v2/databases/{database_cluster_uuid}/users/{username} - Write
Add a New Database
To add a new database to an existing cluster, send a POST request to `/v2/databases/$DATABASE_ID/dbs`. Note: Database management is not supported for Caching or Valkey clusters. The response will be a JSON object with a key called `db`. The value of this will be an object that contains the standard attributes associated with a database.
POST /v2/databases/{database_cluster_uuid}/dbs - Write
Add a New Connection Pool (PostgreSQL)
For PostgreSQL database clusters, connection pools can be used to allow a database to share its idle connections. The popular PostgreSQL connection pooling utility PgBouncer is used to provide this service. [See here for more information](https://docs.digitalocean.com/products/databases/postgresql/how-to/manage-connection-pools/) about how and why to use PgBouncer connection pooling including details about the available transaction modes. To add a new connection pool to a PostgreSQL database cluster, send a POST request to `/v2/databases/$DATABASE_ID/pools` specifying a name for the pool, the user to connect with, the database to connect to, as well as its desired size and transaction mode.
POST /v2/databases/{database_cluster_uuid}/pools - Write
Update Connection Pools (PostgreSQL)
To update a connection pool for a PostgreSQL database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`.
PUT /v2/databases/{database_cluster_uuid}/pools/{pool_name} - Write
Configure the Eviction Policy for a Caching or Valkey Cluster
To configure an eviction policy for an existing Caching or Valkey cluster, send a PUT request to `/v2/databases/$DATABASE_ID/eviction_policy` specifying the desired policy.
PUT /v2/databases/{database_cluster_uuid}/eviction_policy - Write
Update SQL Mode for a Cluster
To configure the SQL modes for an existing MySQL cluster, send a PUT request to `/v2/databases/$DATABASE_ID/sql_mode` specifying the desired modes. See the official MySQL 8 documentation for a [full list of supported SQL modes](https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sql-mode-full). A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/{database_cluster_uuid}/sql_mode - Write
Upgrade Major Version for a Database
To upgrade the major version of a database, send a PUT request to `/v2/databases/$DATABASE_ID/upgrade`, specifying the target version. A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/{database_cluster_uuid}/upgrade - Write
Configure Autoscale Settings for a Database Cluster
To configure autoscale settings for an existing database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/autoscale`, specifying the autoscale configuration. A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/{database_cluster_uuid}/autoscale - Write
Create Topic for a Kafka Cluster
To create a topic attached to a Kafka cluster, send a POST request to `/v2/databases/$DATABASE_ID/topics`. The result will be a JSON object with a `topic` key.
POST /v2/databases/{database_cluster_uuid}/topics - Write
Update Topic for a Kafka Cluster
To update a topic attached to a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. The result will be a JSON object with a `topic` key.
PUT /v2/databases/{database_cluster_uuid}/topics/{topic_name} - Write
Create Logsink for a Database Cluster
To create logsink for a database cluster, send a POST request to `/v2/databases/$DATABASE_ID/logsink`.
POST /v2/databases/{database_cluster_uuid}/logsink - Write
Update Logsink for a Database Cluster
To update a logsink for a database cluster, send a PUT request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`.
PUT /v2/databases/{database_cluster_uuid}/logsink/{logsink_id} - Write
Create Schema Registry for Kafka Cluster
To create a Kafka schema for a database cluster, send a POST request to `/v2/databases/$DATABASE_ID/schema-registry`.
POST /v2/databases/{database_cluster_uuid}/schema-registry - Write
Update Schema Registry Configuration for a kafka Cluster
To update the Schema Registry configuration for a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/schema-registry/config`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters.
PUT /v2/databases/{database_cluster_uuid}/schema-registry/config - Write
Update Schema Registry Configuration for a Subject of kafka Cluster
To update the Schema Registry configuration for a Subject of a Kafka cluster, send a PUT request to `/v2/databases/$DATABASE_ID/schema-registry/config/$SUBJECT_NAME`. The response is a JSON object with a `compatibility_level` key, which is set to an object containing any database configuration parameters.
PUT /v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name} - Write
Update Database Clusters' Metrics Endpoint Credentials
To update the credentials for all database clusters' metrics endpoints, send a PUT request to `/v2/databases/metrics/credentials`. A successful request will receive a 204 No Content status code with no body in response.
PUT /v2/databases/metrics/credentials - Destructive
Destroy a Database Cluster
To destroy a specific database, send a DELETE request to `/v2/databases/$DATABASE_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid} - Destructive
Stop an Online Migration
To stop an online migration, send a DELETE request to `/v2/databases/$DATABASE_ID/online-migration/$MIGRATION_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid}/online-migration/{migration_id} - Destructive
Destroy a Read-only Replica
To destroy a specific read-only replica, send a DELETE request to `/v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME`. **Note**: Read-only replicas are not supported for Caching or Valkey clusters. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid}/replicas/{replica_name} - Destructive
Remove a Database User
To remove a specific database user, send a DELETE request to `/v2/databases/$DATABASE_ID/users/$USERNAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. Note: User management is not supported for Caching or Valkey clusters.
DELETE /v2/databases/{database_cluster_uuid}/users/{username} - Destructive
Reset a Database User's Password or Authentication Method
To reset the password for a database user, send a POST request to `/v2/databases/$DATABASE_ID/users/$USERNAME/reset_auth`. For `mysql` databases, the authentication method can be specifying by including a key in the JSON body called `mysql_settings` with the `auth_plugin` value specified. The response will be a JSON object with a `user` key. This will be set to an object containing the standard database user attributes.
POST /v2/databases/{database_cluster_uuid}/users/{username}/reset_auth - Destructive
Delete a Database
To delete a specific database, send a DELETE request to `/v2/databases/$DATABASE_ID/dbs/$DB_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed. Note: Database management is not supported for Caching or Valkey clusters.
DELETE /v2/databases/{database_cluster_uuid}/dbs/{database_name} - Destructive
Delete a Connection Pool (PostgreSQL)
To delete a specific connection pool for a PostgreSQL database cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid}/pools/{pool_name} - Destructive
Delete Topic for a Kafka Cluster
To delete a single topic within a Kafka cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/topics/$TOPIC_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid}/topics/{topic_name} - Destructive
Delete Logsink for a Database Cluster
To delete a logsink for a database cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`.
DELETE /v2/databases/{database_cluster_uuid}/logsink/{logsink_id} - Destructive
Delete a Kafka Schema by Subject Name
To delete a specific schema by subject name for a Kafka cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/schema-registry/$SUBJECT_NAME`.
DELETE /v2/databases/{database_cluster_uuid}/schema-registry/{subject_name} - Destructive
Delete Index for OpenSearch Cluster
To delete a single index within OpenSearch cluster, send a DELETE request to `/v2/databases/$DATABASE_ID/indexes/$INDEX_NAME`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/databases/{database_cluster_uuid}/indexes/{index_name}
Dedicated Inference
- Read
Get a Dedicated Inference
Retrieve an existing Dedicated Inference by ID. Send a GET request to `/v2/dedicated-inferences/{dedicated_inference_id}`. The status in the response is one of active, new, provisioning, updating, deleting, or error.
GET /v2/dedicated-inferences/{dedicated_inference_id} - Read
List Dedicated Inferences
List all Dedicated Inference instances for your team. Send a GET request to `/v2/dedicated-inferences`. You may filter by region and use page and per_page for pagination.
GET /v2/dedicated-inferences - Read
List Dedicated Inference Accelerators
List all accelerators (GPUs) in use by a Dedicated Inference instance. Send a GET request to `/v2/dedicated-inferences/{dedicated_inference_id}/accelerators`. Optionally filter by slug and use page/per_page for pagination.
GET /v2/dedicated-inferences/{dedicated_inference_id}/accelerators - Read
Get a Dedicated Inference Accelerator
Retrieve a single accelerator by ID for a Dedicated Inference instance. Send a GET request to `/v2/dedicated-inferences/{dedicated_inference_id}/accelerators/{accelerator_id}`.
GET /v2/dedicated-inferences/{dedicated_inference_id}/accelerators/{accelerator_id} - Read
Get Dedicated Inference CA Certificate
Get the CA certificate for a Dedicated Inference instance (base64-encoded). Required for private endpoint connectivity. Send a GET request to `/v2/dedicated-inferences/{dedicated_inference_id}/ca`.
GET /v2/dedicated-inferences/{dedicated_inference_id}/ca - Read
List Dedicated Inference Tokens
List all access tokens for a Dedicated Inference instance. Token values are not returned; only id, name, created_at, and is_managed. Send a GET request to `/v2/dedicated-inferences/{dedicated_inference_id}/tokens`.
GET /v2/dedicated-inferences/{dedicated_inference_id}/tokens - Read
List Dedicated Inference Sizes
Get available Dedicated Inference sizes and pricing for supported GPUs. Send a GET request to `/v2/dedicated-inferences/sizes`.
GET /v2/dedicated-inferences/sizes - Read
Get Dedicated Inference GPU Model Config
Get supported GPU and model configurations for Dedicated Inference. Use this to discover supported GPU slugs and model slugs (e.g. Hugging Face). Send a GET request to `/v2/dedicated-inferences/gpu-model-config`.
GET /v2/dedicated-inferences/gpu-model-config - Write
Update a Dedicated Inference
Update an existing Dedicated Inference. Send a PATCH request to `/v2/dedicated-inferences/{dedicated_inference_id}` with updated `spec` and/or `access_tokens`. Status will move to updating and return to active when done.
PATCH /v2/dedicated-inferences/{dedicated_inference_id} - Write
Create a Dedicated Inference
Create a new Dedicated Inference for your team. Send a POST request to `/v2/dedicated-inferences` with a `spec` object (version, name, region, vpc, enable_public_endpoint, model_deployments) and optional `access_tokens` (e.g. hugging_face_token for gated models). The response code 202 Accepted indicates the request was accepted for processing; it does not indicate success or failure. The token value is returned only on create; store it securely.
POST /v2/dedicated-inferences - Write
Create a Dedicated Inference Token
Create a new access token for a Dedicated Inference instance. Send a POST request to `/v2/dedicated-inferences/{dedicated_inference_id}/tokens` with a `name`. The token value is returned only once in the response; store it securely.
POST /v2/dedicated-inferences/{dedicated_inference_id}/tokens - Destructive
Delete a Dedicated Inference
Delete an existing Dedicated Inference. Send a DELETE request to `/v2/dedicated-inferences/{dedicated_inference_id}`. The response 202 Accepted indicates the request was accepted for processing.
DELETE /v2/dedicated-inferences/{dedicated_inference_id} - Destructive
Revoke a Dedicated Inference Token
Revoke (delete) an access token for a Dedicated Inference instance. Send a DELETE request to `/v2/dedicated-inferences/{dedicated_inference_id}/tokens/{token_id}`.
DELETE /v2/dedicated-inferences/{dedicated_inference_id}/tokens/{token_id}
Domains
- Read
List All Domains
To retrieve a list of all of the domains in your account, send a GET request to `/v2/domains`.
GET /v2/domains - Read
Retrieve an Existing Domain
To get details about a specific domain, send a GET request to `/v2/domains/$DOMAIN_NAME`.
GET /v2/domains/{domain_name} - Write
Create a New Domain
To create a new domain, send a POST request to `/v2/domains`. Set the "name" attribute to the domain name you are adding. Optionally, you may set the "ip_address" attribute, and an A record will be automatically created pointing to the apex domain.
POST /v2/domains - Destructive
Delete a Domain
To delete a domain, send a DELETE request to `/v2/domains/$DOMAIN_NAME`.
DELETE /v2/domains/{domain_name}
Domain Records
- Read
List All Domain Records
To get a listing of all records configured for a domain, send a GET request to `/v2/domains/$DOMAIN_NAME/records`. The list of records returned can be filtered by using the `name` and `type` query parameters. For example, to only include A records for a domain, send a GET request to `/v2/domains/$DOMAIN_NAME/records?type=A`. `name` must be a fully qualified record name. For example, to only include records matching `sub.example.com`, send a GET request to `/v2/domains/$DOMAIN_NAME/records?name=sub.example.com`. Both name and type may be used together.
GET /v2/domains/{domain_name}/records - Read
Retrieve an Existing Domain Record
To retrieve a specific domain record, send a GET request to `/v2/domains/$DOMAIN_NAME/records/$RECORD_ID`.
GET /v2/domains/{domain_name}/records/{domain_record_id} - Write
Create a New Domain Record
To create a new record to a domain, send a POST request to `/v2/domains/$DOMAIN_NAME/records`. The request must include all of the required fields for the domain record type being added. See the [attribute table](#tag/Domain-Records) for details regarding record types and their respective required attributes.
POST /v2/domains/{domain_name}/records - Write
Update a Domain Record
To update an existing record, send a PATCH request to `/v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID`. Any attribute valid for the record type can be set to a new value for the record. See the [attribute table](#tag/Domain-Records) for details regarding record types and their respective attributes.
PATCH /v2/domains/{domain_name}/records/{domain_record_id} - Write
Update a Domain Record
To update an existing record, send a PUT request to `/v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID`. Any attribute valid for the record type can be set to a new value for the record. See the [attribute table](#tag/Domain-Records) for details regarding record types and their respective attributes.
PUT /v2/domains/{domain_name}/records/{domain_record_id} - Destructive
Delete a Domain Record
To delete a record for a domain, send a DELETE request to `/v2/domains/$DOMAIN_NAME/records/$DOMAIN_RECORD_ID`. The record will be deleted and the response status will be a 204. This indicates a successful request with no body returned.
DELETE /v2/domains/{domain_name}/records/{domain_record_id}
Droplets
- Read
List All Droplets
To list all Droplets in your account, send a GET request to `/v2/droplets`. The response body will be a JSON object with a key of `droplets`. This will be set to an array containing objects each representing a Droplet. These will contain the standard Droplet attributes. ### Filtering Results by Tag It's possible to request filtered results by including certain query parameters. To only list Droplets assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your GET request. For example, `/v2/droplets?tag_name=$TAG_NAME`. ### GPU Droplets By default, only non-GPU Droplets are returned. To list only GPU Droplets, set the `type` query parameter to `gpus`. For example, `/v2/droplets?type=gpus`.
GET /v2/droplets - Read
Retrieve an Existing Droplet
To show information about an individual Droplet, send a GET request to `/v2/droplets/$DROPLET_ID`.
GET /v2/droplets/{droplet_id} - Read
List Backups for a Droplet
To retrieve any backups associated with a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/backups`. You will get back a JSON object that has a `backups` key. This will be set to an array of backup objects, each of which contain the standard Droplet backup attributes.
GET /v2/droplets/{droplet_id}/backups - Read
Retrieve the Backup Policy for an Existing Droplet
To show information about an individual Droplet's backup policy, send a GET request to `/v2/droplets/$DROPLET_ID/backups/policy`.
GET /v2/droplets/{droplet_id}/backups/policy - Read
List Backup Policies for All Existing Droplets
To list information about the backup policies for all Droplets in the account, send a GET request to `/v2/droplets/backups/policies`.
GET /v2/droplets/backups/policies - Read
List Supported Droplet Backup Policies
To retrieve a list of all supported Droplet backup policies, send a GET request to `/v2/droplets/backups/supported_policies`.
GET /v2/droplets/backups/supported_policies - Read
List Snapshots for a Droplet
To retrieve the snapshots that have been created from a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/snapshots`. You will get back a JSON object that has a `snapshots` key. This will be set to an array of snapshot objects, each of which contain the standard Droplet snapshot attributes.
GET /v2/droplets/{droplet_id}/snapshots - Read
List All Available Kernels for a Droplet
To retrieve a list of all kernels available to a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/kernels` The response will be a JSON object that has a key called `kernels`. This will be set to an array of `kernel` objects, each of which contain the standard `kernel` attributes.
GET /v2/droplets/{droplet_id}/kernels - Read
List all Firewalls Applied to a Droplet
To retrieve a list of all firewalls available to a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/firewalls` The response will be a JSON object that has a key called `firewalls`. This will be set to an array of `firewall` objects, each of which contain the standard `firewall` attributes.
GET /v2/droplets/{droplet_id}/firewalls - Read
List Neighbors for a Droplet
To retrieve a list of any "neighbors" (i.e. Droplets that are co-located on the same physical hardware) for a specific Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/neighbors`. The results will be returned as a JSON object with a key of `droplets`. This will be set to an array containing objects representing any other Droplets that share the same physical hardware. An empty array indicates that the Droplet is not co-located any other Droplets associated with your account.
GET /v2/droplets/{droplet_id}/neighbors - Read
List Associated Resources for a Droplet
To list the associated billable resources that can be destroyed along with a Droplet, send a GET request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources` endpoint. This endpoint will only return resources that you are authorized to see. For example, to see associated Reserved IPs, include the `reserved_ip:read` scope. The response will be a JSON object containing `snapshots`, `volumes`, and `volume_snapshots` keys. Each will be set to an array of objects containing information about the associated resources.
GET /v2/droplets/{droplet_id}/destroy_with_associated_resources - Read
Check Status of a Droplet Destroy with Associated Resources Request
To check on the status of a request to destroy a Droplet with its associated resources, send a GET request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/status` endpoint.
GET /v2/droplets/{droplet_id}/destroy_with_associated_resources/status - Read
List All Droplet Neighbors
To retrieve a list of all Droplets that are co-located on the same physical hardware, send a GET request to `/v2/reports/droplet_neighbors_ids`. The results will be returned as a JSON object with a key of `neighbor_ids`. This will be set to an array of arrays. Each array will contain a set of Droplet IDs for Droplets that share a physical server. An empty array indicates that all Droplets associated with your account are located on separate physical hardware.
GET /v2/reports/droplet_neighbors_ids - Write
Create a New Droplet
To create a new Droplet, send a POST request to `/v2/droplets` setting the required attributes. A Droplet will be created using the provided information. The response body will contain a JSON object with a key called `droplet`. The value will be an object containing the standard attributes for your new Droplet. The response code, 202 Accepted, does not indicate the success or failure of the operation, just that the request has been accepted for processing. The `actions` returned as part of the response's `links` object can be used to check the status of the Droplet create event. ### Create Multiple Droplets Creating multiple Droplets is very similar to creating a single Droplet. Instead of sending `name` as a string, send `names` as an array of strings. A Droplet will be created for each name you send using the associated information. Up to ten Droplets may be created this way at a time. Rather than returning a single Droplet, the response body will contain a JSON array with a key called `droplets`. This will be set to an array of JSON objects, each of which will contain the standard Droplet attributes. The response code, 202 Accepted, does not indicate the success or failure of any operation, just that the request has been accepted for processing. The array of `actions` returned as part of the response's `links` object can be used to check the status of each individual Droplet create event.
POST /v2/droplets - Destructive
Deleting Droplets by Tag
To delete **all** Droplets assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your DELETE request. For example, `/v2/droplets?tag_name=$TAG_NAME`. This endpoint requires `tag:read` scope. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/droplets - Destructive
Delete an Existing Droplet
To delete a Droplet, send a DELETE request to `/v2/droplets/$DROPLET_ID`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/droplets/{droplet_id} - Destructive
Selectively Destroy a Droplet and its Associated Resources
To destroy a Droplet along with a sub-set of its associated resources, send a DELETE request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/selective` endpoint. The JSON body of the request should include `reserved_ips`, `snapshots`, `volumes`, or `volume_snapshots` keys each set to an array of IDs for the associated resources to be destroyed. The IDs can be found by querying the Droplet's associated resources. Any associated resource not included in the request will remain and continue to accrue changes on your account. A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources.
DELETE /v2/droplets/{droplet_id}/destroy_with_associated_resources/selective - Destructive
Destroy a Droplet and All of its Associated Resources (Dangerous)
To destroy a Droplet along with all of its associated resources, send a DELETE request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/dangerous` endpoint. The headers of this request must include an `X-Dangerous` key set to `true`. To preview which resources will be destroyed, first query the Droplet's associated resources. This operation _can not_ be reverse and should be used with caution. A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources.
DELETE /v2/droplets/{droplet_id}/destroy_with_associated_resources/dangerous - Destructive
Retry a Droplet Destroy with Associated Resources Request
If the status of a request to destroy a Droplet with its associated resources reported any errors, it can be retried by sending a POST request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/retry` endpoint. Only one destroy can be active at a time per Droplet. If a retry is issued while another destroy is in progress for the Droplet a 409 status code will be returned. A successful response will include a 202 response code and no content.
POST /v2/droplets/{droplet_id}/destroy_with_associated_resources/retry
Droplet Actions
- Read
List Actions for a Droplet
To retrieve a list of all actions that have been executed for a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/actions`. The results will be returned as a JSON object with an `actions` key. This will be set to an array filled with `action` objects containing the standard `action` attributes.
GET /v2/droplets/{droplet_id}/actions - Read
Retrieve a Droplet Action
To retrieve a Droplet action, send a GET request to `/v2/droplets/$DROPLET_ID/actions/$ACTION_ID`. The response will be a JSON object with a key called `action`. The value will be a Droplet action object.
GET /v2/droplets/{droplet_id}/actions/{action_id} - Write
Acting on Tagged Droplets
Some actions can be performed in bulk on tagged Droplets. The actions can be initiated by sending a POST to `/v2/droplets/actions?tag_name=$TAG_NAME` with the action arguments. Only a sub-set of action types are supported: - `power_cycle` - `power_on` - `power_off` - `shutdown` - `enable_ipv6` (**Warning:** The Droplet must be powered off before enabling IPv6 on an existing Droplet.) - `enable_backups` - `disable_backups` - `snapshot` (also requires `image:create` permission)
POST /v2/droplets/actions - Destructive
Initiate a Droplet Action
To initiate an action on a Droplet send a POST request to `/v2/droplets/$DROPLET_ID/actions`. In the JSON body to the request, set the `type` attribute to one of the supported action types: | Action | Details | Required Permissions | | ---------------------------------------- | ----------- | ----------- | | <nobr>`enable_backups`</nobr> | Enables backups for a Droplet | <nobr>`droplet:update`</nobr> | | <nobr>`disable_backups`</nobr> | Disables backups for a Droplet | <nobr>`droplet:update`</nobr> | | <nobr>`change_backup_policy`</nobr> | Update the backup policy for a Droplet | <nobr>`droplet:update`</nobr> | | <nobr>`reboot`</nobr> | Reboots a Droplet. A `reboot` action is an attempt to reboot the Droplet in a graceful way, similar to using the `reboot` command from the console. | <nobr>`droplet:update`</nobr> | | <nobr>`power_cycle`</nobr> | Power cycles a Droplet. A `powercycle` action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch. | <nobr>`droplet:update`</nobr> | | <nobr>`shutdown`</nobr> | Shuts down a Droplet. A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the `shutdown` command from the console. Since a `shutdown` command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a `power_off` action to ensure the Droplet is off. | <nobr>`droplet:update`</nobr> | | <nobr>`power_off`</nobr> | Powers off a Droplet. A `power_off` event is a hard shutdown and should only be used if the `shutdown` action is not successful. It is similar to cutting the power on a server and could lead to complications. | <nobr>`droplet:update`</nobr> | | <nobr>`power_on`</nobr> | Powers on a Droplet. | <nobr>`droplet:update`</nobr> | | <nobr>`restore`</nobr> | Restore a Droplet using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact. | <nobr>`droplet:update`</nobr><br><nobr>`droplet:admin`</nobr> | | <nobr>`password_reset`</nobr> | Resets the root password for a Droplet. A new password will be provided via email. It must be changed after first use. | <nobr>`droplet:update`</nobr><br><nobr>`droplet:admin`</nobr> | | <nobr>`resize`</nobr> | Resizes a Droplet. Set the `size` attribute to a size slug. If a permanent resize with disk changes included is desired, set the `disk` attribute to `true`. | <nobr>`droplet:update`</nobr><br><nobr>`droplet:create`</nobr> | | <nobr>`rebuild`</nobr> | Rebuilds a Droplet from a new base image. Set the `image` attribute to an image ID or slug. | <nobr>`droplet:update`</nobr><br><nobr>`droplet:admin`</nobr> | | <nobr>`rename`</nobr> | Renames a Droplet. | <nobr>`droplet:update`</nobr> | | <nobr>`change_kernel`</nobr> | Changes a Droplet's kernel. Only applies to Droplets with externally managed kernels. All Droplets created after March 2017 use internal kernels by default. | <nobr>`droplet:update`</nobr> | | <nobr>`enable_ipv6`</nobr> | Enables IPv6 for a Droplet. Once enabled for a Droplet, IPv6 can not be disabled. **Warning:** The Droplet must be powered off before enabling IPv6 on an existing Droplet. When enabling IPv6 on an existing Droplet, [additional OS-level configuration](https://docs.digitalocean.com/products/networking/ipv6/how-to/enable/#on-existing-droplets) is required. | <nobr>`droplet:update`</nobr> | | <nobr>`snapshot`</nobr> | Takes a snapshot of a Droplet. | <nobr>`droplet:update`</nobr><br><nobr>`image:create`</nobr> |
POST /v2/droplets/{droplet_id}/actions
Droplet Autoscale Pools
- Read
List All Autoscale Pools
To list all autoscale pools in your team, send a GET request to `/v2/droplets/autoscale`. The response body will be a JSON object with a key of `autoscale_pools` containing an array of autoscale pool objects. These each contain the standard autoscale pool attributes.
GET /v2/droplets/autoscale - Read
Retrieve an Existing Autoscale Pool
To show information about an individual autoscale pool, send a GET request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID`.
GET /v2/droplets/autoscale/{autoscale_pool_id} - Read
List members
To list the Droplets in an autoscale pool, send a GET request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/members`. The response body will be a JSON object with a key of `droplets`. This will be set to an array containing information about each of the Droplets in the autoscale pool.
GET /v2/droplets/autoscale/{autoscale_pool_id}/members - Read
List history events
To list all of the scaling history events of an autoscale pool, send a GET request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/history`. The response body will be a JSON object with a key of `history`. This will be set to an array containing objects each representing a history event.
GET /v2/droplets/autoscale/{autoscale_pool_id}/history - Write
Create a New Autoscale Pool
To create a new autoscale pool, send a POST request to `/v2/droplets/autoscale` setting the required attributes. The response body will contain a JSON object with a key called `autoscale_pool` containing the standard attributes for the new autoscale pool.
POST /v2/droplets/autoscale - Write
Update Autoscale Pool
To update the configuration of an existing autoscale pool, send a PUT request to `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID`. The request must contain a full representation of the autoscale pool including existing attributes.
PUT /v2/droplets/autoscale/{autoscale_pool_id} - Destructive
Delete autoscale pool
To destroy an autoscale pool, send a DELETE request to the `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID` endpoint. A successful response will include a 202 response code and no content.
DELETE /v2/droplets/autoscale/{autoscale_pool_id} - Destructive
Delete autoscale pool and resources
To destroy an autoscale pool and its associated resources (Droplets), send a DELETE request to the `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/dangerous` endpoint.
DELETE /v2/droplets/autoscale/{autoscale_pool_id}/dangerous
Firewalls
- Read
List All Firewalls
To list all of the firewalls available on your account, send a GET request to `/v2/firewalls`.
GET /v2/firewalls - Read
Retrieve an Existing Firewall
To show information about an existing firewall, send a GET request to `/v2/firewalls/$FIREWALL_ID`.
GET /v2/firewalls/{firewall_id} - Write
Create a New Firewall
To create a new firewall, send a POST request to `/v2/firewalls`. The request must contain at least one inbound or outbound access rule.
POST /v2/firewalls - Write
Add Droplets to a Firewall
To assign a Droplet to a firewall, send a POST request to `/v2/firewalls/$FIREWALL_ID/droplets`. In the body of the request, there should be a `droplet_ids` attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
POST /v2/firewalls/{firewall_id}/droplets - Write
Add Tags to a Firewall
To assign a tag representing a group of Droplets to a firewall, send a POST request to `/v2/firewalls/$FIREWALL_ID/tags`. In the body of the request, there should be a `tags` attribute containing a list of tag names. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
POST /v2/firewalls/{firewall_id}/tags - Write
Add Rules to a Firewall
To add additional access rules to a firewall, send a POST request to `/v2/firewalls/$FIREWALL_ID/rules`. The body of the request may include an inbound_rules and/or outbound_rules attribute containing an array of rules to be added. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
POST /v2/firewalls/{firewall_id}/rules - Destructive
Update a Firewall
To update the configuration of an existing firewall, send a PUT request to `/v2/firewalls/$FIREWALL_ID`. The request should contain a full representation of the firewall including existing attributes. **Note that any attributes that are not provided will be reset to their default values.** <br><br>You must have read access (e.g. `droplet:read`) to all resources attached to the firewall to successfully update the firewall.
PUT /v2/firewalls/{firewall_id} - Destructive
Delete a Firewall
To delete a firewall send a DELETE request to `/v2/firewalls/$FIREWALL_ID`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/firewalls/{firewall_id} - Destructive
Remove Droplets from a Firewall
To remove a Droplet from a firewall, send a DELETE request to `/v2/firewalls/$FIREWALL_ID/droplets`. In the body of the request, there should be a `droplet_ids` attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/firewalls/{firewall_id}/droplets - Destructive
Remove Tags from a Firewall
To remove a tag representing a group of Droplets from a firewall, send a DELETE request to `/v2/firewalls/$FIREWALL_ID/tags`. In the body of the request, there should be a `tags` attribute containing a list of tag names. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/firewalls/{firewall_id}/tags - Destructive
Remove Rules from a Firewall
To remove access rules from a firewall, send a DELETE request to `/v2/firewalls/$FIREWALL_ID/rules`. The body of the request may include an `inbound_rules` and/or `outbound_rules` attribute containing an array of rules to be removed. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/firewalls/{firewall_id}/rules
Floating IPs
- Read
List All Floating IPs
To list all of the floating IPs available on your account, send a GET request to `/v2/floating_ips`.
GET /v2/floating_ips - Read
Retrieve an Existing Floating IP
To show information about a floating IP, send a GET request to `/v2/floating_ips/$FLOATING_IP_ADDR`.
GET /v2/floating_ips/{floating_ip} - Write
Create a New Floating IP
On creation, a floating IP must be either assigned to a Droplet or reserved to a region. * To create a new floating IP assigned to a Droplet, send a POST request to `/v2/floating_ips` with the `droplet_id` attribute. * To create a new floating IP reserved to a region, send a POST request to `/v2/floating_ips` with the `region` attribute.
POST /v2/floating_ips - Destructive
Delete a Floating IP
To delete a floating IP and remove it from your account, send a DELETE request to `/v2/floating_ips/$FLOATING_IP_ADDR`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/floating_ips/{floating_ip}
Floating IP Actions
- Read
List All Actions for a Floating IP
To retrieve all actions that have been executed on a floating IP, send a GET request to `/v2/floating_ips/$FLOATING_IP/actions`.
GET /v2/floating_ips/{floating_ip}/actions - Read
Retrieve an Existing Floating IP Action
To retrieve the status of a floating IP action, send a GET request to `/v2/floating_ips/$FLOATING_IP/actions/$ACTION_ID`.
GET /v2/floating_ips/{floating_ip}/actions/{action_id} - Write
Initiate a Floating IP Action
To initiate an action on a floating IP send a POST request to `/v2/floating_ips/$FLOATING_IP/actions`. In the JSON body to the request, set the `type` attribute to on of the supported action types: | Action | Details |------------|-------- | `assign` | Assigns a floating IP to a Droplet | `unassign` | Unassign a floating IP from a Droplet
POST /v2/floating_ips/{floating_ip}/actions
Functions
- Read
List Namespaces
Returns a list of namespaces associated with the current user. To get all namespaces, send a GET request to `/v2/functions/namespaces`.
GET /v2/functions/namespaces - Read
Get Namespace
Gets the namespace details for the given namespace UUID. To get namespace details, send a GET request to `/v2/functions/namespaces/$NAMESPACE_ID` with no parameters.
GET /v2/functions/namespaces/{namespace_id} - Read
List Triggers
Returns a list of triggers associated with the current user and namespace. To get all triggers, send a GET request to `/v2/functions/namespaces/$NAMESPACE_ID/triggers`.
GET /v2/functions/namespaces/{namespace_id}/triggers - Read
Get Trigger
Gets the trigger details. To get the trigger details, send a GET request to `/v2/functions/namespaces/$NAMESPACE_ID/triggers/$TRIGGER_NAME`.
GET /v2/functions/namespaces/{namespace_id}/triggers/{trigger_name} - Read
List Namespace Access Keys
Lists all access keys for a serverless functions namespace. To list access keys, send a GET request to `/v2/functions/namespaces/{namespace_id}/keys`.
GET /v2/functions/namespaces/{namespace_id}/keys - Write
Create Namespace
Creates a new serverless functions namespace in the desired region and associates it with the provided label. A namespace is a collection of functions and their associated packages, triggers, and project specifications. To create a namespace, send a POST request to `/v2/functions/namespaces` with the `region` and `label` properties.
POST /v2/functions/namespaces - Write
Create Trigger
Creates a new trigger for a given function in a namespace. To create a trigger, send a POST request to `/v2/functions/namespaces/$NAMESPACE_ID/triggers` with the `name`, `function`, `type`, `is_enabled` and `scheduled_details` properties.
POST /v2/functions/namespaces/{namespace_id}/triggers - Write
Update Trigger
Updates the details of the given trigger. To update a trigger, send a PUT request to `/v2/functions/namespaces/$NAMESPACE_ID/triggers/$TRIGGER_NAME` with new values for the `is_enabled ` or `scheduled_details` properties.
PUT /v2/functions/namespaces/{namespace_id}/triggers/{trigger_name} - Write
Create a Namespace Access Key
Creates a new access key for a serverless functions namespace. The access key can be used to authenticate requests to the namespace's functions. The secret key is only returned once upon creation. To create an access key, send a POST request to `/v2/functions/namespaces/{namespace_id}/keys`.
POST /v2/functions/namespaces/{namespace_id}/keys - Write
Update a Namespace Access Key
Updates the name of an access key for a serverless functions namespace. To update an access key, send a PUT request to `/v2/functions/namespaces/{namespace_id}/keys/{key_id}`.
PUT /v2/functions/namespaces/{namespace_id}/keys/{key_id} - Destructive
Delete Namespace
Deletes the given namespace. When a namespace is deleted all assets, in the namespace are deleted, this includes packages, functions and triggers. Deleting a namespace is a destructive operation and assets in the namespace are not recoverable after deletion. Some metadata is retained, such as activations, or soft deleted for reporting purposes. To delete namespace, send a DELETE request to `/v2/functions/namespaces/$NAMESPACE_ID`. A successful deletion returns a 204 response.
DELETE /v2/functions/namespaces/{namespace_id} - Destructive
Delete Trigger
Deletes the given trigger. To delete trigger, send a DELETE request to `/v2/functions/namespaces/$NAMESPACE_ID/triggers/$TRIGGER_NAME`. A successful deletion returns a 204 response.
DELETE /v2/functions/namespaces/{namespace_id}/triggers/{trigger_name} - Destructive
Delete a Namespace Access Key
Deletes an access key for a serverless functions namespace. To delete an access key, send a DELETE request to `/v2/functions/namespaces/{namespace_id}/keys/{key_id}`.
DELETE /v2/functions/namespaces/{namespace_id}/keys/{key_id}
Images
- Read
List All Images
To list all of the images available on your account, send a GET request to /v2/images. ## Filtering Results ----- It's possible to request filtered results by including certain query parameters. **Image Type** Either 1-Click Application or OS Distribution images can be filtered by using the `type` query parameter. > Important: The `type` query parameter does not directly relate to the `type` attribute. To retrieve only ***distribution*** images, include the `type` query parameter set to distribution, `/v2/images?type=distribution`. To retrieve only ***application*** images, include the `type` query parameter set to application, `/v2/images?type=application`. **User Images** To retrieve only the private images of a user, include the `private` query parameter set to true, `/v2/images?private=true`. **Tags** To list all images assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your GET request. For example, `/v2/images?tag_name=$TAG_NAME`.
GET /v2/images - Read
Retrieve an Existing Image
To retrieve information about an image, send a `GET` request to `/v2/images/$IDENTIFIER`.
GET /v2/images/{image_id} - Write
Create a Custom Image
To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.
POST /v2/images - Write
Update an Image
To update an image, send a `PUT` request to `/v2/images/$IMAGE_ID`. Set the `name` attribute to the new value you would like to use. For custom images, the `description` and `distribution` attributes may also be updated.
PUT /v2/images/{image_id} - Write
Initiate an Image Account Transfer
To initiate an account transfer for an image, send a POST request to `/v2/images/$IMAGE_ID/account_transfer`. Only snapshot images may be transferred by this endpoint to another account. An image account transfer always has exactly one recipient, specified in the request body. The recipient can be one of the following: * A DigitalOcean account, denoted by `recipient_email` in the request body. The recipient will receive an email with instructions to accept the transfer. Once the recipient accepts the transfer, the image will be moved to their account. * A DigitalOcean team, denoted by `recipient_uuid` in the request body. If the user has sufficient permissions in the recipient team, the transfer will be automatically accepted and the image will be moved to the recipient team's account. Otherwise, the transfer will be pending until a user with sufficient permissions in the recipient team accepts the transfer.
POST /v2/images/{image_id}/account_transfer - Write
Accept an Image Account Transfer
To accept an account transfer for an image, send a POST request to `/v2/images/$IMAGE_ID/account_transfer/accept`.
POST /v2/images/{image_id}/account_transfer/accept - Write
Cancel an Image Account Transfer
To cancel an account transfer for an image, send a POST request to `/v2/images/$IMAGE_ID/account_transfer/cancel`. Only the sender of an image account transfer can cancel the transfer. If the transfer is canceled, the image will remain in the sender's account and will not be transferred to the recipient.
POST /v2/images/{image_id}/account_transfer/cancel - Write
Decline an Image Account Transfer
To decline an account transfer for an image, send a POST request to `/v2/images/$IMAGE_ID/account_transfer/decline`. Only the recipient of an image account transfer can decline the transfer. If the transfer is declined, the image will remain in the sender's account and will not be transferred to the recipient.
POST /v2/images/{image_id}/account_transfer/decline - Destructive
Delete an Image
To delete a snapshot or custom image, send a `DELETE` request to `/v2/images/$IMAGE_ID`.
DELETE /v2/images/{image_id}
Image Actions
- Read
List All Actions for an Image
To retrieve all actions that have been executed on an image, send a GET request to `/v2/images/$IMAGE_ID/actions`.
GET /v2/images/{image_id}/actions - Read
Retrieve an Existing Action
To retrieve the status of an image action, send a GET request to `/v2/images/$IMAGE_ID/actions/$IMAGE_ACTION_ID`.
GET /v2/images/{image_id}/actions/{action_id} - Write
Initiate an Image Action
The following actions are available on an Image. ## Convert an Image to a Snapshot To convert an image, for example, a backup to a snapshot, send a POST request to `/v2/images/$IMAGE_ID/actions`. Set the `type` attribute to `convert`. ## Transfer an Image To transfer an image to another region, send a POST request to `/v2/images/$IMAGE_ID/actions`. Set the `type` attribute to `transfer` and set `region` attribute to the slug identifier of the region you wish to transfer to.
POST /v2/images/{image_id}/actions
Insights
- Read
List Alert Instances
To list alert instances for your account, send a GET request to `/v2/insights/alert-instances`. Alert instances are read-only records of alert rule firings against your resources. Results can optionally be filtered by `status`, `rule_id`, or `resource_urn`. Results are ordered by `triggered_at` descending (newest first). Because the list is append-only and continuously growing, offset-based pagination is best-effort: newly triggered instances may shift older rows onto subsequent pages between fetches. For stable pagination, filter by `rule_id` or a fixed time window on the client side.
GET /v2/insights/alert-instances - Read
Retrieve an Alert Instance
To retrieve a single alert instance, send a GET request to `/v2/insights/alert-instances/{id}`.
GET /v2/insights/alert-instances/{id} - Read
List Alert Rules
To list alert rules for your account, send a GET request to `/v2/insights/alert-rules`. Results are paginated with `page` and `per_page` (default `20`, maximum `200`). Optionally filter by `resource_urn`.
GET /v2/insights/alert-rules - Read
Retrieve an Alert Rule
To retrieve an alert rule, send a GET request to `/v2/insights/alert-rules/{id}`.
GET /v2/insights/alert-rules/{id} - Read
List Notification Channels
To list all notification channels for your account, send a GET request to `/v2/insights/notification-channels`. Results are paginated with `page` and `per_page` (default `20`, maximum `200`).
GET /v2/insights/notification-channels - Read
Retrieve a Notification Channel
To retrieve a notification channel, send a GET request to `/v2/insights/notification-channels/{id}`. Secret credentials are never returned. When a secret is configured, the response includes an optional `*_status` object (for example `webhook_url_status`) with `configured: true`.
GET /v2/insights/notification-channels/{id} - Read
Execute an instant PromQL query
To evaluate a PromQL expression at a single point in time, send a GET request to `/v2/insights/query/{region}/prom/api/v1/query`.
GET /v2/insights/query/{region}/prom/api/v1/query - Read
Execute a range PromQL query
To evaluate a PromQL expression over a time range, send a GET request to `/v2/insights/query/{region}/prom/api/v1/query_range`.
GET /v2/insights/query/{region}/prom/api/v1/query_range - Read
List label names
To list label names, send a GET request to `/v2/insights/query/{region}/prom/api/v1/labels`.
GET /v2/insights/query/{region}/prom/api/v1/labels - Read
List label names
To list label names, send a POST request to `/v2/insights/query/{region}/prom/api/v1/labels` with `application/x-www-form-urlencoded` parameters.
POST /v2/insights/query/{region}/prom/api/v1/labels - Read
List values for a label
To list values for a label name, send a GET request to `/v2/insights/query/{region}/prom/api/v1/label/{name}/values`.
GET /v2/insights/query/{region}/prom/api/v1/label/{name}/values - Read
Find series by label selectors
To find series matching one or more selectors, send a GET request to `/v2/insights/query/{region}/prom/api/v1/series`.
GET /v2/insights/query/{region}/prom/api/v1/series - Read
Search logs
To search log records in a region, send a POST request to `/v2/insights/query/{region}/logs/search` with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. `pagination.limit` defaults to 100 and is clamped to 1000. Cursor pagination requires ordering by `timestamp` alone; other sort orders return `has_more: false` and cannot be paged.
POST /v2/insights/query/{region}/logs/search - Read
Search traces
To search traces in a region, send a POST request to `/v2/insights/query/{region}/traces/search` with a JSON body describing the time range, optional filter, ordering, and pagination. Each result is one trace, aggregated from all of its spans in the time range. A trace is included when at least one of its spans matches `filter`. The time range must not exceed 7 days (`168h`). `pagination.limit` defaults to 100 (also used when `limit` is `0`) and must be between 0 and 1000. Results are ordered by `started` descending unless `order_by` is set. JSON field names use snake_case (`time_range`, `order_by`, `has_more`, `trace_id`). Unknown request properties, invalid filters, and out-of-range values are rejected with `400`. Each request searches a single region; there is no multi-region search. Supported regions are `ams2`, `ams3`, `atl1`, `blr1`, `fra1`, `lon1`, `mem1`, `nyc1`, `nyc2`, `nyc3`, `ric1`, `sfo1`, `sfo2`, `sfo3`, `sgp1`, `syd1`, and `tor1`. Requests time out after 60 seconds. Errors produced by the traces service (`400`) have a `text/plain` body containing a short message. Authentication and authorization errors (`401`, `403`), rate limiting (`429`), and routing errors (for example, `404` for an unknown region) come from the API gateway and use the standard JSON error object with `id` and `message`. `403` is also returned for accounts that are in a trial or not in good standing. If the regional traces backend cannot be reached, the response is `502` with a `text/plain` body.
POST /v2/insights/query/{region}/traces/search - Read
Retrieve an existing trace
To retrieve a single trace and all of its spans, send a GET request to `/v2/insights/query/{region}/traces/{trace_id}`. Only spans that started within the lookup window are returned. The window defaults to the last 7 days and can be narrowed with the `from` and `to` query parameters; it must not exceed 7 days, and `from` must not be after `to`. Spans are returned ordered by start time. At most 10,000 spans are returned; `truncated` is `true` when the trace has more. A trace ID with no spans in the window returns `404`, as do malformed or uppercase trace IDs. A trace is only resolvable in the region that ingested it; querying another region also returns `404`. Supported regions are `ams2`, `ams3`, `atl1`, `blr1`, `fra1`, `lon1`, `mem1`, `nyc1`, `nyc2`, `nyc3`, `ric1`, `sfo1`, `sfo2`, `sfo3`, `sgp1`, `syd1`, and `tor1`. Requests time out after 60 seconds. Errors produced by the traces service (`400`, and `404` when no trace is found) have a `text/plain` body containing a short message. Authentication and authorization errors (`401`, `403`), rate limiting (`429`), and routing errors (for example, `404` for an unknown region) come from the API gateway and use the standard JSON error object with `id` and `message`. `403` is also returned for accounts that are in a trial or not in good standing. If the regional traces backend cannot be reached, the response is `502` with a `text/plain` body. JSON field names use snake_case (`trace_id`, `span_id`, `start_time`, `end_time`, `duration_ns`, `service_name`, `status_code`, `parent_span_id`).
GET /v2/insights/query/{region}/traces/{trace_id} - Read
Search spans
To search spans in a region, send a POST request to `/v2/insights/query/{region}/spans/search` with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. `pagination.limit` defaults to 100 and must be between 1 and 1000. Results are ordered by `start_time` descending by default. Cursor-based pagination is not yet supported; `pagination.has_more` indicates whether additional spans matched beyond the returned page.
POST /v2/insights/query/{region}/spans/search - Read
List Resource Signal Enablement
To list the resources in your account that have telemetry signal enablement recorded, along with the current state of their metrics, logs, and traces signals, send a GET request to `/v2/insights/resources`. Results are paginated with `pagination.page` and `pagination.per_page` (default `20`, maximum `200`) and can be sorted with `pagination.sort` and `pagination.sort_direction`. Optionally filter by `filter.product_types` and `filter.regions`. A signal is omitted from a resource when no explicit enablement has ever been recorded for it.
GET /v2/insights/resources - Read
Retrieve Resource Signal Enablement
To retrieve the current metrics, logs, and traces signal enablement for a single resource, send a GET request to `/v2/insights/resources/{resource_urn}`. A `404` is returned when no signal enablement has been recorded for the resource.
GET /v2/insights/resources/{resource_urn} - Write
Create an Alert Rule
To create an alert rule, send a POST request to `/v2/insights/alert-rules` with a `spec` containing `name`, `query`, `thresholds`, and at least one `notification_channels` binding. `status` defaults to `ALERT_RULE_STATUS_ACTIVE` when omitted. `re_alert_duration` defaults to `RE_ALERT_DURATION_4H` when omitted. `query.metric` must be a dotted OpenTelemetry name such as `do.droplets.cpu_utilization`. Underscored Prometheus-style names are rejected with `422 Unprocessable Entity`.
POST /v2/insights/alert-rules - Write
Update an Alert Rule
This PUT endpoint uses merge semantics. To update an alert rule, send a request to `/v2/insights/alert-rules/{id}` with a full `spec`. Omit `notification_channels` to keep existing bindings. Omit `status` or `re_alert_duration` to keep those existing values.
PUT /v2/insights/alert-rules/{id} - Write
Create a Notification Channel
To create a notification channel, send a POST request to `/v2/insights/notification-channels` with a `name` and exactly one of `email`, `slack`, or `webhook`. Email recipients must be verified team member addresses. Webhook URLs must use HTTPS. Secret fields (`slack.webhook_url`, webhook credentials) are write-only. Subsequent reads never return secret values; they include optional `*_status` objects when a secret is configured.
POST /v2/insights/notification-channels - Write
Update a Notification Channel
To update a notification channel, send a PUT request to `/v2/insights/notification-channels/{id}` with a `name` and exactly one of `email`, `slack`, or `webhook`. Sending a secret field rotates it; omitting the secret field keeps the existing value. Responses never return secret values; they include optional `*_status` objects when a secret is configured.
PUT /v2/insights/notification-channels/{id} - Write
Execute an instant PromQL query
To evaluate a PromQL expression at a single point in time, send a POST request to `/v2/insights/query/{region}/prom/api/v1/query` with `application/x-www-form-urlencoded` parameters.
POST /v2/insights/query/{region}/prom/api/v1/query - Write
Execute a range PromQL query
To evaluate a PromQL expression over a time range, send a POST request to `/v2/insights/query/{region}/prom/api/v1/query_range` with `application/x-www-form-urlencoded` parameters.
POST /v2/insights/query/{region}/prom/api/v1/query_range - Write
Find series by label selectors
To find series matching one or more selectors, send a POST request to `/v2/insights/query/{region}/prom/api/v1/series` with `application/x-www-form-urlencoded` parameters.
POST /v2/insights/query/{region}/prom/api/v1/series - Write
Update Resource Signal Enablement
To enable or disable telemetry signals for a resource, send a PUT request to `/v2/insights/resources/{resource_urn}/signals`. This endpoint uses merge semantics. Set `metrics`, `logs`, or `traces` to `true` or `false` to change that signal; omit a signal to leave it unchanged. At least one signal must be set. `region` is only used when the resource has no existing enablement. On later updates, omit it or send the stored value; changing the region is rejected with a `400`. Requires both the `insights:update` and `insights:create` scopes.
PUT /v2/insights/resources/{resource_urn}/signals - Destructive
Delete an Alert Rule
To delete an alert rule, send a DELETE request to `/v2/insights/alert-rules/{id}`.
DELETE /v2/insights/alert-rules/{id} - Destructive
Delete a Notification Channel
To delete a notification channel, send a DELETE request to `/v2/insights/notification-channels/{id}`. Deleting a channel that is still referenced by one or more alert rules returns `409 Conflict`.
DELETE /v2/insights/notification-channels/{id}
Signals
- Read
List All Consent Records
To list all signals consent records for your team, send a GET request to `/v1/consent`. Each record indicates whether signals collection is enabled for a source: per-environment records (`source: agent`) for Harness Runtime, and the team-level record (`source: inference`) for Serverless Inference chat completions. Pass `?source=agent` or `?source=inference` to return only that source's records. When filtered, the response also echoes the `source`.
GET /v1/consent - Read
Retrieve Consent for an Environment
To retrieve the consent record for a specific environment, send a GET request to `/v1/consent/{environment_id}`. The response includes an `enabled` field indicating whether signals collection is on for this environment. This endpoint only serves per-environment (`source: agent`) records. Team-level inference consent is read from `GET /v1/consent?source=inference`.
GET /v1/consent/{environment_id} - Read
List Sessions for an Environment
To list signals sessions for a specific environment, send a GET request to `/v1/signals/agents/{environment_id}/sessions`. Results are paginated using cursor-based pagination with `limit` and `after` parameters.
GET /v1/signals/agents/{environment_id}/sessions - Read
List Dialogues for a Session
To list the dialogue turns within a specific session, send a GET request to `/v1/signals/sessions/{session_id}/dialogues`. Each dialogue represents a single turn of conversation between a user and the environment, along with any signals detected. Results are paginated using cursor-based pagination.
GET /v1/signals/sessions/{session_id}/dialogues - Read
List Export Jobs
To list signals export jobs for your team, send a GET request to `/v1/signals/exports`. Results are paginated using cursor-based pagination with `limit` and `after` parameters.
GET /v1/signals/exports - Read
Get Export Options
To retrieve the available filter options for creating an export, send a GET request to `/v1/signals/exports/options`. The response lists valid signal types that can be used in the `signal_type` filter when creating an export.
GET /v1/signals/exports/options - Read
Retrieve an Export Job
To retrieve the status and details of a signals export job, send a GET request to `/v1/signals/exports/{export_id}`.
GET /v1/signals/exports/{export_id} - Read
Get Export Download URL
To retrieve a pre-signed download URL for a completed export, send a GET request to `/v1/signals/exports/{export_id}/download`. The export must have a `complete` status. The URL is temporary and will expire.
GET /v1/signals/exports/{export_id}/download - Read
List Data Deletion Jobs
To list signals data deletion jobs for your team, newest first, send a GET request to `/v1/signals/deletions`. Results are paginated using cursor-based pagination with `limit` and `after` parameters.
GET /v1/signals/deletions - Read
Retrieve a Data Deletion Job
To retrieve the status of a signals data deletion job, send a GET request to `/v1/signals/deletions/{deletion_id}`.
GET /v1/signals/deletions/{deletion_id} - Write
Update Team-Level Consent
To enable or disable signals collection for a source that is consented at the team level, send a PUT request to `/v1/consent?source=inference` with an `enabled` boolean in the request body. Currently the only team-level source is `inference`, which covers Serverless Inference chat completions made by your team. To revoke consent, send the same request with `enabled` set to `false`. The `source` query parameter is required. Per-environment consent for Harness Runtime environments is managed with `PUT /v1/consent/{environment_id}` instead.
PUT /v1/consent - Write
Update Consent for an Environment
To enable or disable signals collection for a specific environment, send a PUT request to `/v1/consent/{environment_id}` with an `enabled` boolean in the request body. This endpoint only manages per-environment (`source: agent`) consent. To manage team-level consent for Serverless Inference, use `PUT /v1/consent?source=inference` instead.
PUT /v1/consent/{environment_id} - Write
Create an Export Job
To create a new signals data export, send a POST request to `/v1/signals/exports`. To export one Harness Runtime environment, include its `environment_id` (`type` defaults to `agent`). Deprecated `agent_id` is still accepted. To export the team's Serverless Inference Signals conversations, set `type` to `inference` and omit `environment_id` and `agent_id`. You may optionally filter the export by `signal_type`, `session_ids`, `start_time`, and `end_time`. Use the export options endpoint to discover available signal types. The export job runs asynchronously. Poll the get export endpoint to check its status. When complete, use the download endpoint to retrieve a pre-signed URL.
POST /v1/signals/exports - Destructive
Create a Data Deletion Job
To permanently delete Signals conversation data, send a POST request to `/v1/signals/deletions`. Deletion cannot be undone. Two deletion types are supported: - `agent` — deletes Signals conversations for one Harness Runtime environment and turns off collection for that environment. Requires `environment_id` (the environment's Environment Config ID). Deprecated `agent_id` is still accepted; both set and equal is accepted, both set and different returns 400. On create, matching conversations are hidden from Signals reads immediately. Wait until the job is `complete` before enabling Signals for the environment again. - `inference` — deletes Serverless Inference Signals conversations for your whole team (team-wide; not limited to one endpoint or model) that were collected at or before the deletion request, and turns off team inference collection (`source=inference`). Do not send `environment_id` or `agent_id`. On create, matching conversations are hidden from Signals reads immediately. The job runs asynchronously; poll the get endpoint until `status` is `complete` or `failed`. DigitalOcean may retry transient processing errors while a job is still active. If a job ends as `failed`, matching conversations stay hidden and collection stays off; send the same create request again to retry. Earlier export files are not deleted and remain available until they expire. Note: Deletion removes Signals conversation data for the requested scope. Aggregated Insights or metrics charts may still show historical summary datapoints after deletion. Those summaries are not the same as recoverable conversation content. The endpoint is idempotent: if a queued or running job already exists for the same target, it is returned with `200 OK`. A new job returns `202 Accepted`. Each team can have a limited number of active jobs; requests beyond that limit return `429 Too Many Requests`.
POST /v1/signals/deletions
Kubernetes
- Read
List All Kubernetes Clusters
To list all of the Kubernetes clusters on your account, send a GET request to `/v2/kubernetes/clusters`.
GET /v2/kubernetes/clusters - Read
Retrieve an Existing Kubernetes Cluster
To show information about an existing Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID`.
GET /v2/kubernetes/clusters/{cluster_id} - Read
List Associated Resources for Cluster Deletion
To list the associated billable resources that can be destroyed along with a cluster, send a GET request to the `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/destroy_with_associated_resources` endpoint.
GET /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources - Read
Retrieve the kubeconfig for a Kubernetes Cluster
This endpoint returns a kubeconfig file in YAML format. It can be used to connect to and administer the cluster using the Kubernetes command line tool, `kubectl`, or other programs supporting kubeconfig files (e.g., client libraries). The resulting kubeconfig file uses token-based authentication for clusters supporting it, and certificate-based authentication otherwise. For a list of supported versions and more information, see "[How to Connect to a DigitalOcean Kubernetes Cluster](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/)". To retrieve a kubeconfig file for use with a Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig`. Clusters supporting token-based authentication may define an expiration by passing a duration in seconds as a query parameter to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig?expiry_seconds=$DURATION_IN_SECONDS`. If not set or 0, then the token will have a 7 day expiry. The query parameter has no impact for other kubeconfig types. Using an `sso` kubeconfig type requires `doctl` to be installed to handle the client side of the OAuth2 flow. Kubernetes Roles granted to a user are derived from that user's DigitalOcean role. Predefined roles (Owner, Member, Modifier etc.) have an automatic mapping to Kubernetes roles. Custom roles are not automatically mapped to any Kubernetes roles, and require [additional configuration](https://docs.digitalocean.com/products/kubernetes/how-to/set-up-custom-rolebindings/) by a cluster administrator.
GET /v2/kubernetes/clusters/{cluster_id}/kubeconfig - Read
Retrieve Credentials for a Kubernetes Cluster
This endpoint returns a JSON object . It can be used to programmatically construct Kubernetes clients which cannot parse kubeconfig files. The resulting JSON object contains token-based authentication for clusters supporting it, and certificate-based authentication otherwise. For a list of supported versions and more information, see "[How to Connect to a DigitalOcean Kubernetes Cluster](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/)". To retrieve credentials for accessing a Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/credentials`. Clusters supporting token-based authentication may define an expiration by passing a duration in seconds as a query parameter to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/credentials?expiry_seconds=$DURATION_IN_SECONDS`. If not set or 0, then the token will have a 7 day expiry. The query parameter has no impact in certificate-based authentication.
GET /v2/kubernetes/clusters/{cluster_id}/credentials - Read
Retrieve Available Upgrades for an Existing Kubernetes Cluster
To determine whether a cluster can be upgraded, and the versions to which it can be upgraded, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/upgrades`.
GET /v2/kubernetes/clusters/{cluster_id}/upgrades - Read
List All Node Pools in a Kubernetes Clusters
To list all of the node pools in a Kubernetes clusters, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools`.
GET /v2/kubernetes/clusters/{cluster_id}/node_pools - Read
Retrieve a Node Pool for a Kubernetes Cluster
To show information about a specific node pool in a Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools/$NODE_POOL_ID`.
GET /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id} - Read
Retrieve User Information for a Kubernetes Cluster
To show information the user associated with a Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/user`.
GET /v2/kubernetes/clusters/{cluster_id}/user - Read
List Available Regions, Node Sizes, and Versions of Kubernetes
To list the versions of Kubernetes available for use, the regions that support Kubernetes, and the available node sizes, send a GET request to `/v2/kubernetes/options`.
GET /v2/kubernetes/options - Read
Fetch Clusterlint Diagnostics for a Kubernetes Cluster
To request clusterlint diagnostics for your cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/clusterlint`. If the `run_id` query parameter is provided, then the diagnostics for the specific run is fetched. By default, the latest results are shown. To find out how to address clusterlint feedback, please refer to [the clusterlint check documentation](https://github.com/digitalocean/clusterlint/blob/master/checks.md).
GET /v2/kubernetes/clusters/{cluster_id}/clusterlint - Read
Fetch Status Messages for a Kubernetes Cluster
To retrieve status messages for a Kubernetes cluster, send a GET request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/status_messages`. Status messages inform users of any issues that come up during the cluster lifecycle.
GET /v2/kubernetes/clusters/{cluster_id}/status_messages - Write
Create a New Kubernetes Cluster
To create a new Kubernetes cluster, send a POST request to `/v2/kubernetes/clusters`. The request must contain at least one node pool with at least one worker. The request may contain a maintenance window policy describing a time period when disruptive maintenance tasks may be carried out. Omitting the policy implies that a window will be chosen automatically. See [here](https://docs.digitalocean.com/products/kubernetes/how-to/upgrade-cluster/) for details.
POST /v2/kubernetes/clusters - Write
Update a Kubernetes Cluster
To update a Kubernetes cluster, send a PUT request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID` and specify one or more of the attributes below.
PUT /v2/kubernetes/clusters/{cluster_id} - Write
Upgrade a Kubernetes Cluster
To immediately upgrade a Kubernetes cluster to a newer patch release of Kubernetes, send a POST request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/upgrade`. The body of the request must specify a version attribute. Available upgrade versions for a cluster can be fetched from `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/upgrades`.
POST /v2/kubernetes/clusters/{cluster_id}/upgrade - Write
Add a Node Pool to a Kubernetes Cluster
To add an additional node pool to a Kubernetes clusters, send a POST request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools` with the following attributes.
POST /v2/kubernetes/clusters/{cluster_id}/node_pools - Write
Update a Node Pool in a Kubernetes Cluster
To update the name of a node pool, edit the tags applied to it, or adjust its number of nodes, send a PUT request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools/$NODE_POOL_ID` with the following attributes.
PUT /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id} - Write
Recycle a Kubernetes Node Pool (deprecated)
The endpoint has been deprecated. Please use the DELETE `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools/$NODE_POOL_ID/nodes/$NODE_ID` method instead.
POST /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id}/recycle - Write
Run Clusterlint Checks on a Kubernetes Cluster
Clusterlint helps operators conform to Kubernetes best practices around resources, security and reliability to avoid common problems while operating or upgrading the clusters. To request a clusterlint run on your cluster, send a POST request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/clusterlint`. This will run all checks present in the `doks` group by default, if a request body is not specified. Optionally specify the below attributes. For information about the available checks, please refer to [the clusterlint check documentation](https://github.com/digitalocean/clusterlint/blob/master/checks.md).
POST /v2/kubernetes/clusters/{cluster_id}/clusterlint - Write
Add Container Registry to Kubernetes Clusters
To integrate the container registry with Kubernetes clusters, send a POST request to `/v2/kubernetes/registry`.
POST /v2/kubernetes/registry - Write
Add Container Registries to Kubernetes Clusters
To integrate the container registries with Kubernetes clusters, send a POST request to `/v2/kubernetes/registries`.
POST /v2/kubernetes/registries - Destructive
Delete a Kubernetes Cluster
To delete a Kubernetes cluster and all services deployed to it, send a DELETE request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID`. A 204 status code with no body will be returned in response to a successful request.
DELETE /v2/kubernetes/clusters/{cluster_id} - Destructive
Selectively Delete a Cluster and its Associated Resources
To delete a Kubernetes cluster along with a subset of its associated resources, send a DELETE request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/destroy_with_associated_resources/selective`. The JSON body of the request should include `load_balancers`, `volumes`, or `volume_snapshots` keys each set to an array of IDs for the associated resources to be destroyed. The IDs can be found by querying the cluster's associated resources endpoint. Any associated resource not included in the request will remain and continue to accrue changes on your account.
DELETE /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources/selective - Destructive
Delete a Cluster and All of its Associated Resources (Dangerous)
To delete a Kubernetes cluster with all of its associated resources, send a DELETE request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/destroy_with_associated_resources/dangerous`. A 204 status code with no body will be returned in response to a successful request.
DELETE /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources/dangerous - Destructive
Delete a Node Pool in a Kubernetes Cluster
To delete a node pool, send a DELETE request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools/$NODE_POOL_ID`. A 204 status code with no body will be returned in response to a successful request. Nodes in the pool will subsequently be drained and deleted.
DELETE /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id} - Destructive
Delete a Node in a Kubernetes Cluster
To delete a single node in a pool, send a DELETE request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools/$NODE_POOL_ID/nodes/$NODE_ID`. Appending the `skip_drain=1` query parameter to the request causes node draining to be skipped. Omitting the query parameter or setting its value to `0` carries out draining prior to deletion. Appending the `replace=1` query parameter to the request causes the node to be replaced by a new one after deletion. Omitting the query parameter or setting its value to `0` deletes without replacement.
DELETE /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id}/nodes/{node_id} - Destructive
Remove Container Registry from Kubernetes Clusters
To remove the container registry from Kubernetes clusters, send a DELETE request to `/v2/kubernetes/registry`.
DELETE /v2/kubernetes/registry - Destructive
Remove Container Registries from Kubernetes Clusters
To remove the container registries from Kubernetes clusters, send a DELETE request to `/v2/kubernetes/registries`.
DELETE /v2/kubernetes/registries
Load Balancers
- Read
List All Load Balancers
To list all of the load balancer instances on your account, send a GET request to `/v2/load_balancers`.
GET /v2/load_balancers - Read
Retrieve an Existing Load Balancer
To show information about a load balancer instance, send a GET request to `/v2/load_balancers/$LOAD_BALANCER_ID`.
GET /v2/load_balancers/{lb_id} - Write
Create a New Load Balancer
To create a new load balancer instance, send a POST request to `/v2/load_balancers`. You can specify the Droplets that will sit behind the load balancer using one of two methods: * Set `droplet_ids` to a list of specific Droplet IDs. * Set `tag` to the name of a tag. All Droplets with this tag applied will be assigned to the load balancer. Additional Droplets will be automatically assigned as they are tagged. These methods are mutually exclusive.
POST /v2/load_balancers - Write
Add Droplets to a Load Balancer
To assign a Droplet to a load balancer instance, send a POST request to `/v2/load_balancers/$LOAD_BALANCER_ID/droplets`. In the body of the request, there should be a `droplet_ids` attribute containing a list of Droplet IDs. Individual Droplets can not be added to a load balancer configured with a Droplet tag. Attempting to do so will result in a "422 Unprocessable Entity" response from the API. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
POST /v2/load_balancers/{lb_id}/droplets - Write
Add Forwarding Rules to a Load Balancer
To add an additional forwarding rule to a load balancer instance, send a POST request to `/v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules`. In the body of the request, there should be a `forwarding_rules` attribute containing an array of rules to be added. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
POST /v2/load_balancers/{lb_id}/forwarding_rules - Destructive
Update a Load Balancer
To update a load balancer's settings, send a PUT request to `/v2/load_balancers/$LOAD_BALANCER_ID`. The request should contain a full representation of the load balancer including existing attributes. It may contain _one of_ the `droplets_ids` or `tag` attributes as they are mutually exclusive. **Note that any attribute that is not provided will be reset to its default value.**
PUT /v2/load_balancers/{lb_id} - Destructive
Delete a Load Balancer
To delete a load balancer instance, disassociating any Droplets assigned to it and removing it from your account, send a DELETE request to `/v2/load_balancers/$LOAD_BALANCER_ID`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/load_balancers/{lb_id} - Destructive
Delete a Global Load Balancer CDN Cache
To delete a Global load balancer CDN cache, send a DELETE request to `/v2/load_balancers/$LOAD_BALANCER_ID/cache`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/load_balancers/{lb_id}/cache - Destructive
Remove Droplets from a Load Balancer
To remove a Droplet from a load balancer instance, send a DELETE request to `/v2/load_balancers/$LOAD_BALANCER_ID/droplets`. In the body of the request, there should be a `droplet_ids` attribute containing a list of Droplet IDs. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/load_balancers/{lb_id}/droplets - Destructive
Remove Forwarding Rules from a Load Balancer
To remove forwarding rules from a load balancer instance, send a DELETE request to `/v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules`. In the body of the request, there should be a `forwarding_rules` attribute containing an array of rules to be removed. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/load_balancers/{lb_id}/forwarding_rules
MicroVMs [Public Preview]
- Read
List all MicroVMs
To list all of the MicroVMs on your team, send a GET request to `/v2/microvms`. The `region`, `name`, and `tag_name` filters combine with AND.
GET /v2/microvms - Read
List MicroVM options
To list the default region, sizes, prices, account limits, and features available to your team, send a GET request to `/v2/microvms/options`.
GET /v2/microvms/options - Read
List checkpoints
To list your team's checkpoints, newest first, send a GET request to `/v2/microvms/checkpoints`. To list one MicroVM's checkpoints, add the `microvm_id` query parameter.
GET /v2/microvms/checkpoints - Read
Retrieve a checkpoint
To show information about a checkpoint, send a GET request to `/v2/microvms/checkpoints/{checkpoint_id}`.
GET /v2/microvms/checkpoints/{checkpoint_id} - Read
Retrieve a MicroVM
To show information about a MicroVM, send a GET request to `/v2/microvms/{microvm_id}`. The endpoint is in the `urls` entry with `default` set to `true`. Its `hostname` is empty and its `status` is `PENDING` until provisioning finishes.
GET /v2/microvms/{microvm_id} - Read
Open a console in a MicroVM
To open an interactive `/bin/sh` console in a MicroVM's workload container, open a WebSocket connection to `wss://api.digitalocean.com/v2/microvms/{microvm_id}/console`. Send the API token in the `Authorization` header of the handshake. Browsers cannot set this header, so you cannot open the console from browser JavaScript. The image must include `/bin/sh`. A MicroVM can have four consoles open at a time. If the MicroVM is paused and auto-resume is on, opening a console resumes it.
GET /v2/microvms/{microvm_id}/console - Write
Create a MicroVM
To create a MicroVM, send a POST request to `/v2/microvms`. `name` and `source` are required. Set `source.oci_ref` to create the MicroVM from a `linux/amd64` container image, or `source.checkpoint_id` to create it from a checkpoint. With `oci_ref`, `region` and `size` are also required. A MicroVM created from an image is returned with `state` set to `creating`. Poll `GET /v2/microvms/{microvm_id}` until `state` is `running`. A MicroVM created from a checkpoint is usually returned already `running`. All settings are fixed at creation. There is no update endpoint.
POST /v2/microvms - Write
Pause a MicroVM
To pause a MicroVM, send a POST request to `/v2/microvms/{microvm_id}/pause`. Pausing suspends the MicroVM's processes and preserves its memory, files, and processes. A paused MicroVM incurs storage charges only. The request returns when the change completes. Pausing a MicroVM that is already paused succeeds. The request returns HTTP 400 when the MicroVM is `creating`, `terminated`, or `failed`.
POST /v2/microvms/{microvm_id}/pause - Write
Resume a MicroVM
To resume a paused MicroVM, send a POST request to `/v2/microvms/{microvm_id}/resume`. The request returns when the change completes. Resuming a MicroVM that is already running succeeds. The request returns HTTP 400 when the MicroVM is `creating`, `terminated`, or `failed`.
POST /v2/microvms/{microvm_id}/resume - Write
Create a checkpoint of a MicroVM
To create a checkpoint of a running or paused MicroVM, send a POST request to `/v2/microvms/{microvm_id}/checkpoints`. The capture runs in the background and does not change the MicroVM's state. Poll `GET /v2/microvms/checkpoints/{checkpoint_id}` until `status` is `CHECKPOINT_AVAILABLE`.
POST /v2/microvms/{microvm_id}/checkpoints - Destructive
Delete a checkpoint
To delete a checkpoint, send a DELETE request to `/v2/microvms/checkpoints/{checkpoint_id}`. You can no longer create MicroVMs from a deleted checkpoint. The request returns HTTP 400 while the checkpoint is still being captured. A successful request returns a `204 No Content` status code.
DELETE /v2/microvms/checkpoints/{checkpoint_id} - Destructive
Delete a MicroVM
To delete a MicroVM and the data on its disk, send a DELETE request to `/v2/microvms/{microvm_id}`. The MicroVM's checkpoints are not deleted. A successful request returns a `204 No Content` status code.
DELETE /v2/microvms/{microvm_id} - Destructive
Run a command in a MicroVM
To run a command in a MicroVM's workload container, send a POST request to `/v2/microvms/{microvm_id}/exec`. `argv` runs directly, not through a shell, with standard input closed. If the MicroVM is paused and auto-resume is on, the request resumes it and waits until it is running. A command has 60 seconds to finish. Your team can run 32 commands at once and 60 commands per minute. Rejected requests count toward the per-minute limit.
POST /v2/microvms/{microvm_id}/exec
Monitoring
- Read
List Alert Policies
Returns all alert policies that are configured for the given account. To List all alert policies, send a GET request to `/v2/monitoring/alerts`.
GET /v2/monitoring/alerts - Read
Retrieve an Existing Alert Policy
To retrieve a given alert policy, send a GET request to `/v2/monitoring/alerts/{alert_uuid}`
GET /v2/monitoring/alerts/{alert_uuid} - Read
Get Droplet Bandwidth Metrics
To retrieve bandwidth metrics for a given Droplet, send a GET request to `/v2/monitoring/metrics/droplet/bandwidth`. Use the `interface` query parameter to specify if the results should be for the `private` or `public` interface. Use the `direction` query parameter to specify if the results should be for `inbound` or `outbound` traffic. The metrics in the response body are in megabits per second (Mbps).
GET /v2/monitoring/metrics/droplet/bandwidth - Read
Get Droplet CPU Metrics
To retrieve CPU metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/cpu`.
GET /v2/monitoring/metrics/droplet/cpu - Read
Get Droplet Filesystem Free Metrics
To retrieve filesystem free metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/filesystem_free`.
GET /v2/monitoring/metrics/droplet/filesystem_free - Read
Get Droplet Filesystem Size Metrics
To retrieve filesystem size metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/filesystem_size`.
GET /v2/monitoring/metrics/droplet/filesystem_size - Read
Get Droplet Load1 Metrics
To retrieve 1 minute load average metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/load_1`.
GET /v2/monitoring/metrics/droplet/load_1 - Read
Get Droplet Load5 Metrics
To retrieve 5 minute load average metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/load_5`.
GET /v2/monitoring/metrics/droplet/load_5 - Read
Get Droplet Load15 Metrics
To retrieve 15 minute load average metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/load_15`.
GET /v2/monitoring/metrics/droplet/load_15 - Read
Get Droplet Cached Memory Metrics
To retrieve cached memory metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/memory_cached`.
GET /v2/monitoring/metrics/droplet/memory_cached - Read
Get Droplet Free Memory Metrics
To retrieve free memory metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/memory_free`.
GET /v2/monitoring/metrics/droplet/memory_free - Read
Get Droplet Total Memory Metrics
To retrieve total memory metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/memory_total`.
GET /v2/monitoring/metrics/droplet/memory_total - Read
Get Droplet Available Memory Metrics
To retrieve available memory metrics for a given droplet, send a GET request to `/v2/monitoring/metrics/droplet/memory_available`.
GET /v2/monitoring/metrics/droplet/memory_available - Read
Get App Memory Percentage Metrics
To retrieve memory percentage metrics for a given app, send a GET request to `/v2/monitoring/metrics/apps/memory_percentage`.
GET /v2/monitoring/metrics/apps/memory_percentage - Read
Get App CPU Percentage Metrics
To retrieve cpu percentage metrics for a given app, send a GET request to `/v2/monitoring/metrics/apps/cpu_percentage`.
GET /v2/monitoring/metrics/apps/cpu_percentage - Read
Get App Restart Count Metrics
To retrieve restart count metrics for a given app, send a GET request to `/v2/monitoring/metrics/apps/restart_count`.
GET /v2/monitoring/metrics/apps/restart_count - Read
Get Load Balancer Frontend Total Current Active Connections Metrics
To retrieve frontend total current active connections for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_connections_current`.
GET /v2/monitoring/metrics/load_balancer/frontend_connections_current - Read
Get Load Balancer Frontend Max Connections Limit Metrics
To retrieve frontend max connections limit for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_connections_limit`.
GET /v2/monitoring/metrics/load_balancer/frontend_connections_limit - Read
Get Load Balancer Frontend Average Percentage CPU Utilization Metrics
To retrieve frontend average percentage CPU utilization for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_cpu_utilization`.
GET /v2/monitoring/metrics/load_balancer/frontend_cpu_utilization - Read
Get Load Balancer Frontend Firewall Dropped Bytes Metrics
To retrieve firewall dropped bytes for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_bytes`. This is currently only supported for network load balancers.
GET /v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_bytes - Read
Get Load Balancer Frontend Firewall Dropped Packets Metrics
To retrieve firewall dropped packets per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_packets`. This is currently only supported for network load balancers.
GET /v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_packets - Read
Get Load Balancer Frontend HTTP Rate Of Response Code Metrics
To retrieve frontend HTTP rate of response code for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_http_responses`.
GET /v2/monitoring/metrics/load_balancer/frontend_http_responses - Read
Get Load Balancer Frontend HTTP Requests Metrics
To retrieve frontend HTTP requests per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_http_requests_per_second`.
GET /v2/monitoring/metrics/load_balancer/frontend_http_requests_per_second - Read
Get Load Balancer Frontend HTTP Throughput Metrics
To retrieve frontend HTTP throughput in bytes per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_network_throughput_http`.
GET /v2/monitoring/metrics/load_balancer/frontend_network_throughput_http - Read
Get Load Balancer Frontend UDP Throughput Metrics
To retrieve frontend UDP throughput in bytes per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_network_throughput_udp`.
GET /v2/monitoring/metrics/load_balancer/frontend_network_throughput_udp - Read
Get Load Balancer Frontend TCP Throughput Metrics
To retrieve frontend TCP throughput in bytes per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_network_throughput_tcp`.
GET /v2/monitoring/metrics/load_balancer/frontend_network_throughput_tcp - Read
Get Network Load Balancer Frontend TCP Throughput Metrics
To retrieve frontend TCP throughput in bytes per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_nlb_tcp_network_throughput`.
GET /v2/monitoring/metrics/load_balancer/frontend_nlb_tcp_network_throughput - Read
Get Network Load Balancer Frontend UDP Throughput Metrics
To retrieve frontend UDP throughput in bytes per second for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_nlb_udp_network_throughput`.
GET /v2/monitoring/metrics/load_balancer/frontend_nlb_udp_network_throughput - Read
Get Load Balancer Frontend Current TLS Connections Rate Metrics
To retrieve frontend current TLS connections rate for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_tls_connections_current`.
GET /v2/monitoring/metrics/load_balancer/frontend_tls_connections_current - Read
Get Load Balancer Frontend Max TLS Connections Limit Metrics
To retrieve frontend max TLS connections limit for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_tls_connections_limit`.
GET /v2/monitoring/metrics/load_balancer/frontend_tls_connections_limit - Read
Get Load Balancer Frontend Closed TLS Connections For Exceeded Rate Limit Metrics
To retrieve frontend closed TLS connections for exceeded rate limit for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/frontend_tls_connections_exceeding_rate_limit`.
GET /v2/monitoring/metrics/load_balancer/frontend_tls_connections_exceeding_rate_limit - Read
Get Load Balancer Droplets Average HTTP Session Duration Metrics
To retrieve Droplets average HTTP session duration in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_avg`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_avg - Read
Get Load Balancer Droplets 50th Percentile HTTP Session Duration Metrics
To retrieve Droplets 50th percentile HTTP session duration in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_50p`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_50p - Read
Get Load Balancer Droplets 95th Percentile HTTP Session Duration Metrics
To retrieve Droplets 95th percentile HTTP session duration in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_95p`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_95p - Read
Get Load Balancer Droplets Average HTTP Response Time Metrics
To retrieve Droplets average HTTP response time in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_response_time_avg`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_response_time_avg - Read
Get Load Balancer Droplets 50th Percentile HTTP Response Time Metrics
To retrieve Droplets 50th percentile HTTP response time in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_response_time_50p`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_response_time_50p - Read
Get Load Balancer Droplets 95th Percentile HTTP Response Time Metrics
To retrieve Droplets 95th percentile HTTP response time in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_response_time_95p`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_response_time_95p - Read
Get Load Balancer Droplets 99th Percentile HTTP Response Time Metrics
To retrieve Droplets 99th percentile HTTP response time in seconds for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_response_time_99p`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_response_time_99p - Read
Get Load Balancer Droplets Queue Size Metrics
To retrieve Droplets queue size for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_queue_size`.
GET /v2/monitoring/metrics/load_balancer/droplets_queue_size - Read
Get Load Balancer Droplets HTTP Rate Of Response Code Metrics
To retrieve Droplets HTTP rate of response code for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_http_responses`.
GET /v2/monitoring/metrics/load_balancer/droplets_http_responses - Read
Get Load Balancer Droplets Active Connections Metrics
To retrieve Droplets active connections for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_connections`.
GET /v2/monitoring/metrics/load_balancer/droplets_connections - Read
Get Load Balancer Droplets Health Check Status Metrics
To retrieve Droplets health check status for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_health_checks`.
GET /v2/monitoring/metrics/load_balancer/droplets_health_checks - Read
Get Load Balancer Droplets Downtime Status Metrics
To retrieve Droplets downtime status for a given load balancer, send a GET request to `/v2/monitoring/metrics/load_balancer/droplets_downtime`.
GET /v2/monitoring/metrics/load_balancer/droplets_downtime - Read
Get Droplet Autoscale Pool Current Size
To retrieve the current size for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/current_instances`.
GET /v2/monitoring/metrics/droplet_autoscale/current_instances - Read
Get Droplet Autoscale Pool Target Size
To retrieve the target size for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/target_instances`.
GET /v2/monitoring/metrics/droplet_autoscale/target_instances - Read
Get Droplet Autoscale Pool Current Average CPU utilization
To retrieve the current average CPU utilization for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/current_cpu_utilization`.
GET /v2/monitoring/metrics/droplet_autoscale/current_cpu_utilization - Read
Get Droplet Autoscale Pool Target Average CPU utilization
To retrieve the target average CPU utilization for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/target_cpu_utilization`.
GET /v2/monitoring/metrics/droplet_autoscale/target_cpu_utilization - Read
Get Droplet Autoscale Pool Current Average Memory utilization
To retrieve the current average memory utilization for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/current_memory_utilization`.
GET /v2/monitoring/metrics/droplet_autoscale/current_memory_utilization - Read
Get Droplet Autoscale Pool Target Average Memory utilization
To retrieve the target average memory utilization for a given Droplet Autoscale Pool, send a GET request to `/v2/monitoring/metrics/droplet_autoscale/target_memory_utilization`.
GET /v2/monitoring/metrics/droplet_autoscale/target_memory_utilization - Read
Get Database MySQL CPU Usage Metrics
Retrieve CPU usage (percent) for a MySQL cluster. Response is a time series of cluster-level CPU usage. Use **aggregate** to get avg, max, or min over the range.
GET /v2/monitoring/metrics/database/mysql/cpu_usage - Read
Get Database MySQL Load Average Metrics
Retrieve load metrics for a MySQL cluster. Use **metric** for the window: **load1** (1-minute), **load5** (5-minute), or **load15** (15-minute). Use **aggregate** to get either the average (avg) or maximum (max) over that window over the time range.
GET /v2/monitoring/metrics/database/mysql/load - Read
Get Database MySQL Memory Usage Metrics
Retrieve memory usage (percent) for a MySQL cluster. Use **aggregate** (avg, max, or min) over the time range.
GET /v2/monitoring/metrics/database/mysql/memory_usage - Read
Get Database MySQL Disk Usage Metrics
Retrieve disk usage (percent) for a MySQL cluster. Use **aggregate** (avg, max, or min) over the time range.
GET /v2/monitoring/metrics/database/mysql/disk_usage - Read
Get Database MySQL Threads Connected Metrics
Retrieve current threads connected for a MySQL service (gauge).
GET /v2/monitoring/metrics/database/mysql/threads_connected - Read
Get Database MySQL Threads Created Rate Metrics
Retrieve threads created rate for a MySQL service (per second).
GET /v2/monitoring/metrics/database/mysql/threads_created_rate - Read
Get Database MySQL Threads Active Metrics
Retrieve active (running) threads for a MySQL service.
GET /v2/monitoring/metrics/database/mysql/threads_active - Read
Get Database MySQL Index vs Sequential Reads Metrics
Retrieve index vs sequential reads ratio (percent) for a MySQL service — i.e. percentage of reads using an index.
GET /v2/monitoring/metrics/database/mysql/index_vs_sequential_reads - Read
Get Database MySQL Operations Throughput Metrics
Retrieve operations rate (per second) for a MySQL service. Use **metric** to choose select, insert, update, or delete.
GET /v2/monitoring/metrics/database/mysql/op_rates - Read
Get Database MySQL Schema Throughput Metrics
Retrieve table I/O throughput (rows per second) for a schema. Requires **schema** and **metric** (insert, fetch, update, delete).
GET /v2/monitoring/metrics/database/mysql/schema_throughput - Read
Get Database MySQL Schema Latency Metrics
Retrieve table I/O latency (seconds) for a schema. Requires **schema** and **metric** (insert, fetch, update, delete).
GET /v2/monitoring/metrics/database/mysql/schema_latency - Read
List Logging Destinations
To list all logging destinations, send a GET request to `/v2/monitoring/sinks/destinations`.
GET /v2/monitoring/sinks/destinations - Read
Get Logging Destination
To get the details of a destination, send a GET request to `/v2/monitoring/sinks/destinations/${destination_uuid}`.
GET /v2/monitoring/sinks/destinations/{destination_uuid} - Read
Lists all sinks
To list all sinks, send a GET request to `/v2/monitoring/sinks`.
GET /v2/monitoring/sinks - Read
Get Sink
To get the details of a sink (resources and destination), send a GET request to `/v2/monitoring/sinks/${sink_uuid}`.
GET /v2/monitoring/sinks/{sink_uuid} - Write
Create Alert Policy
To create a new alert, send a POST request to `/v2/monitoring/alerts`.
POST /v2/monitoring/alerts - Write
Update an Alert Policy
To update en existing policy, send a PUT request to `v2/monitoring/alerts/{alert_uuid}`.
PUT /v2/monitoring/alerts/{alert_uuid} - Write
Create Logging Destination
To create a new destination, send a POST request to `/v2/monitoring/sinks/destinations`.
POST /v2/monitoring/sinks/destinations - Write
Update Logging Destination
To update the details of a destination, send a PATCH request to `/v2/monitoring/sinks/destinations/${destination_uuid}`.
POST /v2/monitoring/sinks/destinations/{destination_uuid} - Write
Create Sink
To create a new sink, send a POST request to `/v2/monitoring/sinks`. Forwards logs from the resources identified in `resources` to the specified pre-existing destination.
POST /v2/monitoring/sinks - Destructive
Delete an Alert Policy
To delete an alert policy, send a DELETE request to `/v2/monitoring/alerts/{alert_uuid}`
DELETE /v2/monitoring/alerts/{alert_uuid} - Destructive
Delete Logging Destination
To delete a destination and all associated sinks, send a DELETE request to `/v2/monitoring/sinks/destinations/${destination_uuid}`.
DELETE /v2/monitoring/sinks/destinations/{destination_uuid} - Destructive
Delete Sink
To delete a sink, send a DELETE request to `/v2/monitoring/sinks/${sink_uuid}`.
DELETE /v2/monitoring/sinks/{sink_uuid}
NFS
- Read
List NFS shares per region
To list NFS shares, send a GET request to `/v2/nfs?region=${region}`. A successful request will return all NFS shares belonging to the authenticated user.
GET /v2/nfs - Read
Get an NFS share
To get an NFS share, send a GET request to `/v2/nfs/{nfs_id}?region=${region}`. A successful request will return the NFS share.
GET /v2/nfs/{nfs_id} - Read
List NFS snapshots per region
To list all NFS snapshots, send a GET request to `/v2/nfs/snapshots?region=${region}&share_id={share_id}`. A successful request will return all NFS snapshots belonging to the authenticated user in the specified region. Optionally, you can filter snapshots by a specific NFS share by including the `share_id` query parameter.
GET /v2/nfs/snapshots - Read
Get an NFS snapshot by ID
To get an NFS snapshot, send a GET request to `/v2/nfs/snapshots/{nfs_snapshot_id}?region=${region}`. A successful request will return the NFS snapshot.
GET /v2/nfs/snapshots/{nfs_snapshot_id} - Read
List NFS access points for a share
To list access points for an NFS share, send a GET request to `/v2/nfs/shares/{share_id}/access_points`. You may use query parameters to filter by status. A successful request will return a list of NFS access points ordered with the default access point first, then by `created_at` ascending.
GET /v2/nfs/shares/{share_id}/access_points - Read
Get an NFS access point
To get an NFS access point, send a GET request to `/v2/nfs/access_points/{access_point_id}`. A successful request will return the NFS access point.
GET /v2/nfs/access_points/{access_point_id} - Write
Create a new NFS share
To create a new NFS share, send a POST request to `/v2/nfs`.
POST /v2/nfs - Write
Create an NFS access point
To create a new access point on an NFS share, send a POST request to `/v2/nfs/shares/{share_id}/access_points`. A successful request will return the newly created access point and an action object. The parent share must be in `ACTIVE` or `INACTIVE` status. Validation failures and precondition errors (such as an ineligible share state) return `400 Bad Request`. Duplicate name or path conflicts return `409 Conflict`.
POST /v2/nfs/shares/{share_id}/access_points - Destructive
Delete an NFS share
To delete an NFS share, send a DELETE request to `/v2/nfs/{nfs_id}?region=${region}`. A successful request will return a `204 No Content` status code.
DELETE /v2/nfs/{nfs_id} - Destructive
Delete an NFS snapshot
To delete an NFS snapshot, send a DELETE request to `/v2/nfs/snapshots/{nfs_snapshot_id}?region=${region}`. A successful request will return a `204 No Content` status code.
DELETE /v2/nfs/snapshots/{nfs_snapshot_id} - Destructive
Delete an NFS access point
To delete an NFS access point, send a DELETE request to `/v2/nfs/access_points/{access_point_id}`. A successful request will soft-delete the access point and return the deleted access point with status `ACCESS_POINT_DELETED` and an action object indicating the delete operation. The default access point (`is_default: true`) cannot be deleted. Access points already in `ACCESS_POINT_DELETED` or `ACCESS_POINT_FAILED` status return `400 Bad Request`.
DELETE /v2/nfs/access_points/{access_point_id}
NFS Actions
- Write
Initiate an NFS action
To execute an action (such as resize) on a specified NFS share, send a POST request to `/v2/nfs/{nfs_id}/actions`. In the JSON body to the request, set the `type` attribute to on of the supported action types: | Action | Details | | -------------------------------- | ----------- | | <nobr>`resize`</nobr> | Resizes an NFS share. Set the size_gib attribute to a desired value in GiB | | <nobr>`snapshot`</nobr> | Takes a snapshot of an NFS share | | <nobr>`attach`</nobr> | Attaches an NFS share to a VPC. Set the vpc_id attribute to the desired VPC ID | | <nobr>`detach`</nobr> | Detaches an NFS share from a VPC. Set the vpc_id attribute to the desired VPC ID | | <nobr>`reassign`</nobr> | Reassigns an NFS share from one VPC to another. Set the old_vpc_id and new_vpc_id attributes to the desired VPC IDs | | <nobr>`switch_performance_tier`</nobr> | Switches the performance tier of an NFS share. Set the performance_tier attribute to the desired tier (e.g., standard, high) |
POST /v2/nfs/{nfs_id}/actions
Organizations
- Read
List Teams in an Organization
To list all teams in an organization, send a GET request to `/v2/organizations/teams`. This endpoint must be called in an organization context.
GET /v2/organizations/teams - Write
Create a Team in an Organization
To create a new team within an organization, send a POST request to `/v2/organizations/team`. This endpoint must be called in an organization context. Optionally include `invitations` to invite users to the new team. The `owner` role cannot be assigned via invitation.
POST /v2/organizations/team
Partner Network Connect
- Read
List all partner attachments
To list all of the Partner Attachments on your account, send a `GET` request to `/v2/partner_network_connect/attachments`.
GET /v2/partner_network_connect/attachments - Read
Retrieve an existing partner attachment
To get the details of a partner attachment, send a `GET` request to `/v2/partner_network_connect/attachments/{pa_id}`.
GET /v2/partner_network_connect/attachments/{pa_id} - Read
Get current BGP auth key for the partner attachment
To get the current BGP auth key for a partner attachment, send a `GET` request to `/v2/partner_network_connect/attachments/{pa_id}/bgp_auth_key`.
GET /v2/partner_network_connect/attachments/{pa_id}/bgp_auth_key - Read
List remote routes for a partner attachment
To list all remote routes associated with a partner attachment, send a `GET` request to `/v2/partner_network_connect/attachments/{pa_id}/remote_routes`.
GET /v2/partner_network_connect/attachments/{pa_id}/remote_routes - Read
Get the current service key for the partner attachment
To get the current service key for a partner attachment, send a `GET` request to `/v2/partner_network_connect/attachments/{pa_id}/service_key`.
GET /v2/partner_network_connect/attachments/{pa_id}/service_key - Write
Create a new partner attachment
To create a new partner attachment, send a `POST` request to `/v2/partner_network_connect/attachments` with a JSON object containing the required configuration details.
POST /v2/partner_network_connect/attachments - Write
Update an existing partner attachment
To update an existing partner attachment, send a `PATCH` request to `/v2/partner_network_connect/attachments/{pa_id}` with a JSON object containing the fields to be updated.
PATCH /v2/partner_network_connect/attachments/{pa_id} - Write
Regenerate the service key for the partner attachment
This operation generates a new service key for the specified partner attachment. The operation is asynchronous, and the response is an empty JSON object returned with a 202 status code. To poll for the new service key, send a `GET` request to `/v2/partner_network_connect/attachments/{pa_id}/service_key`.
POST /v2/partner_network_connect/attachments/{pa_id}/service_key - Destructive
Delete an existing partner attachment
To delete an existing partner attachment, send a `DELETE` request to `/v2/partner_network_connect/attachments/{pa_id}`.
DELETE /v2/partner_network_connect/attachments/{pa_id}
Projects
- Read
List All Projects
To list all your projects, send a GET request to `/v2/projects`.
GET /v2/projects - Read
Retrieve the Default Project
To get your default project, send a GET request to `/v2/projects/default`.
GET /v2/projects/default - Read
Retrieve an Existing Project
To get a project, send a GET request to `/v2/projects/$PROJECT_ID`.
GET /v2/projects/{project_id} - Write
Create a Project
To create a project, send a POST request to `/v2/projects`.
POST /v2/projects - Write
Update the Default Project
To update you default project, send a PUT request to `/v2/projects/default`. All of the following attributes must be sent.
PUT /v2/projects/default - Write
Patch the Default Project
To update only specific attributes of your default project, send a PATCH request to `/v2/projects/default`. At least one of the following attributes needs to be sent.
PATCH /v2/projects/default - Write
Update a Project
To update a project, send a PUT request to `/v2/projects/$PROJECT_ID`. All of the following attributes must be sent.
PUT /v2/projects/{project_id} - Write
Patch a Project
To update only specific attributes of a project, send a PATCH request to `/v2/projects/$PROJECT_ID`. At least one of the following attributes needs to be sent.
PATCH /v2/projects/{project_id} - Destructive
Delete an Existing Project
To delete a project, send a DELETE request to `/v2/projects/$PROJECT_ID`. To be deleted, a project must not have any resources assigned to it. Any existing resources must first be reassigned or destroyed, or you will receive a 412 error. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/projects/{project_id}
Project Resources
- Read
List Project Resources
To list all your resources in a project, send a GET request to `/v2/projects/$PROJECT_ID/resources`. This endpoint will only return resources that you are authorized to see. For example, to see Droplets in a project, include the `droplet:read` scope.
GET /v2/projects/{project_id}/resources - Read
List Default Project Resources
To list all your resources in your default project, send a GET request to `/v2/projects/default/resources`. Only resources that you are authorized to see will be returned. For example, to see Droplets in a project, include the `droplet:read` scope.
GET /v2/projects/default/resources - Write
Assign Resources to a Project
To assign resources to a project, send a POST request to `/v2/projects/$PROJECT_ID/resources`. You must have both `project:assign_resource` and `<resource>:read` scopes to assign new resources. For example, to assign a Droplet to a project, include both the `project:assign_resource` and `droplet:read` scopes. The `project:update` scope also grants `project:assign_resource`.
POST /v2/projects/{project_id}/resources - Write
Assign Resources to Default Project
To assign resources to your default project, send a POST request to `/v2/projects/default/resources`. You must have both `project:assign_resource` and `<resource>:read` scopes to assign new resources. For example, to assign a Droplet to the default project, include both the `project:assign_resource` and `droplet:read` scopes. The `project:update` scope also grants `project:assign_resource`.
POST /v2/projects/default/resources
Regions
- Read
List All Data Center Regions
To list all of the regions that are available, send a GET request to `/v2/regions`. The response will be a JSON object with a key called `regions`. The value of this will be an array of `region` objects, each of which will contain the standard region attributes.
GET /v2/regions
Container Registries
- Read
List All Container Registries
To get information about any container registry in your account, send a GET request to `/v2/registries/`.
GET /v2/registries - Read
Get a Container Registry By Name
To get information about any container registry in your account, send a GET request to `/v2/registries/{registry_name}`.
GET /v2/registries/{registry_name} - Read
Get Docker Credentials By Registry Name
In order to access your container registry with the Docker client or from a Kubernetes cluster, you will need to configure authentication. The necessary JSON configuration can be retrieved by sending a GET request to `/v2/registries/{registry_name}/docker-credentials`. The response will be in the format of a Docker `config.json` file. To use the config in your Kubernetes cluster, create a Secret with: kubectl create secret generic docr \ --from-file=.dockerconfigjson=config.json \ --type=kubernetes.io/dockerconfigjson By default, the returned credentials have read-only access to your registry and cannot be used to push images. This is appropriate for most Kubernetes clusters. To retrieve read/write credentials, suitable for use with the Docker client or in a CI system, read_write may be provided as query parameter. For example: `/v2/registries/{registry_name}/docker-credentials?read_write=true` By default, the returned credentials will not expire. To retrieve credentials with an expiry set, expiry_seconds may be provided as a query parameter. For example: `/v2/registries/{registry_name}/docker-credentials?expiry_seconds=3600` will return credentials that expire after one hour.
GET /v2/registries/{registry_name}/docker-credentials - Read
Get Subscription Information
A subscription is automatically created when you configure your container registry. To get information about your subscription, send a GET request to `/v2/registries/subscription`. It is similar to GET `/v2/registry/subscription`.
GET /v2/registries/subscription - Read
List Registry Options (Subscription Tiers and Available Regions)
This endpoint serves to provide additional information as to which option values are available when creating a container registry. There are multiple subscription tiers available for container registry. Each tier allows a different number of image repositories to be created in your registry, and has a different amount of storage and transfer included. There are multiple regions available for container registry and controls where your data is stored. To list the available options, send a GET request to `/v2/registries/options`. This is similar to GET `/v2/registry/options`.
GET /v2/registries/options - Read
Get Active Garbage Collection
To get information about the currently-active garbage collection for a registry, send a GET request to `/v2/registry/$REGISTRY_NAME/garbage-collection`.
GET /v2/registries/{registry_name}/garbage-collection - Read
List Garbage Collections
To get information about past garbage collections for a registry, send a GET request to `/v2/registry/$REGISTRY_NAME/garbage-collections`.
GET /v2/registries/{registry_name}/garbage-collections - Read
List All Container Registry Repositories (V2)
To list all repositories in your container registry, send a GET request to `/v2/registries/$REGISTRY_NAME/repositoriesV2`. It is similar to GET `/v2/registry/$REGISTRY_NAME/repositoriesV2`.
GET /v2/registries/{registry_name}/repositoriesV2 - Read
List All Container Registry Repository Tags
To list all tags in one of your container registry's repository, send a GET request to `/v2/registries/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to list tags for `registry.digitalocean.com/example/my/repo`, the path would be `/v2/registry/example/repositories/my%2Frepo/tags`. It is similar to GET `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags`.
GET /v2/registries/{registry_name}/repositories/{repository_name}/tags - Read
List All Container Registry Repository Manifests
To list all manifests in your container registry repository, send a GET request to `/v2/registries/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to list manifests for `registry.digitalocean.com/example/my/repo`, the path would be `/v2/registry/example/repositories/my%2Frepo/digests`. It is similar to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests`.
GET /v2/registries/{registry_name}/repositories/{repository_name}/digests - Read
Validate a Container Registry Name
To validate that a container registry name is available for use, send a POST request to `/v2/registries/validate-name`. If the name is both formatted correctly and available, the response code will be 204 and contain no body. If the name is already in use, the response will be a 409 Conflict. It is similar to `/v2/registry/validate-name`.
POST /v2/registries/validate-name - Write
Create Container Registry
To create your container registry, send a POST request to `/v2/registries`. The `name` becomes part of the URL for images stored in the registry. For example, if your registry is called `example`, an image in it will have the URL `registry.digitalocean.com/example/image:tag`.
POST /v2/registries - Write
Update Subscription Tier
After creating your registry, you can switch to a different subscription tier to better suit your needs. To do this, send a POST request to `/v2/registries/subscription`. It is similar to POST `/v2/registry/subscription`.
POST /v2/registries/subscription - Write
Update Garbage Collection
To cancel the currently-active garbage collection for a registry, send a PUT request to `/v2/registries/$REGISTRY_NAME/garbage-collection/$GC_UUID` and specify one or more of the attributes below. It is similar to PUT `/v2/registries/$REGISTRY_NAME/garbage-collection/$GC_UUID`.
PUT /v2/registries/{registry_name}/garbage-collection/{garbage_collection_uuid} - Destructive
Delete Container Registry By Name
To delete your container registry, destroying all container image data stored in it, send a DELETE request to `/v2/registries/{registry_name}`.
DELETE /v2/registries/{registry_name} - Destructive
Start Garbage Collection
Garbage collection enables users to clear out unreferenced blobs (layer & manifest data) after deleting one or more manifests from a repository. If there are no unreferenced blobs resulting from the deletion of one or more manifests, garbage collection is effectively a noop. [See here for more information](https://docs.digitalocean.com/products/container-registry/how-to/clean-up-container-registry/) about how and why you should clean up your container registry periodically. To request a garbage collection run on your registry, send a POST request to `/v2/registries/$REGISTRY_NAME/garbage-collection`. This will initiate the following sequence of events on your registry. * Set the registry to read-only mode, meaning no further write-scoped JWTs will be issued to registry clients. Existing write-scoped JWTs will continue to work until they expire which can take up to 15 minutes. * Wait until all existing write-scoped JWTs have expired. * Scan all registry manifests to determine which blobs are unreferenced. * Delete all unreferenced blobs from the registry. * Record the number of blobs deleted and bytes freed, mark the garbage collection status as `success`. * Remove the read-only mode restriction from the registry, meaning write-scoped JWTs will once again be issued to registry clients.
POST /v2/registries/{registry_name}/garbage-collection - Destructive
Delete Container Registry Repository
To delete a container repository including all of its tags, send a DELETE request to `/v2/registries/$REGISTRY_NAME/repositories/$REPOSITORY_NAME`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/registries/{registry_name}/repositories/{repository_name} - Destructive
Delete Container Registry Repository Tag
To delete a container repository tag in on of our container registries, send a DELETE request to `/v2/registries/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags/$TAG`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to delete `registry.digitalocean.com/example/my/repo:mytag`, the path would be `/v2/registry/example/repositories/my%2Frepo/tags/mytag`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully. It is similar to DELETE `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags/$TAG`.
DELETE /v2/registries/{registry_name}/repositories/{repository_name}/tags/{repository_tag} - Destructive
Delete Container Registry Repository Manifest
To delete a container repository manifest by digest in one of your registries, send a DELETE request to `/v2/registries/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests/$MANIFEST_DIGEST`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to delete `registry.digitalocean.com/example/my/repo@sha256:abcd`, the path would be `/v2/registry/example/repositories/my%2Frepo/digests/sha256:abcd`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully. It is similar to DELETE `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests/$MANIFEST_DIGEST`.
DELETE /v2/registries/{registry_name}/repositories/{repository_name}/digests/{manifest_digest}
Container Registry
- Read
Get Container Registry Information (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To get information about your container registry, send a GET request to `/v2/registry`. This operation is not compatible with multiple registries in a DO account. You should use `/v2/registries/{registry_name}` instead.
GET /v2/registry - Read
Get Subscription (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** A subscription is automatically created when you configure your container registry. To get information about your subscription, send a GET request to `/v2/registry/subscription`.
GET /v2/registry/subscription - Read
Get Docker Credentials for Container Registry (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** In order to access your container registry with the Docker client or from a Kubernetes cluster, you will need to configure authentication. The necessary JSON configuration can be retrieved by sending a GET request to `/v2/registry/docker-credentials`. The response will be in the format of a Docker `config.json` file. To use the config in your Kubernetes cluster, create a Secret with: kubectl create secret generic docr \ --from-file=.dockerconfigjson=config.json \ --type=kubernetes.io/dockerconfigjson By default, the returned credentials have read-only access to your registry and cannot be used to push images. This is appropriate for most Kubernetes clusters. To retrieve read/write credentials, suitable for use with the Docker client or in a CI system, read_write may be provided as query parameter. For example: `/v2/registry/docker-credentials?read_write=true` By default, the returned credentials will not expire. To retrieve credentials with an expiry set, expiry_seconds may be provided as a query parameter. For example: `/v2/registry/docker-credentials?expiry_seconds=3600` will return credentials that expire after one hour.
GET /v2/registry/docker-credentials - Read
Validate a Container Registry Name (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To validate that a container registry name is available for use, send a POST request to `/v2/registry/validate-name`. If the name is both formatted correctly and available, the response code will be 204 and contain no body. If the name is already in use, the response will be a 409 Conflict.
POST /v2/registry/validate-name - Read
List All Container Registry Repositories (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** This endpoint has been deprecated in favor of the _List All Container Registry Repositories [V2]_ endpoint. To list all repositories in your container registry, send a GET request to `/v2/registry/$REGISTRY_NAME/repositories`.
GET /v2/registry/{registry_name}/repositories - Read
List All Container Registry Repositories (V2) (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To list all repositories in your container registry, send a GET request to `/v2/registry/$REGISTRY_NAME/repositoriesV2`.
GET /v2/registry/{registry_name}/repositoriesV2 - Read
List All Container Registry Repository Tags (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To list all tags in your container registry repository, send a GET request to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to list tags for `registry.digitalocean.com/example/my/repo`, the path would be `/v2/registry/example/repositories/my%2Frepo/tags`.
GET /v2/registry/{registry_name}/repositories/{repository_name}/tags - Read
List All Container Registry Repository Manifests (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To list all manifests in your container registry repository, send a GET request to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to list manifests for `registry.digitalocean.com/example/my/repo`, the path would be `/v2/registry/example/repositories/my%2Frepo/digests`.
GET /v2/registry/{registry_name}/repositories/{repository_name}/digests - Read
Get Active Garbage Collection (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To get information about the currently-active garbage collection for a registry, send a GET request to `/v2/registry/$REGISTRY_NAME/garbage-collection`.
GET /v2/registry/{registry_name}/garbage-collection - Read
List Garbage Collections (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To get information about past garbage collections for a registry, send a GET request to `/v2/registry/$REGISTRY_NAME/garbage-collections`.
GET /v2/registry/{registry_name}/garbage-collections - Read
List Registry Options (Subscription Tiers and Available Regions) (deprecated)
**Note: This endpoint is deprecated and may be removed in a future version. There is no alternative.****Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** This endpoint serves to provide additional information as to which option values are available when creating a container registry. There are multiple subscription tiers available for container registry. Each tier allows a different number of image repositories to be created in your registry, and has a different amount of storage and transfer included. There are multiple regions available for container registry and controls where your data is stored. To list the available options, send a GET request to `/v2/registry/options`.
GET /v2/registry/options - Write
Create Container Registry (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To create your container registry, send a POST request to `/v2/registry`. The `name` becomes part of the URL for images stored in the registry. For example, if your registry is called `example`, an image in it will have the URL `registry.digitalocean.com/example/image:tag`.
POST /v2/registry - Write
Update Subscription Tier (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** After creating your registry, you can switch to a different subscription tier to better suit your needs. To do this, send a POST request to `/v2/registry/subscription`.
POST /v2/registry/subscription - Write
Update Garbage Collection (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To cancel the currently-active garbage collection for a registry, send a PUT request to `/v2/registry/$REGISTRY_NAME/garbage-collection/$GC_UUID` and specify one or more of the attributes below.
PUT /v2/registry/{registry_name}/garbage-collection/{garbage_collection_uuid} - Destructive
Delete Container Registry (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To delete your container registry, destroying all container image data stored in it, send a DELETE request to `/v2/registry`. This operation is not compatible with multiple registries in a DO account. You should use `/v2/registries/{registry_name}` instead.
DELETE /v2/registry - Destructive
Delete Container Registry Repository Tag (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To delete a container repository tag, send a DELETE request to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags/$TAG`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to delete `registry.digitalocean.com/example/my/repo:mytag`, the path would be `/v2/registry/example/repositories/my%2Frepo/tags/mytag`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/registry/{registry_name}/repositories/{repository_name}/tags/{repository_tag} - Destructive
Delete Container Registry Repository Manifest (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** To delete a container repository manifest by digest, send a DELETE request to `/v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests/$MANIFEST_DIGEST`. Note that if your repository name contains `/` characters, it must be URL-encoded in the request URL. For example, to delete `registry.digitalocean.com/example/my/repo@sha256:abcd`, the path would be `/v2/registry/example/repositories/my%2Frepo/digests/sha256:abcd`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/registry/{registry_name}/repositories/{repository_name}/digests/{manifest_digest} - Destructive
Start Garbage Collection (deprecated)
**Note: This endpoint is deprecated. Please use the `/v2/registries` endpoint instead.** Garbage collection enables users to clear out unreferenced blobs (layer & manifest data) after deleting one or more manifests from a repository. If there are no unreferenced blobs resulting from the deletion of one or more manifests, garbage collection is effectively a noop. [See here for more information](https://docs.digitalocean.com/products/container-registry/how-to/clean-up-container-registry/) about how and why you should clean up your container registry periodically. To request a garbage collection run on your registry, send a POST request to `/v2/registry/$REGISTRY_NAME/garbage-collection`. This will initiate the following sequence of events on your registry. * Set the registry to read-only mode, meaning no further write-scoped JWTs will be issued to registry clients. Existing write-scoped JWTs will continue to work until they expire which can take up to 15 minutes. * Wait until all existing write-scoped JWTs have expired. * Scan all registry manifests to determine which blobs are unreferenced. * Delete all unreferenced blobs from the registry. * Record the number of blobs deleted and bytes freed, mark the garbage collection status as `success`. * Remove the read-only mode restriction from the registry, meaning write-scoped JWTs will once again be issued to registry clients.
POST /v2/registry/{registry_name}/garbage-collection
Reserved IPs
- Read
List All Reserved IPs
To list all of the reserved IPs available on your account, send a GET request to `/v2/reserved_ips`.
GET /v2/reserved_ips - Read
Retrieve an Existing Reserved IP
To show information about a reserved IP, send a GET request to `/v2/reserved_ips/$RESERVED_IP_ADDR`.
GET /v2/reserved_ips/{reserved_ip} - Write
Create a New Reserved IP
On creation, a reserved IP must be either assigned to a Droplet or reserved to a region. * To create a new reserved IP assigned to a Droplet, send a POST request to `/v2/reserved_ips` with the `droplet_id` attribute. * To create a new reserved IP reserved to a region, send a POST request to `/v2/reserved_ips` with the `region` attribute.
POST /v2/reserved_ips - Destructive
Delete a Reserved IP
To delete a reserved IP and remove it from your account, send a DELETE request to `/v2/reserved_ips/$RESERVED_IP_ADDR`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/reserved_ips/{reserved_ip}
Reserved IP Actions
- Read
List All Actions for a Reserved IP
To retrieve all actions that have been executed on a reserved IP, send a GET request to `/v2/reserved_ips/$RESERVED_IP/actions`.
GET /v2/reserved_ips/{reserved_ip}/actions - Read
Retrieve an Existing Reserved IP Action
To retrieve the status of a reserved IP action, send a GET request to `/v2/reserved_ips/$RESERVED_IP/actions/$ACTION_ID`.
GET /v2/reserved_ips/{reserved_ip}/actions/{action_id} - Write
Initiate a Reserved IP Action
To initiate an action on a reserved IP send a POST request to `/v2/reserved_ips/$RESERVED_IP/actions`. In the JSON body to the request, set the `type` attribute to on of the supported action types: | Action | Details |------------|-------- | `assign` | Assigns a reserved IP to a Droplet | `unassign` | Unassign a reserved IP from a Droplet
POST /v2/reserved_ips/{reserved_ip}/actions
Reserved IPv6
- Read
List All Reserved IPv6s
To list all of the reserved IPv6s available on your account, send a GET request to `/v2/reserved_ipv6`.
GET /v2/reserved_ipv6 - Read
Retrieve an Existing Reserved IPv6
To show information about a reserved IPv6, send a GET request to `/v2/reserved_ipv6/$RESERVED_IPV6`.
GET /v2/reserved_ipv6/{reserved_ipv6} - Write
Create a New Reserved IPv6
On creation, a reserved IPv6 must be reserved to a region. * To create a new reserved IPv6 reserved to a region, send a POST request to `/v2/reserved_ipv6` with the `region_slug` attribute.
POST /v2/reserved_ipv6 - Destructive
Delete a Reserved IPv6
To delete a reserved IP and remove it from your account, send a DELETE request to `/v2/reserved_ipv6/$RESERVED_IPV6`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
DELETE /v2/reserved_ipv6/{reserved_ipv6}
Reserved IPv6 Actions
- Write
Initiate a Reserved IPv6 Action
To initiate an action on a reserved IPv6 send a POST request to `/v2/reserved_ipv6/$RESERVED_IPV6/actions`. In the JSON body to the request, set the `type` attribute to on of the supported action types: | Action | Details |------------|-------- | `assign` | Assigns a reserved IPv6 to a Droplet | `unassign` | Unassign a reserved IPv6 from a Droplet
POST /v2/reserved_ipv6/{reserved_ipv6}/actions
BYOIP Prefixes
- Read
List BYOIP Prefixes
To list all BYOIP prefixes, send a GET request to `/v2/byoip_prefixes`. A successful response will return a list of all BYOIP prefixes associated with the account.
GET /v2/byoip_prefixes - Read
Get a BYOIP Prefix
To get a BYOIP prefix, send a GET request to `/v2/byoip_prefixes/$byoip_prefix_uuid`. A successful response will return the details of the specified BYOIP prefix.
GET /v2/byoip_prefixes/{byoip_prefix_uuid} - Read
List BYOIP Prefix Resources
To list resources associated with BYOIP prefixes, send a GET request to `/v2/byoip_prefixes/{byoip_prefix_uuid}/ips`. A successful response will return a list of resources associated with the specified BYOIP prefix.
GET /v2/byoip_prefixes/{byoip_prefix_uuid}/ips - Write
Create a BYOIP Prefix
To create a BYOIP prefix, send a POST request to `/v2/byoip_prefixes`. A successful request will initiate the process of bringing your BYOIP Prefix into your account. The response will include the details of the created prefix, including its UUID and status.
POST /v2/byoip_prefixes - Write
Update a BYOIP Prefix
To update a BYOIP prefix, send a PATCH request to `/v2/byoip_prefixes/$byoip_prefix_uuid`. Currently, you can update the advertisement status of the prefix. The response will include the updated details of the prefix.
PATCH /v2/byoip_prefixes/{byoip_prefix_uuid} - Destructive
Delete a BYOIP Prefix
To delete a BYOIP prefix and remove it from your account, send a DELETE request to `/v2/byoip_prefixes/$byoip_prefix_uuid`. A successful request will receive a 202 status code with no body in response. This indicates that the request was accepted and the prefix is being deleted.
DELETE /v2/byoip_prefixes/{byoip_prefix_uuid}
Security
- Read
List Scans
To list all CSPM scans, send a GET request to `/v2/security/scans`.
GET /v2/security/scans - Read
Get Scan
To get a CSPM scan by ID, send a GET request to `/v2/security/scans/{scan_id}`.
GET /v2/security/scans/{scan_id} - Read
Get Latest Scan
To get the latest CSPM scan, send a GET request to `/v2/security/scans/latest`.
GET /v2/security/scans/latest - Read
List Finding Affected Resources
To get affected resources for a scan finding, send a GET request to `/v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources`.
GET /v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources - Read
List Settings
To list CSPM scan settings, send a GET request to `/v2/security/settings`.
GET /v2/security/settings - Write
Create Scan
To create a CSPM scan, send a POST request to `/v2/security/scans`.
POST /v2/security/scans - Write
Create Scan Rule
To mark a scan finding as a false positive, send a POST request to `/v2/security/scans/rules` to create a new scan rule.
POST /v2/security/scans/rules - Write
Update Plan
To update CSPM plan coverage, send a PUT request to `/v2/security/settings/plan`.
PUT /v2/security/settings/plan - Write
Create Suppression
To suppress scan findings, send a POST request to `/v2/security/settings/suppressions`.
POST /v2/security/settings/suppressions - Destructive
Delete Suppression
To remove a suppression, send a DELETE request to `/v2/security/settings/suppressions/{suppression_uuid}`.
DELETE /v2/security/settings/suppressions/{suppression_uuid}
Sizes
- Read
List All Droplet Sizes
To list all of available Droplet sizes, send a GET request to `/v2/sizes`. The response will be a JSON object with a key called `sizes`. The value of this will be an array of `size` objects each of which contain the standard size attributes.
GET /v2/sizes
Snapshots
- Read
List All Snapshots
To list all of the snapshots available on your account, send a GET request to `/v2/snapshots`. The response will be a JSON object with a key called `snapshots`. This will be set to an array of `snapshot` objects, each of which will contain the standard snapshot attributes. ### Filtering Results by Resource Type It's possible to request filtered results by including certain query parameters. #### List Droplet Snapshots To retrieve only snapshots based on Droplets, include the `resource_type` query parameter set to `droplet`. For example, `/v2/snapshots?resource_type=droplet`. #### List Volume Snapshots To retrieve only snapshots based on volumes, include the `resource_type` query parameter set to `volume`. For example, `/v2/snapshots?resource_type=volume`.
GET /v2/snapshots - Read
Retrieve an Existing Snapshot
To retrieve information about a snapshot, send a GET request to `/v2/snapshots/$SNAPSHOT_ID`. The response will be a JSON object with a key called `snapshot`. The value of this will be an snapshot object containing the standard snapshot attributes.
GET /v2/snapshots/{snapshot_id} - Destructive
Delete a Snapshot
Both Droplet and volume snapshots are managed through the `/v2/snapshots/` endpoint. To delete a snapshot, send a DELETE request to `/v2/snapshots/$SNAPSHOT_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/snapshots/{snapshot_id}
Spaces Keys
- Read
List Spaces Access Keys
To list Spaces Access Key, send a GET request to `/v2/spaces/keys`. Sort parameter must be used with Sort Direction.
GET /v2/spaces/keys - Read
Get a Spaces Access Key
To get a Spaces Access Key, send a GET request to `/v2/spaces/keys/$ACCESS_KEY`. A successful request will return the Access Key.
GET /v2/spaces/keys/{access_key} - Write
Create a New Spaces Access Key
To create a new Spaces Access Key, send a POST request to `/v2/spaces/keys`. At the moment, you cannot mix a fullaccess permission with scoped permissions. A fullaccess permission will be prioritized if fullaccess and scoped permissions are both added.
POST /v2/spaces/keys - Write
Update Spaces Access Keys
To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`. At the moment, you cannot convert a fullaccess key to a scoped key or vice versa. You can only update the name of the key.
PUT /v2/spaces/keys/{access_key} - Write
Update Spaces Access Keys
To update Spaces Access Key, send a PUT or PATCH request to `/v2/spaces/keys/$ACCESS_KEY`. At the moment, you cannot convert a fullaccess key to a scoped key or vice versa. You can only update the name of the key.
PATCH /v2/spaces/keys/{access_key} - Destructive
Delete a Spaces Access Key
To delete a Spaces Access Key, send a DELETE request to `/v2/spaces/keys/$ACCESS_KEY`. A successful request will return a `204 No Content` status code.
DELETE /v2/spaces/keys/{access_key}
Tags
- Read
List All Tags
To list all of your tags, you can send a GET request to `/v2/tags`. This endpoint will only return tagged resources that you are authorized to see (e.g. Droplets will only be returned if you have `droplet:read`).
GET /v2/tags - Read
Retrieve a Tag
To retrieve an individual tag, you can send a `GET` request to `/v2/tags/$TAG_NAME`. This endpoint will only return tagged resources that you are authorized to see. For example, to see tagged Droplets, include the `droplet:read` scope.
GET /v2/tags/{tag_id} - Write
Create a New Tag
To create a tag you can send a POST request to `/v2/tags` with a `name` attribute.
POST /v2/tags - Write
Tag a Resource
Resources can be tagged by sending a POST request to `/v2/tags/$TAG_NAME/resources` with an array of json objects containing `resource_id` and `resource_type` attributes. Currently only tagging of Droplets, Databases, Images, Volumes, and Volume Snapshots is supported. `resource_type` is expected to be the string `droplet`, `database`, `image`, `volume` or `volume_snapshot`. `resource_id` is expected to be the ID of the resource as a string. In order to tag a resource, you must have both `tag:create` and `<resource type>:update` scopes. For example, to tag a Droplet, you must have `tag:create` and `droplet:update`.
POST /v2/tags/{tag_id}/resources - Destructive
Delete a Tag
A tag can be deleted by sending a `DELETE` request to `/v2/tags/$TAG_NAME`. Deleting a tag also untags all the resources that have previously been tagged by the Tag
DELETE /v2/tags/{tag_id} - Destructive
Untag a Resource
Resources can be untagged by sending a DELETE request to `/v2/tags/$TAG_NAME/resources` with an array of json objects containing `resource_id` and `resource_type` attributes. Currently only untagging of Droplets, Databases, Images, Volumes, and Volume Snapshots is supported. `resource_type` is expected to be the string `droplet`, `database`, `image`, `volume` or `volume_snapshot`. `resource_id` is expected to be the ID of the resource as a string. In order to untag a resource, you must have both `tag:delete` and `<resource type>:update` scopes. For example, to untag a Droplet, you must have `tag:delete` and `droplet:update`.
DELETE /v2/tags/{tag_id}/resources
Vector Databases
- Read
List All Vector Databases
To list all of the vector databases on your account, send a GET request to `/v2/vector-databases`. Use the `page` and `per_page` query parameters to paginate the results. The response body contains a `vector_dbs` array of vector database objects and a `total` field with the overall count.
GET /v2/vector-databases - Read
Retrieve an Existing Vector Database
To show information about an existing vector database, send a GET request to `/v2/vector-databases/{id}`. The response body contains a JSON object with a `vector_db` key holding the standard vector database attributes, including an embedded `endpoints` object with the connection information needed to access the database.
GET /v2/vector-databases/{id} - Read
List Backups for a Vector Database
To list the available backups for a vector database, send a GET request to `/v2/vector-databases/{id}/backups`. Only backups with a status of `SUCCESS` are returned.
GET /v2/vector-databases/{id}/backups - Read
Retrieve the Status of a Restore
To check the status of a restore operation, send a GET request to `/v2/vector-databases/{id}/backups/{backup_id}/restore`. The response body contains the current status of the restore.
GET /v2/vector-databases/{id}/backups/{backup_id}/restore - Read
Retrieve Admin Credentials for a Vector Database
To retrieve the admin credentials for a vector database, send a GET request to `/v2/vector-databases/{id}/credentials`. The response body contains the `user_id` and `api_token` for the admin user provisioned on the cluster.
GET /v2/vector-databases/{id}/credentials - Write
Create a New Vector Database
To create a vector database, send a POST request to `/v2/vector-databases`. The response body contains a JSON object with a `vector_db` key holding the newly created database. Its initial `status` is `creating` and changes to `active` once the database is ready to receive traffic.
POST /v2/vector-databases - Write
Update a Vector Database
To update an existing vector database, send a PUT request to `/v2/vector-databases/{id}`. The response body contains a JSON object with a `vector_db` key holding the updated vector database.
PUT /v2/vector-databases/{id} - Write
Restore a Vector Database from a Backup
To restore a vector database from a backup, send a POST request to `/v2/vector-databases/{id}/backups/{backup_id}/restore`. The restore runs asynchronously; use the restore-status endpoint to monitor its progress.
POST /v2/vector-databases/{id}/backups/{backup_id}/restore - Write
Resize a Vector Database
To resize a vector database, send a POST request to `/v2/vector-databases/{id}/resize`. This changes the database's resource tier. The response body contains a JSON object with the updated vector database.
POST /v2/vector-databases/{id}/resize - Destructive
Delete a Vector Database
To delete a vector database, send a DELETE request to `/v2/vector-databases/{id}`. Deleting a vector database is irreversible and destroys the underlying instance along with its data.
DELETE /v2/vector-databases/{id} - Destructive
Update Tags on a Vector Database
To update the tags on a vector database, send a PUT request to `/v2/vector-databases/{id}/tags`. The supplied set of tags replaces the database's existing tags.
PUT /v2/vector-databases/{id}/tags
Block Storage
- Read
List All Block Storage Volumes
To list all of the block storage volumes available on your account, send a GET request to `/v2/volumes`. ## Filtering Results ### By Region The `region` may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: `/v2/volumes?region=nyc1` ### By Name It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to `/v2/volumes?name=$VOLUME_NAME`. **Note:** You can only create one volume per region with the same name. ### By Name and Region It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`.
GET /v2/volumes - Read
Retrieve an Existing Volume Snapshot
To retrieve the details of a snapshot that has been created from a volume, send a GET request to `/v2/volumes/snapshots/$VOLUME_SNAPSHOT_ID`.
GET /v2/volumes/snapshots/{snapshot_id} - Read
Retrieve an Existing Block Storage Volume
To show information about a block storage volume, send a GET request to `/v2/volumes/$VOLUME_ID`.
GET /v2/volumes/{volume_id} - Read
List Snapshots for a Volume
To retrieve the snapshots that have been created from a volume, send a GET request to `/v2/volumes/$VOLUME_ID/snapshots`.
GET /v2/volumes/{volume_id}/snapshots - Write
Create a New Block Storage Volume
To create a new volume, send a POST request to `/v2/volumes`. Optionally, a `filesystem_type` attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.
POST /v2/volumes - Write
Create Snapshot from a Volume
To create a snapshot from a volume, sent a POST request to `/v2/volumes/$VOLUME_ID/snapshots`.
POST /v2/volumes/{volume_id}/snapshots - Destructive
Delete a Block Storage Volume by Name
Block storage volumes may also be deleted by name by sending a DELETE request with the volume's **name** and the **region slug** for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/volumes - Destructive
Delete a Volume Snapshot
To delete a volume snapshot, send a DELETE request to `/v2/volumes/snapshots/$VOLUME_SNAPSHOT_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
DELETE /v2/volumes/snapshots/{snapshot_id} - Destructive
Delete a Block Storage Volume
To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to `/v2/volumes/$VOLUME_ID`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.
DELETE /v2/volumes/{volume_id}
Block Storage Actions
- Read
List All Actions for a Volume
To retrieve all actions that have been executed on a volume, send a GET request to `/v2/volumes/$VOLUME_ID/actions`.
GET /v2/volumes/{volume_id}/actions - Read
Retrieve an Existing Volume Action
To retrieve the status of a volume action, send a GET request to `/v2/volumes/$VOLUME_ID/actions/$ACTION_ID`.
GET /v2/volumes/{volume_id}/actions/{action_id} - Destructive
Initiate A Block Storage Action By Volume Name
To initiate an action on a block storage volume by Name, send a POST request to `~/v2/volumes/actions`. The body should contain the appropriate attributes for the respective action. ## Attach a Block Storage Volume to a Droplet | Attribute | Details | | ----------- | ------------------------------------------------------------------- | | type | This must be `attach` | | volume_name | The name of the block storage volume | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located | Each volume may only be attached to a single Droplet. However, up to fifteen volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attached. On older Droplets, [additional configuration](https://docs.digitalocean.com/products/volumes/how-to/mount/) is required. ## Remove a Block Storage Volume from a Droplet | Attribute | Details | | ----------- | ------------------------------------------------------------------- | | type | This must be `detach` | | volume_name | The name of the block storage volume | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located |
POST /v2/volumes/actions - Destructive
Initiate A Block Storage Action By Volume Id
To initiate an action on a block storage volume by Id, send a POST request to `~/v2/volumes/$VOLUME_ID/actions`. The body should contain the appropriate attributes for the respective action. ## Attach a Block Storage Volume to a Droplet | Attribute | Details | | ---------- | ------------------------------------------------------------------- | | type | This must be `attach` | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located | Each volume may only be attached to a single Droplet. However, up to fifteen volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attached. On older Droplets, [additional configuration](https://docs.digitalocean.com/products/volumes/how-to/mount/) is required. ## Remove a Block Storage Volume from a Droplet | Attribute | Details | | ---------- | ------------------------------------------------------------------- | | type | This must be `detach` | | droplet_id | Set to the Droplet's ID | | region | Set to the slug representing the region where the volume is located | ## Resize a Volume | Attribute | Details | | -------------- | ------------------------------------------------------------------- | | type | This must be `resize` | | size_gigabytes | The new size of the block storage volume in GiB (1024^3) | | region | Set to the slug representing the region where the volume is located | Volumes may only be resized upwards. The maximum size for a volume is 16TiB.
POST /v2/volumes/{volume_id}/actions
VPCs
- Read
List All VPCs
To list all of the VPCs on your account, send a GET request to `/v2/vpcs`.
GET /v2/vpcs - Read
Retrieve an Existing VPC
To show information about an existing VPC, send a GET request to `/v2/vpcs/$VPC_ID`.
GET /v2/vpcs/{vpc_id} - Read
List the Member Resources of a VPC
To list all of the resources that are members of a VPC, send a GET request to `/v2/vpcs/$VPC_ID/members`. To only list resources of a specific type that are members of the VPC, included a `resource_type` query parameter. For example, to only list Droplets in the VPC, send a GET request to `/v2/vpcs/$VPC_ID/members?resource_type=droplet`. Only resources that you are authorized to see will be returned (e.g. to see Droplets, you must have `droplet:read`).
GET /v2/vpcs/{vpc_id}/members - Read
List the Peerings of a VPC
To list all of a VPC's peerings, send a GET request to `/v2/vpcs/$VPC_ID/peerings`.
GET /v2/vpcs/{vpc_id}/peerings - Write
Create a New VPC
To create a VPC, send a POST request to `/v2/vpcs` specifying the attributes in the table below in the JSON body. **Note:** If you do not currently have a VPC network in a specific datacenter region, the first one that you create will be set as the default for that region. The default VPC for a region cannot be changed or deleted.
POST /v2/vpcs - Write
Update a VPC
To update information about a VPC, send a PUT request to `/v2/vpcs/$VPC_ID`.
PUT /v2/vpcs/{vpc_id} - Write
Partially Update a VPC
To update a subset of information about a VPC, send a PATCH request to `/v2/vpcs/$VPC_ID`.
PATCH /v2/vpcs/{vpc_id} - Write
Create a Peering with a VPC
To create a new VPC peering for a given VPC, send a POST request to `/v2/vpcs/$VPC_ID/peerings`.
POST /v2/vpcs/{vpc_id}/peerings - Write
Update a VPC Peering
To update the name of a VPC peering in a particular VPC, send a PATCH request to `/v2/vpcs/$VPC_ID/peerings/$VPC_PEERING_ID` with the new `name` in the request body.
PATCH /v2/vpcs/{vpc_id}/peerings/{vpc_peering_id} - Destructive
Delete a VPC
To delete a VPC, send a DELETE request to `/v2/vpcs/$VPC_ID`. A 204 status code with no body will be returned in response to a successful request. The default VPC for a region can not be deleted. Additionally, a VPC can only be deleted if it does not contain any member resources. Attempting to delete a region's default VPC or a VPC that still has members will result in a 403 Forbidden error response.
DELETE /v2/vpcs/{vpc_id}
VPC Routes [Public Preview]
- Read
List VPC Routes
To list the read-only VPC-scoped routes for a VPC, send a GET request to `/v2/vpcs/$VPC_UUID/routes`. VPC-scoped routes cannot be created, updated, or deleted through the public API.
GET /v2/vpcs/{vpc_uuid}/routes - Read
List VPC Subnet Routes
To list routes for a VPC subnet, send a GET request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID/routes`. The response includes VPC-scoped routes propagated into the subnet and subnet-scoped routes.
GET /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}/routes - Write
Create a VPC Subnet Route
To add a static route to a VPC subnet, send a POST request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID/routes`. This route is additional to the routes the VPC already propagates to the subnet. The server assigns the route's `id` and `type`. Droplet targets must use a numeric ID. A Droplet UUID or another invalid `target_urns` value returns a 422 response.
POST /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}/routes - Write
Update a VPC Subnet Route
To update the next hop for a user-defined VPC subnet route, send a PATCH request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID/routes/$ROUTE_UUID`. The `destination_cidr` cannot be changed. Droplet targets must use a numeric ID. A Droplet UUID or another invalid `target_urns` value returns a 422 response.
PATCH /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}/routes/{route_uuid} - Destructive
Delete a VPC Subnet Route
To delete a user-defined VPC subnet route, send a DELETE request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID/routes/$ROUTE_UUID`. Managed routes cannot be deleted. A successful request returns a 204 status code with no response body.
DELETE /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}/routes/{route_uuid}
VPC Subnets [Public Preview]
- Read
List VPC Subnets
To list all subnets within a VPC, send a GET request to `/v2/vpcs/$VPC_UUID/subnets`.
GET /v2/vpcs/{vpc_uuid}/subnets - Read
Retrieve a VPC Subnet
To retrieve a specific subnet within a VPC, send a GET request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID`.
GET /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid} - Read
List the Member Resources of a VPC Subnet
To list all resources that are members of a VPC subnet, send a GET request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID/members`. To list only members of a specific type, include the `resource_type` query parameter. Only resources that you are authorized to view are returned. For example, viewing Droplets requires the `droplet:read` scope.
GET /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}/members - Write
Create a VPC Subnet
To create a subnet within a VPC, send a POST request to `/v2/vpcs/$VPC_UUID/subnets` with a name and, optionally, an IP range.
POST /v2/vpcs/{vpc_uuid}/subnets - Write
Update a VPC Subnet
To update the name of a specific subnet within a VPC, send a PATCH request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID`.
PATCH /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid} - Destructive
Delete a VPC Subnet
To delete a specific subnet from a VPC, send a DELETE request to `/v2/vpcs/$VPC_UUID/subnets/$SUBNET_UUID`. A successful request returns a 204 status code with no response body.
DELETE /v2/vpcs/{vpc_uuid}/subnets/{subnet_uuid}
VPC Peerings
- Read
List All VPC Peerings
To list all of the VPC peerings on your account, send a GET request to `/v2/vpc_peerings`.
GET /v2/vpc_peerings - Read
Retrieve an Existing VPC Peering
To show information about an existing VPC Peering, send a GET request to `/v2/vpc_peerings/$VPC_PEERING_ID`.
GET /v2/vpc_peerings/{vpc_peering_id} - Write
Create a New VPC Peering
To create a new VPC Peering, send a POST request to `/v2/vpc_peerings` specifying a name and a list of two VPC IDs to peer. The response code, 202 Accepted, does not indicate the success or failure of the operation, just that the request has been accepted for processing.
POST /v2/vpc_peerings - Write
Update a VPC peering
To update the name of a VPC peering, send a PATCH request to `/v2/vpc_peerings/$VPC_PEERING_ID` with the new `name` in the request body.
PATCH /v2/vpc_peerings/{vpc_peering_id} - Destructive
Delete a VPC peering
To delete a VPC peering, send a DELETE request to `/v2/vpc_peerings/$VPC_PEERING_ID`.
DELETE /v2/vpc_peerings/{vpc_peering_id}
VPC NAT Gateways
- Read
List All VPC NAT Gateways
To list all VPC NAT gateways in your team, send a GET request to `/v2/vpc_nat_gateways`. The response body will be a JSON object with a key of `vpc_nat_gateways` containing an array of VPC NAT gateway objects. These each contain the standard VPC NAT gateway attributes.
GET /v2/vpc_nat_gateways - Read
Retrieve an Existing VPC NAT Gateway
To show information about an individual VPC NAT gateway, send a GET request to `/v2/vpc_nat_gateways/$VPC_NAT_GATEWAY_ID`.
GET /v2/vpc_nat_gateways/{id} - Write
Create a New VPC NAT Gateway
To create a new VPC NAT gateway, send a POST request to `/v2/vpc_nat_gateways` setting the required attributes. The response body will contain a JSON object with a key called `vpc_nat_gateway` containing the standard attributes for the new VPC NAT gateway.
POST /v2/vpc_nat_gateways - Write
Update VPC NAT Gateway
To update the configuration of an existing VPC NAT Gateway, send a PUT request to `/v2/vpc_nat_gateways/$VPC_NAT_GATEWAY_ID`. The request must contain a full representation of the VPC NAT Gateway including existing attributes.
PUT /v2/vpc_nat_gateways/{id} - Destructive
Delete VPC NAT Gateway
To destroy a VPC NAT Gateway, send a DELETE request to the `/v2/vpc_nat_gateways/$VPC_NAT_GATEWAY_ID` endpoint. A successful response will include a 202 response code and no content.
DELETE /v2/vpc_nat_gateways/{id}
Uptime
- Read
List All Checks
To list all of the Uptime checks on your account, send a GET request to `/v2/uptime/checks`.
GET /v2/uptime/checks - Read
Retrieve an Existing Check
To show information about an existing check, send a GET request to `/v2/uptime/checks/$CHECK_ID`.
GET /v2/uptime/checks/{check_id} - Read
Retrieve Check State
To show information about an existing check's state, send a GET request to `/v2/uptime/checks/$CHECK_ID/state`.
GET /v2/uptime/checks/{check_id}/state - Read
List All Alerts
To list all of the alerts for an Uptime check, send a GET request to `/v2/uptime/checks/$CHECK_ID/alerts`.
GET /v2/uptime/checks/{check_id}/alerts - Read
Retrieve an Existing Alert
To show information about an existing alert, send a GET request to `/v2/uptime/checks/$CHECK_ID/alerts/$ALERT_ID`.
GET /v2/uptime/checks/{check_id}/alerts/{alert_id} - Write
Create a New Check
To create an Uptime check, send a POST request to `/v2/uptime/checks` specifying the attributes in the table below in the JSON body.
POST /v2/uptime/checks - Write
Update a Check
To update the settings of an Uptime check, send a PUT request to `/v2/uptime/checks/$CHECK_ID`.
PUT /v2/uptime/checks/{check_id} - Write
Create a New Alert
To create an Uptime alert, send a POST request to `/v2/uptime/checks/$CHECK_ID/alerts` specifying the attributes in the table below in the JSON body.
POST /v2/uptime/checks/{check_id}/alerts - Write
Update an Alert
To update the settings of an Uptime alert, send a PUT request to `/v2/uptime/checks/$CHECK_ID/alerts/$ALERT_ID`.
PUT /v2/uptime/checks/{check_id}/alerts/{alert_id} - Destructive
Delete a Check
To delete an Uptime check, send a DELETE request to `/v2/uptime/checks/$CHECK_ID`. A 204 status code with no body will be returned in response to a successful request. Deleting a check will also delete alerts associated with the check.
DELETE /v2/uptime/checks/{check_id} - Destructive
Delete an Alert
To delete an Uptime alert, send a DELETE request to `/v2/uptime/checks/$CHECK_ID/alerts/$ALERT_ID`. A 204 status code with no body will be returned in response to a successful request.
DELETE /v2/uptime/checks/{check_id}/alerts/{alert_id}
Agent Platform API
- Read
List Agents
To list all agents, send a GET request to `/v2/gen-ai/agents`.
GET /v2/gen-ai/agents - Read
List Agent API Keys
To list all agent API keys, send a GET request to `/v2/gen-ai/agents/{agent_uuid}/api_keys`.
GET /v2/gen-ai/agents/{agent_uuid}/api_keys - Read
Retrieve an Existing Agent
To retrieve details of an agent, GET request to `/v2/gen-ai/agents/{uuid}`. The response body is a JSON object containing the agent.
GET /v2/gen-ai/agents/{uuid} - Read
View Agent Routes
To view agent routes for an agent, send a GET requtest to `/v2/gen-ai/agents/{uuid}/child_agents`.
GET /v2/gen-ai/agents/{uuid}/child_agents - Read
Get Agent 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.
GET /v2/gen-ai/agents/{uuid}/usage - Read
List Agent Versions
To list all agent versions, send a GET request to `/v2/gen-ai/agents/{uuid}/versions`.
GET /v2/gen-ai/agents/{uuid}/versions - Read
List Anthropic API Keys
To list all Anthropic API keys, send a GET request to `/v2/gen-ai/anthropic/keys`.
GET /v2/gen-ai/anthropic/keys - Read
Get Anthropic API Key
To retrieve details of an Anthropic API key, send a GET request to `/v2/gen-ai/anthropic/keys/{api_key_uuid}`.
GET /v2/gen-ai/anthropic/keys/{api_key_uuid} - Read
List agents by Anthropic key
List Agents by Anthropic Key.
GET /v2/gen-ai/anthropic/keys/{uuid}/agents - Read
List Custom Models
To list custom models, send a GET request to `/v2/gen-ai/custom_models`.
GET /v2/gen-ai/custom_models - Read
Get Custom Model
To retrieve details of a custom model, send a GET request to `/v2/gen-ai/custom_models/{uuid}`.
GET /v2/gen-ai/custom_models/{uuid} - Read
List Evaluation Datasets
To list evaluation datasets, send a GET request to `/v2/gen-ai/evaluation_datasets`.
GET /v2/gen-ai/evaluation_datasets - Read
Get Download URL for Evaluation Dataset
To get a presigned download URL for an evaluation dataset, send a GET request to `/v2/genai/evaluation_datasets/{dataset_uuid}/download_url`.
GET /v2/gen-ai/evaluation_datasets/{dataset_uuid}/download_url - Read
List Evaluation Metrics
To list all evaluation metrics, send a GET request to `/v2/gen-ai/evaluation_metrics`.
GET /v2/gen-ai/evaluation_metrics - Read
Retrieve Information About an Existing Evaluation Run
To retrive information about an existing evaluation run, send a GET request to `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}`.
GET /v2/gen-ai/evaluation_runs/{evaluation_run_uuid} - Read
Retrieve Results of an Evaluation Run
To retrieve results of an evaluation run, send a GET request to `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results`.
GET /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results - Read
Retrieve Results of an Evaluation Run Prompt
To retrieve results of an evaluation run, send a GET request to `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}`.
GET /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id} - Read
List Evaluation Test Cases
To list all evaluation test cases, send a GET request to `/v2/gen-ai/evaluation_test_cases`.
GET /v2/gen-ai/evaluation_test_cases - Read
List Evaluation Runs by Test Case
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`.
GET /v2/gen-ai/evaluation_test_cases/{evaluation_test_case_uuid}/evaluation_runs - Read
Retrieve Information About an Existing Evaluation Test Case
To retrive information about an existing evaluation test case, send a GET request to `/v2/gen-ai/evaluation_test_case/{test_case_uuid}`.
GET /v2/gen-ai/evaluation_test_cases/{test_case_uuid} - Read
List Indexing Jobs for a Knowledge Base
To list all indexing jobs for a knowledge base, send a GET request to `/v2/gen-ai/indexing_jobs`.
GET /v2/gen-ai/indexing_jobs - Read
List Data Sources for Indexing Job for a Knowledge Base
To list all datasources for an indexing job, send a GET request to `/v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources`.
GET /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources - Read
Get Signed URL for Indexing Job Details
To get a signed URL for indexing job details, send a GET request to `/v2/gen-ai/indexing_jobs/{uuid}/details_signed_url`.
GET /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/details_signed_url - Read
Retrieve Status of Indexing Job for a Knowledge Base
To get status of an indexing Job for a knowledge base, send a GET request to `/v2/gen-ai/indexing_jobs/{uuid}`.
GET /v2/gen-ai/indexing_jobs/{uuid} - Read
List Knowledge Bases
To list all knowledge bases, send a GET request to `/v2/gen-ai/knowledge_bases`.
GET /v2/gen-ai/knowledge_bases - Read
List Data Sources for a Knowledge Base
To list all data sources for a knowledge base, send a GET request to `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources`.
GET /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources - Read
List Indexing Jobs for a Knowledge Base
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`.
GET /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/indexing_jobs - Read
Retrieve Information About an Existing Knowledge Base
To retrive information about an existing knowledge base, send a GET request to `/v2/gen-ai/knowledge_bases/{uuid}`.
GET /v2/gen-ai/knowledge_bases/{uuid} - Read
List Model Evaluation Metrics
To list all available metrics for model evaluation, send a GET request to `/v2/genai/model_evaluation_metrics`.
GET /v2/gen-ai/model_evaluation_metrics - Read
List Model Evaluation Presets
To list all saved model evaluation presets, send a GET request to `/v2/genai/model_evaluation_presets`.
GET /v2/gen-ai/model_evaluation_presets - Read
Retrieve Model Evaluation Preset
To retrieve a saved model evaluation preset, send a GET request to `/v2/genai/model_evaluation_presets/{eval_preset_uuid}`.
GET /v2/gen-ai/model_evaluation_presets/{eval_preset_uuid} - Read
List Model Evaluation Runs
To list model evaluation runs, send a GET request to `/v2/genai/model_evaluation_runs`.
GET /v2/gen-ai/model_evaluation_runs - Read
Retrieve Model Evaluation Run
To retrieve a model evaluation run, send a GET request to `/v2/genai/model_evaluation_runs/{eval_run_uuid}`.
GET /v2/gen-ai/model_evaluation_runs/{eval_run_uuid} - Read
Get Download URL for Model Evaluation Run Results
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`.
GET /v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/results/download_url - Read
List Available Models
To list all models, send a GET request to `/v2/gen-ai/models`.
GET /v2/gen-ai/models - Read
List Model API Keys
To list all model API keys, send a GET request to `/v2/gen-ai/models/api_keys`.
GET /v2/gen-ai/models/api_keys - Read
List Model Catalog
Returns all available models.
GET /v2/gen-ai/models/catalog - Read
Get Model Catalog Card
Returns detailed information for a specific model in the catalog including capabilities, pricing, and code examples.
GET /v2/gen-ai/models/catalog/{id} - Read
List Model Routers
To list model routers, send a GET request to `/v2/gen-ai/models/routers`.
GET /v2/gen-ai/models/routers - Read
List Model Router Presets
To list model router presets, send a GET request to `/v2/gen-ai/models/routers/presets`.
GET /v2/gen-ai/models/routers/presets - Read
List Model Router Task Presets
To list model router task presets, send a GET request to `/v2/gen-ai/models/routers/tasks/presets`.
GET /v2/gen-ai/models/routers/tasks/presets - Read
Retrieve an Existing Model Router
To retrieve details of a model router, send a GET request to `/v2/gen-ai/models/routers/{uuid}`.
GET /v2/gen-ai/models/routers/{uuid} - Read
Get 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
GET /v2/gen-ai/oauth2/url - Read
List OpenAI API Keys
To list all OpenAI API keys, send a GET request to `/v2/gen-ai/openai/keys`.
GET /v2/gen-ai/openai/keys - Read
Get OpenAI API Key
To retrieve details of an OpenAI API key, send a GET request to `/v2/gen-ai/openai/keys/{api_key_uuid}`.
GET /v2/gen-ai/openai/keys/{api_key_uuid} - Read
List agents by OpenAI key
List Agents by OpenAI Key.
GET /v2/gen-ai/openai/keys/{uuid}/agents - Read
List Datacenter Regions
To list all datacenter regions, send a GET request to `/v2/gen-ai/regions`.
GET /v2/gen-ai/regions - Read
List Common Scenario & Goal Library
To list the platform-curated Common Scenario & Goal Library, send a GET request to `/v2/gen-ai/scenario_library`.
GET /v2/gen-ai/scenario_library - Read
List Scenarios In Library Entry
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`.
GET /v2/gen-ai/scenario_library/{library_scenario_uuid}/scenarios - Read
List Scenario Sets
To list scenario sets, send a GET request to `/v2/gen-ai/scenario_sets`.
GET /v2/gen-ai/scenario_sets - Read
Retrieve Scenario Set
To retrieve a scenario set, send a GET request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}`.
GET /v2/gen-ai/scenario_sets/{scenario_set_uuid} - Read
Retrieve Scenario Set 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`.
GET /v2/gen-ai/scenario_sets/{scenario_set_uuid}/download_url - Read
List Scenarios
To list the scenarios in a scenario set, send a GET request to `/v2/gen-ai/scenario_sets/{scenario_set_uuid}/scenarios`.
GET /v2/gen-ai/scenario_sets/{scenario_set_uuid}/scenarios - Read
Get Scheduled Indexing for Knowledge Base
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}`.
GET /v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid} - Read
List Simulation Runs
To list simulation runs, send a GET request to `/v2/gen-ai/simulation_runs`.
GET /v2/gen-ai/simulation_runs - Read
Retrieve Simulation Run
To retrieve a simulation run, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}`.
GET /v2/gen-ai/simulation_runs/{run_uuid} - Read
List Simulation Episodes
To list the episodes within a simulation run, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/episodes`.
GET /v2/gen-ai/simulation_runs/{run_uuid}/episodes - Read
Retrieve Simulation Episode
To retrieve a single episode, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid}`.
GET /v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid} - Read
Retrieve Episode Trajectory
To retrieve an episode's live trajectory, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid}/trajectory`. Poll while the episode is running to watch turn-by-turn progress.
GET /v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid}/trajectory - Read
Retrieve Episode Trajectory Download URL
To retrieve a presigned download URL for an episode's trajectory, send a GET request to `/v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid}/trajectory_url`.
GET /v2/gen-ai/simulation_runs/{run_uuid}/episodes/{episode_uuid}/trajectory_url - Read
List Workspaces
To list all workspaces, send a GET request to `/v2/gen-ai/workspaces`.
GET /v2/gen-ai/workspaces - Read
Retrieve an Existing Workspace
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.
GET /v2/gen-ai/workspaces/{workspace_uuid} - Read
List agents by Workspace
To list all agents by a Workspace, send a GET request to `/v2/gen-ai/workspaces/{workspace_uuid}/agents`.
GET /v2/gen-ai/workspaces/{workspace_uuid}/agents - Read
List Evaluation Test Cases by Workspace
To list all evaluation test cases by a workspace, send a GET request to `/v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases`.
GET /v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases - Write
Create an Agent
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.
POST /v2/gen-ai/agents - Write
Create an Agent API Key
To create an agent API key, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/api_keys`.
POST /v2/gen-ai/agents/{agent_uuid}/api_keys - Write
Update API Key for an Agent
To update an agent API key, send a PUT request to `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`.
PUT /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid} - Write
Regenerate API Key for an Agent
To regenerate an agent API key, send a PUT request to `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate`.
PUT /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate - Write
Add Function Route to an Agent
To create a function route for an agent, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/functions`.
POST /v2/gen-ai/agents/{agent_uuid}/functions - Write
Update Function Route for an Agent
To update the function route, send a PUT request to `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`.
PUT /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid} - Write
Attach Guardrails to an Agent
To attach guardrails to an agent, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/guardrails`.
POST /v2/gen-ai/agents/{agent_uuid}/guardrails - Write
Attach Knowledge Bases to an Agent
To attach knowledge bases to an agent, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases`
POST /v2/gen-ai/agents/{agent_uuid}/knowledge_bases - Write
Attach Knowledge Base to an Agent
To attach a knowledge base to an agent, send a POST request to `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}`
POST /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid} - Write
Add Agent Route to an Agent
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}`.
POST /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid} - Write
Update Agent Route for an Agent
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}`.
PUT /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid} - Write
Update an Agent
To update an agent, send a PUT request to `/v2/gen-ai/agents/{uuid}`. The response body is a JSON object containing the agent.
PUT /v2/gen-ai/agents/{uuid} - Write
Update Agent Status
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`.
PUT /v2/gen-ai/agents/{uuid}/deployment_visibility - Write
Create Anthropic API Key
To create an Anthropic API key, send a POST request to `/v2/gen-ai/anthropic/keys`.
POST /v2/gen-ai/anthropic/keys - Write
Update Anthropic API Key
To update an Anthropic API key, send a PUT request to `/v2/gen-ai/anthropic/keys/{api_key_uuid}`.
PUT /v2/gen-ai/anthropic/keys/{api_key_uuid} - Write
Import Custom Model
To import a custom model, send a POST request to `/v2/gen-ai/custom_models/import`.
POST /v2/gen-ai/custom_models/import - Write
Update Custom Model Metadata
To update custom model metadata, send a PATCH request to `/v2/gen-ai/custom_models/{uuid}/metadata`.
PATCH /v2/gen-ai/custom_models/{uuid}/metadata - Write
Create Evaluation Dataset
To create an evaluation dataset, send a POST request to `/v2/gen-ai/evaluation_datasets`.
POST /v2/gen-ai/evaluation_datasets - Write
Create Presigned URLs for Evaluation Dataset File Upload
To create presigned URLs for evaluation dataset file upload, send a POST request to `/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls`.
POST /v2/gen-ai/evaluation_datasets/file_upload_presigned_urls - Write
Create Custom Evaluation Metric
To create a custom LLM-as-judge metric for model evaluation, send a POST request to `/v2/gen-ai/custom_evaluation_metrics`.
POST /v2/gen-ai/custom_evaluation_metrics - Write
Update Custom Evaluation Metric
To update a custom metric (issuing a new metric UUID), send a PUT request to `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}`.
PUT /v2/gen-ai/custom_evaluation_metrics/{metric_uuid} - Write
Run an Evaluation Test Case
To run an evaluation test case, send a POST request to `/v2/gen-ai/evaluation_runs`.
POST /v2/gen-ai/evaluation_runs - Write
Create Evaluation Test Case.
To create an evaluation test-case send a POST request to `/v2/gen-ai/evaluation_test_cases`.
POST /v2/gen-ai/evaluation_test_cases - Write
Update an Evaluation Test Case.
To update an evaluation test-case send a PUT request to `/v2/gen-ai/evaluation_test_cases/{test_case_uuid}`.
PUT /v2/gen-ai/evaluation_test_cases/{test_case_uuid} - Write
Start Indexing Job for a Knowledge Base
To start an indexing job for a knowledge base, send a POST request to `/v2/gen-ai/indexing_jobs`.
POST /v2/gen-ai/indexing_jobs - Write
Create a Knowledge Base
To create a knowledge base, send a POST request to `/v2/gen-ai/knowledge_bases`.
POST /v2/gen-ai/knowledge_bases - Write
Create Presigned URLs for Data Source File Upload
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`.
POST /v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls - Write
Add Data Source to a Knowledge Base
To add a data source to a knowledge base, send a POST request to `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources`.
POST /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources - Write
Update Data Source options
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}`.
PUT /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid} - Write
Update a Knowledge Base
To update a knowledge base, send a PUT request to `/v2/gen-ai/knowledge_bases/{uuid}`.
PUT /v2/gen-ai/knowledge_bases/{uuid} - Write
Create Presigned URLs for Model Evaluation Dataset File Upload
To create presigned URLs for model evaluation dataset file upload, send a POST request to `/v2/genai/model_evaluation/datasets/file_upload_presigned_urls`.
POST /v2/gen-ai/model_evaluation/datasets/file_upload_presigned_urls - Write
Create Model Evaluation Run
To create a model evaluation run, send a POST request to `/v2/genai/model_evaluation_runs`.
POST /v2/gen-ai/model_evaluation_runs - Write
Update Model Evaluation Run
To update a model evaluation run's display name, send a PATCH request to `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}`.
PATCH /v2/gen-ai/model_evaluation_runs/{eval_run_uuid} - Write
Create a Model API Key (deprecated)
**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`.
POST /v2/gen-ai/models/api_keys - Write
Update API Key for a Model
To update a model API key, send a PUT request to `/v2/gen-ai/models/api_keys/{api_key_uuid}`.
PUT /v2/gen-ai/models/api_keys/{api_key_uuid} - Write
Regenerate API Key for a Model
To regenerate a model API key, send a PUT request to `/v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate`.
PUT /v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate - Write
Create a Model Router
To create a model router, send a POST request to `/v2/gen-ai/models/routers`.
POST /v2/gen-ai/models/routers - Write
Update a Model Router
To update a model router, send a PUT request to `/v2/gen-ai/models/routers/{uuid}`.
PUT /v2/gen-ai/models/routers/{uuid} - Write
Get 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'
POST /v2/gen-ai/oauth2/dropbox/tokens - Write
Create OpenAI API Key
To create an OpenAI API key, send a POST request to `/v2/gen-ai/openai/keys`.
POST /v2/gen-ai/openai/keys - Write
Update OpenAI API Key
To update an OpenAI API key, send a PUT request to `/v2/gen-ai/openai/keys/{api_key_uuid}`.
PUT /v2/gen-ai/openai/keys/{api_key_uuid} - Write
Create Scenario Set From Library
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.
POST /v2/gen-ai/scenario_library/{library_scenario_uuid}/create_scenario_set - Write
Create Scenario Set
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.
POST /v2/gen-ai/scenario_sets - Write
Create Presigned URLs for Scenario Set File Upload
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`.
POST /v2/gen-ai/scenario_sets/file_upload_presigned_urls - Write
Generate Scenario Set
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.
POST /v2/gen-ai/scenario_sets/generate - Write
Duplicate Scenario Set
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.
POST /v2/gen-ai/scenario_sets/{scenario_set_uuid}/duplicate - Write
Create scheduled indexing for knowledge base
To create scheduled indexing for a knowledge base, send a POST request to `/v2/gen-ai/scheduled-indexing`.
POST /v2/gen-ai/scheduled-indexing - Write
Create Simulation Run
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.
POST /v2/gen-ai/simulation_runs - Write
Update Simulation Run
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.
PUT /v2/gen-ai/simulation_runs/{run_uuid} - Write
Create a Workspace
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.
POST /v2/gen-ai/workspaces - Write
Update a Workspace
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.
PUT /v2/gen-ai/workspaces/{workspace_uuid} - Write
Move Agents to a Workspace
To move all listed agents a given workspace, send a PUT request to `/v2/gen-ai/workspaces/{workspace_uuid}/agents`.
PUT /v2/gen-ai/workspaces/{workspace_uuid}/agents - Destructive
Delete API Key for an Agent
To delete an API key for an agent, send a DELETE request to `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`.
DELETE /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid} - Destructive
Delete Function Route for an Agent
To delete a function route from an agent, send a DELETE request to `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`.
DELETE /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid} - Destructive
Detach a Guardrail from an Agent
To detach a guardrail from an agent, send a DELETE request to `/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}`.
DELETE /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid} - Destructive
Detach Knowledge Base from an Agent
To detach a knowledge base from an agent, send a DELETE request to `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}`.
DELETE /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid} - Destructive
Delete Agent Route for an Agent
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}`.
DELETE /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid} - Destructive
Delete an Agent
To delete an agent, send a DELETE request to `/v2/gen-ai/agents/{uuid}`.
DELETE /v2/gen-ai/agents/{uuid} - Destructive
Rollback to Agent Version
To update to a specific agent version, send a PUT request to `/v2/gen-ai/agents/{uuid}/versions`.
PUT /v2/gen-ai/agents/{uuid}/versions - Destructive
Delete Anthropic API Key
To delete an Anthropic API key, send a DELETE request to `/v2/gen-ai/anthropic/keys/{api_key_uuid}`.
DELETE /v2/gen-ai/anthropic/keys/{api_key_uuid} - Destructive
Delete Custom Model
To delete a custom model, send a DELETE request to `/v2/genai/custom_models/{uuid}`.
DELETE /v2/gen-ai/custom_models/{uuid} - Destructive
Delete Evaluation Dataset
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.
DELETE /v2/gen-ai/evaluation_datasets/{dataset_uuid} - Destructive
Delete Custom Evaluation Metric
To soft-delete a custom model evaluation metric, send a DELETE request to `/v2/gen-ai/custom_evaluation_metrics/{metric_uuid}`.
DELETE /v2/gen-ai/custom_evaluation_metrics/{metric_uuid} - Destructive
Cancel Indexing Job for a Knowledge Base
To cancel an indexing job for a knowledge base, send a PUT request to `/v2/gen-ai/indexing_jobs/{uuid}/cancel`.
PUT /v2/gen-ai/indexing_jobs/{uuid}/cancel - Destructive
Delete a Data Source from a Knowledge Base
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}`.
DELETE /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid} - Destructive
Delete a Knowledge Base
To delete a knowledge base, send a DELETE request to `/v2/gen-ai/knowledge_bases/{uuid}`.
DELETE /v2/gen-ai/knowledge_bases/{uuid} - Destructive
Delete Model Evaluation Preset
To delete a saved model evaluation preset, send a DELETE request to `/v2/gen-ai/model_evaluation_presets/{eval_preset_uuid}`.
DELETE /v2/gen-ai/model_evaluation_presets/{eval_preset_uuid} - Destructive
Delete Model Evaluation Run
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.
DELETE /v2/gen-ai/model_evaluation_runs/{eval_run_uuid} - Destructive
Cancel Model Evaluation Run
To cancel an in-progress model evaluation run, send a PUT request to `/v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/cancel`.
PUT /v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/cancel - Destructive
Delete API Key for a Model
To delete an API key for a model, send a DELETE request to `/v2/gen-ai/models/api_keys/{api_key_uuid}`.
DELETE /v2/gen-ai/models/api_keys/{api_key_uuid} - Destructive
Delete a Model Router
To delete a model router, send a DELETE request to `/v2/gen-ai/models/routers/{uuid}`.
DELETE /v2/gen-ai/models/routers/{uuid} - Destructive
Delete OpenAI API Key
To delete an OpenAI API key, send a DELETE request to `/v2/gen-ai/openai/keys/{api_key_uuid}`.
DELETE /v2/gen-ai/openai/keys/{api_key_uuid} - Destructive
Update Scenario Set
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.
PUT /v2/gen-ai/scenario_sets/{scenario_set_uuid} - Destructive
Delete Scenario Set
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.
DELETE /v2/gen-ai/scenario_sets/{scenario_set_uuid} - Destructive
Delete Scheduled Indexing
Delete Scheduled Indexing for knowledge base, send a DELETE request to `/v2/gen-ai/scheduled-indexing/{uuid}`.
DELETE /v2/gen-ai/scheduled-indexing/{uuid} - Destructive
Delete Simulation Run
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.
DELETE /v2/gen-ai/simulation_runs/{run_uuid} - Destructive
Cancel Simulation Run
To cancel an in-progress simulation run, send a PATCH request to `/v2/gen-ai/simulation_runs/{run_uuid}/cancel`.
PATCH /v2/gen-ai/simulation_runs/{run_uuid}/cancel - Destructive
Delete a Workspace
To delete a workspace, send a DELETE request to `/v2/gen-ai/workspace/{workspace_uuid}`.
DELETE /v2/gen-ai/workspaces/{workspace_uuid}
Serverless Inference
- Read
List available models
Lists the currently available models, and provides basic information about each one such as the owner and availability.
GET /v1/models - Read
Retrieve a video generation job
Returns the current state of a video generation job. Poll until `status` reaches a terminal value such as `completed` or `failed`.
GET /v1/videos/{video_id} - Read
Download generated video content
Downloads the generated MP4 for a completed video generation job.
GET /v1/videos/{video_id}/content - Write
Create a model response for the given chat conversation
Creates a model response for the given chat conversation.
POST /v1/chat/completions - Write
Create the next assistant message
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
POST /v1/messages - Write
Generate images from text prompts
Creates a high-quality image from a text prompt using GPT-IMAGE-2, the latest image generation model with automatic prompt optimization and enhanced visual capabilities.
POST /v1/images/generations - Write
Create a System One evaluation
Evaluates a provided state against one or more typed questions using TypeSafe AI's Jev model. Unlike chat completion endpoints, System One returns typed answers, a truth-likelihood score, a choice from a fixed set, or a numeric score, each paired with a calibrated probability, instead of free-form text.
POST /v1/systemone - Write
Send Prompt to a Model Using the Responses API
Generate text responses from text prompts. This endpoint supports both streaming and non-streaming responses for supported text models.
POST /v1/responses - Write
Generate Image, Audio, or Text-to-Speech Using fal Models
Generate Image, Audio, or Text-to-Speech Using fal Models. This endpoint starts an asynchronous job and returns a request_id. The job status is QUEUED initially. Use the request_id to poll for the result.
POST /v1/async-invoke - Write
Generate speech from text
Convert text input to speech audio. The response may be raw audio bytes (`audio/mpeg`, `audio/wav`, and similar) or a JSON envelope with base64-encoded audio in `data[].b64_json`.
POST /v1/audio/speech - Write
Start a video generation job
Start an asynchronous video generation job from a text prompt. Poll `GET /v1/videos/{video_id}` until the job reaches a terminal status, then download the MP4 with `GET /v1/videos/{video_id}/content` or from `output.url` when present.
POST /v1/videos
Serverless Inference, Embeddings
- Write
Create embedding
Create vector embeddings for one or more text inputs. OpenAI-compatible request and response. Unknown fields in the request body are rejected. There is no streaming response for this endpoint.
POST /v1/embeddings
Agent Inference
- Write
Create a model response for the given chat conversation
Creates a model response for the given chat conversation via a customer-provisioned agent endpoint.
POST /api/v1/chat/completions
Batch Inference
- Read
List Batch Inference Jobs
Returns a cursor-paginated list of batch jobs, ordered newest first. Use `limit` to control page size and `after` to page forward using the `last_id` from the previous response.
GET /v1/batches - Read
Retrieve a Batch Inference Job
Returns the current state of a batch job. Poll until `status` reaches a terminal value (`completed`, `failed`, `expired`, or `cancelled`).
GET /v1/batches/{batch_id} - Read
Get Batch Inference Results Download Links
Returns short-lived presigned download URLs for the output (and optional error sidecar) of a completed batch job. If results are not yet ready, the response sets `result_available: false` or returns `412 Precondition Failed`; in both cases, keep polling batch status and retry. Download the artifacts soon after fetching — the URLs are short-lived. Result files themselves are retained for up to 30 days after the job completes, after which they are deleted.
GET /v1/batches/{batch_id}/results - Write
Create a Batch Inference Input File
Creates a file record and returns a `file_id` plus a short-lived presigned `PUT` URL (typically valid for ~15 minutes). Upload the raw JSONL bytes to `upload_url` (see `PUT /{upload_path}`) before calling `POST /v1/batches`.
POST /v1/batches/files - Write
Upload a Batch Inference Input File
Uploads the raw JSONL bytes to the presigned `upload_url` returned by `POST /v1/batches/files`. **The URL is dynamic — do not construct it.** Use the `upload_url` value from the previous step verbatim. Its host, path, and query parameters are part of the short-lived (~15 minute) signature and change per request; the server and path shown here are illustrative. If the URL expires before the upload completes, create a new file intent and retry. `POST /v1/batches` performs a `HEAD` check on the uploaded object and will reject the batch if this upload has not completed. Send the raw JSONL bytes verbatim. Presigned PUT URLs are signature-sensitive to request headers — prefer `application/octet-stream` or omit `Content-Type` entirely. A custom value (for example `application/jsonl`) can cause signature mismatches unless the URL was signed for that exact header.
PUT /<upload_url> - Write
Create a Batch Inference Job
Submits a batch job against a previously uploaded JSONL input file. The upload must have completed before this call; otherwise the request is rejected. Supply a unique `request_id` to make the submission idempotent — retries with the same value return the existing job. When `provider` is `openai`, the `url` on each JSONL line must match `endpoint`.
POST /v1/batches - Destructive
Cancel a Batch Inference Job
Requests cancellation of a batch job. The job transitions to `cancelling` and, once in-flight requests drain, to `cancelled`. Jobs already in a terminal state (`completed`, `failed`, `expired`, `cancelled`) cannot be cancelled and return `409 Conflict`. Cancellation is also rejected with `409 Conflict` while the job has not yet been submitted to the upstream provider — there is nothing to cancel until the provider batch id is assigned. Partial results produced before cancellation remain available via `GET /v1/batches/{batch_id}/results`.
POST /v1/batches/{batch_id}/cancel
No operations match.
See How connections work for access and permissions, or browse all integrations.