Skip to content
Changelog

Report a bug

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

    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

    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

    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

  • 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

    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

    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&region=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&region=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

See How connections work for access and permissions, or browse all integrations.