diff --git a/bun.lock b/bun.lock index 405615f..02e0a16 100644 --- a/bun.lock +++ b/bun.lock @@ -32,6 +32,7 @@ }, }, "overrides": { + "fast-uri": "3.1.2", "lodash": "4.18.1", }, "packages": { @@ -521,7 +522,7 @@ "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="], - "fast-uri": ["fast-uri@3.1.0", "", {}, "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA=="], + "fast-uri": ["fast-uri@3.1.2", "", {}, "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ=="], "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="], diff --git a/docs/developers-guide.md b/docs/developers-guide.md index 1644ee1..c6075c7 100644 --- a/docs/developers-guide.md +++ b/docs/developers-guide.md @@ -84,6 +84,20 @@ make markdownlint 2>&1 | tee /tmp/markdownlint-digitalpuddle-${BRANCH}.out make nixie 2>&1 | tee /tmp/nixie-digitalpuddle-${BRANCH}.out ``` +Refresh the pinned DigitalOcean OpenAPI artefact when intentionally updating +the public API contract: + +```bash +bun scripts/refresh-digitalocean-openapi.ts +``` + +The generated contract lives at `src/openapi/digitalocean.openapi.yaml`, and +its source, upstream commit, refresh command, response metadata, byte length, +and SHA-256 hash are recorded in +`src/openapi/digitalocean.openapi.provenance.json`. Updating the pin is a +compatibility event, so review operation-count and capability-classification +changes before committing it. + Build the package when changing the CommonJS CLI: ```bash diff --git a/docs/digitalpuddle-technical-design.md b/docs/digitalpuddle-technical-design.md index 337cd18..841f560 100755 --- a/docs/digitalpuddle-technical-design.md +++ b/docs/digitalpuddle-technical-design.md @@ -314,6 +314,11 @@ All public endpoints live under `/v2`. The implementation is contract-first: route shapes and JSON schemas come from the pinned OpenAPI spec, while behaviour is layered in selectively. +The pinned bundled contract lives at `src/openapi/digitalocean.openapi.yaml`. +Its source URL, upstream `digitalocean/openapi` commit, refresh command, +response metadata, byte length, and SHA-256 hash are recorded in +`src/openapi/digitalocean.openapi.provenance.json`. + ### 8.2 v1 vertical slice The first meaningful release targets the Nile Valley DOKS path, not the entire diff --git a/docs/execplans/1-1-3-define-the-release-capability-policy-for-operations.md b/docs/execplans/1-1-3-define-the-release-capability-policy-for-operations.md new file mode 100644 index 0000000..cdef5b1 --- /dev/null +++ b/docs/execplans/1-1-3-define-the-release-capability-policy-for-operations.md @@ -0,0 +1,697 @@ +# Define the release capability policy for operations + +This ExecPlan (execution plan) is a living document. The sections +`Constraints`, `Tolerances`, `Risks`, `Progress`, `Surprises & Discoveries`, +`Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work +proceeds. + +Status: DRAFT + +## Purpose / big picture + +DigitalPuddle cannot safely grow its DigitalOcean `/v2` surface until every +operation has a single, machine-readable release capability classification. +Roadmap task 1.1.3 defines that policy for `scriptable`, `engine-backed`, +`stubbed`, and `unsupported` operations. + +After this plan is approved and implemented, a maintainer can inspect the +operation registry and see the same capability data driving generated +capability documentation, private admin reporting, and public +`501 Not Implemented` responses. The observable success signal is that every +operation from the pinned DigitalOcean OpenAPI contract is classified exactly +once, unsupported operations return a DigitalOcean-shaped `501` envelope, and +the generated capability matrix cannot drift from runtime dispatch. + +This plan is planning-only until approved. Do not implement it until the user +explicitly approves this exact plan or an updated revision. + +## Approval gate + +This plan has two phases: + +1. Draft phase: write and review this ExecPlan only. +2. Execution phase: after explicit user approval, add the capability policy, + tests, documentation updates, roadmap update, CodeRabbit review, commits, + push, and pull request work described below. + +Silence is not approval. A future agent must not start the execution phase +until a user message explicitly approves the plan or asks for named revisions. + +## Constraints + +- Keep Simulacrum as the HTTP and routing backplane. This follows + `docs/adr/0001-simulacrum-backplane.md`. +- Keep the DigitalOcean OpenAPI pin as the public contract source of truth. + This follows `docs/adr/0002-digitalocean-openapi-pin.md`. +- Keep v1 optimized for the Nile Valley DigitalOcean Kubernetes Service (DOKS) + path, not broad DigitalOcean emulation. This follows + `docs/adr/0003-doks-first-slice.md` and + `docs/adr/0006-v1-product-boundaries.md`. +- Keep engine side effects out of public handlers. Capability policy may say + an operation is `engine-backed`, but only the worker may call k3d, MinIO, or + future engine adapters. +- Protect hexagonal boundaries: pure policy logic belongs in the OpenAPI or + domain/application boundary; HTTP handlers, admin routes, file generation, + and unsupported response writers are adapters that consume that policy. +- Do not classify private `/_digitalpuddle/*` admin routes as DigitalOcean + public operations. The release capability policy applies to public `/v2` + operations from the pinned DigitalOcean contract. +- The default for any public `/v2` operation not explicitly assigned to + `scriptable`, `engine-backed`, or `stubbed` is `unsupported`. +- Unsupported public operations must return a DigitalOcean-shaped error + response with HTTP status `501`. DigitalOcean documents error objects with + `id`, `message`, and optional `request_id`; use that shape unless the pinned + schema requires a more specific envelope. +- Do not make normal simulator operation depend on outbound calls to real + DigitalOcean. +- Documentation must use en-GB-oxendict spelling and follow + `docs/documentation-style-guide.md`. +- Run gates sequentially. Do not run format checks, lint, or tests in + parallel. +- Use `tee` for gates, so truncated terminal output can be inspected later. +- Commit only after the relevant gates pass. + +If satisfying the task requires violating any constraint, stop, record the +conflict in `Decision Log`, and ask the user how to proceed. + +## Tolerances + +- Scope: if implementation requires a broad source-layout migration beyond + `src/openapi`, narrowly needed route assembly seams, tests, and documentation, + stop and ask for approval. +- File count: if implementation needs to modify more than twelve tracked files + before generated artefacts, stop and explain why the plan no longer fits the + foundation-policy slice. +- Lines: if implementation exceeds roughly 900 net non-generated lines, stop + and split the work into a smaller policy milestone and a follow-on + integration milestone. +- Dependencies: if a new runtime dependency is required, stop and ask for + approval. Development-only dependencies are allowed only when the existing + toolchain cannot validate a required invariant. +- Public API: if the implementation must change an existing exported + TypeScript API that inherited Simulacat users may import, stop and ask for + approval. +- OpenAPI pin: if the work cannot be implemented without adding or refreshing + the pinned DigitalOcean OpenAPI artefact first, stop and either re-scope this + task into 1.3.1 or ask for approval to pull 1.3.1 forward. +- Ambiguity: if an operation could reasonably be classified in two different + non-unsupported classes and the choice changes runtime behaviour, stop and + present the options. +- Validation: if any gate still fails after two focused correction attempts, + stop with the failing log path and a concise diagnosis. +- CodeRabbit: if `coderabbit review --agent` raises a concern that requires a + design change, update this plan and wait for approval before continuing. +- Time: if one implementation stage exceeds two hours of active work, pause + and update `Progress`, `Surprises & Discoveries`, and `Decision Log` before + continuing. + +## Risks + +- Risk: task 1.3.1, the pinned DigitalOcean OpenAPI artefact, may not exist + when this task is implemented. + Severity: high. + Likelihood: medium. + Mitigation: make the policy module accept an injected operation list and add + fixture-driven tests now. Stop if a full upstream pin is required to complete + the acceptance criteria. + +- Risk: classifying capability in handlers would couple domain policy to + transport code and make generated docs drift from runtime dispatch. + Severity: high. + Likelihood: medium. + Mitigation: create a pure policy and registry module first, then make + handlers, generated docs, and admin reporting consume that same model. + +- Risk: `engine-backed` may be confused with "implemented now" even when the + engine adapter or worker milestone has not landed. + Severity: medium. + Likelihood: high. + Mitigation: store separate fields for capability class and implementation + readiness, or require every `engine-backed` operation to declare its worker + and engine dependency explicitly. + +- Risk: unsupported behaviour can accidentally become route-not-found behaviour + if the OpenAPI registry and catch-all handler are assembled separately. + Severity: high. + Likelihood: medium. + Mitigation: add a registry coverage test proving every public operation has + either a concrete handler or the shared unsupported adapter. + +- Risk: OpenAPI operation IDs can be absent, duplicated, or changed by upstream + spec evolution. + Severity: medium. + Likelihood: medium. + Mitigation: key registry records by method and normalized path, treat + `operationId` as a query alias, and fail fast on duplicate aliases. + +- Risk: property tests or formal proof could become ceremonial if the + invariants are too small or only restate implementation details. + Severity: medium. + Likelihood: medium. + Mitigation: use `fast-check` for registry invariants over generated + operation sets. Use LemmaScript only if a substantive invariant emerges, such + as total classification coverage or precedence rules that are worth proving + independent of one fixture. + +- Risk: documentation-only roadmap closure could be mistaken for the + implemented capability policy. + Severity: medium. + Likelihood: medium. + Mitigation: do not mark roadmap task 1.1.3 done until the approved + implementation lands. The planning pull request must describe itself as a + pre-implementation plan. + +## Progress + +- [x] (2026-05-11) Read repository instructions, branch state, roadmap item + 1.1.3, the technical design, current guides, Makefile, and the previous + ExecPlan. +- [x] (2026-05-11) Rename the branch to + `1-1-3-define-the-release-capability-policy-for-operations`. +- [x] (2026-05-11) Use a Wyvern agent team to gather planning briefs on + documentation, source-layout, test, and boundary risks. +- [x] (2026-05-11) Use Firecrawl to check external references for OpenAPI + extension metadata, HTTP `501` semantics, DigitalOcean error envelopes, and + LemmaScript prior art. +- [x] (2026-05-11) Draft this pre-implementation ExecPlan. +- [ ] Receive explicit user approval before implementing the capability policy. +- [ ] Add or update the architecture decision record for the capability policy + if implementation confirms that a durable policy decision is needed. +- [ ] Implement the pure capability policy and operation registry model. +- [ ] Connect generated capability documentation, admin reporting, and + unsupported response behaviour to the shared policy source. +- [ ] Add unit, behavioural, property, and any justified proof validation. +- [ ] Update relevant user, developer, design, and roadmap documentation. +- [ ] Run `make check-fmt`, `make lint`, `make test`, and any additional + Markdown or proof gates. +- [ ] Run `coderabbit review --agent` after each major implementation + milestone and clear all concerns. +- [ ] Commit each gated implementation milestone. +- [ ] Mark roadmap task 1.1.3 done only after the implemented feature passes + gates. + +## Surprises & discoveries + +- Observation: the repository still contains the inherited GitHub-oriented + TypeScript layout, and the target `src/openapi`, `src/handlers`, + `src/worker`, and `src/admin` directories do not yet exist. + Evidence: `leta files src` lists `src/rest`, `src/graphql`, and `src/store` + as the active source areas. + Impact: the first implementation should create only the minimum new + capability-policy boundary needed for this task and avoid a full layout + migration, which belongs to roadmap task 1.2.2. + +- Observation: the previous completed ExecPlan for 1.1.2 was documentation-led + and closed a decision task through ADR and guide updates. + Evidence: `docs/execplans/1-1-2-resolve-open-questions.md` records that + pattern. + Impact: task 1.1.3 is more implementation-facing than 1.1.2 because success + requires generated docs and `501` responses to share policy data. This plan + therefore includes code, test, and documentation milestones. + +- Observation: OpenAPI specification extensions are a common way to attach + non-standard metadata to operations, including operation-level fields whose + names start with `x-`. + Evidence: Swagger's OpenAPI extension documentation describes `x-` custom + properties on operations. + Impact: if DigitalPuddle writes an enriched generated OpenAPI or matrix, the + policy can use a DigitalPuddle-specific extension such as + `x-digitalpuddle-capability` without pretending it is upstream + DigitalOcean data. + +- Observation: HTTP `501` is the standards-aligned status for a server lacking + support for required request functionality. + Evidence: RFC 9110 section 15.6.2 defines `501 Not Implemented` for that + condition. + Impact: the unsupported adapter should use `501` deliberately, with the + DigitalOcean error envelope layered on top. + +- Observation: DigitalOcean documents 400 and 500 error responses as JSON + objects with `id`, `message`, and optional `request_id`. + Evidence: DigitalOcean's public API overview describes those fields. + Impact: `unsupported` responses should follow that envelope shape and should + include rate-limit headers once the shared response helpers exist. + +## Decision Log + +- Decision: this plan treats the capability policy as a domain/application + policy consumed by adapters, not as handler-local metadata. + Rationale: generated docs, admin reporting, and unsupported responses must + use one source of truth. This follows the hexagonal architecture dependency + rule and avoids route adapter drift. + Date/Author: 2026-05-11, Codex. + +- Decision: public operation records are keyed canonically by HTTP method and + normalized OpenAPI path, with `operationId` as a lookup alias. + Rationale: method and path uniquely identify dispatch. Operation IDs are + useful for generated clients and docs, but upstream specs can rename or omit + them. + Date/Author: 2026-05-11, Codex. + +- Decision: `unsupported` is an explicit classification, and also the default + for any public operation not listed in an intentional non-unsupported policy. + Rationale: DigitalPuddle must fail closed and never invent happy-path + behaviour for an unmodelled DigitalOcean route. + Date/Author: 2026-05-11, Codex. + +- Decision: the planning pull request must not mark roadmap task 1.1.3 done. + Rationale: the roadmap item's success criteria require implemented generated + docs and `501` responses. This draft only authorizes that implementation + after approval. + Date/Author: 2026-05-11, Codex. + +## Outcomes & retrospective + +This plan is still in draft. No runtime capability-policy implementation has +landed yet, and no roadmap entry should be marked done from the draft alone. + +## Context and orientation + +DigitalPuddle is a local DigitalOcean-shaped simulator being adapted from a +Simulacat Core baseline. Simulacrum is the HTTP and routing backplane: it owns +the lower-level server and routing mechanics, while DigitalPuddle supplies the +DigitalOcean-specific contract, state, handlers, worker, engines, journal, and +admin surface. + +The source of truth for product architecture is +`docs/digitalpuddle-technical-design.md`. The build order is +`docs/roadmap.md`. Durable architecture decisions live under `docs/adr/`. +Maintainer workflow rules live in `docs/developers-guide.md`, and +user-visible expectations live in `docs/users-guide.md`. + +Roadmap task 1.1.3 lives under "1.1. Close the first implementation +decisions". It cites these technical design sections: + +- section 7.1, which defines the OpenAPI operation registry and the four + capability classes; +- section 8.2, which lists the recommended v1 `/v2` endpoint matrix and the + initial class for each route in the Nile Valley DOKS path; +- section 16, which names the target repository layout, including + `src/openapi`, `src/handlers`, and `src/admin`. + +The four capability classes mean: + +- `scriptable`: the route is fully modelled using deterministic store reads, + store writes, validation, scheduling, and normal worker transitions. It does + not require direct substrate side effects from an engine adapter. +- `engine-backed`: the route is modelled by DigitalPuddle state and an + asynchronous worker, but completion requires a side effect through an engine + adapter such as k3d or MinIO. +- `stubbed`: the route intentionally returns static or lightweight data that is + useful for client compatibility, such as Kubernetes version options, without + pretending to support the full product surface. +- `unsupported`: the route is recognized as part of the public DigitalOcean + surface but intentionally unavailable in this release. It returns explicit + `501 Not Implemented` with a DigitalOcean-shaped error envelope. + +The current source tree is still transitional. `src/rest`, `src/graphql`, and +`src/store` are inherited GitHub-oriented surfaces. New DigitalPuddle work +should move toward the target layout without expanding the inherited GitHub +surface unnecessarily. + +Relevant skills for future implementation: + +- Use `leta` before source navigation and refactoring. +- Use `hexagonal-architecture` to keep pure capability policy separate from + HTTP, generated docs, and admin adapters. +- Use `zod4-typescript` if runtime validation schemas are introduced for + capability policy files, generated matrices, or admin payloads. +- Apply `pr-creation` when opening the draft pull request. +- Follow `commit-message` for file-based commit messages. + +## Plan of work + +### Stage A: confirm policy scope and create the durable decision + +Start by rereading `docs/roadmap.md`, +`docs/digitalpuddle-technical-design.md`, `docs/adr/0002-digitalocean-openapi-pin.md`, +`docs/adr/0003-doks-first-slice.md`, +`docs/adr/0004-deterministic-worker.md`, and +`docs/adr/0006-v1-product-boundaries.md`. + +If the approved implementation still confirms that the capability policy is a +durable architectural decision, add `docs/adr/0007-release-capability-policy.md`. +The ADR should record the four classes, the fail-closed default, the single +source-of-truth rule, the method-and-path canonical key, and the consequence +that generated docs and unsupported responses consume the same registry. + +End this stage by running Markdown formatting and linting for the ADR and +documentation touched so far. Run `coderabbit review --agent` if the ADR makes +or changes a material design decision. + +### Stage B: add the pure capability policy module + +Create the minimum target OpenAPI boundary, expected to be `src/openapi/`. +Add a pure module for capability types and policy rules. Suggested files are: + +- `src/openapi/capabilities.ts` for exported types such as + `CapabilityClass`, `OperationKey`, `CapabilityRecord`, and the policy + builder; +- `src/openapi/capability-policy.ts` for the v1 override table if keeping data + separate from helpers improves readability; +- `tests/openapi/capabilities.test.ts` for unit tests. + +The module should accept normalized operation metadata rather than reading +files, environment variables, or HTTP state directly. A reasonable target API +is: + +```ts +export type CapabilityClass = + | "scriptable" + | "engine-backed" + | "stubbed" + | "unsupported"; + +export type OperationKey = { + readonly method: string; + readonly path: string; +}; + +export type CapabilityRecord = OperationKey & { + readonly operationId?: string; + readonly capability: CapabilityClass; + readonly release: "v1" | "future"; + readonly source: "explicit" | "default-unsupported"; + readonly rationale: string; + readonly requiresWorker: boolean; + readonly requiresEngine: boolean; +}; +``` + +Keep this API small. If implementation needs more fields, document why in the +Decision Log before adding them. + +Tests in this stage should cover: + +- method normalization, including mixed-case methods; +- path normalization without losing OpenAPI path parameters; +- default `unsupported` classification for unlisted operations; +- duplicate method/path overrides failing fast; +- duplicate `operationId` aliases failing fast; +- class invariants, such as `engine-backed` requiring both worker and engine + flags and `scriptable` requiring neither engine side effects nor adapter + calls. + +Use `fast-check` for invariants over generated operation lists, for example: +every unique method/path input produces exactly one output record, and +permuting the input operation order does not change the sorted matrix. + +### Stage C: connect the registry to generated capability output + +Add a reproducible matrix generator or a pure projection that the later +generator and admin route can use. If the pinned DigitalOcean OpenAPI artefact +does not exist yet, use a narrow fixture that represents the section 8.2 +routes and document that full upstream coverage lands with roadmap tasks 1.3.1 +and 1.3.2. + +The generated or projected matrix should expose: + +- OpenAPI pin or fixture provenance; +- total operation count; +- counts by capability class; +- one row per operation with method, path, operation ID where available, + capability class, release status, rationale, and engine or worker + requirements. + +If the implementation writes a checked-in generated artefact, place it under a +documented path such as `docs/reference/capabilities.v1.json` only after +confirming that the repository wants generated documentation committed. If the +implementation only exposes a generator function now, document the future +checked-in artefact in `docs/developers-guide.md`. + +Tests in this stage should assert stable sorting and stable output. Snapshot +tests are acceptable only when the input fixture is small and deterministic. + +### Stage D: connect unsupported behaviour to the same policy + +Add the shared unsupported response adapter at the intended handler boundary, +expected to become `src/handlers/unsupported.ts` or a narrowly scoped +transitional route adapter if `src/handlers` does not yet exist. Do not bury +the policy inside the adapter. + +The unsupported adapter should accept a `CapabilityRecord` and produce a +DigitalOcean-shaped response with: + +- HTTP status `501`; +- JSON body with `id: "not_implemented"` or another documented + DigitalOcean-compatible identifier; +- `message` naming that the operation is unsupported by this DigitalPuddle + release; +- operation metadata only if that does not violate the public error-envelope + contract. + +If the public `/v2` route assembly does not exist yet, implement the adapter +and behavioural tests around the adapter contract rather than creating a full +HTTP backplane prematurely. If a route assembly seam already exists, add a +behavioural test proving a classified unsupported route and a registered route +with no concrete handler both return the same `501` envelope. + +### Stage E: update documentation and user-facing contracts + +Update `docs/digitalpuddle-technical-design.md` sections 7.1, 8.2, 13, 16, and +17 as needed so they describe the implemented policy. The design should say +which file or generated artefact is authoritative. + +Update `docs/developers-guide.md` with contributor rules: + +- add new public `/v2` behaviour by updating capability policy first; +- do not add a handler that lacks a capability record; +- do not mark an operation `engine-backed` unless it has an explicit worker and + engine plan; +- update generated capability output and tests when classifications change. + +Update `docs/users-guide.md` with user-facing behaviour: + +- where users can inspect capabilities when the admin route exists; +- what `scriptable`, `engine-backed`, `stubbed`, and `unsupported` mean; +- that unsupported DigitalOcean routes fail explicitly with `501`, not + silently with success. + +Update `docs/roadmap.md` to mark task 1.1.3 done only after the implemented +policy, tests, docs, and gates have landed. Do not mark it done for this +pre-implementation plan alone. + +### Stage F: final review, gating, commit, push, and pull request + +Run the full required gates sequentially. Use `/tmp` log files with the branch +name sanitized for path safety. Run CodeRabbit after each major milestone and +clear concerns before proceeding. For the final implementation branch, inspect +the full branch diff from merge base before writing the pull request body. + +Create a draft pull request using the `pr-creation` skill. The pull request +title for the pre-implementation plan should be: + +```plaintext +Define the release capability policy for operations (1.1.3) +``` + +The pull request summary must link this ExecPlan and state whether the pull +request is pre-implementation or an implementation of the approved plan. + +## Concrete steps + +Run commands from the repository root: + +```bash +cd /home/leynos/.lody/repos/github---leynos---digitalpuddle/worktrees/6d46b825-ca2a-42d5-a734-1b86cfb825c7 +``` + +Confirm branch and status: + +```bash +git branch --show-current +git status --short +``` + +Expected branch: + +```plaintext +1-1-3-define-the-release-capability-policy-for-operations +``` + +During implementation, create the policy module and tests, then run focused +tests first. The exact test names will depend on the final file layout, but +the command shape should be: + +```bash +BRANCH=$(git branch --show-current | tr '/ ' '__') +bun test --max-concurrency=1 tests/openapi/capabilities.test.ts 2>&1 | tee /tmp/test-capabilities-digitalpuddle-${BRANCH}.out +``` + +Run formatting after documentation or TypeScript edits: + +```bash +BRANCH=$(git branch --show-current | tr '/ ' '__') +bun fmt 2>&1 | tee /tmp/fmt-digitalpuddle-${BRANCH}.out +``` + +Run the required project gates sequentially: + +```bash +BRANCH=$(git branch --show-current | tr '/ ' '__') +make check-fmt 2>&1 | tee /tmp/check-fmt-digitalpuddle-${BRANCH}.out +make lint 2>&1 | tee /tmp/lint-digitalpuddle-${BRANCH}.out +make test 2>&1 | tee /tmp/test-digitalpuddle-${BRANCH}.out +``` + +Run Markdown-specific gates when documentation changes: + +```bash +BRANCH=$(git branch --show-current | tr '/ ' '__') +make markdownlint 2>&1 | tee /tmp/markdownlint-digitalpuddle-${BRANCH}.out +make nixie 2>&1 | tee /tmp/nixie-digitalpuddle-${BRANCH}.out +``` + +Run CodeRabbit review after each major milestone: + +```bash +coderabbit review --agent +``` + +Commit with a file-based commit message: + +```bash +git add docs/execplans/1-1-3-define-the-release-capability-policy-for-operations.md +COMMIT_MSG_DIR=$(mktemp -d) +cat > "$COMMIT_MSG_DIR/COMMIT_MSG.md" << 'ENDOFMSG' +Define release capability policy plan + +Add the pre-implementation ExecPlan for roadmap task 1.1.3 so +the capability policy can be reviewed before code changes land. +ENDOFMSG +git commit -F "$COMMIT_MSG_DIR/COMMIT_MSG.md" +rm -rf "$COMMIT_MSG_DIR" +``` + +Push and set upstream tracking: + +```bash +git push -u origin 1-1-3-define-the-release-capability-policy-for-operations +``` + +Create a draft pull request only after validating the branch diff and writing a +body file according to the `pr-creation` skill. + +## Validation and acceptance + +For this pre-implementation planning branch, acceptance is: + +- `docs/execplans/1-1-3-define-the-release-capability-policy-for-operations.md` + exists and is self-contained. +- The plan has an explicit approval gate and does not authorize implementation + before approval. +- The plan signposts `leta`, `hexagonal-architecture`, `zod4-typescript`, + `commit-message`, and `pr-creation` where they are relevant. +- The plan records Wyvern and Firecrawl research inputs. +- `make check-fmt`, `make lint`, and `make test` pass. +- A draft pull request is opened with `(1.1.3)` in the title and this ExecPlan + linked in the summary. + +For the future approved implementation, acceptance is: + +- Every operation in the pinned DigitalOcean OpenAPI contract is classified + exactly once by method and normalized path. +- The classification can be queried by method, path, operation ID, and + capability class. +- Generated capability output and runtime unsupported behaviour consume the + same registry data. +- Unsupported public `/v2` operations return a DigitalOcean-shaped + `501 Not Implemented` response. +- Missing classification, duplicate method/path entries, and duplicate + operation ID aliases fail fast in tests. +- Unit tests cover policy classification, lookup, and invariant checks. +- Behavioural tests cover generated matrix output and unsupported response + behaviour. +- Property tests with `fast-check` cover non-trivial registry invariants across + generated operation sets. +- A LemmaScript proof is added only if implementation introduces an axiom or + contractual invariant that benefits from proof beyond property tests. +- `docs/digitalpuddle-technical-design.md`, `docs/users-guide.md`, + `docs/developers-guide.md`, and `docs/roadmap.md` are synchronized with the + implemented behaviour. +- `make check-fmt`, `make lint`, and `make test` pass. +- `coderabbit review --agent` raises no unresolved concerns. + +## Idempotence and recovery + +The policy module should be pure and deterministic, so tests can be rerun +without environment cleanup. Generated artefacts must either be fully +reproducible or omitted from the repository until the generator is stable. + +If formatting changes touch unrelated Markdown or TypeScript files, inspect +the diff before staging and do not include unrelated churn. If a gate fails, +read the corresponding `/tmp` log, make the smallest correction, rerun only the +failed gate first, then rerun the full required gate sequence before commit. + +If a branch push fails because the remote branch does not exist, rerun the +push with `-u origin +1-1-3-define-the-release-capability-policy-for-operations`. If it fails because +the remote contains unrelated work, stop and ask before rebasing or force +pushing. + +## Artefacts and notes + +External references checked during planning: + +- Swagger OpenAPI extension documentation: specification extensions use `x-` + custom fields and are supported at the operation level. +- RFC 9110 section 15.6.2: `501 Not Implemented` is the HTTP status for a + server that lacks support for the required request functionality. +- DigitalOcean public API overview: 400 and 500 error responses use JSON error + bodies with `id`, `message`, and optional `request_id`; successful collection + responses use resource roots, `meta`, `links`, and rate-limit headers. +- LemmaScript prior art: available examples show TypeScript-adjacent formal + verification through a proof pipeline, but this task should use it only for a + substantive invariant rather than as a checkbox. + +Wyvern agent inputs incorporated into this plan: + +- Keep the registry as the single source for docs, admin reporting, and + unsupported responses. +- Prefer method/path as the canonical dispatch key and operation ID as a query + alias. +- Treat generated matrix and runtime dispatch drift as the main failure mode. +- Account for the current transitional GitHub-oriented source tree and avoid a + full repository layout migration in this task. + +## Interfaces and dependencies + +The implementation should introduce no new runtime dependency. It should use +standard TypeScript, Bun's test runner, existing project formatting and lint +tooling, and `fast-check` only if already available or approved as a +development-only dependency. + +The capability policy should expose pure functions comparable to these names: + +```ts +export function buildCapabilityRegistry( + operations: readonly OpenApiOperation[], + policy: CapabilityPolicy, +): CapabilityRegistry; + +export function getCapabilityByRoute( + registry: CapabilityRegistry, + key: OperationKey, +): CapabilityRecord | undefined; + +export function getCapabilityByOperationId( + registry: CapabilityRegistry, + operationId: string, +): CapabilityRecord | undefined; + +export function listCapabilitiesByClass( + registry: CapabilityRegistry, + capability: CapabilityClass, +): readonly CapabilityRecord[]; +``` + +The unsupported adapter should depend on `CapabilityRecord`, not on raw +OpenAPI documents or local policy tables. That boundary keeps classification +logic testable without the HTTP adapter and lets generated docs consume the +same registry. + +## Revision notes + +- 2026-05-11: Initial draft. Captures the pre-implementation plan, external + research notes, Wyvern planning inputs, approval gate, and future validation + criteria for roadmap task 1.1.3. diff --git a/docs/roadmap.md b/docs/roadmap.md index ce3572e..080d75c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -83,12 +83,13 @@ This step answers whether public routing can be driven from a pinned DigitalOcean OpenAPI contract while preserving Simulacrum as the HTTP backplane. The outcome unlocks route-level implementation and capability reporting. -- [ ] 1.3.1. Add the pinned DigitalOcean OpenAPI artefact and a repeatable +- [x] 1.3.1. Add the pinned DigitalOcean OpenAPI artefact and a repeatable refresh script with provenance. - Requires 1.1.1. - See `digitalpuddle-technical-design.md` §§4, 7.1, 8.1, and 20. - Success: the repository records the upstream source, pin, refresh command, and generated artefact hash. + - Pin: see `src/openapi/digitalocean.openapi.provenance.json`. - [ ] 1.3.2. Build the operation registry from the pinned OpenAPI contract. - Requires 1.1.3 and 1.3.1. - See `digitalpuddle-technical-design.md` §§7.1, 8.1, 8.2, and 13. diff --git a/package.json b/package.json index 71de22e..acf8266 100644 --- a/package.json +++ b/package.json @@ -97,7 +97,8 @@ "typescript": "^6.0.2" }, "overrides": { - "lodash": "4.18.1" + "lodash": "4.18.1", + "fast-uri": "3.1.2" }, "inlinedDependencies": { "starfx": "0.15.0" diff --git a/scripts/refresh-digitalocean-openapi.ts b/scripts/refresh-digitalocean-openapi.ts new file mode 100644 index 0000000..9952e3f --- /dev/null +++ b/scripts/refresh-digitalocean-openapi.ts @@ -0,0 +1,136 @@ +#!/usr/bin/env bun +/** + * @file Refreshes the pinned bundled DigitalOcean OpenAPI artefact. + * + * Downloads DigitalOcean's bundled public API v2 YAML, validates selected + * response headers for provenance, redacts webhook-shaped upstream examples, + * computes the SHA-256 hash of the checked-in artefact, and writes both + * `src/openapi/digitalocean.openapi.yaml` and + * `src/openapi/digitalocean.openapi.provenance.json`. + * + * Run `bun scripts/refresh-digitalocean-openapi.ts` when intentionally + * updating the pinned contract. The provenance records the source URL, upstream + * commit SHA, fetch timestamp, response headers, byte length, content hash, and + * redaction notes so contract updates are reproducible and reviewable. + */ + +import {execFile} from 'node:child_process'; +import {createHash} from 'node:crypto'; +import {mkdir, writeFile} from 'node:fs/promises'; +import {dirname} from 'node:path'; +import {promisify} from 'node:util'; +import {z} from 'zod'; + +const execFileAsync = promisify(execFile); + +const artefactUrl = 'https://api-engineering.nyc3.digitaloceanspaces.com/spec-ci/DigitalOcean-public.v2.yaml'; +const upstreamRepository = 'https://github.com/digitalocean/openapi.git'; +const upstreamBranch = 'main'; +const artefactPath = 'src/openapi/digitalocean.openapi.yaml'; +const provenancePath = 'src/openapi/digitalocean.openapi.provenance.json'; +const refreshCommand = 'bun scripts/refresh-digitalocean-openapi.ts'; +const redactedSecretExamples = [ + { + pattern: /https:\/\/hooks[.]slack[.]com\/services\/T00000000\/B00000000\/[A-Z]+/g, + description: 'Slack webhook placeholder with zeroed workspace and channel identifiers' + }, + { + pattern: /https:\/\/hooks[.]slack[.]com\/services\/T1234567\/AAAAAAAA\/ZZZZZZ/g, + description: 'Slack webhook placeholder with sample workspace and channel identifiers' + } +] as const; +const redactedWebhookExample = 'https://example.invalid/redacted-slack-webhook'; + +const gitLsRemoteOutputSchema = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})\s+refs\/heads\/main$/); +const fetchResponseHeadersSchema = z.object({ + contentType: z.string().nullable(), + etag: z.string().nullable(), + lastModified: z.string().nullable() +}); + +type FetchArtefactResult = { + readonly response: Response; + readonly headers: z.infer; +}; + +const now = (): string => new Date().toISOString(); + +/** + * Resolves the current upstream branch commit with `git ls-remote`. + * + * @returns The upstream commit identifier as a SHA-1 or SHA-256 hex string. + * @throws Error when `git` fails or the output does not match the expected + * branch-ref shape. + */ +async function currentUpstreamCommit(): Promise { + const {stdout} = await execFileAsync('git', ['ls-remote', upstreamRepository, `refs/heads/${upstreamBranch}`], { + encoding: 'utf8' + }); + const output = gitLsRemoteOutputSchema.parse(stdout.trim()); + const [sha] = output.split(/\s+/); + return sha; +} + +/** + * Fetches the canonical bundled DigitalOcean OpenAPI artefact. + * + * Selected response headers are validated with `fetchResponseHeadersSchema` so + * Content-Type, ETag, and Last-Modified can be recorded in provenance. + * + * @returns The fetch response and validated provenance headers. + * @throws Error when the fetch fails, the response is not OK, or response + * header validation fails. + */ +async function fetchArtefact(signal?: AbortSignal): Promise { + const response = await fetch(artefactUrl, {signal}); + if (!response.ok) { + throw new Error(`Failed to fetch ${artefactUrl}: ${response.status} ${response.statusText}`); + } + const headers = fetchResponseHeadersSchema.parse({ + contentType: response.headers.get('content-type'), + etag: response.headers.get('etag'), + lastModified: response.headers.get('last-modified') + }); + return {response, headers}; +} + +const abortController = new AbortController(); +const timeout = setTimeout(() => abortController.abort(), 30_000); +const {response, headers} = await fetchArtefact(abortController.signal); +clearTimeout(timeout); + +const sourceBytes = new Uint8Array(await response.arrayBuffer()); +const sourceText = new TextDecoder().decode(sourceBytes); +const artefactText = redactedSecretExamples.reduce( + (text, redaction) => text.replaceAll(redaction.pattern, redactedWebhookExample), + sourceText +); +const artefactBytes = new TextEncoder().encode(artefactText); +const sha256 = createHash('sha256').update(artefactBytes).digest('hex'); +const upstreamCommit = await currentUpstreamCommit(); + +await mkdir(dirname(artefactPath), {recursive: true}); +await writeFile(artefactPath, artefactBytes); + +const provenance = { + artefact: artefactPath, + sourceUrl: artefactUrl, + upstreamRepository, + upstreamBranch, + upstreamCommit, + refreshCommand, + fetchedAt: now(), + contentLength: artefactBytes.byteLength, + sha256, + redactions: redactedSecretExamples.map(({description}) => ({ + description, + replacement: redactedWebhookExample, + reason: 'Avoid committing webhook-shaped example secrets from the upstream specification.' + })), + responseHeaders: headers +} as const; + +await writeFile(provenancePath, `${JSON.stringify(provenance, null, 2)}\n`); + +console.log(`Wrote ${artefactPath} (${artefactBytes.byteLength} bytes, sha256:${sha256})`); +console.log(`Wrote ${provenancePath}`); diff --git a/src/openapi/README.md b/src/openapi/README.md new file mode 100644 index 0000000..3c66970 --- /dev/null +++ b/src/openapi/README.md @@ -0,0 +1,20 @@ +# DigitalOcean OpenAPI contract + +This directory contains the pinned, bundled DigitalOcean public API v2 +OpenAPI contract used by DigitalPuddle. + +- `digitalocean.openapi.yaml` is the bundled OpenAPI artefact fetched from + DigitalOcean's generated specification endpoint. +- `digitalocean.openapi.provenance.json` records the source URL, + upstream `digitalocean/openapi` commit, refresh command, response + metadata, byte length, and SHA-256 hash. + +Refresh the pin with: + +```bash +bun scripts/refresh-digitalocean-openapi.ts +``` + +Updating this artefact is a compatibility event. Review the operation +count, hash, and downstream capability classification changes before +committing a refreshed pin. diff --git a/src/openapi/digitalocean.openapi.provenance.json b/src/openapi/digitalocean.openapi.provenance.json new file mode 100644 index 0000000..2bf5899 --- /dev/null +++ b/src/openapi/digitalocean.openapi.provenance.json @@ -0,0 +1,28 @@ +{ + "artefact": "src/openapi/digitalocean.openapi.yaml", + "sourceUrl": "https://api-engineering.nyc3.digitaloceanspaces.com/spec-ci/DigitalOcean-public.v2.yaml", + "upstreamRepository": "https://github.com/digitalocean/openapi.git", + "upstreamBranch": "main", + "upstreamCommit": "781eb485d1136605e02178f9c48a48fd679eb242", + "refreshCommand": "bun scripts/refresh-digitalocean-openapi.ts", + "fetchedAt": "2026-05-14T21:45:08.083Z", + "contentLength": 2927232, + "sha256": "604848f4ec226b1fea2be80552c3e501c5b3e695c3cc5dfc077450101f8bd1ba", + "redactions": [ + { + "description": "Slack webhook placeholder with zeroed workspace and channel identifiers", + "replacement": "https://example.invalid/redacted-slack-webhook", + "reason": "Avoid committing webhook-shaped example secrets from the upstream specification." + }, + { + "description": "Slack webhook placeholder with sample workspace and channel identifiers", + "replacement": "https://example.invalid/redacted-slack-webhook", + "reason": "Avoid committing webhook-shaped example secrets from the upstream specification." + } + ], + "responseHeaders": { + "contentType": "application/yaml", + "etag": "\"bf6c729dd0cf8eea6a9c8a666ca92e41\"", + "lastModified": "Thu, 14 May 2026 16:03:32 GMT" + } +} diff --git a/src/openapi/digitalocean.openapi.yaml b/src/openapi/digitalocean.openapi.yaml new file mode 100644 index 0000000..1efa3cb --- /dev/null +++ b/src/openapi/digitalocean.openapi.yaml @@ -0,0 +1,86089 @@ +openapi: 3.0.0 +info: + title: DigitalOcean API + version: '2.0' + description: '' + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + contact: + name: DigitalOcean API Team + email: api-engineering@digitalocean.com + termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/ +servers: + - url: https://api.digitalocean.com + description: production +tags: + - name: Public APIs Introduction + x-displayName: Introduction + x-traitTag: true + description: > + The DigitalOcean API allows you to manage Droplets and resources within + the + + DigitalOcean cloud in a simple, programmatic way using conventional HTTP + requests. + + + All of the functionality that you are familiar with in the DigitalOcean + + control panel is also available through the API, allowing you to script + the + + complex actions that your situation requires. + + + The API documentation will start with a general overview about the design + + and technology that has been implemented, followed by reference + information + + about specific endpoints. + + + ## Requests + + + Any tool that is fluent in HTTP can communicate with the API simply by + + requesting the correct URI. Requests should be made using the HTTPS + protocol + + so that traffic is encrypted. The interface responds to different methods + + depending on the action required. + + + |Method|Usage| + + |--- |--- | + + |GET|For simple retrieval of information about your account, Droplets, or + environment, you should use the GET method. The information you request + will be returned to you as a JSON object. The attributes defined by the + JSON object can be used to form additional requests. Any request using + the GET method is read-only and will not affect any of the objects you are + querying.| + + |DELETE|To destroy a resource and remove it from your account and + environment, the DELETE method should be used. This will remove the + specified object if it is found. If it is not found, the operation will + return a response indicating that the object was not found. This + idempotency means that you do not have to check for a resource's + availability prior to issuing a delete command, the final state will be + the same regardless of its existence.| + + |PUT|To update the information about a resource in your account, the PUT + method is available. Like the DELETE Method, the PUT method is + idempotent. It sets the state of the target using the provided values, + regardless of their current values. Requests using the PUT method do not + need to check the current attributes of the object.| + + |PATCH|Some resources support partial modification. In these cases, the + PATCH method is available. Unlike PUT which generally requires a complete + representation of a resource, a PATCH request is a set of instructions on + how to modify a resource updating only specific attributes.| + + |POST|To create a new object, your request should specify the POST method. + The POST request includes all of the attributes necessary to create a new + object. When you wish to create a new object, send a POST request to the + target endpoint.| + + |HEAD|Finally, to retrieve metadata information, you should use the HEAD + method to get the headers. This returns only the header of what would be + returned with an associated GET request. Response headers contain some + useful information about your API access and the results that are + available for your request. For instance, the headers contain your current + rate-limit value and the amount of time available until the limit resets. + It also contains metrics about the total number of objects found, + pagination information, and the total content length.| + + + + ## HTTP Statuses + + + Along with the HTTP methods that the API responds to, it will also return + + standard HTTP statuses, including error codes. + + + In the event of a problem, the status will contain the error code, while + the + + body of the response will usually contain additional information about the + + problem that was encountered. + + + In general, if the status returned is in the 200 range, it indicates that + + the request was fulfilled successfully and that no error was encountered. + + + Return codes in the 400 range typically indicate that there was an issue + + with the request that was sent. Among other things, this could mean that + you + + did not authenticate correctly, that you are requesting an action that you + + do not have authorization for, that the object you are requesting does not + + exist, or that your request is malformed. + + + If you receive a status in the 500 range, this generally indicates a + + server-side problem. This means that we are having an issue on our end and + + cannot fulfill your request currently. + + + 400 and 500 level error responses will include a JSON object in their + body, + + including the following attributes: + + + |Name|Type|Description| + + |--- |--- |--- | + + |id|string|A short identifier corresponding to the HTTP status code + returned. For example, the ID for a response returning a 404 status code + would be "not_found."| + + |message|string|A message providing additional information about the + error, including details to help resolve it when possible.| + + |request_id|string|Optionally, some endpoints may include a request ID + that should be provided when reporting bugs or opening support tickets to + help identify the issue.| + + + ### Example Error Response + + + ``` + HTTP/1.1 403 Forbidden + { + "id": "forbidden", + "message": "You do not have access for the attempted action." + } + ``` + + + ## Responses + + + When a request is successful, a response body will typically be sent back + in + + the form of a JSON object. An exception to this is when a DELETE request + is + + processed, which will result in a successful HTTP 204 status and an empty + + response body. + + + Inside of this JSON object, the resource root that was the target of the + + request will be set as the key. This will be the singular form of the word + + if the request operated on a single object, and the plural form of the + word + + if a collection was processed. + + + For example, if you send a GET request to `/v2/droplets/$DROPLET_ID` you + + will get back an object with a key called "`droplet`". However, if you + send + + the GET request to the general collection at `/v2/droplets`, you will get + + back an object with a key called "`droplets`". + + + The value of these keys will generally be a JSON object for a request on a + + single object and an array of objects for a request on a collection of + + objects. + + + ### Response for a Single Object + + + ```json + { + "droplet": { + "name": "example.com" + . . . + } + } + ``` + + + ### Response for an Object Collection + + + ```json + { + "droplets": [ + { + "name": "example.com" + . . . + }, + { + "name": "second.com" + . . . + } + ] + } + ``` + + + ## Meta + + + In addition to the main resource root, the response may also contain a + + `meta` object. This object contains information about the response itself. + + + The `meta` object contains a `total` key that is set to the total number + of + + objects returned by the request. This has implications on the `links` + object + + and pagination. + + + The `meta` object will only be displayed when it has a value. Currently, + the + + `meta` object will have a value when a request is made on a collection + (like + + `droplets` or `domains`). + + + + ### Sample Meta Object + + + ```json + { + . . . + "meta": { + "total": 43 + } + . . . + } + ``` + + + ## Links & Pagination + + + The `links` object is returned as part of the response body when + pagination + + is enabled. By default, 20 objects are returned per page. If the response + + contains 20 objects or fewer, no `links` object will be returned. If the + + response contains more than 20 objects, the first 20 will be returned + along + + with the `links` object. + + + You can request a different pagination limit or force pagination by + + appending `?per_page=` to the request with the number of items you would + + like per page. For instance, to show only two results per page, you could + + add `?per_page=2` to the end of your query. The maximum number of results + + per page is 200. + + + The `links` object contains a `pages` object. The `pages` object, in turn, + + contains keys indicating the relationship of additional pages. The values + of + + these are the URLs of the associated pages. The keys will be one of the + + following: + + + * **first**: The URI of the first page of results. + + * **prev**: The URI of the previous sequential page of results. + + * **next**: The URI of the next sequential page of results. + + * **last**: The URI of the last page of results. + + + The `pages` object will only include the links that make sense. So for the + + first page of results, no `first` or `prev` links will ever be set. This + + convention holds true in other situations where a link would not make + sense. + + + ### Sample Links Object + + + ```json + { + . . . + "links": { + "pages": { + "last": "https://api.digitalocean.com/v2/images?page=2", + "next": "https://api.digitalocean.com/v2/images?page=2" + } + } + . . . + } + ``` + + + ## Rate Limit + + + Requests through the API are rate limited per OAuth token. Current rate + limits: + + + * 5,000 requests per hour + + * 250 requests per minute (5% of the hourly total) + + + Once you exceed either limit, you will be rate limited until the next + cycle + + starts. Space out any requests that you would otherwise issue in bursts + for + + the best results. + + + The rate limiting information is contained within the response headers of + + each request. The relevant headers are: + + + * **ratelimit-limit**: The number of requests that can be made per hour. + + * **ratelimit-remaining**: The number of requests that remain before you + hit your request limit. See the information below for how the request + limits expire. + + * **ratelimit-reset**: This represents the time when the oldest request + will expire. The value is given in [Unix epoch + time](http://en.wikipedia.org/wiki/Unix_time). See below for more + information about how request limits expire. + + + More rate limiting information is returned only within burst limit error + response headers: + + * **retry-after**: The number of seconds to wait before making another + request when rate limited. + + + As long as the `ratelimit-remaining` count is above zero, you will be able + + to make additional requests. + + + The way that a request expires and is removed from the current limit count + + is important to understand. Rather than counting all of the requests for + an + + hour and resetting the `ratelimit-remaining` value at the end of the hour, + + each request instead has its own timer. + + + This means that each request contributes toward the `ratelimit-remaining` + + count for one complete hour after the request is made. When that request's + + timer runs out, it is no longer counted towards the request limit. + + + This has implications on the meaning of the `ratelimit-reset` header as + + well. Because the entire rate limit is not reset at one time, the value of + + this header is set to the time when the _oldest_ request will expire. + + + Keep this in mind if you see your `ratelimit-reset` value change, but not + + move an entire hour into the future. + + + If the `ratelimit-remaining` reaches zero, subsequent requests will + receive + + a 429 error code until the request reset has been reached. + + + `ratelimit-remaining` reaching zero can also indicate that the "burst + limit" of 250 + + requests per minute limit was met, even if the 5,000 requests per hour + limit was not. + + In this case, the 429 error response will include a `retry-after` header + to indicate how + + long to wait (in seconds) until the request may be retried. + + + You can see the format of the response in the examples. + + + **Note:** The following endpoints have special rate limit requirements + that + + are independent of the limits defined above. + + + * Only 10 `GET` requests to the `/v2/account/keys` endpoint to list SSH + keys can be made per 60 seconds. + + * Only 5 requests to any and all `v2/cdn/endpoints` can be made per 10 + seconds. This includes `v2/cdn/endpoints`, + `v2/cdn/endpoints/$ENDPOINT_ID`, and `v2/cdn/endpoints/$ENDPOINT_ID/cache`. + * Only 50 strings within the `files` json struct in the + `v2/cdn/endpoints/$ENDPOINT_ID/cache` + [payload](https://docs.digitalocean.com/reference/api/api-reference/#operation/cdn_purge_cache) + can be requested every 20 seconds. + + ### Sample Rate Limit Headers + + + ``` + . . . + ratelimit-limit: 1200 + ratelimit-remaining: 1193 + rateLimit-reset: 1402425459 + . . . + ``` + + ### Sample Rate Limit Headers When Burst Limit is Reached: + + ``` + . . . + ratelimit-limit: 5000 + ratelimit-remaining: 0 + rateLimit-reset: 1402425459 + retry-after: 29 + . . . + ``` + + + ### Sample Rate Exceeded Response + + + ``` + 429 Too Many Requests + { + id: "too_many_requests", + message: "API Rate limit exceeded." + } + ``` + + + ## Curl Examples + + + Throughout this document, some example API requests will be given using + the + + `curl` command. This will allow us to demonstrate the various endpoints in + a + + simple, textual format. + + These examples assume that you are using a Linux or macOS command line. To run + these commands on a Windows machine, you can either use cmd.exe, + PowerShell, or WSL: + + + * For cmd.exe, use the `set VAR=VALUE` + [syntax](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) + + to define environment variables, call them with `%VAR%`, then replace all + backslashes (`\`) in the examples with carets (`^`). + + + * For PowerShell, use the `$Env:VAR = "VALUE"` + [syntax](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2) + + to define environment variables, call them with `$Env:VAR`, then replace + `curl` with `curl.exe` and all backslashes (`\`) in the examples with + backticks (`` ` ``). + + + * WSL is a compatibility layer that allows you to emulate a Linux terminal + on a Windows machine. + + Install WSL with our [community + tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-the-windows-subsystem-for-linux-2-on-microsoft-windows-10), + + then follow this API documentation normally. + + + The names of account-specific references (like Droplet IDs, for instance) + + will be represented by variables. For instance, a Droplet ID may be + + represented by a variable called `$DROPLET_ID`. You can set the associated + + variables in your environment if you wish to use the examples without + + modification. + + + The first variable that you should set to get started is your OAuth + + authorization token. The next section will go over the details of this, + but + + you can set an environmental variable for it now. + + + Generate a token by going to the [Apps & + API](https://cloud.digitalocean.com/settings/applications) + + section of the DigitalOcean control panel. Use an existing token if you + have + + saved one, or generate a new token with the "Generate new token" button. + + Copy the generated token and use it to set and export the TOKEN variable + in + + your environment as the example shows. + + + You may also wish to set some other variables now or as you go along. For + + example, you may wish to set the `DROPLET_ID` variable to one of your + + Droplet IDs since this will be used frequently in the API. + + + If you are following along, make sure you use a Droplet ID that you + control + + so that your commands will execute correctly. + + + If you need access to the headers of a response through `curl`, you can + pass + + the `-i` flag to display the header information along with the body. If + you + + are only interested in the header, you can instead pass the `-I` flag, + which + + will exclude the response body entirely. + + + + ### Set and Export your OAuth Token + + + ``` + + export DIGITALOCEAN_TOKEN=your_token_here + + ``` + + + ### Set and Export a Variable + + + ``` + + export DROPLET_ID=1111111 + + ``` + + + ## Parameters + + + There are two different ways to pass parameters in a request with the API. + + + When passing parameters to create or update an object, parameters should + be + + passed as a JSON object containing the appropriate attribute names and + + values as key-value pairs. When you use this format, you should specify + that + + you are sending a JSON object in the header. This is done by setting the + + `Content-Type` header to `application/json`. This ensures that your + request + + is interpreted correctly. + + + When passing parameters to filter a response on GET requests, parameters + can + + be passed using standard query attributes. In this case, the parameters + + would be embedded into the URI itself by appending a `?` to the end of the + + URI and then setting each attribute with an equal sign. Attributes can be + + separated with a `&`. Tools like `curl` can create the appropriate URI + when + + given parameters and values; this can also be done using the `-F` flag and + + then passing the key and value as an argument. The argument should take + the + + form of a quoted string with the attribute being set to a value with an + + equal sign. + + + ### Pass Parameters as a JSON Object + + + ``` + curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name": "example.com", "ip_address": "127.0.0.1"}' \ + -X POST "https://api.digitalocean.com/v2/domains" + ``` + + + ### Pass Filter Parameters as a Query String + + + ``` + curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -X GET \ + "https://api.digitalocean.com/v2/images?private=true" + ``` + + + ## Cross Origin Resource Sharing + + + In order to make requests to the API from other domains, the API + implements + + Cross Origin Resource Sharing (CORS) support. + + + CORS support is generally used to create AJAX requests outside of the + domain + + that the request originated from. This is necessary to implement projects + + like control panels utilizing the API. This tells the browser that it can + + send requests to an outside domain. + + + The procedure that the browser initiates in order to perform these actions + + (other than GET requests) begins by sending a "preflight" request. This + sets + + the `Origin` header and uses the `OPTIONS` method. The server will reply + + back with the methods it allows and some of the limits it imposes. The + + client then sends the actual request if it falls within the allowed + + constraints. + + + This process is usually done in the background by the browser, but you can + + use curl to emulate this process using the example provided. The headers + + that will be set to show the constraints are: + + + * **Access-Control-Allow-Origin**: This is the domain that is sent by + the client or browser as the origin of the request. It is set through an + `Origin` header. + + * **Access-Control-Allow-Methods**: This specifies the allowed options + for requests from that domain. This will generally be all available + methods. + + * **Access-Control-Expose-Headers**: This will contain the headers that + will be available to requests from the origin domain. + + * **Access-Control-Max-Age**: This is the length of time that the access + is considered valid. After this expires, a new preflight should be sent. + + * **Access-Control-Allow-Credentials**: This will be set to `true`. It + basically allows you to send your OAuth token for authentication. + + + You should not need to be concerned with the details of these headers, + + because the browser will typically do all of the work for you. + - name: 1-Click Applications + description: >- + 1-Click applications are pre-built Droplet images or Kubernetes apps with + software, + + features, and configuration details already set up for you. They can be + found in the + + [DigitalOcean Marketplace](https://marketplace.digitalocean.com/). + - name: Account + description: Provides information about your current account. + - name: Actions + description: >- + Actions are records of events that have occurred on the resources in your + account. + + These can be things like rebooting a Droplet, or transferring an image to + a new region. + + + An action object is created every time one of these actions is initiated. + The action + + object contains information about the current status of the action, start + and complete + + timestamps, and the associated resource type and ID. + + + Every action that creates an action object is available through this + endpoint. Completed + + actions are not removed from this list and are always available for + querying. + + + **Note:** You can pass the following HTTP header with the request to have + the API return + + the `reserved_ips` stanza instead of the `floating_ips` stanza: + + + - `Accept: application/vnd.digitalocean.reserveip+json` + - name: Add-Ons + description: >- + Add-ons are third-party applications that can be added to your + DigitalOcean account. + + They are available through the [DigitalOcean + Marketplace](https://marketplace.digitalocean.com/). + + Add-ons can be used to enhance the functionality of your existing + resources or to provide + + additional services. + + + The Add-Ons API allows you to manage these resources, including creating, + listing, and retrieving + + details about specific add-on resources. + - name: Apps + description: >- + App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean + that allows + + developers to publish code directly to DigitalOcean servers without + worrying about the + + underlying infrastructure. + + + Most API operations are centered around a few core object types. Following + are the + + definitions of these types. These definitions will be omitted from the + operation-specific + + documentation. + + + For documentation on app specifications (`AppSpec` objects), please refer + to the + + [product + documentation](https://docs.digitalocean.com/products/app-platform/reference/app-spec/)). + - name: Billing + description: >- + The billing endpoints allow you to retrieve your account balance, + invoices, + + billing history, and insights. + + + **Balance:** By sending requests to the `/v2/customers/my/balance` + endpoint, you can + + retrieve the balance information for the requested customer account. + + + **Invoices:** + [Invoices](https://docs.digitalocean.com/platform/billing/invoices/) + + are generated on the first of each month for every DigitalOcean + + customer. An invoice preview is generated daily, which can be accessed + + with the `preview` keyword in place of `$INVOICE_UUID`. To interact with + + invoices, you will generally send requests to the invoices endpoint at + + `/v2/customers/my/invoices`. + + + **Billing History:** Billing history is a record of billing events for + your account. + + For example, entries may include events like payments made, invoices + + issued, or credits granted. To interact with invoices, you + + will generally send requests to the invoices endpoint at + + `/v2/customers/my/billing_history`. + + + **Billing Insights:** 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 items do not necessarily encompass all + invoicing factors for the entire month. + `v2/billing/{account_urn}/insights/{start_date}/{end_date}` where account_urn is the URN of the customer + account, can be a team (do:team:uuid) or an organization + (do:teamgroup:uuid). The date range specified by + + start_date and end_date must be in YYYY-MM-DD format. + - name: Block Storage + description: >- + [DigitalOcean Block Storage + Volumes](https://docs.digitalocean.com/products/volumes/) + + provide expanded storage capacity for your Droplets and can be moved + + between Droplets within a specific region. + + + Volumes function as raw block devices, meaning they appear to the + + operating system as locally attached storage which can be formatted using + + any file system supported by the OS. They may be created in sizes from + + 1GiB to 16TiB. + + + By sending requests to the `/v2/volumes` endpoint, you can list, create, + or + + delete volumes as well as attach and detach them from Droplets + - name: Block Storage Actions + description: |- + Block storage actions are commands that can be given to a DigitalOcean + Block Storage Volume. An example would be detaching or attaching a volume + from a Droplet. These requests are made on the + `/v2/volumes/$VOLUME_ID/actions` endpoint. + + An action object is returned. These objects hold the current status of the + requested action. + - name: BYOIP Prefixes + description: >- + Bring your own IP (BYOIP) lets you provision your own IPv4 network + prefixes + + to your account, then assign those IPs to your DigitalOcean resources. + + BYOIP supports the following features: + + * IPv4 addresses + + * Network sizes of anywhere from `/24` (256 addresses) to `/18` (16,384 + addresses) + + * Same API and management interface as our existing reserved IPs feature + + * Assignable to Droplets only + - name: CDN Endpoints + description: |- + Content hosted in DigitalOcean's object storage solution, + [Spaces](https://docs.digitalocean.com/products/spaces/), + can optionally be served by our globally distributed Content Delivery + Network (CDN). By sending requests to `/v2/cdn/endpoints`, you can list, + create, or delete CDN Endpoints as well as purge cached content. To use a + custom subdomain to access the CDN Endpoint, provide the ID of a + DigitalOcean managed TLS certificate and the fully qualified domain name + for the custom subdomain. + + CDN endpoints have a rate limit of five requests per 10 seconds. + - name: Certificates + description: >- + In order to perform SSL termination on load balancers, DigitalOcean offers + + two types of [SSL certificate + management](https://docs.digitalocean.com/platform/teams/manage-certificates): + + + * **Custom**: User-generated certificates may be uploaded to DigitalOcean + + where they will be placed in a fully encrypted and isolated storage + system. + + + * **Let's Encrypt**: Certificates may be automatically generated by + + DigitalOcean utilizing an integration with Let's Encrypt, the free and + + open certificate authority. These certificates will also be automatically + + renewed as required. + - name: Container Registry + description: >- + DigitalOcean offers the ability for you to create a + + [private container + registry](https://docs.digitalocean.com/products/container-registry/) + + to store your Docker images for use with your Kubernetes clusters. This + + container registry runs inside the same datacenters as your cluster, + + ensuring reliable and performant rollout of image deployments. + + + You can only create one registry per DigitalOcean account, but you can use + + that registry to create as many repositories as you wish. + - name: Container Registries + description: >- + DigitalOcean now supports up to nine additional registries (for a total + maximum of 10) per team + + if your container registry uses the Professional subscription plan. The + storage is shared among + + the registries. This set of new APIs is backward compatible with + `/v2/registry`. However, if you + + create more than one registry under a Professional plan, some of the + `/v2/registry` APIs would not work. + + Hence, it is recommended to use `/v2/registries` for multiple registries. + - name: Databases + description: >- + DigitalOcean's [managed database + service](https://docs.digitalocean.com/products/databases) + + simplifies the creation and management of highly available database + clusters. Currently, it + + offers support for + [PostgreSQL](http://docs.digitalocean.com/products/databases/postgresql/), + + [Caching](https://docs.digitalocean.com/products/databases/redis/), + + [Valkey](https://docs.digitalocean.com/products/databases/valkey/), + + [MySQL](https://docs.digitalocean.com/products/databases/mysql/), + + [MongoDB](https://docs.digitalocean.com/products/databases/mongodb/), and + + [OpenSearch](https://docs.digitalocean.com/products/databases/opensearch/). + + + By sending requests to the `/v2/databases` endpoint, you can list, create, + or delete + + database clusters as well as scale the size of a cluster, add or remove + read-only replicas, + + and manage other configuration details. + + + Database clusters may be deployed in a multi-node, high-availability + configuration. + + If your machine type is above the basic nodes, your node plan is above the + smallest option, + + or you are running MongoDB, you may additionally include up to two standby + nodes in your cluster. + + + The size of individual nodes in a database cluster is represented by a + human-readable slug, + + which is used in some of the following requests. Each slug denotes the + node's identifier, + + CPU count, and amount of RAM, in that order. + + + For a list of currently available database slugs and options, use the + `/v2/databases/options` endpoint or use the + + `doctl databases options` + [command](https://docs.digitalocean.com/reference/doctl/reference/databases/options). + - name: Dedicated Inference + description: >- + [Dedicated + Inference](https://docs.digitalocean.com/products/agent-platform/dedicated-inference/) + + delivers scalable production-grade LLM hosting on DigitalOcean. Create, + list, get, update, + + and delete Dedicated Inference instances; manage accelerators, CA + certificate, sizes, + + GPU model config, and access tokens. + - name: Domain Records + description: >- + Domain record resources are used to set or retrieve information about the + + individual DNS records configured for a domain. This allows you to build + + and manage DNS zone files by adding and modifying individual records for a + + domain. + + + The [DigitalOcean DNS management + interface](https://docs.digitalocean.com/products/networking/dns/) + + allows you to configure the following DNS records: + + + Name | + Description + | + + ------|----------------------------------------------------------------------------------------------------------------------------------------------------| + + A | This record type is used to map an IPv4 address to a + hostname. + | + + AAAA | This record type is used to map an IPv6 address to a + hostname. + | + + CAA | As specified in RFC-6844, this record type can be used to restrict + which certificate authorities are permitted to issue certificates for a + domain. | + + CNAME | This record type defines an alias for your canonical hostname (the + one defined by an A or AAAA + record). | + + MX | This record type is used to define the mail exchanges used for the + domain. + | + + NS | This record type defines the name servers that are used for this + zone. + | + + TXT | This record type is used to associate a string of text with a + hostname, primarily used for + verification. | + + SRV | This record type specifies the location (hostname and port number) + of servers for specific + services. | + + SOA | This record type defines administrative information about the + zone. Can only have ttl changed, cannot be + deleted | + - name: Domains + description: >- + Domain resources are domain names that you have purchased from a domain + + name registrar that you are managing through the + + [DigitalOcean DNS + interface](https://docs.digitalocean.com/products/networking/dns/). + + + This resource establishes top-level control over each domain. Actions that + + affect individual domain records should be taken on the + + [Domain Records](#tag/Domain-Records) resource. + - name: Droplet Actions + description: |- + Droplet actions are tasks that can be executed on a Droplet. These can be + things like rebooting, resizing, snapshotting, etc. + + Droplet action requests are generally targeted at one of the "actions" + endpoints for a specific Droplet. The specific actions are usually + initiated by sending a POST request with the action and arguments as + parameters. + + Droplet action requests create a Droplet actions object, which can be used + to get information about the status of an action. Creating a Droplet + action is asynchronous: the HTTP call will return the action object before + the action has finished processing on the Droplet. The current status of + an action can be retrieved from either the Droplet actions endpoint or the + global actions endpoint. If a Droplet action is uncompleted it may block + the creation of a subsequent action for that Droplet, the locked attribute + of the Droplet will be true and attempts to create a Droplet action will + fail with a status of 422. + - name: Droplets + description: >- + A [Droplet](https://docs.digitalocean.com/products/droplets/) is a + DigitalOcean + + virtual machine. By sending requests to the Droplet endpoint, you can + + list, create, or delete Droplets. + + + Some of the attributes will have an object value. The `region` and `image` + + objects will all contain the standard attributes of their associated + + types. Find more information about each of these objects in their + + respective sections. + - name: Droplet Autoscale Pools + description: >- + Droplet autoscale pools manage automatic horizontal scaling for your + applications based on resource usage (CPU, memory, or both) or a static + configuration. + - name: Embeddings + description: >- + Text embedding vectors via `POST /v1/embeddings` on the + + [Serverless + Inference](https://docs.digitalocean.com/reference/api/api-reference/#tag/Serverless-Inference) + base URL + + `https://inference.do-ai.run` (bearer model access key). + - name: Firewalls + description: >- + [DigitalOcean Cloud + Firewalls](https://docs.digitalocean.com/products/networking/firewalls/) + + provide the ability to restrict network access to and from a Droplet + + allowing you to define which ports will accept inbound or outbound + + connections. By sending requests to the `/v2/firewalls` endpoint, you can + + list, create, or delete firewalls as well as modify access rules. + - name: Floating IP Actions + description: >- + As of 16 June 2022, we have renamed the Floating IP product to [Reserved + IPs](https://docs.digitalocean.com/reference/api/api-reference/#tag/Reserved-IPs). + + The Reserved IP product's endpoints function the exact same way as + Floating IPs. + + The only difference is the name change throughout the URLs and fields. + + For example, the `floating_ips` field is now the `reserved_ips` field. + + The Floating IP endpoints will remain active until fall 2023 before being + + permanently deprecated. + + + With the exception of the [Projects + API](https://docs.digitalocean.com/reference/api/api-reference/#tag/Projects), + + we will reflect this change as an additional field in the responses across + the API + + where the `floating_ip` field is used. For example, the Droplet metadata + response + + will contain the field `reserved_ips` in addition to the `floating_ips` + field. + + Floating IPs retrieved using the Projects API will retain the original + name. + + + Floating IP actions are commands that can be given to a DigitalOcean + + floating IP. These requests are made on the actions endpoint of a specific + + floating IP. + + + An action object is returned. These objects hold the current status of the + + requested action. + - name: Floating IPs + description: >- + As of 16 June 2022, we have renamed the Floating IP product to [Reserved + IPs](https://docs.digitalocean.com/reference/api/api-reference/#tag/Reserved-IPs). + + The Reserved IP product's endpoints function the exact same way as + Floating IPs. + + The only difference is the name change throughout the URLs and fields. + + For example, the `floating_ips` field is now the `reserved_ips` field. + + The Floating IP endpoints will remain active until fall 2023 before being + + permanently deprecated. + + + With the exception of the [Projects + API](https://docs.digitalocean.com/reference/api/api-reference/#tag/Projects), + + we will reflect this change as an additional field in the responses across + the API + + where the `floating_ip` field is used. For example, the Droplet metadata + response + + will contain the field `reserved_ips` in addition to the `floating_ips` + field. + + Floating IPs retrieved using the Projects API will retain the original + name. + + + [DigitalOcean Floating + IPs](https://docs.digitalocean.com/products/networking/reserved-ips/) + + are publicly-accessible static IP addresses that can be mapped to one of + + your Droplets. They can be used to create highly available setups or other + + configurations requiring movable addresses. + + + Floating IPs are bound to a specific region. + - name: Functions + description: >- + [Serverless functions](https://docs.digitalocean.com/products/functions) + are blocks of code that run on demand without the need to manage any + infrastructure. + + You can develop functions on your local machine and then deploy them to a + namespace using `doctl`, the [official DigitalOcean CLI + tool](https://docs.digitalocean.com/reference/doctl). + + + The Serverless Functions API currently only supports creating and managing + namespaces. + - name: GradientAI Platform + description: >- + The API lets you build GPU-powered AI agents with pre-built or custom + foundation models, function and agent routes, and RAG pipelines with + knowledge bases. + - name: Image Actions + description: |- + Image actions are commands that can be given to a DigitalOcean image. In + general, these requests are made on the actions endpoint of a specific + image. + + An image action object is returned. These objects hold the current status + of the requested action. + - name: Images + description: >- + A DigitalOcean [image](https://docs.digitalocean.com/products/images/) can + be + + used to create a Droplet and may come in a number of flavors. Currently, + + there are five types of images: snapshots, backups, applications, + + distributions, and custom images. + + + * [Snapshots](https://docs.digitalocean.com/products/snapshots/) provide + + a full copy of an existing Droplet instance taken on demand. + + + * [Backups](https://docs.digitalocean.com/products/backups/) are similar + + to snapshots but are created automatically at regular intervals when + + enabled for a Droplet. + + + * [Custom images](https://docs.digitalocean.com/products/custom-images/) + + are Linux-based virtual machine images (raw, qcow2, vhdx, vdi, and vmdk + + formats are supported) that you may upload for use on DigitalOcean. + + + * Distributions are the public Linux distributions that are available to + + be used as a base to create Droplets. + + + * Applications, or [1-Click + Apps](https://docs.digitalocean.com/products/marketplace/), + + are distributions pre-configured with additional software. + + + To interact with images, you will generally send requests to the images + + endpoint at /v2/images. + - name: Kubernetes + description: >- + [DigitalOcean + Kubernetes](https://docs.digitalocean.com/products/kubernetes/) + + allows you to quickly deploy scalable and secure Kubernetes clusters. By + + sending requests to the `/v2/kubernetes/clusters` endpoint, you can list, + + create, or delete clusters as well as scale node pools up and down, + + recycle individual nodes, and retrieve the kubeconfig file for use with + + a cluster. + - name: Load Balancers + description: >- + [DigitalOcean Load + Balancers](https://docs.digitalocean.com/products/networking/load-balancers/) + + provide a way to distribute traffic across multiple Droplets. By sending + + requests to the `/v2/load_balancers` endpoint, you can list, create, or + + delete load balancers as well as add or remove Droplets, forwarding rules, + + and other configuration details. + - name: Monitoring + description: >- + The DigitalOcean Monitoring API makes it possible to programmatically + retrieve metrics as well as configure alert + + policies based on these metrics. The Monitoring API can help you gain + insight into how your apps are performing + + and consuming resources. + - name: NFS + description: >- + NFS lets you create fully managed, POSIX-compliant network file storage + that delivers secure, + + high-performance shared storage right inside your VPC. This enables + seamless data sharing across Droplets in a VPC. + - name: NFS Actions + description: |- + NFS actions are tasks that can be executed on an NFS share. These can be + things like resizing, snapshotting, etc. + - name: Partner Network Connect + description: |- + Partner Network Connect lets you establish high-bandwidth, low-latency + network connections directly between DigitalOcean VPC networks and other + public cloud providers or on-premises datacenters. + - name: Project Resources + description: >- + Project Resources are resources that can be grouped into your projects. + + You can group resources (like Droplets, Spaces, load balancers, domains, + + and floating IPs) in ways that align with the applications you host on + + DigitalOcean. + + + ### Supported Resource Types Examples + + + Projects resources are identified by uniform resource names or URNs. A + + valid URN has the following format: `do:resource_type:resource_id`. The + + following resource types are supported: + + + Resource Type | Example URN + + -------------------|------------ + + App Platform App | `do:app:be5aab85-851b-4cab-b2ed-98d5a63ba4e8` + + Database | `do:dbaas:83c7a55f-0d84-4760-9245-aba076ec2fb2` + + Domain | `do:domain:example.com` + + Droplet | `do:droplet:4126873` + + Floating IP | `do:floatingip:192.168.99.100` + + Kubernetes Cluster | `do:kubernetes:bd5f5959-5e1e-4205-a714-a914373942af` + + Load Balancer | + `do:loadbalancer:39052d89-8dd4-4d49-8d5a-3c3b6b365b5b` + + Space | `do:space:my-website-assets` + + Volume | `do:volume:6fc4c277-ea5c-448a-93cd-dd496cfef71f` + + + ### Resource Status Codes + + + When assigning and retrieving resources in projects, a `status` attribute + + is returned that indicates if a resource was successfully retrieved or + + assigned. The status codes can be one of the following: + + + Status Code | Explanation + + -------------------|------------ + + `ok` | There was no problem retrieving or assigning a + resource. + + `not_found` | The resource was not found. + + `assigned` | The resource was successfully assigned. + + `already_assigned` | The resource was already assigned. + + `service_down` | There was a problem retrieving or assigning a + resource. Please try again. + - name: Projects + description: |- + Projects allow you to organize your resources into groups that fit the way + you work. You can group resources (like Droplets, Spaces, load balancers, + domains, and floating IPs) in ways that align with the applications + you host on DigitalOcean. + - name: Regions + description: Provides information about DigitalOcean data center regions. + - name: Reserved IP Actions + description: >- + As of 16 June 2022, we have renamed the [Floating + IP](https://docs.digitalocean.com/reference/api/api-reference/#tag/Floating-IPs) + + product to Reserved IPs. The Reserved IP product's endpoints function the + exact + + same way as Floating IPs. The only difference is the name change + throughout the + + URLs and fields. For example, the `floating_ips` field is now the + `reserved_ips` field. + + The Floating IP endpoints will remain active until fall 2023 before being + + permanently deprecated. + + + With the exception of the [Projects + API](https://docs.digitalocean.com/reference/api/api-reference/#tag/Projects), + + we will reflect this change as an additional field in the responses across + the API + + where the `floating_ip` field is used. For example, the Droplet metadata + response + + will contain the field `reserved_ips` in addition to the `floating_ips` + field. + + Floating IPs retrieved using the Projects API will retain the original + name. + + + Reserved IP actions are commands that can be given to a DigitalOcean + + reserved IP. These requests are made on the actions endpoint of a specific + + reserved IP. + + + An action object is returned. These objects hold the current status of the + + requested action. + - name: Reserved IPs + description: >- + As of 16 June 2022, we have renamed the [Floating + IP](https://docs.digitalocean.com/reference/api/api-reference/#tag/Floating-IPs) + + product to Reserved IPs. The Reserved IP product's endpoints function the + exact + + same way as Floating IPs. The only difference is the name change + throughout the + + URLs and fields. For example, the `floating_ips` field is now the + `reserved_ips` field. + + The Floating IP endpoints will remain active until fall 2023 before being + + permanently deprecated. + + + With the exception of the [Projects + API](https://docs.digitalocean.com/reference/api/api-reference/#tag/Projects), + + we will reflect this change as an additional field in the responses across + the API + + where the `floating_ip` field is used. For example, the Droplet metadata + response + + will contain the field `reserved_ips` in addition to the `floating_ips` + field. + + Floating IPs retrieved using the Projects API will retain the original + name. + + + DigitalOcean Reserved IPs are publicly-accessible static IP addresses that + can be + + mapped to one of your Droplets. They can be used to create highly + available + + setups or other configurations requiring movable addresses. + + + Reserved IPs are bound to a specific region. + - name: Reserved IPv6 + description: >- + DigitalOcean Reserved IPv6s are publicly-accessible static IP addresses + that can be + + mapped to one of your Droplets. They can be used to create highly + available + + setups or other configurations requiring movable addresses. + + + Reserved IPv6s are bound to a specific region. + - name: Reserved IPv6 Actions + description: >- + Reserved IPv6 actions requests are made on the actions endpoint of a + specific + + reserved IPv6. + + + An action object is returned. These objects hold the current status of the + + requested action. + - name: Security + description: Security CSPM endpoints for scans, scan findings, and settings. + - name: Sizes + description: |- + The sizes objects represent different packages of hardware resources that + can be used for Droplets. When a Droplet is created, a size must be + selected so that the correct resources can be allocated. + + Each size represents a plan that bundles together specific sets of + resources. This includes the amount of RAM, the number of virtual CPUs, + disk space, and transfer. The size object also includes the pricing + details and the regions that the size is available in. + - name: Snapshots + description: |- + [Snapshots](https://docs.digitalocean.com/products/snapshots/) are saved + instances of a Droplet or a block storage volume, which is reflected in + the `resource_type` attribute. In order to avoid problems with compressing + filesystems, each defines a `min_disk_size` attribute which is the minimum + size of the Droplet or volume disk when creating a new resource from the + saved snapshot. + + To interact with snapshots, you will generally send requests to the + snapshots endpoint at `/v2/snapshots`. + - name: Spaces Keys + description: |- + Spaces keys authenticate requests to DigitalOcean Spaces Buckets. + You can create, list, update, or delete Spaces keys by sending requests to + to the `/v2/spaces/keys` endpoint. + - name: SSH Keys + description: Manage SSH keys available on your account. + - name: Tags + description: >- + A tag is a label that can be applied to a resource (currently Droplets, + + Images, Volumes, Volume Snapshots, and Database clusters) in order to + + better organize or facilitate the lookups and actions on it. + + + Tags have two attributes: a user defined `name` attribute and an embedded + + `resources` attribute with information about resources that have been + tagged. + - name: Uptime + description: >- + [DigitalOcean Uptime + Checks](https://docs.digitalocean.com/products/uptime/) provide the + ability to monitor your endpoints from around the world, and alert you + when they're slow, unavailable, or SSL certificates are expiring. + + To interact with Uptime, you will generally send requests to the Uptime + endpoint at `/v2/uptime/`. + - name: VPC NAT Gateways + description: >- + [VPC NAT + Gateways](https://docs.digitalocean.com/products/networking/vpc/how-to/create-nat-gateway/) + + allow resources in a private VPC to access the public internet without + + exposing them to incoming traffic. + + + By sending requests to the `/v2/vpc_nat_gateways` endpoint, you can + create, + + configure, list, and delete VPC NAT Gateways as well as retrieve + information + + about the resources assigned to them. + - name: VPC Peerings + description: >- + [VPC + Peerings](https://docs.digitalocean.com/products/networking/vpc/how-to/create-peering/) + + join two VPC networks with a secure, private connection. This allows + + resources in those networks to connect to each other's private IP + addresses + + as if they were in the same network. + - name: VPCs + description: >- + [VPCs (virtual private + clouds)](https://docs.digitalocean.com/products/networking/vpc/) + + allow you to create virtual networks containing resources that can + + communicate with each other in full isolation using private IP addresses. + + + By sending requests to the `/v2/vpcs` endpoint, you can create, configure, + + list, and delete custom VPCs as well as retrieve information about the + + resources assigned to them. + - name: Inference Introduction + x-displayName: Introduction + x-traitTag: true + description: > + The DigitalOcean Gradient™ AI Agentic Cloud provides inference + capabilities through + + two API variants: + + + - **Serverless Inference**: Access serverless inference models using an + inference key + at `https://inference.do-ai.run`. + - **Agent Inference**: Integrate multi-agent workflows into your AI + applications using + a customer-specific agent endpoint. + + These APIs are independent of the main DigitalOcean control-plane API + (`https://api.digitalocean.com`). + + + ## Base URLs + + + | API | Base URL | + + |-----|----------| + + | Serverless Inference | `https://inference.do-ai.run` | + + | Agent Inference | `https://{your-agent-url}.agents.do-ai.run` | + + + ## Requests + + + Any tool that is fluent in HTTP can communicate with the API simply by + + requesting the correct URI. Requests should be made using the HTTPS + protocol + + so that traffic is encrypted. The interface responds to different methods + + depending on the action required. + + + |Method|Usage| + + |--- |--- | + + |GET|For simple retrieval of information about your account, Droplets, or + environment, you should use the GET method. The information you request + will be returned to you as a JSON object. The attributes defined by the + JSON object can be used to form additional requests. Any request using + the GET method is read-only and will not affect any of the objects you are + querying.| + + |DELETE|To destroy a resource and remove it from your account and + environment, the DELETE method should be used. This will remove the + specified object if it is found. If it is not found, the operation will + return a response indicating that the object was not found. This + idempotency means that you do not have to check for a resource's + availability prior to issuing a delete command, the final state will be + the same regardless of its existence.| + + |PUT|To update the information about a resource in your account, the PUT + method is available. Like the DELETE Method, the PUT method is + idempotent. It sets the state of the target using the provided values, + regardless of their current values. Requests using the PUT method do not + need to check the current attributes of the object.| + + |PATCH|Some resources support partial modification. In these cases, the + PATCH method is available. Unlike PUT which generally requires a complete + representation of a resource, a PATCH request is a set of instructions on + how to modify a resource updating only specific attributes.| + + |POST|To create a new object, your request should specify the POST method. + The POST request includes all of the attributes necessary to create a new + object. When you wish to create a new object, send a POST request to the + target endpoint.| + + |HEAD|Finally, to retrieve metadata information, you should use the HEAD + method to get the headers. This returns only the header of what would be + returned with an associated GET request. Response headers contain some + useful information about your API access and the results that are + available for your request. For instance, the headers contain your current + rate-limit value and the amount of time available until the limit resets. + It also contains metrics about the total number of objects found, + pagination information, and the total content length.| + + + ## HTTP Statuses + + + Along with the HTTP methods that the API responds to, it will also return + + standard HTTP statuses, including error codes. + + + In the event of a problem, the status will contain the error code, while + the + + body of the response will usually contain additional information about the + + problem that was encountered. + + + In general, if the status returned is in the 200 range, it indicates that + + the request was fulfilled successfully and that no error was encountered. + + + Return codes in the 400 range typically indicate that there was an issue + + with the request that was sent. Among other things, this could mean that + you + + did not authenticate correctly, that you are requesting an action that you + + do not have authorization for, that the object you are requesting does not + + exist, or that your request is malformed. + + + If you receive a status in the 500 range, this generally indicates a + + server-side problem. This means that we are having an issue on our end and + + cannot fulfill your request currently. + + + 400 and 500 level error responses will include a JSON object in their + body, + + including the following attributes: + + + |Name|Type|Description| + + |--- |--- |--- | + + |id|string|A short identifier corresponding to the HTTP status code + returned. For example, the ID for a response returning a 404 status code + would be "not_found."| + + |message|string|A message providing additional information about the + error, including details to help resolve it when possible.| + + |request_id|string|Optionally, some endpoints may include a request ID + that should be provided when reporting bugs or opening support tickets to + help identify the issue.| + + + ### Example Error Response + + + ``` + HTTP/1.1 403 Forbidden + { + "id": "forbidden", + "message": "You do not have access for the attempted action." + } + ``` + + + ## Responses + + + When a request is successful, a response body will typically be sent back + in + + one of two formats depending on the request parameters: + + + ### JSON Response (Non-Streaming) + + + By default, or when `stream` is set to `false`, the API returns a complete + JSON + + response once the inference is finished. The response contains the full + generated + + content in a single payload. + + + ```json + { + "id": "chatcmpl-abc123", + "object": "chat.completion", + "created": 1677858242, + "model": "meta-llama/Llama-3.3-70B-Instruct", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I help you today?" + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 10, + "completion_tokens": 12, + "total_tokens": 22 + } + } + ``` + + + ### Streaming Response (Server-Sent Events) + + + When `stream` is set to `true`, the API returns the response as + Server-Sent Events + + (SSE) with content type `text/event-stream`. This allows you to receive + tokens as + + they are generated, providing a more responsive user experience. + + + Each event in the stream is prefixed with `data: ` and contains a JSON + object + + representing a chunk of the response. The stream ends with a `data: + [DONE]` message. + + + ``` + data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677858242,"model":"meta-llama/Llama-3.3-70B-Instruct","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]} + + data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677858242,"model":"meta-llama/Llama-3.3-70B-Instruct","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]} + + data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677858242,"model":"meta-llama/Llama-3.3-70B-Instruct","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} + + data: [DONE] + ``` + + + To consume streaming responses, read the response body line by line, parse + each + + `data:` line as JSON, and process the `delta.content` field to build up + the + + complete response incrementally. + + + ## Rate Limit + + + Requests through the API are rate limited per OAuth token. Current rate + limits: + + + * 5,000 requests per hour + + * 250 requests per minute (5% of the hourly total) + + + Once you exceed either limit, you will be rate limited until the next + cycle + + starts. Space out any requests that you would otherwise issue in bursts + for + + the best results. + + + The rate limiting information is contained within the response headers of + + each request. The relevant headers are: + + + * **ratelimit-limit**: The number of requests that can be made per hour. + + * **ratelimit-remaining**: The number of requests that remain before you + hit your request limit. See the information below for how the request + limits expire. + + * **ratelimit-reset**: This represents the time when the oldest request + will expire. The value is given in [Unix epoch + time](http://en.wikipedia.org/wiki/Unix_time). See below for more + information about how request limits expire. + + + More rate limiting information is returned only within burst limit error + response headers: + + * **retry-after**: The number of seconds to wait before making another + request when rate limited. + + + As long as the `ratelimit-remaining` count is above zero, you will be able + + to make additional requests. + + + The way that a request expires and is removed from the current limit count + + is important to understand. Rather than counting all of the requests for + an + + hour and resetting the `ratelimit-remaining` value at the end of the hour, + + each request instead has its own timer. + + + This means that each request contributes toward the `ratelimit-remaining` + + count for one complete hour after the request is made. When that request's + + timer runs out, it is no longer counted towards the request limit. + + + This has implications on the meaning of the `ratelimit-reset` header as + + well. Because the entire rate limit is not reset at one time, the value of + + this header is set to the time when the _oldest_ request will expire. + + + Keep this in mind if you see your `ratelimit-reset` value change, but not + + move an entire hour into the future. + + + If the `ratelimit-remaining` reaches zero, subsequent requests will + receive + + a 429 error code until the request reset has been reached. + + + `ratelimit-remaining` reaching zero can also indicate that the "burst + limit" of 250 + + requests per minute limit was met, even if the 5,000 requests per hour + limit was not. + + In this case, the 429 error response will include a `retry-after` header + to indicate how + + long to wait (in seconds) until the request may be retried. + + + You can see the format of the response in the examples. + + + ### Sample Rate Limit Headers + + + ``` + . . . + ratelimit-limit: 1200 + ratelimit-remaining: 1193 + rateLimit-reset: 1402425459 + . . . + ``` + + + ### Sample Rate Limit Headers When Burst Limit is Reached: + + + ``` + . . . + ratelimit-limit: 5000 + ratelimit-remaining: 0 + rateLimit-reset: 1402425459 + retry-after: 29 + . . . + ``` + + + ### Sample Rate Exceeded Response + + + ``` + 429 Too Many Requests + { + id: "too_many_requests", + message: "API Rate limit exceeded." + } + ``` + - name: Serverless Inference + description: >- + DigitalOcean Gradient™ AI Agentic Cloud allows access to serverless + inference models. + + You can access models by providing an inference key. + + + **Note:** The Serverless Inference API uses a separate base URL + (`https://inference.do-ai.run`) + + and is independent of the main DigitalOcean control-plane API + (`https://api.digitalocean.com`). + - name: Agent Inference + description: >- + DigitalOcean Gradient™ AI Agentic Cloud allows you to create multi-agent + workflows + + to power your AI applications. This allows developers to integrate agents + into your + + AI applications. + + + **Note:** The Agent Inference API uses a customer-specific base URL (the + agent endpoint) + + and is independent of the main DigitalOcean control-plane API + (`https://api.digitalocean.com`). + - name: Batch Inference + description: |- + Batch Inference is an asynchronous processing capability designed to help + you scale high-volume AI projects more efficiently. Ideal for heavy-duty + workloads like large-scale data classification, evaluations, and content + enrichment, you can submit thousands or even millions of requests in a + single job with a guaranteed results window of 24 hours. By utilizing + off-peak GPU capacity, Batch Inference provides high-performance LLM + access at a significantly reduced price point compared to standard + synchronous APIs, making it a cost-effective choice for non-interactive + workloads. +x-tagGroups: + - name: Public APIs + tags: + - Public APIs Introduction + - 1-Click Applications + - Account + - Actions + - Add-Ons + - Apps + - Billing + - Block Storage + - Block Storage Actions + - BYOIP Prefixes + - CDN Endpoints + - Certificates + - Container Registry + - Container Registries + - Databases + - Dedicated Inference + - Domain Records + - Domains + - Droplet Actions + - Droplets + - Droplet Autoscale Pools + - Firewalls + - Floating IP Actions + - Floating IPs + - Functions + - GradientAI Platform + - Image Actions + - Images + - Kubernetes + - Load Balancers + - Monitoring + - NFS + - NFS Actions + - Partner Network Connect + - Project Resources + - Projects + - Regions + - Reserved IP Actions + - Reserved IPs + - Reserved IPv6 + - Reserved IPv6 Actions + - Security + - Sizes + - Snapshots + - Spaces Keys + - SSH Keys + - Tags + - Uptime + - VPC NAT Gateways + - VPC Peerings + - VPCs + - name: Inference APIs + tags: + - Inference Introduction + - Agent Inference + - Batch Inference + - Embeddings + - Serverless Inference +paths: + /v2/1-clicks: + get: + operationId: oneClicks_list + summary: List 1-Click Applications + description: > + 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. + tags: + - 1-Click Applications + parameters: + - $ref: '#/components/parameters/oneClicks_type' + responses: + '200': + $ref: '#/components/responses/oneClicks_all' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + "https://api.digitalocean.com/v2/1-clicks" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token="") + + one_click_apps = client.one_clicks.list() + security: + - bearer_auth: [] + /v2/1-clicks/kubernetes: + post: + operationId: oneClicks_install_kubernetes + summary: Install Kubernetes 1-Click Applications + description: > + 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`. + tags: + - 1-Click Applications + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/oneClicks_create' + responses: + '200': + $ref: '#/components/responses/oneClicks_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"addon_slugs": ["kube-state-metrics", "loki"], "cluster_uuid": "50a994b6-c303-438f-9495-7e896cfe6b08"}'' \ + "https://api.digitalocean.com/v2/1-clicks/kubernetes" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + install_req = { + "addon_slugs": ["kube-state-metrics", "loki"], + "cluster_uuid": "50a994b6-c303-438f-9495-7e896cfe6b08", + } + install_resp = client.one_clicks.install_kubernetes(install_req) + security: + - bearer_auth: + - kubernetes:update + - addon:create + /v2/account: + get: + operationId: account_get + summary: Get User Information + description: >- + To show information about the current user account, send a GET request + to `/v2/account`. + tags: + - Account + responses: + '200': + $ref: '#/components/responses/account' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/account" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + account_info = client.account.get() + security: + - bearer_auth: + - account:read + /v2/account/keys: + get: + operationId: sshKeys_list + summary: List All SSH Keys + description: >- + 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. + tags: + - SSH Keys + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/sshKeys_all' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/account/keys" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + keys, _, err := client.Keys.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + ssh_keys = client.ssh_keys.all + ssh_keys.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.ssh_keys.list() + security: + - bearer_auth: + - ssh_key:read + post: + operationId: sshKeys_create + summary: Create a New SSH Key + description: >- + 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. + tags: + - SSH Keys + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/sshKeys' + responses: + '201': + $ref: '#/components/responses/sshKeys_new' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"My SSH Public Key","public_key":"ssh-rsa AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example"}' \ + "https://api.digitalocean.com/v2/account/keys" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.KeyCreateRequest{ + Name: "My SSH Public Key", + PublicKey: "ssh-rsa AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example", + } + + transfer, _, err := client.Keys.Create(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + ssh_key = DropletKit::SSHKey.new( + name: 'My SSH Public Key', + public_key: 'ssh-rsa AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example' + ) + client.ssh_keys.create(ssh_key) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "public_key": "ssh-rsa AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example", + "name": "My SSH Public Key" + } + + resp = client.ssh_keys.create(body=req) + security: + - bearer_auth: + - ssh_key:create + /v2/account/keys/{ssh_key_identifier}: + get: + operationId: sshKeys_get + summary: Retrieve an Existing SSH Key + description: >- + 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. + tags: + - SSH Keys + parameters: + - $ref: '#/components/parameters/ssh_key_identifier' + responses: + '200': + $ref: '#/components/responses/sshKeys_existing' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/account/keys/512190" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + key, _, err := client.Keys.GetByID(ctx, 512190) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.ssh_keys.find(id: 512190) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.ssh_keys.get(ssh_key_identifier=512190) + security: + - bearer_auth: + - ssh_key:read + put: + operationId: sshKeys_update + summary: Update an SSH Key's Name + description: >- + 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. + tags: + - SSH Keys + parameters: + - $ref: '#/components/parameters/ssh_key_identifier' + requestBody: + description: Set the `name` attribute to the new name you want to use. + required: true + content: + application/json: + schema: + type: object + properties: + name: + $ref: '#/components/schemas/ssh_key_name' + responses: + '200': + $ref: '#/components/responses/sshKeys_existing' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"Renamed SSH Key"}' \ + "https://api.digitalocean.com/v2/account/keys/512190" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.KeyUpdateRequest{ + Name: "Renamed SSH Key", + } + + key, _, err := client.Keys.UpdateByID(ctx, 512190, updateRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + ssh_key = DropletKit::SSHKey.new(name: 'Renamed SSH Key') + client.ssh_keys.update(ssh_key, id: 512190) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "My SSH Public Key" + } + + resp = client.ssh_keys.update(ssh_key_identifier=512190, body=req) + security: + - bearer_auth: + - ssh_key:update + delete: + operationId: sshKeys_delete + summary: Delete an SSH Key + description: >- + 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. + tags: + - SSH Keys + parameters: + - $ref: '#/components/parameters/ssh_key_identifier' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/account/keys/512190" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Keys.DeleteByID(ctx, 512190) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.ssh_keys.delete(id: 512190) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.ssh_keys.delete(ssh_key_identifier=512190) + security: + - bearer_auth: + - ssh_key:delete + /v2/actions: + get: + operationId: actions_list + summary: List All Actions + description: >- + 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. + tags: + - Actions + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/actions' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + actions, _, err := client.Actions.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + actions = client.actions.all + actions.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + list_resp = client.actions.list() + security: + - bearer_auth: + - actions:read + /v2/actions/{action_id}: + get: + operationId: actions_get + summary: Retrieve an Existing Action + description: >- + To retrieve a specific action object, send a GET request to + `/v2/actions/$ACTION_ID`. + tags: + - Actions + parameters: + - $ref: '#/components/parameters/action_id' + responses: + '200': + $ref: '#/components/responses/action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/actions/36804636" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.Actions.Get(ctx, 36804636) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.actions.find(id: 36804636) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + get_resp = client.actions.get(action_id=36804636) + security: + - bearer_auth: + - actions:read + /v2/add-ons/apps: + get: + operationId: addons_get_app + summary: List Available Add-On Applications + description: > + To fetch details of all available Add-On Applications, send a GET + request to `/v2/add-ons/apps`. + tags: + - Add-Ons + responses: + '200': + $ref: '#/components/responses/addons_get_app' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/add-ons/apps" + security: + - bearer_auth: [] + /v2/add-ons/apps/{app_slug}/metadata: + get: + operationId: addons_get_app_metadata + summary: Get Metadata for an Add-On Application + description: > + 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. + tags: + - Add-Ons + parameters: + - name: app_slug + in: path + required: true + example: example_app + schema: + type: string + description: >- + The slug identifier for the application whose metadata is being + requested. + responses: + '200': + $ref: '#/components/responses/addons_get_app_metadata' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/add-ons/apps/example-app/metadata" + security: + - bearer_auth: [] + /v2/add-ons/saas: + get: + operationId: addons_list + summary: List all Add-On Resources + description: > + To fetch all Add-On Resources under your team, send a GET request to + `/v2/add-ons/saas`. + tags: + - Add-Ons + responses: + '200': + $ref: '#/components/responses/addons_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/add-ons/saas" + security: + - bearer_auth: + - addon:read + post: + operationId: addons_create + summary: Create/Provision a New Add-on Resource + description: > + 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`. + tags: + - Add-Ons + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/addons_resource_new' + required: + - name + - app_slug + - plan_slug + - metadata + responses: + '200': + $ref: '#/components/responses/addons_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"my-addon-resource", "app_slug": "example-app", "plan_slug": "basic_plan", "metadata": [{"name": "company_name", "value": "Sample Company"}]}' \ + "https://api.digitalocean.com/v2/add-ons/saas" + security: + - bearer_auth: + - addon:create + /v2/add-ons/saas/{resource_uuid}: + get: + operationId: addons_get + summary: Get details on an Add-On Resource + description: > + 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. + tags: + - Add-Ons + parameters: + - name: resource_uuid + in: path + required: true + example: 123e4567-e89b-12d3-a456-426614174000 + schema: + type: string + description: The UUID of the add-on resource to retrieve. + responses: + '200': + $ref: '#/components/responses/addons_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/add-ons/saas/123e4567-e89b-12d3-a456-4266141" + security: + - bearer_auth: + - addon:read + delete: + operationId: addons_delete + summary: Delete/Deprovision an Add-on Resource + description: > + 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. + tags: + - Add-Ons + parameters: + - $ref: '#/components/parameters/resource_uuid' + responses: + '200': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/add-ons/saas/123e4567-e89b-12d3-a456-426614174000" + security: + - bearer_auth: + - addon:delete + patch: + operationId: addons_patch + summary: Update the name for an Add-On Resource + description: > + 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. + tags: + - Add-Ons + parameters: + - name: resource_uuid + in: path + required: true + example: 123e4567-e89b-12d3-a456-426614174000 + schema: + type: string + description: The UUID of the add-on resource to rename. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The new name for the add-on resource. + example: new-name + required: + - name + responses: + '200': + $ref: '#/components/responses/addons_update' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"new-name"}' \ + "https://api.digitalocean.com/v2/add-ons/saas/abc12345-6789-0123-4567-89abcdef0123" + security: + - bearer_auth: + - addon:update + /v2/add-ons/saas/{resource_uuid}/plan: + patch: + operationId: addons_patch_plan + summary: Update the plan for an Add-On Resource + description: > + 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. + tags: + - Add-Ons + parameters: + - name: resource_uuid + in: path + required: true + example: 123e4567-e89b-12d3-a456-426614174000 + schema: + type: string + description: The UUID of the add-on resource to update. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + plan_slug: + type: string + description: >- + The slug identifier for the new plan to apply to the add-on + resource. + example: basic_plan + required: + - plan_slug + responses: + '200': + $ref: '#/components/responses/addons_update' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"plan_slug":"new-plan"}' \ + "https://api.digitalocean.com/v2/add-ons/saas/abc12345-6789-0123-4567-89abcdef0123/plan" + security: + - bearer_auth: + - addon:update + /v2/apps: + get: + operationId: apps_list + summary: List All Apps + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/with_projects' + responses: + '200': + $ref: '#/components/responses/list_apps' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list() + security: + - bearer_auth: + - app:read + post: + operationId: apps_create + summary: Create a New App + description: >- + 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/). + tags: + - Apps + parameters: + - $ref: '#/components/parameters/accept' + - $ref: '#/components/parameters/content-type' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_create_app_request' + example: + spec: + name: web-app + region: nyc + disable_edge_cache: true + disable_email_obfuscation: false + enhanced_threat_control_enabled: true + services: + - name: api + github: + branch: main + deploy_on_push: true + repo: digitalocean/sample-golang + run_command: bin/api + environment_slug: node-js + instance_count: 2 + instance_size_slug: apps-s-1vcpu-0.5gb + routes: + - path: /api + egress: + type: DEDICATED_IP + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + required: true + responses: + '200': + $ref: '#/components/responses/new_app' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps" + -d '{"spec":{"name":"web-app","region":"nyc", \ + "services":[{"name":"api","github":{"branch":"main",\ + "deploy_on_push":true,"repo":"digitalocean/sample-golang"}, \ + "run_command":"bin/api","environment_slug":"node-js", \ + "instance_count":2,"instance_size_slug":"apps-s-1vcpu-0.5gb", \ + "routes":[{"path":"/api"}]}]}}' + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + create_resp = client.apps.create( + { + "spec": { + "name": "web-app", + "region": "nyc", + "services": [ + { + "name": "api", + "github": {}, + "run_command": "bin/api", + "environment_slug": "node-js", + "instance_count": 2, + "instance_size_slug": "apps-s-1vcpu-0.5gb", + "routes": [], + } + ], + } + } + ) + security: + - bearer_auth: + - app:create + /v2/apps/{id}: + delete: + operationId: apps_delete + summary: Delete an App + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/id_app' + responses: + '200': + $ref: '#/components/responses/delete_app' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + delete_resp = client.apps.delete(id="b7d64052") + security: + - bearer_auth: + - app:delete + get: + operationId: apps_get + summary: Retrieve an Existing App + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/id_app' + - $ref: '#/components/parameters/app_name' + responses: + '200': + $ref: '#/components/responses/apps_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + create_resp = client.apps.get(id="4f6c71e2") + security: + - bearer_auth: + - app:read + put: + operationId: apps_update + summary: Update an App + description: >- + 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/). + tags: + - Apps + parameters: + - $ref: '#/components/parameters/id_app' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_update_app_request' + required: true + responses: + '200': + $ref: '#/components/responses/update_app' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X PUT \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + "https://api.digitalocean.com/v2/apps/{id}" \ + + -d + '{"alerts":[{"rule":"DEPLOYMENT_FAILED"},{"rule":"DOMAIN_FAILED"}],"domains":[{"domain":"example.com","type":"PRIMARY","zone":"example.com"}],"envs":[{"key":"API_KEY","scope":"RUN_AND_BUILD_TIME","type":"SECRET","value":"EV[1:zqiRIeaaYK/NqctZDYzy6t0pTrtRDez8:wqGpZRrsKN5nPhWQrS479cfBiXT0WQ==]"}],"features":["buildpack-stack=ubuntu-22"],"ingress":{},"name":"example-app","region":"nyc","services":[{"autoscaling":{"max_instance_count":4,"metrics":{"cpu":{"percent":70}},"min_instance_count":2},"git":{"branch":"main","repo_clone_url":"https://github.com/digitalocean/sample-nodejs.git"},"internal_ports":[8080],"log_destinations":[{"name":"your_log_consumer_name","open_search":{"endpoint":"logs.example.com:12345","basic_auth":{"user":"doadmin","password":"1234567890abcdef"},"index_name":"example-index","cluster_name":"example-cluster"}}],"name":"sample-nodejs","run_command":"yarn + start","source_dir":"/"}]}' + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + req = { + "spec": { + "name": "web-app-01", + "region": "nyc", + "domains": [ + { + "domain": "app.example.com", + "type": "DEFAULT", + "wildcard": True, + "zone": "example.com", + "minimum_tls_version": "1.3", + } + ], + "services": [], + "static_sites": [ + { + "cors": { + "allow_origins": [ + {"exact": "https://www.example.com"}, + {"regex": "^.*example.com"}, + ], + "allow_methods": [ + "GET", + "OPTIONS", + "POST", + "PUT", + "PATCH", + "DELETE", + ], + "allow_headers": ["Content-Type", "X-Custom-Header"], + "expose_headers": ["Content-Encoding", "X-Custom-Header"], + "max_age": "5h30m", + "allow_credentials": False, + }, + "routes": [{"path": "/api", "preserve_path_prefix": True}], + } + ], + "jobs": [ + { + "name": "api", + "gitlab": { + "branch": "main", + "deploy_on_push": True, + "repo": "digitalocean/sample-golang", + }, + "image": { + "registry": "registry.hub.docker.com", + "registry_type": "DOCR", + "repository": "origin/master", + "tag": "latest", + }, + "dockerfile_path": "path/to/Dockerfile", + "build_command": "npm run build", + "run_command": "bin/api", + "source_dir": "path/to/dir", + "envs": [ + { + "key": "BASE_URL", + "scope": "BUILD_TIME", + "type": "GENERAL", + "value": "http://example.com", + } + ], + "environment_slug": "node-js", + "log_destinations": { + "name": "my_log_destination", + "papertrail": { + "endpoint": "https://mypapertrailendpoint.com" + }, + "datadog": { + "endpoint": "https://mydatadogendpoint.com", + "api_key": "abcdefghijklmnopqrstuvwxyz0123456789", + }, + "logtail": { + "token": "abcdefghijklmnopqrstuvwxyz0123456789" + }, + "open_search": { + "endpoint": "https://myopensearchendpoint.com:9300" + "index_name": "logs" + "basic_auth": { + "user": "doadmin", + "password": "password" + } + }, + }, + "instance_count": 2, + "instance_size_slug": "apps-s-1vcpu-0.5gb", + "kind": "PRE_DEPLOY", + } + ], + "workers": [ + { + "name": "api", + "gitlab": { + "branch": "main", + "deploy_on_push": True, + "repo": "digitalocean/sample-golang", + }, + "image": { + "registry": "registry.hub.docker.com", + "registry_type": "DOCR", + "repository": "origin/master", + "tag": "latest", + }, + "dockerfile_path": "path/to/Dockerfile", + "build_command": "npm run build", + "run_command": "bin/api", + "source_dir": "path/to/dir", + "envs": [ + { + "key": "BASE_URL", + "scope": "BUILD_TIME", + "type": "GENERAL", + "value": "http://example.com", + } + ], + "environment_slug": "node-js", + "log_destinations": { + "name": "my_log_destination", + "papertrail": { + "endpoint": "https://mypapertrailendpoint.com" + }, + "datadog": { + "endpoint": "https://mydatadogendpoint.com", + "api_key": "abcdefghijklmnopqrstuvwxyz0123456789", + }, + "logtail": { + "token": "abcdefghijklmnopqrstuvwxyz0123456789" + }, + "open_search": { + "endpoint": "https://myopensearchendpoint.com:9300" + "index_name": "logs" + "basic_auth": { + "user": "doadmin", + "password": "password" + } + }, + }, + "instance_count": 2, + "instance_size_slug": "apps-s-1vcpu-0.5gb", + } + ], + "functions": [ + { + "cors": { + "allow_origins": [ + {"exact": "https://www.example.com"}, + {"regex": "^.*example.com"}, + ], + "allow_methods": [ + "GET", + "OPTIONS", + "POST", + "PUT", + "PATCH", + "DELETE", + ], + "allow_headers": ["Content-Type", "X-Custom-Header"], + "expose_headers": ["Content-Encoding", "X-Custom-Header"], + "max_age": "5h30m", + "allow_credentials": False, + }, + "routes": [{"path": "/api", "preserve_path_prefix": True}], + "name": "api", + "source_dir": "path/to/dir", + "alerts": [ + { + "rule": "CPU_UTILIZATION", + "disabled": False, + "operator": "GREATER_THAN", + "value": 2.32, + "window": "FIVE_MINUTES", + } + ], + "envs": [ + { + "key": "BASE_URL", + "scope": "BUILD_TIME", + "type": "GENERAL", + "value": "http://example.com", + } + ], + "gitlab": { + "branch": "main", + "deploy_on_push": True, + "repo": "digitalocean/sample-golang", + }, + "log_destinations": { + "name": "my_log_destination", + "papertrail": { + "endpoint": "https://mypapertrailendpoint.com" + }, + "datadog": { + "endpoint": "https://mydatadogendpoint.com", + "api_key": "abcdefghijklmnopqrstuvwxyz0123456789", + }, + "logtail": { + "token": "abcdefghijklmnopqrstuvwxyz0123456789" + }, + "open_search": { + "endpoint": "https://myopensearchendpoint.com:9300" + "index_name": "logs" + "basic_auth": { + "user": "doadmin", + "password": "password" + } + }, + }, + } + ], + "databases": [ + { + "cluster_name": "cluster_name", + "db_name": "my_db", + "db_user": "superuser", + "engine": "PG", + "name": "prod-db", + "production": True, + "version": "12", + } + ], + “vpc”: { + “id”: “c22d8f48-4bc4-49f5-8ca0-58e7164427ac”, + } + } + update_resp = client.apps.update(id="bb245ba", body=req) + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/restart: + post: + operationId: apps_restart + summary: Restart an App + description: Perform a rolling restart of all or specific components in an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_restart_request' + responses: + '200': + $ref: '#/components/responses/new_app_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/restart" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + create_resp = client.apps.restart(app_id="b6bdf840", + body={"components": ["component1", "component2"]}) + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/components/{component_name}/logs: + get: + operationId: apps_get_logs_active_deployment + summary: Retrieve Active Deployment Logs + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/component' + - $ref: '#/components/parameters/live_updates' + - $ref: '#/components/parameters/log_type' + - $ref: '#/components/parameters/time_wait' + responses: + '200': + $ref: '#/components/responses/list_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/components/{component_name}/logs" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_logs_active_deployment(app_id="a6adf840", + component_name="component") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/components/{component_name}/exec: + get: + operationId: apps_get_exec_active_deployment + summary: Retrieve Exec URL + description: >- + Returns a websocket URL that allows sending/receiving console input and + output to a component of the active deployment if one exists. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/component' + - $ref: '#/components/parameters/instance_name' + responses: + '200': + $ref: '#/components/responses/get_exec' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/components/{component_name}/exec" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_exec_active_deployment(app_id="a6adf840", + component_name="component") + security: + - bearer_auth: + - app:access_console + /v2/apps/{app_id}/instances: + get: + operationId: apps_get_instances + summary: Retrieve App Instances + description: >- + 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. + parameters: + - $ref: '#/components/parameters/app_id' + tags: + - Apps + responses: + '200': + $ref: '#/components/responses/apps_instances' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}/instances" + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/deployments: + get: + operationId: apps_list_deployments + summary: List App Deployments + description: List all deployments of an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/per_page' + - name: deployment_types + description: |- + Optional. Filter deployments by deployment_type + - MANUAL: manual deployment + - DEPLOY_ON_PUSH: deployment triggered by a push to the app's repository + - MAINTENANCE: deployment for maintenance purposes + - MANUAL_ROLLBACK: manual revert to a previous deployment + - AUTO_ROLLBACK: automatic revert to a previous deployment + - UPDATE_DATABASE_TRUSTED_SOURCES: update database trusted sources + - AUTOSCALED: deployment that has been autoscaled + in: query + required: false + schema: + type: array + items: + type: string + enum: + - MANUAL + - DEPLOY_ON_PUSH + - MAINTENANCE + - MANUAL_ROLLBACK + - AUTO_ROLLBACK + - UPDATE_DATABASE_TRUSTED_SOURCES + - AUTOSCALED + example: + - MANUAL + - AUTOSCALED + responses: + '200': + $ref: '#/components/responses/existing_deployments' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_deployments(app_id="4f6c71e2") + security: + - bearer_auth: + - app:read + post: + operationId: apps_create_deployment + summary: Create an App Deployment + description: >- + Creating an app deployment will pull the latest changes from your + repository and schedule a new deployment for your app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_create_deployment_request' + required: true + responses: + '200': + $ref: '#/components/responses/new_app_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + create_resp = client.apps.create_deployment(app_id="b6bdf840", + body={"force_build": True}) + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/deployments/{deployment_id}: + get: + operationId: apps_get_deployment + summary: Retrieve an App Deployment + description: Retrieve information about an app deployment. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/deployment_id' + responses: + '200': + $ref: '#/components/responses/list_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_deployment(app_id="a6adf840", + deployment_id="b6bdf840") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/deployments/{deployment_id}/cancel: + post: + operationId: apps_cancel_deployment + summary: Cancel a Deployment + description: Immediately cancel an in-progress deployment. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/deployment_id' + responses: + '200': + $ref: '#/components/responses/cancel_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/cancel" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + cancel_resp = client.apps.cancel_deployment("12345", "24556") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs: + get: + operationId: apps_get_logs + summary: Retrieve Deployment Logs + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/deployment_id' + - $ref: '#/components/parameters/component' + - $ref: '#/components/parameters/live_updates' + - $ref: '#/components/parameters/log_type' + - $ref: '#/components/parameters/time_wait' + responses: + '200': + $ref: '#/components/responses/list_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_logs(app_id="4f6c71e2", + deployment_id="3aa4d20e", component_name="component") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/deployments/{deployment_id}/logs: + get: + operationId: apps_get_logs_aggregate + summary: Retrieve Aggregate Deployment Logs + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/deployment_id' + - $ref: '#/components/parameters/live_updates' + - $ref: '#/components/parameters/log_type' + - $ref: '#/components/parameters/time_wait' + responses: + '200': + $ref: '#/components/responses/list_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/logs" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_logs_aggregate(app_id="b6bdf840", + deployment_id="a6adf840") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec: + get: + operationId: apps_get_exec + summary: Retrieve Exec URL for Deployment + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/deployment_id' + - $ref: '#/components/parameters/component' + - $ref: '#/components/parameters/instance_name' + responses: + '200': + $ref: '#/components/responses/get_exec' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_exec(app_id="4f6c71e2", + deployment_id="3aa4d20e", component_name="component") + security: + - bearer_auth: + - app:access_console + /v2/apps/{app_id}/logs: + get: + operationId: apps_get_logs_active_deployment_aggregate + summary: Retrieve Active Deployment Aggregate Logs + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/live_updates' + - $ref: '#/components/parameters/log_type' + - $ref: '#/components/parameters/time_wait' + responses: + '200': + $ref: '#/components/responses/list_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/logs" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.apps.get_logs_active_deployment_aggregate(app_id="a6adf840") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/job-invocations: + get: + operationId: apps_list_job_invocations + summary: List Job Invocations + description: List all job invocations for an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/job_names' + - description: The deployment ID + in: query + name: deployment_id + required: false + schema: + type: string + example: 3aa4d20e-5527-4c00-b496-601fbd22520a + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/per_page' + responses: + '200': + $ref: '#/components/responses/list_job_invocations' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_job_invocations(app_id="4f6c71e2") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/job-invocations/{job_invocation_id}: + get: + operationId: apps_get_job_invocation + summary: Get Job Invocations + description: Get a specific job invocation for an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/job_invocation_id' + - $ref: '#/components/parameters/job_name' + responses: + '200': + $ref: '#/components/responses/get_job_invocation' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations/{job_invocation_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_job_invocation(app_id="4f6c71e2", + job_invocation_id="3aa4d20e") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel: + post: + operationId: apps_cancel_job_invocation + summary: Cancel Job Invocation + description: Cancel a specific job invocation for an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/job_invocation_id' + - $ref: '#/components/parameters/job_name' + responses: + '200': + $ref: '#/components/responses/cancel_job_invocation' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.cancel_job_invocation(app_id="4f6c71e2", + job_invocation_id="3aa4d20e") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs: + get: + operationId: apps_get_job_invocation_logs + summary: Retrieve Job Invocation Logs + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - description: The job name to list job invocations for. + in: path + name: job_name + required: true + schema: + type: string + example: component + - $ref: '#/components/parameters/job_invocation_id' + - description: The deployment ID + in: query + name: deployment_id + required: false + schema: + type: string + example: 3aa4d20e-5527-4c00-b496-601fbd22520a + - $ref: '#/components/parameters/live_updates' + - description: The type of logs to retrieve + in: query + name: type + required: true + schema: + type: string + enum: + - JOB_INVOCATION + example: JOB_INVOCATION + - $ref: '#/components/parameters/time_wait' + - $ref: '#/components/parameters/number_lines' + responses: + '200': + $ref: '#/components/responses/apps_get_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_job_invocation_logs(app_id="4f6c71e2", + job_name="component", job_invocation_id="3aa4d20e") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/events: + get: + operationId: apps_list_events + summary: List App Events + description: >- + List all events for an app, including deployments and autoscaling + events. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/per_page' + - description: Filter events by event type. + in: query + name: event_types + required: false + schema: + type: array + items: + type: string + enum: + - UNKNOWN + - DEPLOYMENT + - AUTOSCALING + example: + - DEPLOYMENT + responses: + '200': + $ref: '#/components/responses/list_events' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/events" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_events(app_id="4f6c71e2") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/events/{event_id}: + get: + operationId: apps_get_event + summary: Get an Event + description: Get a single event for an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/event_id' + responses: + '200': + $ref: '#/components/responses/get_event' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_event(app_id="4f6c71e2", + event_id="3aa4d20e") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/events/{event_id}/cancel: + post: + operationId: apps_cancel_event + summary: Cancel an Event + description: Cancel an in-progress autoscaling event. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/event_id' + responses: + '200': + $ref: '#/components/responses/cancel_event' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/cancel" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.cancel_event(app_id="4f6c71e2", + event_id="3aa4d20e") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/events/{event_id}/logs: + get: + operationId: apps_get_event_logs + summary: Retrieve Event Logs + description: Retrieve the logs of an autoscaling event for an app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/event_id' + - $ref: '#/components/parameters/live_updates' + - $ref: '#/components/parameters/log_type' + - $ref: '#/components/parameters/time_wait' + responses: + '200': + $ref: '#/components/responses/list_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/logs?type=AUTOSCALE_EVENT" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.apps.get_event_logs(app_id="4f6c71e2", + event_id="3aa4d20e") + security: + - bearer_auth: + - app:read + /v2/apps/tiers/instance_sizes: + get: + operationId: apps_list_instanceSizes + summary: List Instance Sizes + description: List all instance sizes for `service`, `worker`, and `job` components. + tags: + - Apps + responses: + '200': + $ref: '#/components/responses/list_instance' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/tiers/instance_sizes" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_instance_sizes() + security: + - bearer_auth: + - app:read + /v2/apps/tiers/instance_sizes/{slug}: + get: + operationId: apps_get_instanceSize + summary: Retrieve an Instance Size + description: >- + Retrieve information about a specific instance size for `service`, + `worker`, and `job` components. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/slug_size' + responses: + '200': + $ref: '#/components/responses/get_instance' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/tiers/instance_sizes/{slug}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.get_instance_size(slug="apps-s-1vcpu-0.5gb") + security: + - bearer_auth: + - app:read + /v2/apps/regions: + get: + operationId: apps_list_regions + summary: List App Regions + description: List all regions supported by App Platform. + tags: + - Apps + responses: + '200': + $ref: '#/components/responses/list_regions' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/regions" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_regions() + security: + - bearer_auth: + - app:read + /v2/apps/propose: + post: + operationId: apps_validate_appSpec + summary: Propose an App Spec + description: >- + 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. + tags: + - Apps + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/app_propose' + example: + spec: + name: web-app + region: nyc + services: + - name: api + github: + branch: main + deploy_on_push: true + repo: digitalocean/sample-golang + run_command: bin/api + environment_slug: node-js + instance_count: 2 + instance_size_slug: apps-s-1vcpu-0.5gb + routes: + - path: /api + app_id: b6bdf840-2854-4f87-a36c-5f231c617c84 + required: true + responses: + '200': + $ref: '#/components/responses/propose_app' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/alerts: + get: + operationId: apps_list_alerts + summary: List all app alerts + description: >- + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + responses: + '200': + $ref: '#/components/responses/list_alerts' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/alerts" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.apps.list_alerts(app_id="4f6c71e2") + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/alerts/{alert_id}/destinations: + post: + operationId: apps_assign_alertDestinations + summary: Update destinations for alerts + description: >- + Updates the emails and slack webhook destinations for app alerts. Emails + must be associated to a user with access to the app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - $ref: '#/components/parameters/alert_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_assign_app_alert_destinations_request' + required: true + responses: + '200': + $ref: '#/components/responses/assign_alert_destinations' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}/alerts/{alert_id}/destinations" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "emails": ["sammy@digitalocean.com"], + "slack_webhooks": [ + { + "url": "https://example.invalid/redacted-slack-webhook", + "channel": "Channel Name", + } + ], + } + + + post_resp = client.apps.assign_alert_destinations("12345", "24556", + req) + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/rollback: + post: + operationId: apps_create_rollback + summary: Rollback App + description: > + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_rollback_app_request' + required: true + responses: + '200': + $ref: '#/components/responses/new_app_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a" }' \ + "https://api.digitalocean.com/v2/apps/{app_id}/rollback" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + create_resp = client.apps.create_rollback(app_id="b6bdf840") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/rollback/validate: + post: + operationId: apps_validate_rollback + summary: Validate App Rollback + description: > + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apps_rollback_app_request' + required: true + responses: + '200': + $ref: '#/components/responses/apps_validate_rollback' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a" }' \ + "https://api.digitalocean.com/v2/apps/{app_id}/rollback/validate" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + validate_req = {"deployment_id": "2", "skip_pin": False} + + validate_resp = client.apps.validate_rollback("1", validate_req) + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/rollback/commit: + post: + operationId: apps_commit_rollback + summary: Commit App Rollback + description: > + Commit an app rollback. This action permanently applies the rollback and + unpins the app to resume new deployments. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + responses: + '200': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/rollback/commit" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + commit_resp = client.apps.commit_rollback("1") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/rollback/revert: + post: + operationId: apps_revert_rollback + summary: Revert App Rollback + description: > + 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. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + responses: + '200': + $ref: '#/components/responses/new_app_deployment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{app_id}/rollback/revert" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + revert_resp = client.apps.revert_rollback("1") + security: + - bearer_auth: + - app:update + /v2/apps/{app_id}/metrics/bandwidth_daily: + get: + operationId: apps_get_metrics_bandwidth_daily + summary: Retrieve App Daily Bandwidth Metrics + description: Retrieve daily bandwidth usage metrics for a single app. + tags: + - Apps + parameters: + - $ref: '#/components/parameters/app_id' + - name: date + description: >- + Optional day to query. Only the date component of the timestamp will + be considered. Default: yesterday. + in: query + schema: + type: string + format: date-time + example: '2023-01-17T00:00:00Z' + responses: + '200': + $ref: '#/components/responses/get_metrics_bandwidth_usage' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}/metrics/bandwidth_daily" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.apps.get_metrics_bandwidth_daily(app_id="4f6c71e2") + security: + - bearer_auth: + - app:read + /v2/apps/metrics/bandwidth_daily: + post: + operationId: apps_list_metrics_bandwidth_daily + summary: Retrieve Multiple Apps' Daily Bandwidth Metrics + description: Retrieve daily bandwidth usage metrics for multiple apps. + tags: + - Apps + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/app_metrics_bandwidth_usage_request' + example: + app_ids: + - 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + - c2a93513-8d9b-4223-9d61-5e7272c81cf5 + date: '2023-01-17T00:00:00Z' + required: true + responses: + '200': + $ref: '#/components/responses/list_metrics_bandwidth_usage' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/metrics/bandwidth_daily" \ + -d '{ "app_ids": ["4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"] }' + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "app_ids": [ + "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf", + "c2a93513-8d9b-4223-9d61-5e7272c81cf5", + ], + "date": "2023-01-17T00:00:00Z", + } + + get_resp = client.apps.list_metrics_bandwidth_daily(body=req) + security: + - bearer_auth: + - app:read + /v2/apps/{app_id}/health: + get: + operationId: apps_get_health + summary: Retrieve App Health + description: >- + Retrieve information like health status, cpu and memory utilization of + app components. + parameters: + - $ref: '#/components/parameters/app_id' + tags: + - Apps + responses: + '200': + $ref: '#/components/responses/apps_health' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/apps/{id}/health" + security: + - bearer_auth: + - app:read + /v2/cdn/endpoints: + get: + operationId: cdn_list_endpoints + summary: List All CDN Endpoints + description: >- + To list all of the CDN endpoints available on your account, send a GET + request to `/v2/cdn/endpoints`. + tags: + - CDN Endpoints + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_cdn_endpoints' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/cdn/endpoints" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + cdns, _, err := client.CDNs.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + cdns = client.cdns.all + cdns.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.cdn.list_endpoints() + security: + - bearer_auth: + - cdn:read + post: + operationId: cdn_create_endpoint + summary: Create a New CDN Endpoint + description: > + 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. + tags: + - CDN Endpoints + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/cdn_endpoint' + examples: + CDN Endpoint: + value: + origin: static-images.nyc3.digitaloceanspaces.com + ttl: 3600 + CDN Endpoint With Custom Domain: + value: + origin: static-images.nyc3.digitaloceanspaces.com + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + custom_domain: static.example.com + ttl: 3600 + responses: + '201': + $ref: '#/components/responses/existing_endpoint' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"origin": "static-images.nyc3.digitaloceanspaces.com","certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf","custom_domain": "static.example.com","ttl": 3600}' \ + "https://api.digitalocean.com/v2/cdn/endpoints" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.CDNCreateRequest{ + Origin: "static-images.nyc3.digitaloceanspaces.com", + TTL: 3600, + CustomDomain: "static.example.com", + CertificateID: "892071a0-bb95-49bc-8021-3afd67a210b", + } + + cdn, _, err := client.CDNs.Create(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + cdn = DropletKit::CDN.new( + origin: 'static-images.nyc3.digitaloceanspaces.com', + custom_domain: 'static.example.com', + certificate_id: '892071a0-bb95-49bc-8021-3afd67a210bf', + ttl: 3600 + ) + + client.cdns.create(cdn) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + create_req = {"origin": "static-images.nyc3.digitaloceanspaces.com", + "ttl": 3600} + + create_resp = client.cdn.create_endpoint(create_req) + security: + - bearer_auth: + - cdn:create + /v2/cdn/endpoints/{cdn_id}: + get: + operationId: cdn_get_endpoint + summary: Retrieve an Existing CDN Endpoint + description: >- + To show information about an existing CDN endpoint, send a GET request + to `/v2/cdn/endpoints/$ENDPOINT_ID`. + tags: + - CDN Endpoints + parameters: + - $ref: '#/components/parameters/cdn_endpoint_id' + responses: + '200': + $ref: '#/components/responses/existing_endpoint' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + cdn, _, err := client.CDNs.Get(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.cdns.find(id: '19f06b6a-3ace-4315-b086-499a0e521b76') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.cdn.get_endpoint(cdn_id="aa34ba1") + security: + - bearer_auth: + - cdn:read + put: + operationId: cdn_update_endpoints + summary: Update a CDN Endpoint + description: > + 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`. + tags: + - CDN Endpoints + parameters: + - $ref: '#/components/parameters/cdn_endpoint_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/update_endpoint' + responses: + '200': + $ref: '#/components/responses/existing_endpoint' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X PUT \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d '{"ttl": 1800}' \ + + "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + updateRequest := &godo.CDNUpdateTTLRequest{TTL: 1800} + cdn, _, err := client.CDNs.UpdateTTL(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", updateRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = + '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5' + + client = DropletKit::Client.new(access_token: token) + + + client.cdns.update_ttl(id: '19f06b6a-3ace-4315-b086-499a0e521b76', + ttl: 1800) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + update_req = { + "ttl": 3600, + "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf", + "custom_domain": "static.example.com", + } + + update_resp = client.cdn.update_endpoints("19f06b6a", update_req) + security: + - bearer_auth: + - cdn:update + delete: + operationId: cdn_delete_endpoint + summary: Delete a CDN Endpoint + description: > + 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. + tags: + - CDN Endpoints + parameters: + - $ref: '#/components/parameters/cdn_endpoint_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.CDNs.Delete(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.cdns.delete(id: '19f06b6a-3ace-4315-b086-499a0e521b76') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + delete_resp = client.cdn.delete_endpoint(cdn_id="bba23af") + security: + - bearer_auth: + - cdn:delete + /v2/cdn/endpoints/{cdn_id}/cache: + delete: + operationId: cdn_purge_cache + summary: Purge the Cache for an Existing CDN Endpoint + description: > + 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. + tags: + - CDN Endpoints + parameters: + - $ref: '#/components/parameters/cdn_endpoint_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/purge_cache' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"files": ["assets/img/hero.png","assets/css/*"]}' \ + "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76/cache" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + flushRequest := &godo.CDNFlushCacheRequest{ + Files: []string{"assets/img/hero.png","assets/css/*"}, + } + + _, err := client.CDNs.FlushCache(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", flushRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.cdns.flush_cache( + id: '19f06b6a-3ace-4315-b086-499a0e521b76', + files: ['assets/img/hero.png','assets/css/*'] + ) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + purge_req = {"files": ["path/to/image.png", "path/to/css/*"]} + + purge_resp = client.cdn.purge_cache("19f06b6a", purge_req) + security: + - bearer_auth: + - cdn:delete + /v2/certificates: + get: + operationId: certificates_list + summary: List All Certificates + description: >- + To list all of the certificates available on your account, send a GET + request to `/v2/certificates`. + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/certificate_name' + tags: + - Certificates + responses: + '200': + $ref: '#/components/responses/all_certificates' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/certificates" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + certs, _, err := client.Certificates.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + certificates = client.certificates.all + certificates.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.certificates.list() + security: + - bearer_auth: + - certificate:read + post: + operationId: certificates_create + summary: Create a New Certificate + description: > + 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`. + tags: + - Certificates + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/certificate_request_lets_encrypt' + - $ref: '#/components/schemas/certificate_request_custom' + responses: + '201': + $ref: '#/components/responses/new_certificate' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "web-cert-01", "type": "custom", "private_key": "'"$(- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + key = File.open('/path/to/privkey1.pem', 'r'){ |file| file.read } + + cert = File.open('/path/to/cert1.pem', 'r'){ |file| file.read } + + chain = File.open('/path/to/fullchain1.pem', 'r'){ |file| file.read + } + + + certificate = DropletKit::Certificate.new( + name: 'web-cert-01', + private_key: key, + leaf_certificate: cert, + certificate_chain: chain, + type: 'custom' + ) + + + client.certificates.create(certificate) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + create_resp = client.certificates.create( + { + "name": "web-cert-01", + "type": "lets_encrypt", + "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52\nSVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1\nDwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X\nwrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w\nZ2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F\nZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX\nfqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l\n9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm\ncVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt\neRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF\n0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x\ngtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh\nGGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+\nP8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj\nIntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49\nW1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ\n3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt\nNfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx\npxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG\nRKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0\no4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E\nsAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW\nJUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo\nQbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/\nAangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg\neTuK2xNR0PIM8OI7pRpgyj1I\n-----END PRIVATE KEY-----", + "leaf_certificate": "-----BEGIN CERTIFICATE-----\nMIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA\nMEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD\nExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x\nNzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j\nb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+\nCYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb\n8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4\noFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz\nZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna\nk/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb\nQwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1\nMbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG\nCCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl\ndHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s\nZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu\nZy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW\nMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB\nBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1\ncG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp\ndGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl\nbmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM\nPKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e\niXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD\nD3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7\nq9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/\nWyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu\nUlF1zblDmg2Iaw==\n-----END CERTIFICATE-----", + "certificate_chain": "-----BEGIN CERTIFICATE-----\nMIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA\nMEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD\nExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x\nNzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j\nb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz7tnK6V52SVf+\nCYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb\n8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4\noFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz\nZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna\nk/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb\nQwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1\nMbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG\nCCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl\ndHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s\nZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu\nZy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgEwgeWECysGAQQBgt8TAQEBMIHW\nMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB\nBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1\ncG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp\ndGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBsdHRwczovL2xldHNl\nbmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM\nPKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e\niXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD\nD3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL3o+UIY39X0dV3WOboW2Re8nrkFXJ7\nq9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/\nWyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu\nUlF1zblDmg2Iaw==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/\nMSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT\nDkRTVCBSb290IENBIFgzMB4XDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0Nlow\nSjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxldCdzIEVuY3J5cHQxIzAhBgNVBAMT\nGkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkqhkiG9w0BAQEFAAOC\nAQ8AMIIBCgKCAQEAnNMM8FrlLsd3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4S0EF\nq6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8\nSMx+yk13EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0\nZ8h/pZq4UmEUEz9l6YKHy9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWA\na6xK8xuQSXgvopZPKiAlKQTGdMDQMc2PMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj\n/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIPOIUo4IBfTCCAXkwEgYDVR0T\nAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEEczBxMDIG\nCCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNv\nbTA7BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9k\nc3Ryb290Y2F4My5wN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAw\nVAYDVR0gBE0wSzAIBgZngQwBAgEwPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcC\nARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNyeXB0Lm9yZzA8BgNVHR8ENTAz\nMDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9PVENBWDNDUkwu\nY3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF\nAAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJo\nuM2VcGfl96S8TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/\nwApIvJSwtmVi4MFU5aMqrSDE6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwu\nX4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPMTZ+sOPAveyxindmjkW8lGy+QsRlG\nPfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6\nKOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==\n-----END CERTIFICATE-----", + } + ) + security: + - bearer_auth: + - certificate:create + /v2/certificates/{certificate_id}: + get: + operationId: certificates_get + summary: Retrieve an Existing Certificate + description: >- + To show information about an existing certificate, send a GET request to + `/v2/certificates/$CERTIFICATE_ID`. + tags: + - Certificates + parameters: + - $ref: '#/components/parameters/certificate_id' + responses: + '200': + $ref: '#/components/responses/existing_certificate' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + cert, _, err := client.Certificates.Get(ctx, "892071a0-bb95-49bc-8021-3afd67a210bf") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.certificates.find(id: '892071a0-bb95-49bc-8021-3afd67a210bf') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.certificates.get( + certificate_id="892071a0-bb95-49bc-8021-3afd67a210bf" + ) + security: + - bearer_auth: + - certificate:read + delete: + operationId: certificates_delete + summary: Delete a Certificate + description: | + To delete a specific certificate, send a DELETE request to + `/v2/certificates/$CERTIFICATE_ID`. + tags: + - Certificates + parameters: + - $ref: '#/components/parameters/certificate_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Certificates.Delete(ctx, "892071a0-bb95-49bc-8021-3afd67a210bf") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.certificates.delete(id: + '892071a0-bb95-49bc-8021-3afd67a210bf') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + del_resp = client.certificates.delete( + certificate_id="892071a0-bb95-49bc-8021-3afd67a210bf" + ) + security: + - bearer_auth: + - certificate:delete + /v2/customers/my/balance: + get: + operationId: balance_get + summary: Get Customer Balance + description: >- + To retrieve the balances on a customer's account, send a GET request to + `/v2/customers/my/balance`. + tags: + - Billing + responses: + '200': + $ref: '#/components/responses/balance' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/balance" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + balance = client.balance.get() + security: + - bearer_auth: + - billing:read + /v2/customers/my/billing_history: + get: + operationId: billingHistory_list + summary: List Billing History + description: >- + To retrieve a list of all billing history entries, send a GET request to + `/v2/customers/my/billing_history`. + tags: + - Billing + responses: + '200': + $ref: '#/components/responses/billing_history' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/billing_history" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + balance = client.billing_history.list() + security: + - bearer_auth: + - billing:read + /v2/customers/my/invoices: + get: + operationId: invoices_list + summary: List All Invoices + description: >- + To retrieve a list of all invoices, send a GET request to + `/v2/customers/my/invoices`. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/invoices' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/invoices" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + balance = client.invoices.list() + security: + - bearer_auth: + - billing:read + /v2/customers/my/invoices/{invoice_uuid}: + get: + operationId: invoices_get_byUUID + summary: Retrieve an Invoice by UUID + description: >- + To retrieve the invoice items for an invoice, send a GET request to + `/v2/customers/my/invoices/$INVOICE_UUID`. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/invoice_uuid' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/invoice' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + invoices = client.invoices.get_by_uuid(invoice_uuid=1) + security: + - bearer_auth: + - billing:read + /v2/customers/my/invoices/{invoice_uuid}/csv: + get: + operationId: invoices_get_csvByUUID + summary: Retrieve an Invoice CSV by UUID + description: >- + To retrieve a CSV for an invoice, send a GET request to + `/v2/customers/my/invoices/$INVOICE_UUID/csv`. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/invoice_uuid' + responses: + '200': + $ref: '#/components/responses/invoice_csv' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: text/csv" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681/csv" --output invoice.csv + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + invoices = client.invoices.get_csv_by_uuid(invoice_uuid=1) + security: + - bearer_auth: + - billing:read + /v2/customers/my/invoices/{invoice_uuid}/pdf: + get: + operationId: invoices_get_pdfByUUID + summary: Retrieve an Invoice PDF by UUID + description: >- + To retrieve a PDF for an invoice, send a GET request to + `/v2/customers/my/invoices/$INVOICE_UUID/pdf`. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/invoice_uuid' + responses: + '200': + $ref: '#/components/responses/invoice_pdf' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/pdf" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681/pdf" --output invoice.pdf + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + invoices = client.invoices.get_pdf_by_uuid(invoice_uuid=1) + security: + - bearer_auth: + - billing:read + /v2/customers/my/invoices/{invoice_uuid}/summary: + get: + operationId: invoices_get_summaryByUUID + summary: Retrieve an Invoice Summary by UUID + description: >- + To retrieve a summary for an invoice, send a GET request to + `/v2/customers/my/invoices/$INVOICE_UUID/summary`. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/invoice_uuid' + responses: + '200': + $ref: '#/components/responses/invoice_summary' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681/summary" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + invoice = client.invoices.get_summary_by_uuid(invoice_uuid="1") + security: + - bearer_auth: + - billing:read + /v2/billing/{account_urn}/insights/{start_date}/{end_date}: + get: + operationId: billingInsights_list + summary: List Billing Insights + description: >- + + 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. + tags: + - Billing + parameters: + - $ref: '#/components/parameters/account_urn' + - $ref: '#/components/parameters/start_date' + - $ref: '#/components/parameters/end_date' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/billing_insights' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/billing/do:team:12345678-1234-1234-1234-123456789012/insights/2025-01-01/2025-01-31?per_page=20&page=1" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + insights = client.billing.list_insights( + account_urn="do:team:12345678-1234-1234-1234-123456789012", + start_date="2025-01-01", + end_date="2025-01-31", + per_page=100, + page=1 + ) + security: + - bearer_auth: + - billing:read + /v2/databases/options: + get: + operationId: databases_list_options + summary: List Database Options + description: >- + 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. + tags: + - Databases + responses: + '200': + $ref: '#/components/responses/options' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/options" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + options, _, err := client.Databases.ListOptions(ctx) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.databases.list_options() + security: + - bearer_auth: + - database:read + /v2/databases: + get: + operationId: databases_list_clusters + summary: List All Database Clusters + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/tag_name' + responses: + '200': + $ref: '#/components/responses/database_clusters' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + clusters, _, err := client.Databases.List(ctx, opt) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.databases.list_clusters(tag_name="production") + security: + - bearer_auth: + - database:read + post: + operationId: databases_create_cluster + summary: Create a New Database Cluster + description: >- + 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. + tags: + - Databases + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/database_cluster' + - type: object + properties: + backup_restore: + $ref: '#/components/schemas/database_backup' + examples: + Create a New Database Cluster: + value: + name: backend + engine: pg + version: '14' + region: nyc3 + size: db-s-2vcpu-4gb + storage_size_mib: 61440 + num_nodes: 2 + tags: + - production + Create a New Database Cluster with trusted sources: + value: + name: backend + engine: pg + version: '14' + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 2 + storage_size_mib: 61440 + tags: + - production + rules: + - type: ip_addr + value: 192.168.1.1 + - type: k8s + value: ff2a6c52-5a44-4b63-b99c-0e98e7a63d61 + - type: droplet + value: '163973392' + - type: tag + value: test + description: a test tag + Restore from a Database Cluster Backup: + value: + name: backend-restored + backup_restore: + database_name: backend + backup_created_at: '2019-01-31T19:25:22Z' + engine: pg + version: '14' + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 2 + Create a New Database Cluster with service CNAMEs: + value: + name: backend + engine: pg + version: '14' + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 2 + storage_size_mib: 61440 + tags: + - production + do_settings: + service_cnames: + - db.example.com + - database.myapp.io + Create a New PostgreSQL Advanced Edition Cluster: + value: + name: backend-advanced + engine: advanced_pg + version: '18' + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 3 + storage_size_mib: 61440 + tags: + - production + Create a New MySQL Advanced Edition Cluster: + value: + name: backend-advanced + engine: advanced_mysql + version: 8.4.8 + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 3 + storage_size_mib: 61440 + tags: + - production + Create a Single-Node MySQL Advanced Edition Cluster: + value: + name: backend-advanced-single + engine: advanced_mysql + version: 8.4.8 + region: nyc3 + size: db-s-2vcpu-4gb + num_nodes: 1 + storage_size_mib: 61440 + tags: + - production + responses: + '201': + $ref: '#/components/responses/database_cluster' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "backend", "engine": "pg", "version": "14", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "storage_size_mib": 61440, "tags": ["production"], "do_settings": {"service_cnames": ["db.example.com", "database.myapp.io"]}}' \ + "https://api.digitalocean.com/v2/databases" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.DatabaseCreateRequest{ + Name: "backend", + EngineSlug: "pg", + Version: "14", + Region: "nyc3", + SizeSlug: "db-s-2vcpu-4gb", + NumNodes: 2, + StorageSizeMiB : 61440, + DOSettings: &godo.DOSettings{ + ServiceCnames: []string{"db.example.com", "database.myapp.io"}, + }, + } + + cluster, _, err := client.Databases.Create(ctx, createRequest) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + create_req = { + "name": "backend", + "engine": "pg", + "version": "14", + "region": "nyc3", + "size": "db-s-2vcpu-4gb", + "num_nodes": 2, + "storage_size_mib": 61440, + "tags": [ + "production" + ], + "do_settings": { + "service_cnames": [ + "db.example.com", + "database.myapp.io" + ] + } + } + + create_resp = client.databases.create_cluster(body=create_req) + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}: + get: + operationId: databases_get_cluster + summary: Retrieve an Existing Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/database_cluster' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + cluster, _, err := client.Databases.Get(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_cluster(database_cluster_uuid="a7a89a") + security: + - bearer_auth: + - database:read + delete: + operationId: databases_destroy_cluster + summary: Destroy a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X DELETE \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + _, err := client.Databases.Delete(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_resp = + client.databases.destroy_cluster(database_cluster_uuid="a7abba8") + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/config: + get: + operationId: databases_get_config + summary: Retrieve an Existing Database Cluster Configuration + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/database_config' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/config" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_config(database_cluster_uuid="a7a90ab") + security: + - bearer_auth: + - database:read + patch: + operationId: databases_patch_config + summary: Update the Database Configuration for an Existing Database + description: > + To update the configuration for an existing database cluster, send a + PATCH request to + + `/v2/databases/$DATABASE_ID/config`. + tags: + - Databases + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/database_config' + example: + config: + sql_mode: >- + ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES + sql_require_primary_key: true + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"config": {"sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES","sql_require_primary_key": true}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/config" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.databases.patch_config(database_cluster_uuid="a7aba9d") + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/ca: + get: + operationId: databases_get_ca + summary: Retrieve the Public Certificate + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/ca' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/ca" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + ca, _, err := client.Databases.GetCA(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.databases.get_ca(database_cluster_uuid="aba77ada") + security: + - bearer_auth: + - database:read + /v2/databases/{database_cluster_uuid}/online-migration: + get: + operationId: databases_get_migrationStatus + summary: Retrieve the Status of an Online Migration + description: >- + To retrieve the status of the most recent online migration, send a GET + request to `/v2/databases/$DATABASE_ID/online-migration`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/online_migration' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X GET \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_migration_status(database_cluster_uuid="a7a7ab90") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_onlineMigration + summary: Start an Online Migration + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/source_database' + example: + source: + host: source-do-user-6607903-0.b.db.ondigitalocean.com + dbname: defaultdb + port: 25060 + username: doadmin + password: paakjnfe10rsrsmf + disable_ssl: false + ignore_dbs: + - db0 + - db1 + responses: + '200': + $ref: '#/components/responses/online_migration' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X PUT \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d + '{"source":{"host":"source-do-user-6607903-0.b.db.ondigitalocean.com","dbname":"defaultdb","port":25060,"username":"doadmin","password":"paakjnfe10rsrsmf"},"disable_ssl":false,"ignore_dbs":["db0","db1"]}' + \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "source": { + "host": "source-do-user-6607903-0.b.db.ondigitalocean.com", + "dbname": "defaultdb", + "port": 25060, + "username": "doadmin", + "password": "paakjnfe10rsrsmf" + }, + "disable_ssl": False + "ignore_dbs": ["db0","db1"] + } + + + update_resp = + client.databases.update_online_migration(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/online-migration/{migration_id}: + delete: + operationId: databases_delete_onlineMigration + summary: Stop an Online Migration + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/migration_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X DELETE \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/online-migration/77b28fc8-19ff-11eb-8c9c-c68e24557488" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_resp = + client.databases.delete_online_migration(database_cluster_uuid="9cc10173", + migration="77b28fc8") + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/migrate: + put: + operationId: databases_update_region + summary: Migrate a Database Cluster to a New Region + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + region: + type: string + example: lon1 + description: >- + A slug identifier for the region to which the database + cluster will be migrated. + required: + - region + example: + region: lon1 + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"region":"lon1"}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/migrate" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + migrateRequest := &godo.DatabaseMigrateRequest{ + Region: "lon1", + } + + _, err := client.Databases.Migrate(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", migrateRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "region": "lon1" + } + + + update_resp = + client.databases.update_region(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/resize: + put: + operationId: databases_update_clusterSize + summary: Resize a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/database_cluster_resize' + example: + size: db-s-4vcpu-8gb + num_nodes: 3 + storage_size_mib: 163840 + responses: + '202': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X PUT \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d '{"size":"db-s-4vcpu-8gb", "num_nodes":3, + "storage_size_mib":163840}' \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/resize" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + resizeRequest := &godo.DatabaseResizeRequest{ + SizeSlug: "db-s-4vcpu-8gb", + NumNodes: 3, + StorageSizeMib: 163840, + } + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "size": "db-s-4vcpu-8gb", + "num_nodes": 3, + "storage_size_mib": 163840 + } + + + update_resp = + client.databases.update_cluster_size(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/firewall: + get: + operationId: databases_list_firewall_rules + summary: List Firewall Rules (Trusted Sources) for a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/firewall_rules' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + rules, _, err := client.Databases.GetFirewallRules(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.list_firewall_rules(database_cluster_uuid="a7aab9a") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_firewall_rules + summary: Update Firewall Rules (Trusted Sources) for a Database + description: >- + 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). 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 + tags: + - Databases + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + rules: + type: array + items: + $ref: '#/components/schemas/firewall_rule' + example: + rules: + - type: ip_addr + value: 192.168.1.1 + - type: k8s + value: ff2a6c52-5a44-4b63-b99c-0e98e7a63d61 + - type: droplet + value: '163973392' + - type: tag + value: backend + description: a backend tag + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"rules": [{"type": "ip_addr","value": "192.168.1.1"},{"type": "droplet","value": "163973392"},{"type": "k8s","value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"},{"type": "tag","value": "backend"}]}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + req := godo.DatabaseUpdateFirewallRulesRequest{ + Rules: []*godo.DatabaseFirewallRule{ + { + Type: "ip_addr", + Value: "192.168.1.1", + Description: "a development IP address", + }, + { + Type: "droplet", + Value: "163973392", + }, + { + Type: "k8s", + Value: "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61", + }, + }, + } + _, err := client.Databases.UpdateFirewallRules(ctx, dbID, &req) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "rules": [ + { + "type": "ip_addr", + "value": "192.168.1.1", + "description": "a development IP address", + }, + { + "type": "k8s", + "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61" + }, + { + "type": "droplet", + "value": "163973392" + }, + { + "type": "tag", + "value": "backend" + } + ] + } + + update_resp = + client.databases.update_firewall_rules(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/maintenance: + put: + operationId: databases_update_maintenanceWindow + summary: Configure a Database Cluster's Maintenance Window + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/database_maintenance_window' + example: + day: tuesday + hour: '14:00' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"day": "tuesday", "hour": "14:00"}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/maintenance" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + maintenanceRequest := &godo.DatabaseUpdateMaintenanceRequest{ + Day: "thursday", + Hour: "16:00", + } + + _, err := client.Databases.UpdateMaintenance(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", maintenanceRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "day": "tuesday", + "hour": "14:00" + } + + + update_resp = + client.databases.update_maintenance_window(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/install_update: + put: + operationId: databases_install_update + summary: Start Database Maintenance + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/install_update" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Databases.InstallUpdate(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + update_resp = + client.databases.install_update(database_cluster_uuid="a7a8bas") + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/backups: + get: + operationId: databases_list_backups + summary: List Backups for a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/database_backups' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + backups, _, err := client.Databases.ListBackups(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.list_backups(database_cluster_uuid="a9a8a77") + security: + - bearer_auth: + - database:read + /v2/databases/{database_cluster_uuid}/replicas: + get: + operationId: databases_list_replicas + summary: List All Read-only Replicas + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/database_replicas' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replicas, _, err := client.Databases.ListReplicas(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.list_replicas(database_cluster_uuid="a7aba3") + security: + - bearer_auth: + - database:read + post: + operationId: databases_create_replica + summary: Create a Read-only Replica + description: >- + 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`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/database_replica' + required: + - name + - size + examples: + Create a Read-only Replica: + value: + name: read-nyc3-01 + region: nyc3 + size: db-s-2vcpu-4gb + storage_size_mib: 61440 + Create a Read-only Replica with service CNAMEs: + value: + name: read-nyc3-01 + region: nyc3 + size: db-s-2vcpu-4gb + storage_size_mib: 61440 + do_settings: + service_cnames: + - replica-db.example.com + - read-replica.myapp.io + responses: + '201': + $ref: '#/components/responses/database_replica' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"read-nyc3-01", "region":"nyc3", "size": "db-s-2vcpu-4gb", "storage_size_mib": 61440, "do_settings": {"service_cnames": ["replica-db.example.com", "read-replica.myapp.io"]}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replicaRequest := &godo.DatabaseCreateReplicaRequest{ + Name: "read-nyc3-01", + Region: "nyc3", + Size: "db-s-2vcpu-4gb", + StorageSizeMiB: 61440, + DOSettings: &godo.DOSettings{ + ServiceCnames: []string{"replica-db.example.com", "read-replica.myapp.io"}, + }, + } + + replica, _, err := client.Databases.CreateReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", replicaRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + create_req = { + "name": "read-nyc3-01", + "region": "nyc3", + "size": "db-s-2vcpu-4gb", + "storage_size_mib": 61440, + "do_settings": { + "service_cnames": [ + "replica-db.example.com", + "read-replica.myapp.io" + ] + } + } + + + create_resp = + client.databases.create_replica(database_cluster_uuid="9cc10173", + body=create_req) + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/events: + get: + operationId: databases_list_events_logs + summary: List all Events Logs + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/events_logs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/events" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replicas, _, err := client.Databases.ListProjectEvents(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + security: + - bearer_auth: + - database:read + /v2/databases/{database_cluster_uuid}/replicas/{replica_name}: + get: + operationId: databases_get_replica + summary: Retrieve an Existing Read-only Replica + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/replica_name' + responses: + '200': + $ref: '#/components/responses/database_replica' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replica, _, err := client.Databases.GetReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_replica(database_cluster_uuid="a7a90a", + replica_name="backend-replica") + security: + - bearer_auth: + - database:read + delete: + operationId: databases_destroy_replica + summary: Destroy a Read-only Replica + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/replica_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Databases.DeleteReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_resp = + client.databases.destroy_replica(database_cluster_uuid="ba88aab", + replica_name="read_nyc_3") + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/replicas/{replica_name}/promote: + put: + operationId: databases_promote_replica + summary: Promote a Read-only Replica to become a Primary Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/replica_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01/promote" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Databases.PromoteReplicaToPrimary(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.databases.promote_replica(database_cluster_uuid="a7a8bas", + replica_name="ba8ab22") + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/users: + get: + operationId: databases_list_users + summary: List all Database Users + description: > + 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 MongoDB clusters, additional information will be contained in the + mongo_user_settings object + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/users' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + users, _, err := client.Databases.ListUsers(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", nil) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.list_users(database_cluster_uuid="a7aba3") + security: + - bearer_auth: + - database:read + post: + operationId: databases_add_user + summary: Add a Database User + description: > + 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 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/database_user' + - type: object + properties: + readonly: + type: boolean + example: true + description: > + (To be deprecated: use settings.mongo_user_settings.role + instead for access controls to MongoDB databases). + + For MongoDB clusters, set to `true` to create a + read-only user. + + This option is not currently supported for other + database engines. + + examples: + Add New User: + value: + name: app-01 + Add New User with MySQL Auth Plugin: + value: + name: app-02 + mysql_settings: + auth_plugin: mysql_native_password + Add New Read Only User (MongoDB Only): + value: + name: my-readonly + readonly: true + Add New User that is restricted to a database (MongoDB Only): + value: + name: my-readWrite + settings: + mongo_user_settings: + databases: + - my-db + - my-db-2 + role: readWrite + Add New User for Postgres with replication rights: + value: + name: app-02 + settings: + pg_allow_replication: true + Add New User with Kafka ACLs: + value: + name: app-03 + settings: + acl: + - permission: produceconsume + topic: customer-events + - permission: produce + topic: customer-events.* + - permission: consume + topic: customer-events + responses: + '201': + $ref: '#/components/responses/user' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "app-01"}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + addUserRequest := &godo.DatabaseCreateUserRequest{ + Name: "app-01", + } + + user, _, err := client.Databases.CreateUser(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", addUserRequest) + + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + add_user_resp = + client.databases.add_user(database_cluster_uuid="ab7bb7a", + body={"name": "app-01"}) + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/users/{username}: + get: + operationId: databases_get_user + summary: Retrieve an Existing Database User + description: > + 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 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 + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/username' + responses: + '200': + $ref: '#/components/responses/user' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + user, _, err := client.Databases.GetUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.databases.get_user(database_cluster_uuid="9a9aba", + username="admin") + security: + - bearer_auth: + - database:read + delete: + operationId: databases_delete_user + summary: Remove a Database User + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/username' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Databases.DeleteUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_resp = + client.databases.delete_user(database_cluster_uuid="aba134a", + username="backend_user1") + security: + - bearer_auth: + - database:delete + put: + operationId: databases_update_user + summary: Update a Database User + description: > + 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. + + + 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 update database user, along with + the `settings` object that + + has been updated. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/username' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - type: object + properties: + settings: + $ref: '#/components/schemas/user_settings' + required: + - settings + examples: + Update User Kafka ACLs: + value: + settings: + acl: + - id: acl128aaaa99239 + permission: produceconsume + topic: customer-events + - id: acl293098flskdf + permission: produce + topic: customer-events.* + - id: acl128ajei20123 + permission: consume + topic: customer-events + responses: + '201': + $ref: '#/components/responses/user' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"settings": {"acl": [{"topic": "events", "permission": "produce"}]}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + userName := "test-user" + + updateUserRequest := &godo.DatabaseUpdateUserRequest{ + Settings: { + ACL: [ + { + Permssion: "consume", + Topic: "events", + } + { + Permission: "produce", + Topic: "metrics", + } + ] + } + } + + user, _, err := client.Databases.UpdateUser(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", userName, updateUserRequest) + } + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/users/{username}/reset_auth: + post: + operationId: databases_reset_auth + summary: Reset a Database User's Password or Authentication Method + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/username' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + mysql_settings: + $ref: '#/components/schemas/mysql_settings' + example: + mysql_settings: + auth_plugin: caching_sha2_password + responses: + '200': + $ref: '#/components/responses/user' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"mysql_settings":{"auth_plugin": "caching_sha2_password"}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01/reset_auth" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + resetUserAuthRequest := &godo.DatabaseResetUserAuthRequest{ + MySQLSettings: &DatabaseMySQLUserSettings{ + AuthPlugin: "caching_sha2_password", + }, + } + user, _, err := client.Databases.ResetUserAuth(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", "app-01", resetuserAuthRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "mysql_settings": { + "auth_plugin": "caching_sha2_password" + } + } + + + get_resp = + client.databases.reset_auth(database_cluster_uuid="a7a8bas", + username="admin", body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/dbs: + get: + operationId: databases_list + summary: List All Databases + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/databases' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + dbs, _, err := client.Databases.ListDBs(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + get_resp = client.databases.list(database_cluster_uuid="a7aba9d") + security: + - bearer_auth: + - database:read + post: + operationId: databases_add + summary: Add a New Database + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/database' + example: + name: alpha + responses: + '201': + $ref: '#/components/responses/database' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "alpha"}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createDBReq := &godo.DatabaseCreateDBRequest{ + Name: "alpha", + } + + db, _, err := client.Databases.CreateDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createDBReq) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + add_resp = client.databases.add(database_cluster_uuid="9cc10173", + body={"name": "alpha"}) + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/dbs/{database_name}: + get: + operationId: databases_get + summary: Retrieve an Existing Database + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/database_name' + responses: + '200': + $ref: '#/components/responses/database' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + db, _, err := client.Databases.GetDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.databases.get(database_cluster_uuid="a9a8a77", + database_name="admin") + security: + - bearer_auth: + - database:read + delete: + operationId: databases_delete + summary: Delete a Database + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/database_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Databases.DeleteDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_resp = + client.databases.delete(database_cluster_uuid="a7abda", + database_name="ba1341") + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/pools: + get: + operationId: databases_list_connectionPools + summary: List Connection Pools (PostgreSQL) + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/connection_pools' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X GET / + + -H "Content-Type: application/json" / + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" / + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + pools, _, err := client.Databases.ListPools(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.list_connection_pools(database_cluster_uuid="a7aab9a") + security: + - bearer_auth: + - database:read + post: + operationId: databases_add_connectionPool + summary: Add a New Connection Pool (PostgreSQL) + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/connection_pool' + example: + name: backend-pool + mode: transaction + size: 10 + db: defaultdb + user: doadmin + responses: + '201': + $ref: '#/components/responses/connection_pool' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X POST \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d '{"name": "backend-pool","mode": "transaction","size": 10,"db": + "defaultdb","user": "doadmin"}' \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + createPoolReq := &godo.DatabaseCreatePoolRequest{ + Name: "backend-pool", + Database: "defaultdb", + Size: 10, + User: "doadmin", + Mode: "transaction", + } + + pool, _, err := client.Databases.CreatePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createPoolReq) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + add_conn_pool_req = { + "name": "backend-pool", + "mode": "transaction", + "size": 10, + "db": "defaultdb", + "user": "doadmin" + } + + + add_conn_pool_resp = + client.databases.add_connection_pool(database_cluster_uuid="9cc10173", + body=add_conn_pool_req) + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/pools/{pool_name}: + get: + operationId: databases_get_connectionPool + summary: Retrieve Existing Connection Pool (PostgreSQL) + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/pool_name' + responses: + '200': + $ref: '#/components/responses/connection_pool' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X GET / + + -H "Content-Type: application/json" / + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" / + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + pool, _, err := client.Databases.GetPool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_connection_pool(database_cluster_uuid="a7aba8a", + pool_name="backend-pool") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_connectionPool + summary: Update Connection Pools (PostgreSQL) + description: >- + To update a connection pool for a PostgreSQL database cluster, send a + PUT request to `/v2/databases/$DATABASE_ID/pools/$POOL_NAME`. + tags: + - Databases + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/connection_pool_update' + example: + mode: transaction + size: 10 + db: defaultdb + user: doadmin + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/pool_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X PUT \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d '{"mode": "transaction", "size": 15, "db": "defaultdb", "user": + "doadmin"}' \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + updateReq := &godo.DatabaseUpdatePoolRequest{ + User: "doadmin", + Size: 15, + Database: "defaultdb", + Mode: "transaction", + } + + _, err := client.Databases.UpdatePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool", updateReq) + + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "mode": "transaction", + "size": 10, + "db": "defaultdb", + "user": "doadmin" + } + + + update_resp = + client.databases.update_connection_pool(database_cluster_uuid="a7a8bas", + pool_name="conn_pool", body=req) + security: + - bearer_auth: + - database:update + delete: + operationId: databases_delete_connectionPool + summary: Delete a Connection Pool (PostgreSQL) + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/pool_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X GET \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool" + - lang: Go + source: |- + import ( + "context" + "github.com/digitalocean/godo" + ) + + func main() { + pat := "mytoken" + + client := godo.NewFromToken(pat) + ctx := context.TODO() + + _, err := client.Databases.DeletePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + delete_conn_pool = + client.databases.delete_connection_pool(database_cluster_uuid="9cc10173", + pool_name="backend-pool") + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/eviction_policy: + get: + operationId: databases_get_evictionPolicy + summary: Retrieve the Eviction Policy for a Caching or Valkey Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/eviction_policy_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + db, _, err := client.Databases.GetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_eviction_policy(database_cluster_uuid="a7aa89a") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_evictionPolicy + summary: Configure the Eviction Policy for a Caching or Valkey Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - eviction_policy + properties: + eviction_policy: + $ref: '#/components/schemas/eviction_policy_model' + example: + eviction_policy: allkeys_lru + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"eviction_policy":"allkeys_lru"}' \ + "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + db, _, err := client.Databases.SetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "allkeys_lru") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "eviction_policy": "allkeys_lru" + } + + + update_resp = + client.databases.update_eviction_policy(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/sql_mode: + get: + operationId: databases_get_sql_mode + summary: Retrieve the SQL Modes for a MySQL Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/sql_mode' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + sqlMode, _, err := client.Databases.GetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_sql_mode(database_cluster_uuid="90abaa8") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_sql_mode + summary: Update SQL Mode for a Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/sql_mode' + example: + sql_mode: >- + ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"sql_mode":"ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE"}' \ + "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + sqlMode := "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE" + _, err := client.Databases.SetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", sqlMode) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE" + } + + + update_resp = + client.databases.update_sql_mode(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/upgrade: + put: + operationId: databases_update_major_version + summary: Upgrade Major Version for a Database + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/version-2' + example: + version: '14' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"version":"14"}' \ + "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/upgrade" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "version": "14" + } + + + update_resp = + client.databases.update_major_version(database_cluster_uuid="a7a8bas", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/autoscale: + get: + operationId: databases_get_autoscale + summary: Retrieve Autoscale Configuration for a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/autoscale' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/autoscale" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = + client.databases.get_autoscale(database_cluster_uuid="a7a89a") + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_autoscale + summary: Configure Autoscale Settings for a Database Cluster + description: >- + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/database_autoscale_params' + example: + storage: + enabled: true + threshold_percent: 80 + increment_gib: 10 + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"storage":{"enabled":true,"threshold_percent":80,"increment_gib":10}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/autoscale" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "storage": { + "enabled": True, + "threshold_percent": 80, + "increment_gib": 10 + } + } + + + update_resp = + client.databases.update_autoscale(database_cluster_uuid="a7a89a", + body=req) + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/topics: + get: + operationId: databases_list_kafka_topics + summary: List Topics for a Kafka Cluster + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/kafka_topics' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replicas, _, err := client.Databases.ListTopics(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + security: + - bearer_auth: + - database:read + post: + operationId: databases_create_kafka_topic + summary: Create Topic for a Kafka Cluster + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/kafka_topic_create' + required: + - name + example: + name: customer-events + partitions: 3 + replication: 2 + config: + retention_bytes: -1 + retention_ms: 100000 + responses: + '201': + $ref: '#/components/responses/kafka_topic' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"customer-events", "partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &DatabaseCreateTopicRequest{ + Name: "events", + PartitionCount: 3, + ReplicationFactor: 2, + Config: &TopicConfig{ + RetentionMS: 60000, + } + }, + + cluster, _, err := client.Databases.CreateTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createRequest) + } + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/topics/{topic_name}: + get: + operationId: databases_get_kafka_topic + summary: Get Topic for a Kafka Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_topic_name' + responses: + '200': + $ref: '#/components/responses/kafka_topic' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + topicName := "events" + + user, _, err := client.Databases.GetTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName) + } + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_kafka_topic + summary: Update Topic for a Kafka Cluster + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_topic_name' + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/kafka_topic_update' + example: + partitions: 3 + replication: 2 + config: + retention_bytes: -1 + retention_ms: 100000 + responses: + '200': + $ref: '#/components/responses/kafka_topic' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"partition_count":3, "replication_factor": 3, "config": {"retentionMS": 1000000}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + topicName := "events" + updateRequest := &DatabaseUpdateTopicRequest{ + PartitionCount: 3, + ReplicationFactor: 2, + Config: &TopicConfig{ + RetentionMS: 60000, + }, + } + + _, err := client.Databases.UpdateTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName, updateRequest) + } + security: + - bearer_auth: + - database:update + delete: + operationId: databases_delete_kafka_topic + summary: Delete Topic for a Kafka Cluster + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_topic_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/topics/customer-events" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + topicName := "events" + + _, err := client.Databases.DeleteTopic(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", topicName) + } + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/logsink: + get: + operationId: databases_list_logsink + summary: | + List Logsinks for a Database Cluster + description: | + To list logsinks for a database cluster, send a GET request to + `/v2/databases/$DATABASE_ID/logsink`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/logsinks' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink" + security: + - bearer_auth: + - database:read + post: + operationId: databases_create_logsink + summary: | + Create Logsink for a Database Cluster + description: | + To create logsink for a database cluster, send a POST request to + `/v2/databases/$DATABASE_ID/logsink`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/logsink_create' + required: + - sink_name + - sink_type + - config + examples: + Create an opensearch logsink: + value: + sink_name: logs-sink + sink_type: opensearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: opensearch-logs + index_days_max: 5 + Create an elasticsearch logsink: + value: + sink_name: logs-sink + sink_type: elasticsearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: elasticsearch-logs + index_days_max: 5 + Create a rsyslog logsink: + value: + sink_name: logs-sink + sink_type: rsyslog + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc5424 + Create a datadog logsink: + value: + sink_name: logs-sink + sink_type: datadog + config: + datadog_api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + site: http-intake.logs.datadoghq.com + responses: + '201': + $ref: '#/components/responses/logsink' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"sink_name": "logsink", "sink_type": "rsyslog", "config": {"server": "192.168.10.1", "port": 514, "tls": false, "format": "rfc5424"}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink" + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/logsink/{logsink_id}: + get: + operationId: databases_get_logsink + summary: | + Get Logsink for a Database Cluster + description: | + To get a logsink for a database cluster, send a GET request to + `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/logsink_id' + responses: + '200': + $ref: '#/components/responses/logsink_data' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_logsink + summary: | + Update Logsink for a Database Cluster + description: | + To update a logsink for a database cluster, send a PUT request to + `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/logsink_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/logsink_update' + example: + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc3164 + responses: + '200': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"config": {"server": "192.168.1.1", "port": 514, "tls": false, "format": "rfc3164"}}' \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" + security: + - bearer_auth: + - database:update + delete: + operationId: databases_delete_logsink + summary: | + Delete Logsink for a Database Cluster + description: | + To delete a logsink for a database cluster, send a DELETE request to + `/v2/databases/$DATABASE_ID/logsink/$LOGSINK_ID`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/logsink_id' + responses: + '200': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/logsink/77b28fc8-19ff-11eb-8c9c-c68e24557488" + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/schema-registry: + get: + operationId: databases_list_kafka_schemas + summary: | + List Schemas for Kafka Cluster + description: | + To list all schemas for a Kafka cluster, send a GET request to + `/v2/databases/$DATABASE_ID/schema-registry`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/kafka_schemas' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:read + post: + operationId: databases_create_kafka_schema + summary: | + Create Schema Registry for Kafka Cluster + description: | + To create a Kafka schema for a database cluster, send a POST request to + `/v2/databases/$DATABASE_ID/schema-registry`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/database_kafka_schema_create' + required: + - subject_name + - schema_type + - schema + example: + subject_name: customer-schema + schema_type: AVRO + schema: | + { + "type": "record", + "name": "Customer", + "fields": [ + {"name": "id", "type": "string"}, + {"name": "name", "type": "string"}, + {"name": "email", "type": "string"}, + {"name": "created_at", "type": "long"} + ] + } + responses: + '201': + $ref: '#/components/responses/kafka_schema' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:create + /v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}: + get: + operationId: databases_get_kafka_schema + summary: | + Get a Kafka Schema by Subject Name + description: > + 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`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_schema_subject_name' + responses: + '200': + $ref: '#/components/responses/kafka_schema_version' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + security: + - bearer_auth: + - database:read + delete: + operationId: databases_delete_kafka_schema + summary: | + Delete a Kafka Schema by Subject Name + description: > + 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`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_schema_subject_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + security: + - bearer_auth: + - database:delete + /v2/databases/{database_cluster_uuid}/schema-registry/{subject_name}/versions/{version}: + get: + operationId: databases_get_kafka_schema_version + summary: Get Kafka Schema by Subject Version + description: > + 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`. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_schema_subject_name' + - $ref: '#/components/parameters/kafka_schema_version' + responses: + '200': + $ref: '#/components/responses/kafka_schema_version' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + security: + - bearer_auth: + - database:read + /v2/databases/{database_cluster_uuid}/schema-registry/config: + get: + operationId: databases_get_kafka_schema_config + summary: Retrieve Schema Registry Configuration for a kafka Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/database_schema_registry_config' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_kafka_schema_config + summary: Update Schema Registry Configuration for a kafka Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + requestBody: + content: + application/json: + schema: + type: object + properties: + compatibility_level: + type: string + enum: + - NONE + - BACKWARD + - BACKWARD_TRANSITIVE + - FORWARD + - FORWARD_TRANSITIVE + - FULL + - FULL_TRANSITIVE + description: The compatibility level of the schema registry. + required: + - compatibility_level + example: + compatibility_level: BACKWARD + responses: + '200': + $ref: '#/components/responses/database_schema_registry_config' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:write + /v2/databases/{database_cluster_uuid}/schema-registry/config/{subject_name}: + get: + operationId: databases_get_kafka_schema_subject_config + summary: Retrieve Schema Registry Configuration for a Subject of kafka Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_schema_subject_name' + responses: + '200': + $ref: '#/components/responses/database_schema_registry_subject_config' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:read + put: + operationId: databases_update_kafka_schema_subject_config + summary: Update Schema Registry Configuration for a Subject of kafka Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/kafka_schema_subject_name' + requestBody: + content: + application/json: + schema: + type: object + properties: + compatibility_level: + type: string + enum: + - NONE + - BACKWARD + - BACKWARD_TRANSITIVE + - FORWARD + - FORWARD_TRANSITIVE + - FULL + - FULL_TRANSITIVE + description: The compatibility level of the schema registry. + required: + - compatibility_level + example: + compatibility_level: BACKWARD + responses: + '200': + $ref: '#/components/responses/database_schema_registry_subject_config' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - database:write + /v2/databases/metrics/credentials: + get: + operationId: databases_get_cluster_metrics_credentials + summary: Retrieve Database Clusters' Metrics Endpoint Credentials + description: >- + 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. + tags: + - Databases + responses: + '200': + $ref: '#/components/responses/database_metrics_auth' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/metrics/credentials" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + creds, _, _ := client.Databases.GetMetricsCredentials(ctx) + } + security: + - bearer_auth: + - database:update + - database:view_credentials + put: + operationId: databases_update_cluster_metrics_credentials + summary: Update Database Clusters' Metrics Endpoint Credentials + description: >- + 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. + tags: + - Databases + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/database_metrics_credentials' + example: + credentials: + basic_auth_username: new_username + basic_auth_password: new_password + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"credentials": {"basic_auth_username": "new_username", "basic_auth_password": "new_password"}}'\ + "https://api.digitalocean.com/v2/databases/metrics/credentials" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, _ = client.Databases.UpdateMetricsCredentials(ctx, &godo.DatabaseUpdateMetricsCredentialsRequest{ + Credentials: &godo.DatabaseMetricsCredentials{ + BasicAuthUsername: "a_new_username", + BasicAuthPassword: "a_new_password", + }, + }) + } + security: + - bearer_auth: + - database:update + /v2/databases/{database_cluster_uuid}/indexes: + get: + operationId: databases_list_opeasearch_indexes + summary: List Indexes for a OpenSearch Cluster + description: | + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + responses: + '200': + $ref: '#/components/responses/opensearch_indexes' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/indexes" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + replicas, _, err := client.Databases.ListIndexes(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil) + } + security: + - bearer_auth: + - database:read + /v2/databases/{database_cluster_uuid}/indexes/{index_name}: + delete: + operationId: databases_delete_opensearch_index + summary: Delete Index for OpenSearch Cluster + description: > + 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. + tags: + - Databases + parameters: + - $ref: '#/components/parameters/database_cluster_uuid' + - $ref: '#/components/parameters/opensearch_index_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/indexes/sample-index" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + indexName := "sampe-index" + + _, err := client.Databases.DeleteIndex(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", indexName) + } + security: + - bearer_auth: + - database:delete + /v2/dedicated-inferences/{dedicated_inference_id}: + get: + operationId: dedicatedInferences_get + summary: Get a Dedicated Inference + description: > + 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. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + responses: + '200': + $ref: '#/components/responses/dedicated_inference' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + patch: + operationId: dedicatedInferences_patch + summary: Update a Dedicated Inference + description: > + 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. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/dedicated_inference_update_request' + responses: + '202': + $ref: '#/components/responses/dedicated_inference_update_accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X PATCH + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" \ + -d '{ + "spec": { + "name": "renamed-dedicated-inference", + "region": "atl1", + "vpc": { "uuid": "997615ce-132d-4bae-9270-9ee21b395e5d" }, + "model_deployments": [{ + "model_slug": "mistral/mistral-7b-instruct-v3", + "accelerator_slug": "gpu-mi300x1-192gb", + "node_count": 3 + }] + }, + "access_tokens": { "hugging_face_token": "$HF_TOKEN" } + }' + security: + - bearer_auth: + - dedicated_inference:update + delete: + operationId: dedicatedInferences_delete + summary: Delete a Dedicated Inference + description: > + 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. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X DELETE + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:delete + /v2/dedicated-inferences: + get: + operationId: dedicatedInferences_list + summary: List Dedicated Inferences + description: > + 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. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/region' + responses: + '200': + $ref: '#/components/responses/all_dedicated_inferences' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences?region=nyc2&page=1&per_page=20" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + post: + operationId: dedicatedInferences_create + summary: Create a Dedicated Inference + description: > + 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. + tags: + - Dedicated Inference + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/dedicated_inference_create_request' + responses: + '202': + $ref: '#/components/responses/dedicated_inference_provisioning' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X POST + "https://api.digitalocean.com/v2/dedicated-inferences" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" \ + -d '{ + "spec": { + "version": 1, + "name": "new-dedicated-inference", + "region": "atl1", + "vpc": { "uuid": "7e5c619c-359c-44ca-87e2-47e98170c012" }, + "enable_public_endpoint": true, + "model_deployments": [{ + "model_slug": "mistral/mistral-7b-instruct-v3", + "model_provider": "hugging_face", + "workload_config": {}, + "accelerators": [{ + "scale": 2, + "type": "prefill_decode", + "accelerator_slug": "gpu-mi300x1-192gb" + }] + }] + }, + "access_tokens": { "hugging_face_token": "$HF_TOKEN" } + }' + security: + - bearer_auth: + - dedicated_inference:create + /v2/dedicated-inferences/{dedicated_inference_id}/accelerators: + get: + operationId: dedicatedInferences_list_accelerators + summary: List Dedicated Inference Accelerators + description: > + 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. + tags: + - Dedicated Inference + parameters: + - name: dedicated_inference_id + in: path + required: true + description: A unique identifier for a Dedicated Inference instance. + schema: + type: string + format: uuid + example: 6b5c619c-359c-44ca-87e2-47e98170c01d + - name: per_page + in: query + required: false + description: Number of items returned per page + schema: + type: integer + minimum: 1 + default: 20 + maximum: 200 + example: 20 + - name: page + in: query + required: false + description: Which 'page' of paginated results to return. + schema: + type: integer + minimum: 1 + default: 1 + example: 1 + - name: slug + in: query + required: false + description: Filter accelerators by GPU slug. + schema: + type: string + example: gpu-mi300x1-192gb + responses: + '200': + $ref: '#/components/responses/accelerators_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/accelerators" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + /v2/dedicated-inferences/{dedicated_inference_id}/accelerators/{accelerator_id}: + get: + operationId: dedicatedInferences_get_accelerator + summary: Get a Dedicated Inference Accelerator + description: > + 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}`. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + - $ref: '#/components/parameters/accelerator_id' + responses: + '200': + description: Single accelerator object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/dedicated_inference_accelerator' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/accelerators/5b5c619c-359c-44ca-87e2-47e98170c02f" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + /v2/dedicated-inferences/{dedicated_inference_id}/ca: + get: + operationId: dedicatedInferences_get_ca + summary: Get Dedicated Inference CA Certificate + description: > + 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`. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + responses: + '200': + $ref: '#/components/responses/ca_certificate' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/ca" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + /v2/dedicated-inferences/{dedicated_inference_id}/tokens: + get: + operationId: dedicatedInferences_list_tokens + summary: List Dedicated Inference Tokens + description: > + 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`. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/tokens_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/tokens?page=1&per_page=20" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference_tokens:read + post: + operationId: dedicatedInferences_create_tokens + summary: Create a Dedicated Inference Token + description: > + 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. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/dedicated_inference_token_create_request' + responses: + '202': + $ref: '#/components/responses/token_created' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X POST + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/tokens" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" \ + -d '{"name": "new-inference-token"}' + security: + - bearer_auth: + - dedicated_inference_tokens:create + /v2/dedicated-inferences/{dedicated_inference_id}/tokens/{token_id}: + delete: + operationId: dedicatedInferences_delete_tokens + summary: Revoke a Dedicated Inference Token + description: > + Revoke (delete) an access token for a Dedicated Inference instance. Send + a + + DELETE request to + `/v2/dedicated-inferences/{dedicated_inference_id}/tokens/{token_id}`. + tags: + - Dedicated Inference + parameters: + - $ref: '#/components/parameters/dedicated_inference_id' + - $ref: '#/components/parameters/token_id' + responses: + '204': + description: Token revoked. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X DELETE + "https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/tokens/f11d4795-c1db-4ac3-9aa6-a0ea3c58877e" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference_tokens:delete + /v2/dedicated-inferences/sizes: + get: + operationId: dedicatedInferences_list_sizes + summary: List Dedicated Inference Sizes + description: > + Get available Dedicated Inference sizes and pricing for supported GPUs. + Send a + + GET request to `/v2/dedicated-inferences/sizes`. + tags: + - Dedicated Inference + responses: + '200': + description: Enabled regions and sizes with pricing. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/dedicated_inference_sizes_response' + example: + enabled_regions: + - nyc2 + - atl1 + sizes: + - gpu_slug: gpu-mi300x1-192gb + price_per_hour: '2' + region: nyc2 + currency: USD + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/sizes" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + /v2/dedicated-inferences/gpu-model-config: + get: + operationId: dedicatedInferences_get_gpu_model_config + summary: Get Dedicated Inference GPU Model Config + description: > + 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`. + tags: + - Dedicated Inference + responses: + '200': + description: >- + GPU model configs (gpu_slugs, model_slug, model_name, + is_gated_model). + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: >- + #/components/schemas/dedicated_inference_gpu_model_configs_response + example: + gpu_model_configs: + - gpu_slugs: + - gpu-mi300x1-192gb + model_slug: mistral/mistral-7b-instruct-v3 + model_name: Mistral-7B-Instruct-v0.3 + is_gated_model: true + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -i -X GET + "https://api.digitalocean.com/v2/dedicated-inferences/gpu-model-config" + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DO_TOKEN" + security: + - bearer_auth: + - dedicated_inference:read + /v2/domains: + get: + operationId: domains_list + summary: List All Domains + description: >- + To retrieve a list of all of the domains in your account, send a GET + request to `/v2/domains`. + tags: + - Domains + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_domains_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + domains, _, err := client.Domains.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + domains = client.domains.all + domains.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.domains.list() + security: + - bearer_auth: + - domain:read + post: + operationId: domains_create + summary: Create a New Domain + description: > + 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. + tags: + - Domains + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/domain' + example: + name: example.com + responses: + '201': + $ref: '#/components/responses/create_domain_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"example.com","ip_address":"1.2.3.4"}' \ + "https://api.digitalocean.com/v2/domains" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.DomainCreateRequest{ + Name: "example.com", + IPAddress: "1.2.3.4", + } + + domain, _, err := client.Domains.Create(ctx, createRequest) + + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + domain = DropletKit::Domain.new( + name: 'example.com', + ip_address: '1.2.3.4' + ) + client.domains.create(domain) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example.com" + } + + resp = client.domains.create(body=req) + security: + - bearer_auth: + - domain:create + /v2/domains/{domain_name}: + get: + operationId: domains_get + summary: Retrieve an Existing Domain + description: >- + To get details about a specific domain, send a GET request to + `/v2/domains/$DOMAIN_NAME`. + tags: + - Domains + parameters: + - $ref: '#/components/parameters/domain_name' + responses: + '200': + $ref: '#/components/responses/existing_domain' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains/example.com" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + domain, _, err := client.Domains.Get(ctx, "example.com") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.domains.find(name: 'example.com') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.domains.get(domain_name="example.com") + security: + - bearer_auth: + - domain:read + delete: + operationId: domains_delete + summary: Delete a Domain + description: | + To delete a domain, send a DELETE request to `/v2/domains/$DOMAIN_NAME`. + tags: + - Domains + parameters: + - $ref: '#/components/parameters/domain_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains/example.com" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Domains.Delete(ctx, "example.com") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.domains.delete(name: 'example.com') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + delete_resp = client.domains.delete(domain_name="example.com") + security: + - bearer_auth: + - domain:delete + /v2/domains/{domain_name}/records: + get: + operationId: domains_list_records + summary: List All Domain Records + description: >+ + 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. + + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + - $ref: '#/components/parameters/domain_name_query' + - $ref: '#/components/parameters/domain_type_query' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_domain_records_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains/example.com/records" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + domains, _, err := client.Domains.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + records = client.domain_records.all(for_domain: 'example.com') + records.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.domains.list_records(domain_name="example.com") + security: + - bearer_auth: + - domain:read + post: + operationId: domains_create_record + summary: Create a New Domain Record + description: > + 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. + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/domain_record_a' + - $ref: '#/components/schemas/domain_record_aaaa' + - $ref: '#/components/schemas/domain_record_caa' + - $ref: '#/components/schemas/domain_record_cname' + - $ref: '#/components/schemas/domain_record_mx' + - $ref: '#/components/schemas/domain_record_ns' + - $ref: '#/components/schemas/domain_record_soa' + - $ref: '#/components/schemas/domain_record_srv' + - $ref: '#/components/schemas/domain_record_txt' + discriminator: + propertyName: type + mapping: + A: '#/components/schemas/domain_record_a' + AAAA: '#/components/schemas/domain_record_aaaa' + CAA: '#/components/schemas/domain_record_caa' + CNAME: '#/components/schemas/domain_record_cname' + MX: '#/components/schemas/domain_record_mx' + NS: '#/components/schemas/domain_record_ns' + SOA: '#/components/schemas/domain_record_soa' + SRV: '#/components/schemas/domain_record_srv' + TXT: '#/components/schemas/domain_record_txt' + example: + type: A + name: www + data: 162.10.66.0 + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + responses: + '201': + $ref: '#/components/responses/created_domain_record' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"A","name":"www","data":"162.10.66.0","priority":null,"port":null,"ttl":1800,"weight":null,"flags":null,"tag":null}' \ + "https://api.digitalocean.com/v2/domains/example.com/records" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.DomainRecordEditRequest{ + Type: "A", + Name: "www", + Data: "1.2.3.4", + } + + domainRecord, _, err := client.Domains.CreateRecord(ctx, "example.com", createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + record = DropletKit::DomainRecord.new( + type: 'A', + name: 'www', + data: '162.10.66.0' + ) + client.domain_records.create(record, for_domain: 'example.com') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "type": "A", + "name": "www", + "data": "162.10.66.0", + "priority": None, + "port": None, + "ttl": 1800, + "weight": None, + "flags": None, + "tag": None + } + + + resp = client.domains.create_record(domain_name="example.com", + body=req) + security: + - bearer_auth: + - domain:create + - bearer_auth: + - domain:update + /v2/domains/{domain_name}/records/{domain_record_id}: + get: + operationId: domains_get_record + summary: Retrieve an Existing Domain Record + description: >- + To retrieve a specific domain record, send a GET request to + `/v2/domains/$DOMAIN_NAME/records/$RECORD_ID`. + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + - $ref: '#/components/parameters/domain_record_id' + responses: + '200': + $ref: '#/components/responses/domain_record' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains/example.com/records/3352896" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + record, _, err := client.Domains.Record(ctx, "example.com", 3352896) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.domain_records.find(for_domain: 'example.com', id: 3352896) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + get_resp = client.domains.get_record(domain_name="example.com", + domain_record_id=3352896) + security: + - bearer_auth: + - domain:read + patch: + operationId: domains_patch_record + summary: Update a Domain Record + description: > + 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. + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + - $ref: '#/components/parameters/domain_record_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/domain_record' + example: + name: blog + type: A + responses: + '200': + $ref: '#/components/responses/domain_record' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"blog","type":"A"}' \ + "https://api.digitalocean.com/v2/domains/example.com/records/3352896" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "blog", + "type": "A" + } + + + resp = client.domains.patch_record(domain_name="example.com", + domain_record_id=2432342, body=req) + security: + - bearer_auth: + - domain:update + put: + operationId: domains_update_record + summary: Update a Domain Record + description: > + 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. + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + - $ref: '#/components/parameters/domain_record_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/domain_record' + example: + name: blog + type: CNAME + responses: + '200': + $ref: '#/components/responses/domain_record' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"blog"}' \ + "https://api.digitalocean.com/v2/domains/example.com/records/3352896" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + editRequest := &godo.DomainRecordEditRequest{ + Type: "A", + Name: "blog", + } + + domainRecord, _, err := client.Domains.EditRecord(ctx, "example.com", 3352896, editRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + record = DropletKit::DomainRecord.new(name: 'blog') + + client.domain_records.update(record, for_domain: 'example.com', id: + 3352896) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "blog", + "type": "CNAME" + } + + + resp = client.domains.update_record(domain_name="example.com", + domain_record_id=2432342, body=req) + security: + - bearer_auth: + - domain:update + delete: + operationId: domains_delete_record + summary: Delete a Domain Record + description: | + 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. + tags: + - Domain Records + parameters: + - $ref: '#/components/parameters/domain_name' + - $ref: '#/components/parameters/domain_record_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/domains/example.com/records/3352896" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Domains.DeleteRecord(ctx, "example.com", 3352896) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.domain_records.delete(for_domain: 'example.com', id: 3352896) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "example.com" + } + + + resp = client.domains.delete_record(domain_name="example.com", + domain_record_id=3352896) + security: + - bearer_auth: + - domain:delete + - bearer_auth: + - domain:update + /v2/droplets: + get: + operationId: droplets_list + summary: List All Droplets + description: > + 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`. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/droplet_tag_name' + - $ref: '#/components/parameters/droplet_name' + - $ref: '#/components/parameters/droplet_type' + responses: + '200': + $ref: '#/components/responses/all_droplets' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + droplets, _, err := client.Droplets.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + droplets = client.droplets.all + droplets.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list() + security: + - bearer_auth: + - droplet:read + post: + operationId: droplets_create + summary: Create a New Droplet + description: > + 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. + tags: + - Droplets + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/droplet_single_create' + - $ref: '#/components/schemas/droplet_multi_create' + examples: + Single Droplet Create Request: + $ref: '#/components/examples/droplet_create_request' + Multiple Droplet Create Request: + $ref: '#/components/examples/droplet_multi_create_request' + responses: + '202': + $ref: '#/components/responses/droplet_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"example.com","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64","ssh_keys":[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],"backups":true,"ipv6":true,"monitoring":true,"tags":["env:prod","web"],"user_data":"#cloud-config\nruncmd:\n - touch /test.txt\n","vpc_uuid":"760e09ef-dc84-11e8-981e-3cfdfeaae000"}' \ + "https://api.digitalocean.com/v2/droplets" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.DropletCreateRequest{ + Name: "example.com", + Region: "nyc3", + Size: "s-1vcpu-1gb", + Image: godo.DropletCreateImage{ + Slug: "ubuntu-20-04-x64", + }, + SSHKeys: []godo.DropletCreateSSHKey{ + godo.DropletCreateSSHKey{ID: 289794}, + godo.DropletCreateSSHKey{Fingerprint: "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"} + }, + Backups: true, + IPv6: true, + Monitoring: true, + Tags: []string{"env:prod","web"}, + UserData: "#cloud-config\nruncmd:\n - touch /test.txt\n", + VPCUUID: "760e09ef-dc84-11e8-981e-3cfdfeaae000", + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + droplet = DropletKit::Droplet.new( + name: 'example.com', + region: 'nyc3', + size: 's-1vcpu-1gb', + image: 'ubuntu-20-04-x64', + ssh_keys: [289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"], + backups: true, + ipv6: true, + monitoring: true, + tags: ["env:prod","web"], + user_data: "#cloud-config\nruncmd:\n - touch /test.txt\n", + vpc_uuid: "760e09ef-dc84-11e8-981e-3cfdfeaae000", + ) + client.droplets.create(droplet) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example.com", + "region": "nyc3", + "size": "s-1vcpu-1gb", + "image": "ubuntu-20-04-x64", + "ssh_keys": [ + 289794, + "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45" + ], + "backups": True, + "ipv6": True, + "monitoring": True, + "tags": [ + "env:prod", + "web" + ], + "user_data": "#cloud-config\nruncmd:\n - touch /test.txt\n", + "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000" + } + + resp = client.droplets.create(body=req) + security: + - bearer_auth: + - droplet:create + delete: + operationId: droplets_destroy_byTag + summary: Deleting Droplets by Tag + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_delete_tag_name' + responses: + '204': + $ref: '#/components/responses/no_content_with_content_type' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets?tag_name=awesome" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + client.Droplets.DeleteByTag(ctx, "awesome") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.droplets.delete_for_tag(tag_name: awesome) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.destroy_by_tag(tag_name="production") + security: + - bearer_auth: + - droplet:delete + /v2/droplets/{droplet_id}: + get: + operationId: droplets_get + summary: Retrieve an Existing Droplet + description: | + To show information about an individual Droplet, send a GET request to + `/v2/droplets/$DROPLET_ID`. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '200': + $ref: '#/components/responses/existing_droplet' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplet, _, err := client.Droplets.Get(ctx, 3164494) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.droplets.find(id: 3164494) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.get(droplet_id=594828) + security: + - bearer_auth: + - droplet:read + delete: + operationId: droplets_destroy + summary: Delete an Existing Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '204': + $ref: '#/components/responses/no_content_with_content_type' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Droplets.Delete(ctx, 3164494) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.droplets.delete(id: 3164494) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.destroy(droplet_id=553456) + security: + - bearer_auth: + - droplet:delete + /v2/droplets/{droplet_id}/backups: + get: + operationId: droplets_list_backups + summary: List Backups for a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_droplet_backups' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3067509/backups" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + backups, _, err := client.Droplets.Backups(ctx, 3164494, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + backups = client.droplets.backups(id: 3164494) + backups.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_backups(droplet_id=594828) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/backups/policy: + get: + operationId: droplets_get_backup_policy + summary: Retrieve the Backup Policy for an Existing Droplet + description: > + To show information about an individual Droplet's backup policy, send a + GET + + request to `/v2/droplets/$DROPLET_ID/backups/policy`. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '200': + $ref: '#/components/responses/droplet_backup_policy' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/backups/policy" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplet, _, err := client.Droplets.GetBackupPolicy(ctx, 444909706) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.get_backup_policy(droplet_id=444909706) + security: + - bearer_auth: + - droplet:read + /v2/droplets/backups/policies: + get: + operationId: droplets_list_backup_policies + summary: List Backup Policies for All Existing Droplets + description: > + To list information about the backup policies for all Droplets in the + account, + + send a GET request to `/v2/droplets/backups/policies`. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_droplet_backup_policies' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/backups/policies" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplet, _, err := client.Droplets.ListBackupPolicies(ctx) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_backup_policies() + security: + - bearer_auth: + - droplet:read + /v2/droplets/backups/supported_policies: + get: + operationId: droplets_list_supported_backup_policies + summary: List Supported Droplet Backup Policies + description: | + To retrieve a list of all supported Droplet backup policies, send a GET + request to `/v2/droplets/backups/supported_policies`. + tags: + - Droplets + responses: + '200': + $ref: '#/components/responses/droplets_supported_backup_policies' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/backups/supported_policies" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplet, _, err := client.Droplets.ListSupportedBackupPolicies(ctx) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_supported_backup_policies() + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/snapshots: + get: + operationId: droplets_list_snapshots + summary: List Snapshots for a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_droplet_snapshots' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/snapshots?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + snapshots, _, err := client.Droplets.Snapshots(ctx, 3164494, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + snapshots = client.droplets.snapshots(id: 3164494) + snapshots.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_snapshots(droplet_id=3929391) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/actions: + get: + operationId: dropletActions_list + summary: List Actions for a Droplet + description: > + 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. + tags: + - Droplet Actions + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_droplet_actions' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + actions, _, err := client.Droplets.Actions(ctx, 3164494, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + actions = client.droplets.actions(id: 3164494) + actions.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "blog", + "type": "CNAME" + } + + resp = client.droplet_actions.list(droplet_id=3164494) + security: + - bearer_auth: + - droplet:read + post: + operationId: dropletActions_post + summary: Initiate a Droplet Action + description: > + 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 | + + | ---------------------------------------- | ----------- | ----------- | + + | `enable_backups` | Enables backups for a + Droplet | `droplet:update` | + + | `disable_backups` | Disables backups for a + Droplet | `droplet:update` | + + | `change_backup_policy` | Update the backup policy + for a Droplet | `droplet:update` | + + | `reboot` | 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. | + `droplet:update` | + + | `power_cycle` | 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. | + `droplet:update` | + + | `shutdown` | 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. | + `droplet:update` | + + | `power_off` | 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. | + `droplet:update` | + + | `power_on` | Powers on a Droplet. | + `droplet:update` | + + | `restore` | 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. | `droplet:update`
`droplet:admin` + | + + | `password_reset` | Resets the root password + for a Droplet. A new password will be provided via email. It must be + changed after first use. | + `droplet:update`
`droplet:admin` | + + | `resize` | 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`. | + `droplet:update`
`droplet:create` | + + | `rebuild` | Rebuilds a Droplet from a + new base image. Set the `image` attribute to an image ID or slug. | + `droplet:update`
`droplet:admin` | + + | `rename` | Renames a Droplet. | + `droplet:update` | + + | `change_kernel` | Changes a Droplet's kernel. + Only applies to Droplets with externally managed kernels. All Droplets + created after March 2017 use internal kernels by default. | + `droplet:update` | + + | `enable_ipv6` | Enables IPv6 for a Droplet. + Once enabled for a Droplet, IPv6 can not be disabled. 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. | `droplet:update` | + + | `snapshot` | Takes a snapshot of a + Droplet. | `droplet:update`
`image:create` + | + tags: + - Droplet Actions + parameters: + - $ref: '#/components/parameters/droplet_id' + requestBody: + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the Droplet. Some actions will require additional + + attributes to be set as well. + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/droplet_action' + - $ref: '#/components/schemas/droplet_action_enable_backups' + - $ref: '#/components/schemas/droplet_action_change_backup_policy' + - $ref: '#/components/schemas/droplet_action_restore' + - $ref: '#/components/schemas/droplet_action_resize' + - $ref: '#/components/schemas/droplet_action_rebuild' + - $ref: '#/components/schemas/droplet_action_rename' + - $ref: '#/components/schemas/droplet_action_change_kernel' + - $ref: '#/components/schemas/droplet_action_snapshot' + discriminator: + propertyName: type + mapping: + enable_backups: '#/components/schemas/droplet_action_enable_backups' + disable_backups: '#/components/schemas/droplet_action' + change_backup_policy: '#/components/schemas/droplet_action_change_backup_policy' + reboot: '#/components/schemas/droplet_action' + power_cycle: '#/components/schemas/droplet_action' + shutdown: '#/components/schemas/droplet_action' + power_off: '#/components/schemas/droplet_action' + power_on: '#/components/schemas/droplet_action' + password_reset: '#/components/schemas/droplet_action' + restore: '#/components/schemas/droplet_action_restore' + resize: '#/components/schemas/droplet_action_resize' + rebuild: '#/components/schemas/droplet_action_rebuild' + rename: '#/components/schemas/droplet_action_rename' + change_kernel: '#/components/schemas/droplet_action_change_kernel' + enable_ipv6: '#/components/schemas/droplet_action' + snapshot: '#/components/schemas/droplet_action_snapshot' + responses: + '201': + $ref: '#/components/responses/droplet_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Enable Backups + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"enable_backups"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Disable Backups + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"disable_backups"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Reboot a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"reboot"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Power cycle a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"power_cycle"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Shutdown and Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"shutdown"}' \ + "https://api.digitalocean.com/v2/droplets/3067649/actions" + + # Power off a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"power_off"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Power on a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"power_on"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Restore a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"restore", "image": 12389723 }' \ + "https://api.digitalocean.com/v2/droplets/3067649/actions" + + # Password Reset a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"password_reset"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Resize a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"resize","size":"1gb"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Rebuild a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"rebuild","image":"ubuntu-16-04-x64"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Rename a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"rename","name":"nifty-new-name"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Change the Kernel + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"change_kernel","kernel":991}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Enable IPv6 + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"enable_ipv6"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Enable Private Networking + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"enable_private_networking"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Snapshot a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"snapshot","name":"Nifty New Snapshot"}' \ + "https://api.digitalocean.com/v2/droplets/3164450/actions" + + # Acting on Tagged Droplets + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"enable_backups"}' \ + "https://api.digitalocean.com/v2/droplets/actions?tag_name=awesome" + + # Retrieve a Droplet Action + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164444/actions/36804807" + - lang: Go + source: >- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + // Enable Backups + action, _, err := client.DropletActions.EnableBackups(ctx, 3164450) + + // Disable Backups + + // action, _, err := client.DropletActions.DisableBackups(ctx, + 3164450) + + + // Reboot a Droplet + + // action, _, err := client.DropletActions.Reboot(ctx, 3164450) + + + // Power Cycle a Droplet + + // action, _, err := client.DropletActions.PowerCycle(ctx, 3164450) + + + // Shutdown a Droplet + + // action, _, err := client.DropletActions.Shutdown(ctx, 3067649) + + + // Power Off a Droplet + + // action, _, err := client.DropletActions.PowerOff(ctx, 3164450) + + + // Power On a Droplet + + // action, _, err := client.DropletActions.PowerOn(ctx, 3164450) + + + // Restore a Droplet + + // action, _, err := client.DropletActions.Restore(ctx, 3164449, + 12389723) + + + // Password Reset a Droplet + + // action, _, err := client.DropletActions.PasswordReset(ctx, + 3164450) + + + // Resize a Droplet + + // action, _, err := client.DropletActions.Resize(ctx, 3164450, + "1gb", true) + + + // Rebuild a Droplet + + // action, _, err := client.DropletActions.RebuildByImageSlug(ctx, + 3164450, "ubuntu-16-04-x64") + + + // Rename a Droplet + + // action, _, err := client.DropletActions.Rename(ctx, 3164450, + "nifty-new-name") + + + // Change the Kernel + + // action, _, err := client.DropletActions.ChangeKernel(ctx, + 3164450, 991) + + + // Enable IPv6 + + // action, _, err := client.DropletActions.EnableIPv6(ctx, 3164450) + + + // Enable Private Networking + + // action, _, err := + client.DropletActions.EnablePrivateNetworking(ctx, 3164450) + + + // Snapshot a Droplet + + // action, _, err := client.DropletActions.Snapshot(ctx, 3164450, + "Nifty New Snapshot") + + + // Retrieve a Droplet Action + + // action, _, err := client.DropletActions.Get(ctx, 3164450, + 36804807) + + + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + # Enable Backups + + client.droplet_actions.enable_backups(droplet_id: 3164450) + + + # Disable Backups + + # client.droplet_actions.disable_backups(droplet_id: 3164450) + + + # Reboot a Droplet + + # client.droplet_actions.reboot(droplet_id: 3164450) + + + # Power Cycle a Droplet + + # client.droplet_actions.power_cycle(droplet_id: 3164450) + + + # Shutdown a Droplet + + # client.droplet_actions.shutdown(droplet_id: 3067649) + + + # Power Off a Droplet + + # client.droplet_actions.power_off(droplet_id: 3164450) + + + # Power On a Droplet + + # client.droplet_actions.power_on(droplet_id: 3164450) + + + # Restore a Droplet + + # client.droplet_actions.restore(droplet_id: 3067649, image: + 12389723) + + + # Password Reset a Droplet + + # client.droplet_actions.password_reset(droplet_id: 3164450) + + + # Resize a Droplet + + # client.droplet_actions.resize(droplet_id: 3164450, size: '1gb') + + + # Rebuild a Droplet + + # client.droplet_actions.rebuild(droplet_id: 3164450, image: + 'ubuntu-16-04-x64') + + + # Rename a Droplet + + # client.droplet_actions.rename(droplet_id: 3164450, name: + 'nifty-new-name') + + + # Change the Kernel + + # client.droplet_actions.change_kernel(droplet_id: 3164450, kernel: + 991) + + + # Enable IPv6 + + # client.droplet_actions.enable_ipv6(droplet_id: 3164450) + + + # Enable Private Networking + + # client.droplet_actions.enable_private_networking(droplet_id: + 3164450) + + + # Snapshot a Droplet + + # client.droplet_actions.snapshot(droplet_id: 3164450, name: 'Nifty + New Snapshot') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + # enable back ups example + req = { + "type": "enable_backups" + } + + resp = client.droplet_actions.post(droplet_id=346652, body=req) + security: + - bearer_auth: + - droplet:update + /v2/droplets/actions: + post: + operationId: dropletActions_post_byTag + summary: Acting on Tagged Droplets + description: > + 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` + + - `enable_backups` + + - `disable_backups` + + - `snapshot` (also requires `image:create` permission) + tags: + - Droplet Actions + parameters: + - $ref: '#/components/parameters/droplet_tag_name' + requestBody: + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the Droplet. Some actions will require additional + + attributes to be set as well. + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/droplet_action' + - $ref: '#/components/schemas/droplet_action_snapshot' + discriminator: + propertyName: type + mapping: + enable_backups: '#/components/schemas/droplet_action' + disable_backups: '#/components/schemas/droplet_action' + power_cycle: '#/components/schemas/droplet_action' + shutdown: '#/components/schemas/droplet_action' + power_off: '#/components/schemas/droplet_action' + power_on: '#/components/schemas/droplet_action' + enable_ipv6: '#/components/schemas/droplet_action' + snapshot: '#/components/schemas/droplet_action_snapshot' + responses: + '201': + $ref: '#/components/responses/droplet_actions_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"enable_backups"}' \ + "https://api.digitalocean.com/v2/droplets/actions?tag_name=awesome" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.DropletActions.PowerOffByTag(ctx, "awesome") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.droplet_actions.power_off_for_tag(tag: 'awesome') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + + "type": "enable_backups" + + } + + + resp = + client.droplet_actions.post_by_tag(tag_name="production",body=req) + security: + - bearer_auth: + - droplet:update + /v2/droplets/{droplet_id}/actions/{action_id}: + get: + operationId: dropletActions_get + summary: Retrieve a Droplet Action + description: > + 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. + tags: + - Droplet Actions + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/action_id' + responses: + '200': + $ref: '#/components/responses/action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164444/actions/36804807" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.DropletActions.Get(ctx, 3164450, 36804807) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.droplet_actions.find(droplet_id: 3164444, id: 36804807) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.droplet_actions.get(droplet_id=3934132, + action_id=2432342) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/kernels: + get: + operationId: droplets_list_kernels + summary: List All Available Kernels for a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_kernels' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/kernels?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + kernels, _, err := client.Droplets.Kernels(ctx, 3164494, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + kernels = client.droplets.kernels(id: 3164494) + kernels.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_kernels(droplet_id=594828) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/firewalls: + get: + operationId: droplets_list_firewalls + summary: List all Firewalls Applied to a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_firewalls' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - firewall:read + /v2/droplets/{droplet_id}/neighbors: + get: + operationId: droplets_list_neighbors + summary: List Neighbors for a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '200': + $ref: '#/components/responses/neighbor_droplets' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/neighbors" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_neighbors(droplet_id=594828) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/destroy_with_associated_resources: + get: + operationId: droplets_list_associatedResources + summary: List Associated Resources for a Droplet + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '200': + $ref: '#/components/responses/associated_resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_associated_resources(droplet_id=594828) + security: + - bearer_auth: + - droplet:read + /v2/droplets/{droplet_id}/destroy_with_associated_resources/selective: + delete: + operationId: droplets_destroy_withAssociatedResourcesSelective + summary: Selectively Destroy a Droplet and its Associated Resources + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/selective_destroy_associated_resource' + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"reserved_ips":["6186916"],"snapshots": ["61486916"],"volumes": ["ba49449a-7435-11ea-b89e-0a58ac14480f"],"volume_snapshots": ["edb0478d-7436-11ea-86e6-0a58ac144b91"]}' \ + "https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/selective" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.droplets.destroy_with_associated_resources_selective(droplet_id=524512) + security: + - bearer_auth: + - droplet:delete + - block_storage:delete + - block_storage_snapshot:delete + - image:delete + - reserved_ip:delete + /v2/droplets/{droplet_id}/destroy_with_associated_resources/dangerous: + delete: + operationId: droplets_destroy_withAssociatedResourcesDangerous + summary: Destroy a Droplet and All of its Associated Resources (Dangerous) + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + - $ref: '#/components/parameters/x_dangerous' + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE -H "X-Dangerous: true" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/dangerous" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.droplets.destroy_with_associated_resources_dangerous(droplet_id=524512) + security: + - bearer_auth: + - droplet:delete + - block_storage:delete + - block_storage_snapshot:delete + - image:delete + - reserved_ip:delete + /v2/droplets/{droplet_id}/destroy_with_associated_resources/status: + get: + operationId: droplets_get_DestroyAssociatedResourcesStatus + summary: Check Status of a Droplet Destroy with Associated Resources Request + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '200': + $ref: '#/components/responses/associated_resources_status' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/status" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.droplets.get_destroy_associated_resources_status(droplet_id=5624512) + security: + - bearer_auth: + - droplet:delete + /v2/droplets/{droplet_id}/destroy_with_associated_resources/retry: + post: + operationId: droplets_destroy_retryWithAssociatedResources + summary: Retry a Droplet Destroy with Associated Resources Request + description: > + 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. + tags: + - Droplets + parameters: + - $ref: '#/components/parameters/droplet_id' + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/retry" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.droplets.destroy_retry_with_associated_resources(droplet_id=524512) + security: + - bearer_auth: + - droplet:delete + - block_storage:delete + - block_storage_snapshot:delete + - image:delete + - reserved_ip:delete + /v2/droplets/autoscale: + get: + operationId: autoscalepools_list + summary: List All Autoscale Pools + description: > + 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. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/autoscale_pool_name' + responses: + '200': + $ref: '#/components/responses/all_autoscale_pools' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/autoscale?page=1&per_page=1" + security: + - bearer_auth: + - droplet:read + post: + operationId: autoscalepools_create + summary: Create a New Autoscale Pool + description: > + 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. + tags: + - Droplet Autoscale Pools + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/autoscale_pool_create' + examples: + Autoscale Create Request Dynamic Config: + $ref: '#/components/examples/autoscale_create_request_dynamic' + Autoscale Create Request Static Config: + $ref: '#/components/examples/autoscale_create_request_static' + responses: + '202': + $ref: '#/components/responses/autoscale_pool_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "test-autoscalergroup", + "config": { + "min_instances": 1, + "max_instances": 5, + "target_cpu_utilization": 0.5, + "cooldown_minutes": 5 + }, + "droplet_template": { + "size": "c-2", + "region": "tor1", + "image": "ubuntu-20-04-x64", + "tags": [ + "test-ag-01" + ], + "ssh_keys": [ + "392594", + "385255" + ], + "vpc_uuid": "c472520a-831e-4770-8135-542c57a69daa", + "ipv6": true, + "user_data": "\n#cloud-config\nruncmd:\n- apt-get update\n" + } + }' \ + "https://api.digitalocean.com/v2/droplets/autoscale" + security: + - bearer_auth: + - droplet:create + /v2/droplets/autoscale/{autoscale_pool_id}: + get: + operationId: autoscalepools_get + summary: Retrieve an Existing Autoscale Pool + description: > + To show information about an individual autoscale pool, send a GET + request to + + `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID`. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/autoscale_pool_id' + responses: + '200': + $ref: '#/components/responses/existing_autoscale_pool' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4" + security: + - bearer_auth: + - droplet:read + put: + operationId: autoscalepools_update + summary: Update Autoscale Pool + description: > + 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. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/autoscale_pool_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/autoscale_pool_create' + examples: + Autoscale Update Request: + $ref: '#/components/examples/autoscale_update_request' + responses: + '200': + $ref: '#/components/responses/autoscale_pool_create' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "test-autoscalergroup-01", + "config": { + "min_instances": 1, + "max_instances": 5, + "target_cpu_utilization": 0.5, + "cooldown_minutes": 10 + }, + "droplet_template": { + "size": "c-2", + "region": "tor1", + "image": "ubuntu-20-04-x64", + "tags": [ + "test-ag-01" + ], + "ssh_keys": [ + "372862", + "367582", + "355790" + ], + "vpc_uuid": "4637280e-3842-4661-a628-a6f0392959d3", + "with_droplet_agent": true, + "ipv6": true, + "user_data": "\n#cloud-config\nruncmd:\n- apt-get update\n" + } + }' \ + "https://api.digitalocean.com/v2/droplets/autoscale/d0067f19-c9bd-4d8c-b28b-e464fd1fb250" + security: + - bearer_auth: + - droplet:create + delete: + operationId: autoscalepools_delete + summary: Delete autoscale pool + description: > + 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. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/autoscale_pool_id' + responses: + '202': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4" + security: + - bearer_auth: + - droplet:delete + /v2/droplets/autoscale/{autoscale_pool_id}/dangerous: + delete: + operationId: autoscalepools_delete_dangerous + summary: Delete autoscale pool and resources + description: > + To destroy an autoscale pool and its associated resources (Droplets), + + send a DELETE request to the + `/v2/droplets/autoscale/$AUTOSCALE_POOL_ID/dangerous` endpoint. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/autoscale_pool_id' + - $ref: '#/components/parameters/parameters_x_dangerous' + responses: + '202': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "X-Dangerous: true" \ + "https://api.digitalocean.com/v2/droplets/autoscale/880fee37-d07a-4f94-94a0-f07d9fc7bbb4/dangerous" + security: + - bearer_auth: + - droplet:delete + /v2/droplets/autoscale/{autoscale_pool_id}/members: + get: + operationId: autoscalepools_list_members + summary: List members + description: > + 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. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/autoscale_pool_id' + responses: + '200': + $ref: '#/components/responses/all_members' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/autoscale/d0067f19-c9bd-4d8c-b28b-e464fd1fb250/members" + security: + - bearer_auth: + - droplet:read + /v2/droplets/autoscale/{autoscale_pool_id}/history: + get: + operationId: autoscalepools_list_history + summary: List history events + description: > + 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. + tags: + - Droplet Autoscale Pools + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/autoscale_pool_id' + responses: + '200': + $ref: '#/components/responses/history_events' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/droplets/autoscale/07445b1b-1dc1-414d-b0a7-239ac66a9148/history" + security: + - bearer_auth: + - droplet:read + /v2/firewalls: + get: + operationId: firewalls_list + summary: List All Firewalls + description: >- + To list all of the firewalls available on your account, send a GET + request to `/v2/firewalls`. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/list_firewalls_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/firewalls" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + firewalls, _, err := client.Firewalls.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + firewalls = client.firewalls.all + firewalls.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.firewalls.list() + security: + - bearer_auth: + - firewall:read + post: + operationId: firewalls_create + summary: Create a New Firewall + description: > + To create a new firewall, send a POST request to `/v2/firewalls`. The + request + + must contain at least one inbound or outbound access rule. + tags: + - Firewalls + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/firewall' + - required: + - name + - anyOf: + - title: Inbound Rules + required: + - inbound_rules + - title: Outbound Rules + required: + - outbound_rules + example: + name: firewall + inbound_rules: + - protocol: tcp + ports: '80' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '80' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + droplet_ids: + - 8043964 + responses: + '202': + $ref: '#/components/responses/create_firewall_response' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"80","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": "22","sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"80","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964]}' \ + "https://api.digitalocean.com/v2/firewalls" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.FirewallRequest{ + Name: 'firewall', + InboundRules: []godo.InboundRule{ + { + Protocol: 'tcp', + PortRange: '80', + Sources: &godo.Sources{ + LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'}, + }, + }, + { + Protocol: 'tcp', + PortRange: '22', + Sources: &godo.Sources{ + Addresses: []string{'18.0.0.0/8'}, + Tags: []string{'gateway'}, + }, + }, + }, + OutboundRules: []godo.OutboundRule{ + { + Protocol: 'tcp', + PortRange: '80', + Destinations: &godo.Destinations{ + Addresses: []string{'0.0.0.0/0', '::/0'}, + }, + }, + }, + DropletIDs: []int{8043964}, + } + + firewall, req, err := client.Firewalls.Create(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + firewall = DropletKit::Firewall.new( + name: 'firewall', + inbound_rules: [ + DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '80', + sources: { + load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6'] + } + ), + DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '22', + sources: { + tags: ['gateway'], + addresses: ['18.0.0.0/8'] + } + ) + ], + outbound_rules: [ + DropletKit::FirewallOutboundRule.new( + protocol: 'tcp', + ports: '80', + destinations: { + addresses: ['0.0.0.0/0', '::/0'], + } + ) + ], + droplet_ids: [8043964] + ) + + client.firewalls.create(firewall) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "firewall", + "inbound_rules": [ + { + "protocol": "tcp", + "ports": "80", + "sources": { + "load_balancer_uids": [ + "4de7ac8b-495b-4884-9a69-1050c6793cd6" + ] + } + }, + { + "protocol": "tcp", + "ports": "22", + "sources": { + "tags": [ + "gateway" + ], + "addresses": [ + "18.0.0.0/8" + ] + } + } + ], + "outbound_rules": [ + { + "protocol": "tcp", + "ports": "80", + "destinations": { + "addresses": [ + "0.0.0.0/0", + "::/0" + ] + } + } + ], + "droplet_ids": [ + 8043964 + ] + } + + resp = client.firewalls.create(body=req) + security: + - bearer_auth: + - firewall:create + /v2/firewalls/{firewall_id}: + get: + operationId: firewalls_get + summary: Retrieve an Existing Firewall + description: >- + To show information about an existing firewall, send a GET request to + `/v2/firewalls/$FIREWALL_ID`. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + responses: + '200': + $ref: '#/components/responses/get_firewall_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + firewall, _, err := client.Firewalls.Get(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c') + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.firewalls.find(id: 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.firewalls.get(firewall_id= "as9di9d") + security: + - bearer_auth: + - firewall:read + put: + operationId: firewalls_update + summary: Update a Firewall + description: > + 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.** + +

You must have read access (e.g. `droplet:read`) to all resources + attached + + to the firewall to successfully update the firewall. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + required: + - name + allOf: + - $ref: '#/components/schemas/firewall' + - anyOf: + - title: Inbound Rules + required: + - inbound_rules + - title: Outbound Rules + required: + - outbound_rules + example: + name: frontend-firewall + inbound_rules: + - protocol: tcp + ports: '8080' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '8080' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + droplet_ids: + - 8043964 + tags: + - frontend + responses: + '200': + $ref: '#/components/responses/put_firewall_response' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"8080","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": "22","sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"8080","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964],"tags":["frontend"]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.FirewallRequest{ + Name: 'firewall', + InboundRules: []godo.InboundRule{ + { + Protocol: 'tcp', + PortRange: '8080', + Sources: &godo.Sources{ + LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'}, + }, + }, + { + Protocol: 'tcp', + PortRange: '22', + Sources: &godo.Sources{ + Addresses: []string{'18.0.0.0/8'}, + Tags: []string{'gateway'}, + }, + }, + }, + OutboundRules: []godo.OutboundRule{ + { + Protocol: 'tcp', + PortRange: '8080', + Destinations: &godo.Destinations{ + Addresses: []string{'0.0.0.0/0', '::/0'}, + }, + }, + }, + DropletIDs: []int{8043964}, + Tags: []string{'frontend'} + } + + firewall, req, err := client.Firewalls.Create(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', updateRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + firewall = DropletKit::Firewall.new( + name: 'firewall', + inbound_rules: [ + DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '8080', + sources: { + load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6'] + } + ), + DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '22', + sources: { + tags: ['gateway'], + addresses: ['18.0.0.0/8'] + } + ) + ], + outbound_rules: [ + DropletKit::FirewallOutboundRule.new( + protocol: 'tcp', + ports: '8080', + destinations: { + addresses: ['0.0.0.0/0', '::/0'], + } + ) + ], + droplet_ids: [8043964], + tags: ['frontend'] + ) + + + client.firewalls.update(firewall, id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "frontend-firewall", + "inbound_rules": [ + { + "protocol": "tcp", + "ports": "8080", + "sources": { + "load_balancer_uids": [ + "4de7ac8b-495b-4884-9a69-1050c6793cd6" + ] + } + }, + { + "protocol": "tcp", + "ports": "22", + "sources": { + "tags": [ + "gateway" + ], + "addresses": [ + "18.0.0.0/8" + ] + } + } + ], + "outbound_rules": [ + { + "protocol": "tcp", + "ports": "8080", + "destinations": { + "addresses": [ + "0.0.0.0/0", + "::/0" + ] + } + } + ], + "droplet_ids": [ + 8043964 + ], + "tags": [ + "frontend" + ] + } + + resp = client.firewalls.update(firewall_id="3afda9", body=req) + security: + - bearer_auth: + - firewall:update + delete: + operationId: firewalls_delete + summary: Delete a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Firewalls.Delete(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c') + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.firewalls.delete(id: 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.firewalls.delete(firewall_id= "as9di9d") + security: + - bearer_auth: + - firewall:delete + /v2/firewalls/{firewall_id}/droplets: + post: + operationId: firewalls_assign_droplets + summary: Add Droplets to a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + properties: + droplet_ids: + type: array + description: >- + An array containing the IDs of the Droplets to be assigned + to the firewall. + items: + type: integer + example: + - 49696269 + required: + - droplet_ids + example: + droplet_ids: + - 49696269 + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_ids":[49696269]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Firewalls.AddDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.firewalls.add_droplets([49696269], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "droplet_ids": [ + 49696269 + ] + } + + + resp = client.firewalls.assign_droplets(firewall_id="39fa4gz", + body=req) + security: + - bearer_auth: + - firewall:update + delete: + operationId: firewalls_delete_droplets + summary: Remove Droplets from a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + properties: + droplet_ids: + type: array + description: >- + An array containing the IDs of the Droplets to be removed + from the firewall. + items: + type: integer + example: + - 49696269 + required: + - droplet_ids + example: + droplet_ids: + - 49696269 + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_ids":[49696269]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Firewalls.RemoveDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.firewalls.remove_droplets([49696269], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "droplet_ids": [ + 49696269 + ] + } + + + resp = client.firewalls.delete_droplets(firewall_id="39fa4gz", + body=req) + security: + - bearer_auth: + - firewall:update + /v2/firewalls/{firewall_id}/tags: + post: + operationId: firewalls_add_tags + summary: Add Tags to a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + properties: + tags: + allOf: + - $ref: '#/components/schemas/existing_tags_array' + - description: >- + An array containing the names of the Tags to be assigned + to the firewall. + required: + - tags + example: + tags: + - frontend + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tags":["frontend"]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Firewalls.AddTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend') + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.firewalls.add_tags(['frontend'], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "tags": [ + "frontend" + ] + } + + resp = client.firewalls.add_tags(firewall_id="39fa4gz", body=req) + security: + - bearer_auth: + - firewall:update + delete: + operationId: firewalls_delete_tags + summary: Remove Tags from a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + properties: + tags: + allOf: + - $ref: '#/components/schemas/existing_tags_array' + - description: >- + An array containing the names of the Tags to be removed + from the firewall. + required: + - tags + example: + tags: + - frontend + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tags":["frontend"]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Firewalls.RemoveTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend') + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.firewalls.remove_tags(['frontend'], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "tags": [ + "frontend" + ] + } + + resp = client.firewalls.delete_tags(firewall_id="39fa4gz", body=req) + security: + - bearer_auth: + - firewall:update + /v2/firewalls/{firewall_id}/rules: + post: + operationId: firewalls_add_rules + summary: Add Rules to a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/firewall_rules' + - anyOf: + - title: Inbound Rules + required: + - inbound_rules + - title: Outbound Rules + required: + - outbound_rules + example: + inbound_rules: + - protocol: tcp + ports: '3306' + sources: + droplet_ids: + - 49696269 + outbound_rules: + - protocol: tcp + ports: '3306' + destinations: + droplet_ids: + - 49696269 + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules" + - lang: Go + source: >- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + ruleRequest := &godo.FirewallRulesRequest{ + InboundRules: []godo.InboundRule{ + { + Protocol: 'tcp', + PortRange: '3306', + Sources: &godo.Sources{ + DropletIDs: []int{49696269}, + }, + }, + }, + OutboundRules: []godo.OutboundRule{ + { + Protocol: 'tcp', + PortRange: '3306', + Destinations: &godo.Destinations{ + DropletIDs: []int{49696269}, + }, + }, + }, + } + + + _, err := c.Firewalls.AddRules(ctx, + 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest) + + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + inbound_rule = DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '3306', + sources: { + droplet_ids: [49696269] + } + ) + + + outbound_rule = DropletKit::FirewallOutboundRule.new( + protocol: 'tcp', + ports: '3306', + destinations: { + droplet_ids: [49696269] + } + ) + + + client.firewalls.add_rules(inbound_rules: [inbound_rule], + outbound_rules: [outbound_rule], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "inbound_rules": [ + { + "protocol": "tcp", + "ports": "3306", + "sources": { + "droplet_ids": [ + 49696269 + ] + } + } + ], + "outbound_rules": [ + { + "protocol": "tcp", + "ports": "3306", + "destinations": { + "droplet_ids": [ + 49696269 + ] + } + } + ] + } + + resp = client.firewalls.add_rules(firewall_id="39fa4gz", body=req) + security: + - bearer_auth: + - firewall:update + delete: + operationId: firewalls_delete_rules + summary: Remove Rules from a Firewall + description: > + 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. + tags: + - Firewalls + parameters: + - $ref: '#/components/parameters/firewall_id' + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/firewall_rules' + - anyOf: + - title: Inbound Rules + required: + - inbound_rules + - title: Outbound Rules + required: + - outbound_rules + example: + inbound_rules: + - protocol: tcp + ports: '3306' + sources: + droplet_ids: + - 49696269 + outbound_rules: + - protocol: tcp + ports: '3306' + destinations: + droplet_ids: + - 49696269 + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' \ + "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + ruleRequest := &godo.FirewallRulesRequest{ + InboundRules: []godo.InboundRule{ + { + Protocol: 'tcp', + PortRange: '3306', + Sources: &godo.Sources{ + DropletIDs: []int{49696269}, + }, + }, + }, + OutboundRules: []godo.OutboundRule{ + { + Protocol: 'tcp', + PortRange: '3306', + Destinations: &godo.Destinations{ + DropletIDs: []int{49696269}, + }, + }, + }, + } + + _, err := c.Firewalls.RemoveRules(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest) + + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + inbound_rule = DropletKit::FirewallInboundRule.new( + protocol: 'tcp', + ports: '3306', + sources: { + droplet_ids: [49696269] + } + ) + + + outbound_rule = DropletKit::FirewallOutboundRule.new( + protocol: 'tcp', + ports: '3306', + destinations: { + droplet_ids: [49696269] + } + ) + + + client.firewalls.remove_rules(inbound_rules: [inbound_rule], + outbound_rules: [outbound_rule], id: + 'bb4b2611-3d72-467b-8602-280330ecd65c') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "inbound_rules": [ + { + "protocol": "tcp", + "ports": "3306", + "sources": { + "droplet_ids": [ + 49696269 + ] + } + } + ], + "outbound_rules": [ + { + "protocol": "tcp", + "ports": "3306", + "destinations": { + "droplet_ids": [ + 49696269 + ] + } + } + ] + } + + + resp = client.firewalls.delete_rules(firewall_id="39fa4gz", + body=req) + security: + - bearer_auth: + - firewall:update + /v2/floating_ips: + get: + operationId: floatingIPs_list + summary: List All Floating IPs + description: >- + To list all of the floating IPs available on your account, send a GET + request to `/v2/floating_ips`. + tags: + - Floating IPs + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/floating_ip_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/floating_ips?page=1&per_page=20" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + floatingIPs, _, err := client.FloatingIPs.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + floating_ips = client.floating_ips.all + floating_ips.each + security: + - bearer_auth: + - reserved_ip:read + post: + operationId: floatingIPs_create + summary: Create a New Floating IP + description: >- + 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. + tags: + - Floating IPs + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/floating_ip_create' + responses: + '202': + $ref: '#/components/responses/floating_ip_created' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_id": 123456}' \ + "https://api.digitalocean.com/v2/floating_ips" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.FloatingIPCreateRequest{ + DropletID: 123456, + + } + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + floating_ip = DropletKit::FloatingIp.new(droplet_id: 123456) + client.floating_ips.create(floating_ip) + security: + - bearer_auth: + - reserved_ip:create + /v2/floating_ips/{floating_ip}: + get: + operationId: floatingIPs_get + summary: Retrieve an Existing Floating IP + description: >- + To show information about a floating IP, send a GET request to + `/v2/floating_ips/$FLOATING_IP_ADDR`. + tags: + - Floating IPs + parameters: + - $ref: '#/components/parameters/floating_ip' + responses: + '200': + $ref: '#/components/responses/floating_ip' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + floatingIP, _, err := client.FloatingIPs.Get(ctx, "45.55.96.47") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.floating_ips.find(ip: '45.55.96.47') + security: + - bearer_auth: + - reserved_ip:read + delete: + operationId: floatingIPs_delete + summary: Delete a Floating IP + description: > + 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. + tags: + - Floating IPs + parameters: + - $ref: '#/components/parameters/floating_ip' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.FloatingIPs.Delete(ctx, "45.55.96.34") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.floating_ips.delete(ip: '45.55.96.47') + security: + - bearer_auth: + - reserved_ip:delete + /v2/floating_ips/{floating_ip}/actions: + get: + operationId: floatingIPsAction_list + summary: List All Actions for a Floating IP + description: >- + To retrieve all actions that have been executed on a floating IP, send a + GET request to `/v2/floating_ips/$FLOATING_IP/actions`. + tags: + - Floating IP Actions + parameters: + - $ref: '#/components/parameters/floating_ip' + responses: + '200': + $ref: '#/components/responses/floating_ip_actions' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + actions, _, err := client.FloatingIPActions.List(ctx, '45.55.96.47', opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + actions = client.floating_ip_actions.all(ip: '45.55.96.47') + actions.each + security: + - bearer_auth: + - reserved_ip:read + post: + operationId: floatingIPsAction_post + summary: Initiate a Floating IP Action + description: > + 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 + tags: + - Floating IP Actions + parameters: + - $ref: '#/components/parameters/floating_ip' + requestBody: + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the floating IP. + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/floating_ip_action_unassign' + - $ref: '#/components/schemas/floating_ip_action_assign' + discriminator: + propertyName: type + mapping: + unassign: '#/components/schemas/floating_ip_action_unassign' + assign: '#/components/schemas/floating_ip_action_assign' + responses: + '201': + $ref: '#/components/responses/floating_ip_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Assign a Floating IP to a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"assign","droplet_id":8219222}' \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions" + + # Unassign a Floating IP + # curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"unassign"}' \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Assign a Floating IP to a Droplet + action, _, err := client.FloatingIPActions.Assign(ctx, "45.55.96.47", 8219222) + + // Unassign a Floating IP + // action, _, err := client.FloatingIPActions.Unassign(ctx, "45.55.96.47") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + # Assign a Floating IP to a Droplet + + client.floating_ip_actions.assign(ip: '45.55.96.47', droplet_id: + 8219222) + + + # Unassign a Floating IP + + # client.floating_ip_actions.unassign(ip: '45.55.96.47') + security: + - bearer_auth: + - reserved_ip:update + /v2/floating_ips/{floating_ip}/actions/{action_id}: + get: + operationId: floatingIPsAction_get + summary: Retrieve an Existing Floating IP Action + description: >- + To retrieve the status of a floating IP action, send a GET request to + `/v2/floating_ips/$FLOATING_IP/actions/$ACTION_ID`. + tags: + - Floating IP Actions + parameters: + - $ref: '#/components/parameters/floating_ip' + - $ref: '#/components/parameters/action_id' + responses: + '200': + $ref: '#/components/responses/floating_ip_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions/72531856" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.FloatingIPActions.Get(ctx, "45.55.96.47", 72531856) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.floating_ip_actions.find(ip: '45.55.96.47', id: 72531856) + security: + - bearer_auth: + - reserved_ip:read + /v2/functions/namespaces: + get: + operationId: functions_list_namespaces + summary: List Namespaces + description: >- + Returns a list of namespaces associated with the current user. To get + all namespaces, send a GET request to `/v2/functions/namespaces`. + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/list_namespaces' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.functions.list_namespaces() + security: + - bearer_auth: + - function:read + - function:admin + post: + operationId: functions_create_namespace + summary: Create Namespace + description: >- + 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. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/create_namespace' + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/namespace_created' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_bad_request' + '422': + $ref: '#/components/responses/namespace_limit_reached' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"region": "nyc1", "label": "my namespace label"}' \ + "https://api.digitalocean.com/v2/functions/namespaces" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "region": "nyc1", + "label": "my namespace" + } + + resp = client.functions.create_namespace(body=req) + security: + - bearer_auth: + - function:create + - function:admin + /v2/functions/namespaces/{namespace_id}: + get: + operationId: functions_get_namespace + summary: Get Namespace + description: >- + 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. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + responses: + '200': + $ref: '#/components/responses/namespace_created' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/namespace_not_allowed' + '404': + $ref: '#/components/responses/namespace_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.functions.get_namespace(namespace_id="aff93af3") + security: + - bearer_auth: + - function:admin + delete: + operationId: functions_delete_namespace + summary: Delete Namespace + description: >- + 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. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.functions.delete_namespace(namespace_id="aff93af3") + security: + - bearer_auth: + - function:delete + - function:admin + /v2/functions/namespaces/{namespace_id}/triggers: + get: + operationId: functions_list_triggers + summary: List Triggers + description: >- + 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`. + parameters: + - $ref: '#/components/parameters/namespace_id' + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/list_triggers' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}/triggers" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.functions.list_triggers(namespace_id="39f3ca") + security: + - bearer_auth: + - function:read + - function:admin + post: + operationId: functions_create_trigger + summary: Create Trigger + description: >- + 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. + parameters: + - $ref: '#/components/parameters/namespace_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/create_trigger' + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/trigger_response' + '400': + $ref: '#/components/responses/trigger_bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '422': + $ref: '#/components/responses/trigger_limit_reached' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "my trigger", "function": "hello", "type": "SCHEDULED", "is_enabled": true, "scheduled_details": {"cron": "* * * * *", "body": {"name": "Welcome to DO!"}}}' \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}/triggers" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "my trigger", + "function": "hello", + "type": "SCHEDULED", + "is_enabled": True, + "scheduled_details": { + "cron": "* * * * *", + "body": { + "name": "Welcome to DO!" + } + } + + } + + + resp = client.functions.create_trigger(namespace_id="aff93af3", + body=req) + security: + - bearer_auth: + - function:create + - function:admin + /v2/functions/namespaces/{namespace_id}/triggers/{trigger_name}: + get: + operationId: functions_get_trigger + summary: Get Trigger + description: >- + Gets the trigger details. To get the trigger details, send a GET request + to `/v2/functions/namespaces/$NAMESPACE_ID/triggers/$TRIGGER_NAME`. + parameters: + - $ref: '#/components/parameters/namespace_id' + - $ref: '#/components/parameters/trigger_name' + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/trigger_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/trigger_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}/triggers/{{trigger_name}}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.functions.get_trigger(namespace_id="aff93af3", + trigger_name="trig_name") + security: + - bearer_auth: + - function:read + - function:admin + put: + operationId: functions_update_trigger + summary: Update Trigger + description: >- + 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. + parameters: + - $ref: '#/components/parameters/namespace_id' + - $ref: '#/components/parameters/trigger_name' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/update_trigger' + tags: + - Functions + responses: + '200': + $ref: '#/components/responses/trigger_response' + '400': + $ref: '#/components/responses/trigger_bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/trigger_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"is_enabled": true, "scheduled_details": {"cron": "* * * * *", "body": {"name": "Welcome to DO!"}}}' \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}/triggers/{{trigger_name}}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "is_enabled": true, + "scheduled_details": { + "cron": "* * * * *", + "body": { + "name": "Welcome to DO!" + } + } + } + + + resp = client.functions.update_trigger(namespace_id="39f3ca", + trigger_name="trig_name", body=req) + security: + - bearer_auth: + - function:update + - function:admin + delete: + operationId: functions_delete_trigger + summary: Delete Trigger + description: >- + 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. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + - $ref: '#/components/parameters/trigger_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/trigger_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/{{namespace_id}}/triggers/{{trigger_name}}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.functions.delete_trigger(namespace_id="aff93af3", + trigger_name="trig_name") + security: + - bearer_auth: + - function:delete + - function:admin + /v2/functions/namespaces/{namespace_id}/keys: + get: + operationId: functionsAccessKey_list + summary: List Namespace Access Keys + description: > + Lists all access keys for a serverless functions namespace. + + + To list access keys, send a GET request to + `/v2/functions/namespaces/{namespace_id}/keys`. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + responses: + '200': + $ref: '#/components/responses/access_key_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/keys" + security: + - bearer_auth: + - function:admin + post: + operationId: functionsAccessKey_create + summary: Create a Namespace Access Key + description: > + 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`. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/access_key_create_request' + examples: + Create Non-Expiring Key: + value: + name: my-function-access-key + Create Expiring Key: + value: + name: my-function-access-key + expires_in: 7d + responses: + '201': + $ref: '#/components/responses/access_key_create' + '400': + $ref: '#/components/responses/namespace_bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "my-function-access-key", "expires_in": "1h"}' \ + "https://api.digitalocean.com/v2/functions/namespaces/fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/keys" + security: + - bearer_auth: + - function:admin + /v2/functions/namespaces/{namespace_id}/keys/{key_id}: + put: + operationId: functionsAccessKey_update + summary: Update a Namespace Access Key + description: > + 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}`. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + - $ref: '#/components/parameters/key_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The new name for the access key. + example: updated-key-name + required: + - name + examples: + Update Key Name: + value: + name: updated-key-name + responses: + '200': + $ref: '#/components/responses/access_key_update' + '400': + $ref: '#/components/responses/namespace_bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "updated-key-name"}' \ + "https://api.digitalocean.com/v2/functions/namespaces/fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/keys/dof-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + security: + - bearer_auth: + - function:admin + delete: + operationId: functionsAccessKey_delete + summary: Delete a Namespace Access Key + description: > + 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}`. + tags: + - Functions + parameters: + - $ref: '#/components/parameters/namespace_id' + - $ref: '#/components/parameters/key_id' + responses: + '200': + description: Success. The access key was deleted. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + example: {} + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/namespace_not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/functions/namespaces/fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/keys/dof-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + security: + - bearer_auth: + - function:admin + /v2/images: + get: + operationId: images_list + summary: List All Images + description: > + 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`. + tags: + - Images + parameters: + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/private' + - $ref: '#/components/parameters/tag' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_images' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + // List all images + images, _, err := client.Images.List(ctx, opt) + + // List all application images + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + images, _, err := client.Images.ListApplication(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + # List all images + images = client.images.all + images.each + + # List all application images + images = client.images.all(type: 'application') + images.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.images.list() + security: + - bearer_auth: + - image:read + post: + operationId: images_create_custom + summary: Create a Custom Image + description: > + 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. + tags: + - Images + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/image_new_custom' + responses: + '202': + $ref: '#/components/responses/new_custom_image' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "ubuntu-18.04-minimal", "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img", "distribution": "Ubuntu", "region": "nyc3", "description": "Cloud-optimized image w/ small footprint", "tags":["base-image", "prod"]}' \ + "https://api.digitalocean.com/v2/images" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "ubuntu-18.04-minimal", + "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img", + "distribution": "Ubuntu", + "region": "nyc3", + "description": "Cloud-optimized image w/ small footprint", + "tags": [ + "base-image", + "prod" + ] + } + + resp = client.images.create_custom(body=req) + security: + - bearer_auth: + - image:create + /v2/images/{image_id}: + get: + operationId: images_get + summary: Retrieve an Existing Image + description: | + To retrieve information about an image, send a `GET` request to + `/v2/images/$IDENTIFIER`. + tags: + - Images + parameters: + - in: path + name: image_id + description: > + A unique number (id) or string (slug) used to identify and reference + a + + specific image. + + + **Public** images can be identified by image `id` or `slug`. + + + **Private** images *must* be identified by image `id`. + required: true + schema: + anyOf: + - type: integer + - type: string + examples: + byId: + summary: Retrieve a public or private image by id + value: 62137902 + bySlug: + summary: Retrieve a public image by slug + value: ubuntu-16-04-x64 + responses: + '200': + $ref: '#/components/responses/existing_image' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Get existing image by ID + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images/7555620" + + # Get existing image by slug + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images/ubuntu-16-04-x64" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Get existing image by ID + image, _, err := client.Images.GetByID(ctx, 7555620) + + // Get existing image by slug + // image, _, err := client.Images.GetBySlug(ctx, "ubuntu-16-04-x64") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + # Retrieve image by ID + client.images.find(id: '7555620') + + # Retrieve image by slug + client.images.find(id: 'ubuntu-16-04-x64') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.images.get(image_id=134215) + security: + - bearer_auth: + - image:read + put: + operationId: images_update + summary: Update an Image + description: > + 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. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/image_update' + responses: + '200': + $ref: '#/components/responses/updated_image' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"new-image-name"}' \ + "https://api.digitalocean.com/v2/images/7938391" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.ImageUpdateRequest{ + Name: "new-image-name", + } + + image, _, err := client.Images.Update(ctx, id, updateRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + image = DropletKit::Image.new(name: 'new-image-name') + client.images.update(image, id: 7938391) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "Nifty New Snapshot", + "distribution": "Ubuntu", + "description": " " + } + + resp = client.images.update(image_id=234532, body=req) + security: + - bearer_auth: + - image:update + delete: + operationId: images_delete + summary: Delete an Image + description: > + To delete a snapshot or custom image, send a `DELETE` request to + `/v2/images/$IMAGE_ID`. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images/7938391" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Images.Delete(ctx, 7938391) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.images.delete(id: 7938391) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.images.delete(image_id=134215) + security: + - bearer_auth: + - image:delete + /v2/images/{image_id}/account_transfer: + post: + operationId: images_post_account_transfer_create + summary: Initiate an Image Account Transfer + description: > + 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. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/images_post_account_transfer_create' + responses: + '201': + $ref: '#/components/responses/images_post_account_transfer_created' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # transfer to email + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"recipient_email": "alice@example.com"}' \ + "https://api.digitalocean.com/v2/images/7555620/account_transfer" + + # transfer to team + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"recipient_uuid": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"}' \ + "https://api.digitalocean.com/v2/images/9375231/account_transfer" + security: + - bearer_auth: + - image:update + - image:delete + /v2/images/{image_id}/account_transfer/accept: + post: + operationId: images_post_account_transfer_accept + summary: Accept an Image Account Transfer + description: | + To accept an account transfer for an image, send a POST request to + `/v2/images/$IMAGE_ID/account_transfer/accept`. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/images_post_account_transfer_accept' + responses: + '201': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"transfer_id": 3164444, "recipient_uuid": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"}' \ + "https://api.digitalocean.com/v2/images/9375231/account_transfer/accept" + security: + - bearer_auth: + - image:create + /v2/images/{image_id}/account_transfer/cancel: + post: + operationId: images_post_account_transfer_cancel + summary: Cancel an Image Account Transfer + description: > + 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. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/images_post_account_transfer_cancel' + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"transfer_id": 3164444}' \ + "https://api.digitalocean.com/v2/images/9375231/account_transfer/cancel" + security: + - bearer_auth: + - image:update + /v2/images/{image_id}/account_transfer/decline: + post: + operationId: images_post_account_transfer_decline + summary: Decline an Image Account Transfer + description: > + 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. + tags: + - Images + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/images_post_account_transfer_decline' + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"transfer_id": 3164444}' \ + "https://api.digitalocean.com/v2/images/9375231/account_transfer/decline" + security: + - bearer_auth: + - image:create + /v2/images/{image_id}/actions: + get: + operationId: imageActions_list + summary: List All Actions for an Image + description: >- + To retrieve all actions that have been executed on an image, send a GET + request to `/v2/images/$IMAGE_ID/actions`. + tags: + - Image Actions + parameters: + - $ref: '#/components/parameters/image_id' + responses: + '200': + $ref: '#/components/responses/get_image_actions_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images/7555620/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.image_actions.list(image_id=7938269) + security: + - bearer_auth: + - image:read + post: + operationId: imageActions_post + summary: Initiate an Image Action + description: > + 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. + tags: + - Image Actions + parameters: + - $ref: '#/components/parameters/image_id' + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/image_action_base' + - $ref: '#/components/schemas/image_action_transfer' + discriminator: + propertyName: type + mapping: + convert: '#/components/schemas/image_action_base' + transfer: '#/components/schemas/image_action_transfer' + responses: + '201': + $ref: '#/components/responses/post_image_action_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Transfer an Existing Image + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"transfer","region":"nyc2"}' \ + "https://api.digitalocean.com/v2/images/7938269/actions" + + # Convert an Image into a Snapshot + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"convert"}' \ + "https://api.digitalocean.com/v2/images/7938291/actions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Transfer an existing image + transferRequest := &godo.ActionRequest{ + "type": "transfer", + "region": "nyc2", + } + # Transfer an Image + transfer, _, err := client.ImageActions.Transfer(ctx, 7938269, transferRequest) + + # Convert an Image to a Snapshot + # client.image_actions.convert(image_id: 7938269) + + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + # Transfer an Image + client.image_actions.transfer(image_id: 7938269, region: 'nyc2') + + # Convert an Image to a Snapshot + # client.image_actions.convert(image_id: 7938269) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "type": "convert" + } + resp = client.image_actions.post(image_id=342341, body=req) + security: + - bearer_auth: + - image:update + /v2/images/{image_id}/actions/{action_id}: + get: + operationId: imageActions_get + summary: Retrieve an Existing Action + description: >- + To retrieve the status of an image action, send a GET request to + `/v2/images/$IMAGE_ID/actions/$IMAGE_ACTION_ID`. + tags: + - Image Actions + parameters: + - $ref: '#/components/parameters/image_id' + - $ref: '#/components/parameters/action_id' + responses: + '200': + $ref: '#/components/responses/get_image_action_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/images/7938269/actions/36805527" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.ImageActions.Get(ctx, 7938269, 36805527) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.image_actions.find(image_id: 7938269, id: 36805527) + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.image_actions.get(action_id=36805527, + image_id=7938269) + security: + - bearer_auth: + - image:read + /v2/kubernetes/clusters: + get: + operationId: kubernetes_list_clusters + summary: List All Kubernetes Clusters + description: > + To list all of the Kubernetes clusters on your account, send a GET + request + + to `/v2/kubernetes/clusters`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_clusters' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + clusters, _, err := client.Kubernetes.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + clusters = client.kubernetes_clusters.all + clusters.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.list_clusters() + security: + - bearer_auth: + - kubernetes:read + post: + operationId: kubernetes_create_cluster + summary: Create a New Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/cluster' + examples: + Kubernetes Cluster Request: + $ref: '#/components/examples/kubernetes_clusters_basic_request' + Kubernetes Cluster with Multiple Node Pools Request: + $ref: '#/components/examples/kubernetes_clusters_multi_pool_request' + responses: + '201': + $ref: '#/components/responses/cluster_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "prod-cluster-01","region": "nyc1","version": "1.14.1\ + -do.4","tags": ["production","web-team"],"node_pools": [{"size": "s-1vcpu-2gb","count": 3,"name": "frontend-pool","tags": ["frontend"],"labels": {"service": "frontend", "priority": "high"}},{"size": "c-4","count": 2,"name": "backend-pool"}]}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.KubernetesClusterCreateRequest{ + Name: "prod-cluster-01", + RegionSlug: "nyc1", + VersionSlug: "1.14.1-do.4", + Tags: []string{"production", "web-team"}, + NodePools: []*godo.KubernetesNodePoolCreateRequest{ + &godo.KubernetesNodePoolCreateRequest{ + Name: "frontend-pool", + Size: "s-2vcpu-2gb", + Count: 3, + Tags: []string{"frontend"}, + Labels: map[string]string{"service": "frontend", "priority": "high"}, + }, + &godo.KubernetesNodePoolCreateRequest{ + Name: "backend-pool", + Size: "c-4", + Count: 2, + }, + }, + } + + cluster, _, err := client.Kubernetes.Create(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + cluster = DropletKit::KubernetesCluster.new( + name: 'prod-cluster-01', + region: 'nyc1', + version: '1.14.1-do.4', + tags: ['production', 'web-team'], + node_pools: [ + { + name: 'frontend-pool', + size: 's-2vcpu-2gb', + count: 3, + tags: ['frontend'], + labels: {service: 'frontend', priority: 'high'} + }, + { + name: 'backend-pool', + size: 'c-4', + count: 2 + } + ] + ) + + client.kubernetes_clusters.create(cluster) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "prod-cluster-01", + "region": "nyc1", + "version": "1.18.6-do.0", + "node_pools": [ + { + "size": "s-1vcpu-2gb", + "count": 3, + "name": "worker-pool" + } + ] + } + + resp = client.kubernetes.create_cluster(body=req) + security: + - bearer_auth: + - kubernetes:create + /v2/kubernetes/clusters/{cluster_id}: + get: + operationId: kubernetes_get_cluster + summary: Retrieve an Existing Kubernetes Cluster + description: > + To show information about an existing Kubernetes cluster, send a GET + request + + to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '200': + $ref: '#/components/responses/existing_cluster' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + cluster, _, err := client.Kubernetes.Get(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.find(id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.get_cluster(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:read + put: + operationId: kubernetes_update_cluster + summary: Update a Kubernetes Cluster + description: | + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/cluster_update' + responses: + '202': + $ref: '#/components/responses/updated_cluster' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "stage-cluster-01", "tags":["staging", "web-team"]}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.KubernetesClusterUpdateRequest{ + Name: "stage-cluster-01", + Tags: []string{"staging", "web-team"}, + } + + cluster, _, err := client.Kubernetes.Update(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", updateRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + cluster = DropletKit::KubernetesCluster.new( + name: 'foo', + tags: ['staging', 'web-team'] + ) + + + client.kubernetes_clusters.update(cluster, id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "prod-cluster-01", + "tags": [ + "k8s", + "k8s:bd5f5959-5e1e-4205-a714-a914373942af", + "production", + "web-team" + ], + "maintenance_policy": { + "start_time": "12:00", + "day": "any" + }, + "auto_upgrade": True, + "surge_upgrade": True, + "ha": True + } + + + resp = client.kubernetes.update_cluster(cluster_id="1fd32a", + body=req) + security: + - bearer_auth: + - kubernetes:update + delete: + operationId: kubernetes_delete_cluster + summary: Delete a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.Delete(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.delete(id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.delete_cluster(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:delete + /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources: + get: + operationId: kubernetes_list_associatedResources + summary: List Associated Resources for Cluster Deletion + description: >- + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '200': + $ref: '#/components/responses/associated_kubernetes_resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/destroy_with_associated_resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.ListAssociatedResourcesForDeletion(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.kubernetes.list_associated_resources(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:read + /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources/selective: + delete: + operationId: kubernetes_destroy_associatedResourcesSelective + summary: Selectively Delete a Cluster and its Associated Resources + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/destroy_associated_kubernetes_resources' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"load_balancers": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"],"volumes": ["ba49449a-7435-11ea-b89e-0a58ac14480f"],"volume_snapshots": ["edb0478d-7436-11ea-86e6-0a58ac144b91"]}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/destroy_with_associated_resources/selective" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + deleteReq := &godo.KubernetesClusterDeleteSelectiveRequest{Volumes: []string{"ba49449a-7435-11ea-b89e-0a58ac14480f"}}, _, err := client.Kubernetes.DeleteSelective(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", deleteReq) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "load_balancers": [ + "4de7ac8b-495b-4884-9a69-1050c6793cd6" + ], + "volumes": [ + "ba49449a-7435-11ea-b89e-0a58ac14480f" + ], + "volume_snapshots": [ + "edb0478d-7436-11ea-86e6-0a58ac144b91" + ] + } + + + resp = + client.kubernetes.destroy_associated_resources_selective(cluster_id="da8fda8", + body=req) + security: + - bearer_auth: + - kubernetes:delete + /v2/kubernetes/clusters/{cluster_id}/destroy_with_associated_resources/dangerous: + delete: + operationId: kubernetes_destroy_associatedResourcesDangerous + summary: Delete a Cluster and All of its Associated Resources (Dangerous) + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/destroy_with_associated_resources/dangerous" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.DeleteDangerous(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.kubernetes.destroy_associated_resources_dangerous(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:delete + /v2/kubernetes/clusters/{cluster_id}/kubeconfig: + get: + operationId: kubernetes_get_kubeconfig + summary: Retrieve the kubeconfig for a Kubernetes Cluster + description: > + 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 in certificate-based authentication. + + + Kubernetes Roles granted to a user with a token-based kubeconfig 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_expiry_seconds' + responses: + '200': + $ref: '#/components/responses/kubeconfig' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/kubeconfig" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + config, _, err := client.Kubernetes.GetKubeConfig(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + + kubeConfigFile := string(config.KubeconfigYAML) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.kubeconfig(id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.get_kubeconfig(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:access_cluster + /v2/kubernetes/clusters/{cluster_id}/credentials: + get: + operationId: kubernetes_get_credentials + summary: Retrieve Credentials for a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_expiry_seconds' + responses: + '200': + $ref: '#/components/responses/credentials' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/credentials" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + credentials, _, err := client.Kubernetes.GetCredentials(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.credentials(id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.get_credentials(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:access_cluster + /v2/kubernetes/clusters/{cluster_id}/upgrades: + get: + operationId: kubernetes_get_availableUpgrades + summary: Retrieve Available Upgrades for an Existing Kubernetes Cluster + description: > + 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`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '200': + $ref: '#/components/responses/available_upgrades' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/upgrades" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + upgrades, _, err := client.Kubernetes.GetUpgrades(ctx, "bd5f5959-5e1e-4205-a714-a914373942af") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.kubernetes.get_available_upgrades(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:read + /v2/kubernetes/clusters/{cluster_id}/upgrade: + post: + operationId: kubernetes_upgrade_cluster + summary: Upgrade a Kubernetes Cluster + description: > + 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`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + version: + type: string + example: 1.16.13-do.0 + description: >- + The slug identifier for the version of Kubernetes that the + cluster will be upgraded to. + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/upgrades" + - lang: Go + source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n upgradeRequest := &godo.KubernetesClusterUpgradeRequest{\n \tVersionSlug: \"1.12.3-do.1\",\n }\n}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "version": "1.16.13-do.0" + } + + + resp = client.kubernetes.upgrade_cluster(cluster_id="1fd32a", + body=req) + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/clusters/{cluster_id}/node_pools: + get: + operationId: kubernetes_list_nodePools + summary: List All Node Pools in a Kubernetes Clusters + description: > + To list all of the node pools in a Kubernetes clusters, send a GET + request to + + `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/node_pools`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '200': + $ref: '#/components/responses/all_node_pools' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/node_pools" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + nodePools, _, err := client.Kubernetes.ListNodePools(ctx, "9b729d1c-730c-42e1-b136-59326fb1b3bb", opt) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + node_pools = client.kubernetes_clusters.node_pools(id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + + node_pools.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.list_node_pools(cluster_id="a8fsa8d") + security: + - bearer_auth: + - kubernetes:read + post: + operationId: kubernetes_add_nodePool + summary: Add a Node Pool to a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/kubernetes_node_pool' + example: + size: s-1vcpu-2gb + count: 3 + name: new-pool + tags: + - frontend + auto_scale: true + min_nodes: 3 + max_nodes: 6 + responses: + '201': + $ref: '#/components/responses/node_pool_create' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"size": "s-2vcpu-4gb","count": 1,"name": "pool-02","tags": ["web"], "labels": {"service": "web", "priority": "high"}}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/node_pools" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.KubernetesNodePoolCreateRequest{ + Name: "pool-02", + Size: "s-2vcpu-4gb", + Count: 1, + Tags: []string{"web"}, + Labels: map[string]string{"service": "web", "priority": "high"}, + } + + nodePool, _, err := client.Kubernetes.CreateNodePool(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", createRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + node_pool = DropletKit::KubernetesNodePool.new( + name: 'pool-02', + size: 's-2vcpu-4gb', + count: 1, + tags: ['web'] + labels: {service: 'web', priority: 'high'} + ) + + + client.kubernetes_clusters.create_node_pool(node_pool, id: + 'bd5f5959-5e1e-4205-a714-a914373942af') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "size": "s-1vcpu-2gb", + "count": 3, + "name": "new-pool", + "tags": [ + "frontend" + ], + "auto_scale": True, + "min_nodes": 3, + "max_nodes": 6 + } + + + resp = client.kubernetes.add_node_pool(cluster_id="ba9d8da", + body=req) + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id}: + get: + operationId: kubernetes_get_nodePool + summary: Retrieve a Node Pool for a Kubernetes Cluster + description: > + 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`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_node_pool_id' + responses: + '200': + $ref: '#/components/responses/existing_node_pool' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/credentials" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + nodePool, _, err := client.Kubernetes.GetNodePool(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", "cdda885e-7663-40c8-bc74-3a036c66545d") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.find_node_pool(id: + 'bd5f5959-5e1e-4205-a714-a914373942af', pool_id: + 'cdda885e-7663-40c8-bc74-3a036c66545d') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.kubernetes.get_node_pool(cluster_id="da8fda8", + node_pool_id="a8a8fsa") + security: + - bearer_auth: + - kubernetes:read + put: + operationId: kubernetes_update_nodePool + summary: Update a Node Pool in a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_node_pool_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/kubernetes_node_pool_update' + responses: + '202': + $ref: '#/components/responses/node_pool_update' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "frontend","count": 1, "tags":["frontend"], "labels": {"service": "frontend", "priority": "high"}}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/node_pools/86c9bc8c-b2c3-4d40-8000-b0c7bee27305" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.KubernetesNodePoolUpdateRequest{ + Name: "frontend", + Count: 1, + Tags: []string{"frontend"}, + Labels: map[string]string{"service": "frontend", "priority": "high"}, + } + + nodePool, _, err := client.Kubernetes.UpdateNodePool(ctx, "9b729d1c-730c-42e1-b136-59326fb1b3bb", "e7ed8f7c-6c1e-472f-adfb-4a9a1688b999", updateRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + node_pool = DropletKit::KubernetesNodePool.new( + name: 'frontend', + count: 1, + tags: ['frontend'] + labels: {service: 'frontend', priority: 'high'} + ) + + + client.kubernetes_clusters.update_node_pool(node_pool, id: + 'bd5f5959-5e1e-4205-a714-a914373942af', pool_id: + '86c9bc8c-b2c3-4d40-8000-b0c7bee27305') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "frontend-pool", + "count": 3, + "tags": [ + "k8s", + "k8s:bd5f5959-5e1e-4205-a714-a914373942af", + "k8s-worker", + "production", + "web-team" + ], + "labels": None, + "taints": [ + { + "key": "priority", + "value": "high", + "effect": "NoSchedule" + } + ], + "auto_scale": True, + "min_nodes": 3, + "max_nodes": 6 + } + + + resp = client.kubernetes.update_node_pool(cluster_id="1fd32a", + node_pool_id="392fa3a", body=req) + security: + - bearer_auth: + - kubernetes:update + delete: + operationId: kubernetes_delete_nodePool + summary: Delete a Node Pool in a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_node_pool_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/node_pools/86c9bc8c-b2c3-4d40-8000-b0c7bee27305" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.DeleteNodePool(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", "86c9bc8c-b2c3-4d40-8000-b0c7bee27305") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.kubernetes_clusters.delete_node_pool(id: + 'bd5f5959-5e1e-4205-a714-a914373942af', pool_id: + '86c9bc8c-b2c3-4d40-8000-b0c7bee27305') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.kubernetes.delete_node_pool(cluster_id="da8fda8", + node_pool_id="a8f3da") + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id}/nodes/{node_id}: + delete: + operationId: kubernetes_delete_node + summary: Delete a Node in a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_node_pool_id' + - $ref: '#/components/parameters/kubernetes_node_id' + - $ref: '#/components/parameters/kubernetes_node_skip_drain' + - $ref: '#/components/parameters/kubernetes_node_replace' + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/node_pools/86c9bc8c-b2c3-4d40-8000-b0c7bee27305/nodes/478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f?skip_drain=0&replace=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + recycleRequest := &godo.KubernetesNodePoolRecycleNodesRequest{ + Nodes: []string{"3385619f-8ec3-42ba-bb23-8d21b8ba7518", "4b8f60ff-ba06-4523-a6a4-b8148244c7e6"}, + } + + _, err := client.Kubernetes.RecycleNodePoolNodes(ctx, "bd5f5959-5e1e-4205-a714-a914373942af", "86c9bc8c-b2c3-4d40-8000-b0c7bee27305", recycleRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.kubernetes.delete_node(cluster_id="da8fda8", + node_pool_id="a8f3da", node_id="fa09daf") + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/clusters/{cluster_id}/node_pools/{node_pool_id}/recycle: + post: + operationId: kubernetes_recycle_node_pool + deprecated: true + summary: Recycle a Kubernetes Node Pool + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_node_pool_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + nodes: + type: array + items: + type: string + example: + - d8db5e1a-6103-43b5-a7b3-8a948210a9fc + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - kubernetes:delete + /v2/kubernetes/clusters/{cluster_id}/user: + get: + operationId: kubernetes_get_clusterUser + summary: Retrieve User Information for a Kubernetes Cluster + description: > + To show information the user associated with a Kubernetes cluster, send + a GET + + request to `/v2/kubernetes/clusters/$K8S_CLUSTER_ID/user`. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + responses: + '200': + $ref: '#/components/responses/cluster_user' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/user" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.get_cluster_user(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:read + /v2/kubernetes/options: + get: + operationId: kubernetes_list_options + summary: List Available Regions, Node Sizes, and Versions of Kubernetes + description: >- + 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`. + tags: + - Kubernetes + responses: + '200': + $ref: '#/components/responses/all_options' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/options" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + options, _, err := client.Kubernetes.GetOptions(ctx) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.kubernetes_options.all + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.kubernetes.list_options() + security: + - bearer_auth: + - kubernetes:read + /v2/kubernetes/clusters/{cluster_id}/clusterlint: + post: + operationId: kubernetes_run_clusterLint + summary: Run Clusterlint Checks on a Kubernetes Cluster + description: > + 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). + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/clusterlint_request' + responses: + '202': + $ref: '#/components/responses/clusterlint_run' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"include_groups": ["basic"], "include_checks": ["bare-pods"]}' \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/clusterlint" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "include_groups": [ + "basic", + "doks", + "security" + ], + "include_checks": [ + "bare-pods", + "resource-requirements" + ], + "exclude_groups": [ + "workload-health" + ], + "exclude_checks": [ + "default-namespace" + ] + } + + + resp = client.kubernetes.run_cluster_lint(cluster_id="1fd32a", + body=req) + security: + - bearer_auth: + - kubernetes:update + get: + operationId: kubernetes_get_clusterLintResults + summary: Fetch Clusterlint Diagnostics for a Kubernetes Cluster + description: > + 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). + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/clusterlint_run_id' + responses: + '200': + $ref: '#/components/responses/clusterlint_results' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/clusterlint" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.kubernetes.get_cluster_lint_results(cluster_id="da8fda8") + security: + - bearer_auth: + - kubernetes:read + /v2/kubernetes/registry: + post: + operationId: kubernetes_add_registry + summary: Add Container Registry to Kubernetes Clusters + description: >- + To integrate the container registry with Kubernetes clusters, send a + POST request to `/v2/kubernetes/registry`. + tags: + - Kubernetes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/cluster_registry' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"cluster_uuids": ["bd5f5959-5e1e-4205-a714-a914373942af", "50c2f44c-011d-493e-aee5-361a4a0d1844"]}' \ + "https://api.digitalocean.com/v2/kubernetes/registry" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.AddRegistry(ctx, &godo.KubernetesClusterRegistryRequest{ClusterUUIDs: []string{"bd5f5959-5e1e-4205-a714-a914373942af"}}) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "cluster_uuids": [ + "bd5f5959-5e1e-4205-a714-a914373942af", + "50c2f44c-011d-493e-aee5-361a4a0d1844" + ] + } + + resp = client.kubernetes.add_registry(body=req) + security: + - bearer_auth: + - kubernetes:create + - kubernetes:update + delete: + operationId: kubernetes_remove_registry + summary: Remove Container Registry from Kubernetes Clusters + description: >- + To remove the container registry from Kubernetes clusters, send a DELETE + request to `/v2/kubernetes/registry`. + tags: + - Kubernetes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/cluster_registry' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"cluster_uuids": ["bd5f5959-5e1e-4205-a714-a914373942af", "50c2f44c-011d-493e-aee5-361a4a0d1844"]}' \ + "https://api.digitalocean.com/v2/kubernetes/registry" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Kubernetes.RemoveRegistry(ctx, &godo.KubernetesClusterRegistryRequest{ClusterUUIDs: []string{"bd5f5959-5e1e-4205-a714-a914373942af"}}) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "cluster_uuids": [ + "bd5f5959-5e1e-4205-a714-a914373942af", + "50c2f44c-011d-493e-aee5-361a4a0d1844" + ] + } + + resp = client.kubernetes.remove_registry(body=req) + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/registries: + post: + operationId: kubernetes_add_registries + summary: Add Container Registries to Kubernetes Clusters + description: >- + To integrate the container registries with Kubernetes clusters, send a + POST request to `/v2/kubernetes/registries`. + tags: + - Kubernetes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/cluster_registries' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"cluster_uuids": ["bd5f5959-5e1e-4205-a714-a914373942af", "50c2f44c-011d-493e-aee5-361a4a0d1844"], "registries": ["registry-a", "registry-b"]}' \ + "https://api.digitalocean.com/v2/kubernetes/registries" + security: + - bearer_auth: + - kubernetes:create + - kubernetes:update + delete: + operationId: kubernetes_remove_registries + summary: Remove Container Registries from Kubernetes Clusters + description: >- + To remove the container registries from Kubernetes clusters, send a + DELETE request to `/v2/kubernetes/registries`. + tags: + - Kubernetes + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/cluster_registries' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"cluster_uuids": ["bd5f5959-5e1e-4205-a714-a914373942af", "50c2f44c-011d-493e-aee5-361a4a0d1844"], "registries": ["registry-a", "registry-b"]}' \ + "https://api.digitalocean.com/v2/kubernetes/registries" + security: + - bearer_auth: + - kubernetes:update + /v2/kubernetes/clusters/{cluster_id}/status_messages: + get: + operationId: kubernetes_get_status_messages + summary: Fetch Status Messages for a Kubernetes Cluster + description: > + 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. + tags: + - Kubernetes + parameters: + - $ref: '#/components/parameters/kubernetes_cluster_id' + - $ref: '#/components/parameters/kubernetes_status_messages_since' + responses: + '200': + $ref: '#/components/responses/status_messages' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/kubernetes/clusters/bd5f5959-5e1e-4205-a714-a914373942af/status_messages" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + messages, _, err := client.Kubernetes.GetClusterStatusMessages(ctx, "8d91899c-0739-4a1a-acc5-deadbeefbb8f", nil) + } + security: + - bearer_auth: + - kubernetes:read + /v2/load_balancers: + post: + operationId: loadBalancers_create + summary: Create a New Load Balancer + description: > + 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. + tags: + - Load Balancers + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/load_balancer_create' + examples: + Basic Create Request: + $ref: '#/components/examples/load_balancer_basic_create_request' + SSL Termination Create Request: + $ref: >- + #/components/examples/load_balancer_ssl_termination_create_request + Create Request Using Droplet Tag: + $ref: '#/components/examples/load_balancer_using_tag_create_request' + Sticky Sessions and Custom Health Check: + $ref: >- + #/components/examples/load_balancer_sticky_sessions_and_health_check_create_request + responses: + '202': + $ref: '#/components/responses/load_balancer_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Create new load balancer + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example-lb-01","size_unit": 1, "region": "nyc3", "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "firewall":{"deny":["ip:1.2.3.4","cidr:2.3.4.0/24"],"allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "droplet_ids": [3164444, 3164445]}' \ + "https://api.digitalocean.com/v2/load_balancers" + + # Create new load balancer with Droplet tag + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example-lb-01", "region": "nyc3", "size_unit": 1, "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "firewall":{"deny":["ip:1.2.3.4", "cidr:2.3.4.0/24"],"allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "tag": "web:prod"}' \ + "https://api.digitalocean.com/v2/load_balancers" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.LoadBalancerRequest{ + Name: "example-01", + SizeUnit: "1", + Algorithm: "round_robin", + Region: "nyc3", + ForwardingRules: []godo.ForwardingRule{ + { + EntryProtocol: "http", + EntryPort: 80, + TargetProtocol: "http", + TargetPort: 80, + }, + { + EntryProtocol: "https", + EntryPort: 443, + TargetProtocol: "https", + TargetPort: 443, + TlsPassthrough: true, + }, + }, + HealthCheck: &godo.HealthCheck{ + Protocol: "http", + Port: 80, + Path: "/", + CheckIntervalSeconds: 10, + ResponseTimeoutSeconds: 5, + HealthyThreshold: 5, + UnhealthyThreshold: 3, + }, + StickySessions: &godo.StickySessions{ + Type: "none", + }, + DropletIDs: []int{3164444, 3164445}, + RedirectHttpToHttps: false, + Firewall: &godo.LBFirewall{ + Deny: []string{"ip:1.2.3.4", "cidr:2.3.4.0/24"}, + Allow: []string{"cidr:1.2.0.0/16", "ip:2.3.4.5"}, + } + // Create new load balancer with Droplet tag + // Tag: "web:prod", + // RedirectHttpToHttps: false, + } + + lb, _, err := client.LoadBalancers.Create(ctx, createRequest) + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + load_balancer = DropletKit::LoadBalancer.new( + name: 'example-lb-01', + size_unit: '1', + algorithm: 'round_robin', + # Create new load balancer with Droplet tag + # tag: 'web:prod', + droplet_ids: [ 3164444, 3164445], + redirect_http_to_https: true, + region: 'nyc3', + forwarding_rules: [ + DropletKit::ForwardingRule.new( + entry_protocol: 'http', + entry_port: 80, + target_protocol: 'http', + target_port: 80, + certificate_id: '', + tls_passthrough: false + ), + DropletKit::ForwardingRule.new( + entry_protocol: 'https', + entry_port: 443, + target_protocol: 'https', + target_port: 443, + certificate_id: '', + tls_passthrough: true + ) + ], + sticky_sessions: DropletKit::StickySession.new( + type: 'cookies', + cookie_name: 'DO-LB', + cookie_ttl_seconds: 5 + ), + health_check: DropletKit::HealthCheck.new( + protocol: 'http', + port: 80, + path: '/', + check_interval_seconds: 10, + response_timeout_seconds: 5, + healthy_threshold: 5, + unhealthy_threshold: 3 + ) + ) + client.load_balancers.create(load_balancer) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example-lb-01", + "region": "nyc3", + "forwarding_rules": [ + { + "entry_protocol": "http", + "entry_port": 80, + "target_protocol": "http", + "target_port": 80 + }, + { + "entry_protocol": "https", + "entry_port": 443, + "target_protocol": "https", + "target_port": 443, + "tls_passthrough": True + } + ], + "droplet_ids": [ + 3164444, + 3164445 + ], + "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", + "http_idle_timeout_seconds": 60, + "firewall": { + "deny": [ + "cidr:1.2.0.0/16", + "ip:2.3.4.5" + ], + "allow": [ + "ip:1.2.3.4", + "cidr:2.3.4.0/24" + ] + } + } + + resp = client.load_balancers.create(body=req) + security: + - bearer_auth: + - load_balancer:create + get: + operationId: loadBalancers_list + summary: List All Load Balancers + description: > + To list all of the load balancer instances on your account, send a GET + request + + to `/v2/load_balancers`. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_load_balancers' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/load_balancers" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + lbs, _, err := c.LoadBalancers.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + load_balancers = client.load_balancers.all + load_balancers.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.load_balancers.list() + security: + - bearer_auth: + - load_balancer:read + /v2/load_balancers/{lb_id}: + get: + operationId: loadBalancers_get + summary: Retrieve an Existing Load Balancer + description: > + To show information about a load balancer instance, send a GET request + to + + `/v2/load_balancers/$LOAD_BALANCER_ID`. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + responses: + '200': + $ref: '#/components/responses/existing_load_balancer' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + lb, _, err := client.LoadBalancers.Get(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.load_balancers.find(id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.load_balancers.get(lb_id="afda3ad") + security: + - bearer_auth: + - load_balancer:read + put: + operationId: loadBalancers_update + summary: Update a Load Balancer + description: > + 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.** + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/load_balancer_create' + examples: + load_balancer_update_request: + $ref: '#/components/examples/load_balancer_update_request' + responses: + '200': + $ref: '#/components/responses/updated_load_balancer' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"example-lb-01","size_unit":"2","region":"nyc3","algorithm":"least_connections","forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80},{"entry_protocol":"https","entry_port":444,"target_protocol":"https","target_port":443,"tls_passthrough":true}],"health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3},"sticky_sessions":{"type":"cookies", "cookie_name": "DO_LB", "cookie_ttl_seconds": 300}, "firewall":{"deny":["ip:1.2.3.4","cidr:2.3.4.0/24"], "allow":["cidr:1.2.0.0/16","ip:2.3.4.5"]}, "droplet_ids": [3164444, 3164445]}' \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.LoadBalancerRequest{ + Name: "example-01", + SizeUnit: "2", + Algorithm: "round_robin", + Region: "nyc3", + ForwardingRules: []godo.ForwardingRule{ + { + EntryProtocol: "http", + EntryPort: 80, + TargetProtocol: "http", + TargetPort: 80, + }, + { + EntryProtocol: "https", + EntryPort: 443, + TargetProtocol: "https", + TargetPort: 443, + TlsPassthrough: true, + }, + }, + HealthCheck: &godo.HealthCheck{ + Protocol: "http", + Port: 80, + Path: "/", + CheckIntervalSeconds: 10, + ResponseTimeoutSeconds: 5, + HealthyThreshold: 5, + UnhealthyThreshold: 3, + }, + StickySessions: &godo.StickySessions{ + Type: "cookies", + CookieName: "DO_LB", + CookieTtlSeconds: 300, + }, + DropletIDs: []int{3164444, 3164445}, + RedirectHttpToHttps: false, + Firewall: &godo.LBFirewall{ + Deny: []string{"ip:1.2.3.4", "cidr:2.3.4.0/24"}, + Allow: []string{"cidr:1.2.0.0/16", "ip:2.3.4.5"}, + } + } + + lb, _, err := c.LoadBalancers.Update(ctx, "c2c97ca7-6f63-4e23-8909-906fd86efb5e", updateRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + load_balancer = DropletKit::LoadBalancer.new( + name: 'example-lb-01', + size_unit: '2', + algorithm: 'round_robin', + droplet_ids: [ 3164444, 3164445], + redirect_http_to_https: true, + region: 'nyc3', + forwarding_rules: [ + DropletKit::ForwardingRule.new( + entry_protocol: 'http', + entry_port: 80, + target_protocol: 'http', + target_port: 80, + certificate_id: '', + tls_passthrough: false + ), + DropletKit::ForwardingRule.new( + entry_protocol: 'https', + entry_port: 443, + target_protocol: 'https', + target_port: 443, + certificate_id: '', + tls_passthrough: true + ) + ], + sticky_sessions: DropletKit::StickySession.new( + type: 'cookies', + cookie_name: 'DO-LB-COOKIE', + cookie_ttl_seconds: 5 + ), + health_check: DropletKit::HealthCheck.new( + protocol: 'http', + port: 80, + path: '/', + check_interval_seconds: 10, + response_timeout_seconds: 5, + healthy_threshold: 5, + unhealthy_threshold: 3 + ) + ) + + client.load_balancers.update(load_balancer, id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "updated-example-lb-01", + "region": "nyc3", + "droplet_ids": [ + 3164444, + 3164445 + ], + "algorithm": "round_robin", + "forwarding_rules": [ + { + "entry_protocol": "http", + "entry_port": 80, + "target_protocol": "http", + "target_port": 80, + "certificate_id": "", + "tls_passthrough": false + }, + { + "entry_protocol": "https", + "entry_port": 443, + "target_protocol": "https", + "target_port": 443, + "certificate_id": "", + "tls_passthrough": true + } + ], + "health_check": { + "protocol": "http", + "port": 80, + "path": "/", + "check_interval_seconds": 10, + "response_timeout_seconds": 5, + "healthy_threshold": 5, + "unhealthy_threshold": 3 + }, + "sticky_sessions": { + "type": "none" + }, + "redirect_http_to_https": False, + "enable_proxy_protocol": True, + "enable_backend_keepalive": True, + "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b", + "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", + "http_idle_timeout_seconds": 60, + "firewall": { + "deny": [ + "cidr:1.2.0.0/16", + "ip:2.3.4.5" + ], + "allow": [ + "ip:1.2.3.4", + "cidr:2.3.4.0/24" + ] + } + } + resp = client.load_balancers.update(lb_id="fda9fda", body=req) + security: + - bearer_auth: + - load_balancer:update + delete: + operationId: loadBalancers_delete + summary: Delete a Load Balancer + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.LoadBalancers.Delete(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.load_balancers.delete(id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.load_balancers.delete(lb_id="afda3ad") + security: + - bearer_auth: + - load_balancer:delete + /v2/load_balancers/{lb_id}/cache: + delete: + operationId: loadBalancers_delete_cache + summary: Delete a Global Load Balancer CDN Cache + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/cache" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.LoadBalancers.PurgeCache(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6") + } + security: + - bearer_auth: + - load_balancer:delete + /v2/load_balancers/{lb_id}/droplets: + post: + operationId: loadBalancers_add_droplets + summary: Add Droplets to a Load Balancer + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + droplet_ids: + type: array + items: + type: integer + example: + - 3164444 + - 3164445 + description: >- + An array containing the IDs of the Droplets assigned to the + load balancer. + required: + - droplet_ids + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_ids": [3164446, 3164447]}' \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplets := []int{3164446, 3164447} + _, err := client.LoadBalancers.AddDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.load_balancers.add_droplets([3164446, 3164447], id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "droplet_ids": [ + 3164444, + 3164445 + ] + } + + resp = client.load_balancers.add_droplets(lb_id="1fd32a", body=req) + security: + - bearer_auth: + - load_balancer:update + delete: + operationId: loadBalancers_remove_droplets + summary: Remove Droplets from a Load Balancer + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + droplet_ids: + type: array + items: + type: integer + example: + - 3164444 + - 3164445 + description: >- + An array containing the IDs of the Droplets assigned to the + load balancer. + required: + - droplet_ids + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_ids": [3164446, 3164447]}' \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + droplets := []int{3164446, 3164447} + _, err := client.LoadBalancers.RemoveDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.load_balancers.remove_droplets([3164446, 3164447], id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "droplet_ids": [ + 3164444, + 3164445 + ] + } + + + resp = client.load_balancers.remove_droplets(lb_id="fda9fda", + body=req) + security: + - bearer_auth: + - load_balancer:update + /v2/load_balancers/{lb_id}/forwarding_rules: + post: + operationId: loadBalancers_add_forwardingRules + summary: Add Forwarding Rules to a Load Balancer + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + forwarding_rules: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/forwarding_rule' + required: + - forwarding_rules + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + forwardingRule := []godo.ForwardingRule{ + { + EntryProtocol: "tcp", + EntryPort: 3306, + TargetProtocol: "tcp", + TargetPort: 3306, + }, + } + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + rule = DropletKit::ForwardingRule.new( + entry_protocol: 'tcp', + entry_port: 3306, + target_protocol: 'tcp', + target_port: 3306, + certificate_id: '', + tls_passthrough: false + ) + + client.load_balancers.add_forwarding_rules([rule], id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "forwarding_rules": [ + { + "entry_protocol": "https", + "entry_port": 443, + "target_protocol": "http", + "target_port": 80, + "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf", + "tls_passthrough": False + } + ] + } + + + resp = client.load_balancers.add_forwarding_rules(lb_id="1fd32a", + body=req) + security: + - bearer_auth: + - load_balancer:update + delete: + operationId: loadBalancers_remove_forwardingRules + summary: Remove Forwarding Rules from a Load Balancer + description: > + 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. + tags: + - Load Balancers + parameters: + - $ref: '#/components/parameters/load_balancer_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + forwarding_rules: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/forwarding_rule' + required: + - forwarding_rules + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' \ + "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + forwardingRule := []godo.ForwardingRule{ + { + EntryProtocol: "tcp", + EntryPort: 3306, + TargetProtocol: "tcp", + TargetPort: 3306, + }, + } + + _, err := client.LoadBalancers.RemoveForwardingRules(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", forwardingRule...) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + rule = DropletKit::ForwardingRule.new( + entry_protocol: 'tcp', + entry_port: 3306, + target_protocol: 'tcp', + target_port: 3306, + certificate_id: '', + tls_passthrough: false + ) + + client.load_balancers.remove_forwarding_rules([rule], id: + '4de7ac8b-495b-4884-9a69-1050c6793cd6') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "forwarding_rules": [ + { + "entry_protocol": "https", + "entry_port": 443, + "target_protocol": "http", + "target_port": 80, + "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf", + "tls_passthrough": False + } + ] + } + + + resp = + client.load_balancers.remove_forwarding_rules(lb_id="fda9fda", + body=req) + security: + - bearer_auth: + - load_balancer:update + /v2/monitoring/alerts: + get: + operationId: monitoring_list_alertPolicy + summary: List Alert Policies + description: >- + Returns all alert policies that are configured for the given account. To + List all alert policies, send a GET request to `/v2/monitoring/alerts`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/list_alert_policy_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/alerts" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.monitoring.list_alert_policy() + security: + - bearer_auth: + - monitoring:read + post: + operationId: monitoring_create_alertPolicy + summary: Create Alert Policy + description: To create a new alert, send a POST request to `/v2/monitoring/alerts`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/alert_policy_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + requestBody: + description: > + The `type` field dictates what type of entity that the alert policy + applies to and hence what type of entity is passed in the `entities` + array. If both the `tags` array and `entities` array are empty the + alert policy applies to all entities of the relevant type that are + owned by the user account. Otherwise the following table shows the + valid entity types for each type of alert policy: + + + Type | Description | Valid Entity Type + + -----|-------------|-------------------- + + `v1/insights/droplet/memory_utilization_percent` | alert on the + percent of memory utilization | Droplet ID + + `v1/insights/droplet/disk_read` | alert on the rate of disk read I/O + in MBps | Droplet ID + + `v1/insights/droplet/load_5` | alert on the 5 minute load average | + Droplet ID + + `v1/insights/droplet/load_15` | alert on the 15 minute load average | + Droplet ID + + `v1/insights/droplet/disk_utilization_percent` | alert on the percent + of disk utilization | Droplet ID + + `v1/insights/droplet/cpu` | alert on the percent of CPU utilization | + Droplet ID + + `v1/insights/droplet/disk_write` | alert on the rate of disk write I/O + in MBps | Droplet ID + + `v1/insights/droplet/public_outbound_bandwidth` | alert on the rate of + public outbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/public_inbound_bandwidth` | alert on the rate of + public inbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/private_outbound_bandwidth` | alert on the rate + of private outbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/private_inbound_bandwidth` | alert on the rate of + private inbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/load_1` | alert on the 1 minute load average | + Droplet ID + + `v1/insights/lbaas/avg_cpu_utilization_percent`|alert on the percent + of CPU utilization|load balancer ID + + `v1/insights/lbaas/connection_utilization_percent`|alert on the + percent of connection utilization|load balancer ID + + `v1/insights/lbaas/droplet_health`|alert on Droplet health status + changes|load balancer ID + + `v1/insights/lbaas/tls_connections_per_second_utilization_percent`|alert + on the percent of TLS connections per second utilization (requires at + least one HTTPS forwarding rule)|load balancer ID + + `v1/insights/lbaas/increase_in_http_error_rate_percentage_5xx`|alert + on the percent increase of 5xx level http errors over 5m|load balancer + ID + + `v1/insights/lbaas/increase_in_http_error_rate_percentage_4xx`|alert + on the percent increase of 4xx level http errors over 5m|load balancer + ID + + `v1/insights/lbaas/increase_in_http_error_rate_count_5xx`|alert on the + count of 5xx level http errors over 5m|load balancer ID + + `v1/insights/lbaas/increase_in_http_error_rate_count_4xx`|alert on the + count of 4xx level http errors over 5m|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time`|alert on high + average http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_50p`|alert on high + 50th percentile http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_95p`|alert on high + 95th percentile http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_99p`|alert on high + 99th percentile http response time|load balancer ID + + `v1/dbaas/alerts/load_15_alerts` | alert on 15 minute load average + across the database cluster | database cluster UUID + + `v1/dbaas/alerts/memory_utilization_alerts` | alert on the percent + memory utilization average across the database cluster | database + cluster UUID + + `v1/dbaas/alerts/disk_utilization_alerts` | alert on the percent disk + utilization average across the database cluster | database cluster + UUID + + `v1/dbaas/alerts/cpu_alerts` | alert on the percent CPU usage average + across the database cluster | database cluster UUID + + `v1/droplet/autoscale_alerts/current_instances` | alert on current + pool size | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_instances` | alert on target pool + size | autoscale pool ID + + `v1/droplet/autoscale_alerts/current_cpu_utilization` | alert on + current average CPU utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_cpu_utilization` | alert on target + average CPU utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/current_memory_utilization` | alert on + current average memory utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_memory_utilization` | alert on + target average memory utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/scale_up` | alert on scale up event | + autoscale pool ID + + `v1/droplet/autoscale_alerts/scale_down` | alert on scale down event | + autoscale pool ID + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/alert_policy_request' + x-codeSamples: + - lang: cURL + source: >- + curl -X POST + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/alerts" \ + --data '{"alerts":{"email":["alerts@example.com"]},"compare":"GreaterThan","description":"CPU Alert","enabled":true,"entities":["12345678"],"tags":["droplet_tag"],"type":"v1/insights/droplet/cpu","value":80,"window":"5m"}' + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "alerts": { + "email": [ + "bob@exmaple.com" + ], + "slack": [ + { + "channel": "Production Alerts", + "url": "https://example.invalid/redacted-slack-webhook" + } + ] + }, + "compare": "GreaterThan", + "description": "CPU Alert", + "enabled": True, + "entities": [ + "192018292" + ], + "tags": [ + "droplet_tag" + ], + "type": "v1/insights/droplet/cpu", + "value": 80, + "window": "5m" + } + + resp = client.monitoring.create_alert_policy(body=req) + security: + - bearer_auth: + - monitoring:create + /v2/monitoring/alerts/{alert_uuid}: + get: + operationId: monitoring_get_alertPolicy + summary: Retrieve an Existing Alert Policy + description: >- + To retrieve a given alert policy, send a GET request to + `/v2/monitoring/alerts/{alert_uuid}` + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/alert_policy_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/alert_uuid' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/alerts/78b3da62-27e5-49ba-ac70-5db0b5935c64" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.monitoring.get_alert_policy(alert_uuid="dfa8da") + security: + - bearer_auth: + - monitoring:read + put: + operationId: monitoring_update_alertPolicy + summary: Update an Alert Policy + description: >- + To update en existing policy, send a PUT request to + `v2/monitoring/alerts/{alert_uuid}`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/alert_policy_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/alert_uuid' + requestBody: + description: > + The `type` field dictates what type of entity that the alert policy + applies to and hence what type of entity is passed in the `entities` + array. If both the `tags` array and `entities` array are empty the + alert policy applies to all entities of the relevant type that are + owned by the user account. Otherwise the following table shows the + valid entity types for each type of alert policy: + + + Type | Description | Valid Entity Type + + -----|-------------|-------------------- + + `v1/insights/droplet/memory_utilization_percent` | alert on the + percent of memory utilization | Droplet ID + + `v1/insights/droplet/disk_read` | alert on the rate of disk read I/O + in MBps | Droplet ID + + `v1/insights/droplet/load_5` | alert on the 5 minute load average | + Droplet ID + + `v1/insights/droplet/load_15` | alert on the 15 minute load average | + Droplet ID + + `v1/insights/droplet/disk_utilization_percent` | alert on the percent + of disk utilization | Droplet ID + + `v1/insights/droplet/cpu` | alert on the percent of CPU utilization | + Droplet ID + + `v1/insights/droplet/disk_write` | alert on the rate of disk write I/O + in MBps | Droplet ID + + `v1/insights/droplet/public_outbound_bandwidth` | alert on the rate of + public outbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/public_inbound_bandwidth` | alert on the rate of + public inbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/private_outbound_bandwidth` | alert on the rate + of private outbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/private_inbound_bandwidth` | alert on the rate of + private inbound bandwidth in Mbps | Droplet ID + + `v1/insights/droplet/load_1` | alert on the 1 minute load average | + Droplet ID + + `v1/insights/lbaas/avg_cpu_utilization_percent`|alert on the percent + of CPU utilization|load balancer ID + + `v1/insights/lbaas/connection_utilization_percent`|alert on the + percent of connection utilization|load balancer ID + + `v1/insights/lbaas/droplet_health`|alert on Droplet health status + changes|load balancer ID + + `v1/insights/lbaas/tls_connections_per_second_utilization_percent`|alert + on the percent of TLS connections per second utilization (requires at + least one HTTPS forwarding rule)|load balancer ID + + `v1/insights/lbaas/increase_in_http_error_rate_percentage_5xx`|alert + on the percent increase of 5xx level http errors over 5m|load balancer + ID + + `v1/insights/lbaas/increase_in_http_error_rate_percentage_4xx`|alert + on the percent increase of 4xx level http errors over 5m|load balancer + ID + + `v1/insights/lbaas/increase_in_http_error_rate_count_5xx`|alert on the + count of 5xx level http errors over 5m|load balancer ID + + `v1/insights/lbaas/increase_in_http_error_rate_count_4xx`|alert on the + count of 4xx level http errors over 5m|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time`|alert on high + average http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_50p`|alert on high + 50th percentile http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_95p`|alert on high + 95th percentile http response time|load balancer ID + + `v1/insights/lbaas/high_http_request_response_time_99p`|alert on high + 99th percentile http response time|load balancer ID + + `v1/dbaas/alerts/load_15_alerts` | alert on 15 minute load average + across the database cluster | database cluster UUID + + `v1/dbaas/alerts/memory_utilization_alerts` | alert on the percent + memory utilization average across the database cluster | database + cluster UUID + + `v1/dbaas/alerts/disk_utilization_alerts` | alert on the percent disk + utilization average across the database cluster | database cluster + UUID + + `v1/dbaas/alerts/cpu_alerts` | alert on the percent CPU usage average + across the database cluster | database cluster UUID + + `v1/droplet/autoscale_alerts/current_instances` | alert on current + pool size | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_instances` | alert on target pool + size | autoscale pool ID + + `v1/droplet/autoscale_alerts/current_cpu_utilization` | alert on + current average CPU utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_cpu_utilization` | alert on target + average CPU utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/current_memory_utilization` | alert on + current average memory utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/target_memory_utilization` | alert on + target average memory utilization | autoscale pool ID + + `v1/droplet/autoscale_alerts/scale_up` | alert on scale up event | + autoscale pool ID + + `v1/droplet/autoscale_alerts/scale_down` | alert on scale down event | + autoscale pool ID + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/alert_policy_request' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/alerts/78b3da62-27e5-49ba-ac70-5db0b5935c64" \ + --data '{"alerts":{"email":["alerts@example.com"]},"compare":"GreaterThan","description":"CPU Alert","enabled":true,"entities":["12345678"],"tags":["droplet_tag"],"type":"v1/insights/droplet/cpu","value":80,"window":"5m"}' + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "alerts": { + "email": [ + "bob@exmaple.com" + ], + "slack": [ + { + "channel": "Production Alerts", + "url": "https://example.invalid/redacted-slack-webhook" + } + ] + }, + "compare": "GreaterThan", + "description": "CPU Alert", + "enabled": True, + "entities": [ + "192018292" + ], + "tags": [ + "droplet_tag" + ], + "type": "v1/insights/droplet/cpu", + "value": 80, + "window": "5m" + } + + + resp = client.monitoring.update_alert_policy(alert_uuid="fda9da", + body=req) + security: + - bearer_auth: + - monitoring:update + delete: + operationId: monitoring_delete_alertPolicy + summary: Delete an Alert Policy + description: >- + To delete an alert policy, send a DELETE request to + `/v2/monitoring/alerts/{alert_uuid}` + tags: + - Monitoring + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/alert_uuid' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/alerts/{alert_uuid}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.monitoring.delete_alert_policy(alert_uuid="dfa8da") + security: + - bearer_auth: + - monitoring:delete + /v2/monitoring/metrics/droplet/bandwidth: + get: + operationId: monitoring_get_dropletBandwidthMetrics + summary: Get Droplet Bandwidth Metrics + description: >- + 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). + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/droplet_bandwidth_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/network_interface' + - $ref: '#/components/parameters/network_direction' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/bandwidth?host_id=222651441&interface=public&direction=outbound&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_bandwidth_metrics(alert_uuid="dfa8da", + host_id="17209102", interface="private", direction="inbound", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/cpu: + get: + operationId: monitoring_get_DropletCpuMetrics + summary: Get Droplet CPU Metrics + description: >- + To retrieve CPU metrics for a given droplet, send a GET request to + `/v2/monitoring/metrics/droplet/cpu`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/droplet_cpu_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/cpu?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.monitoring.get_droplet_cpu_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/filesystem_free: + get: + operationId: monitoring_get_dropletFilesystemFreeMetrics + summary: Get Droplet Filesystem Free Metrics + description: >- + To retrieve filesystem free metrics for a given droplet, send a GET + request to `/v2/monitoring/metrics/droplet/filesystem_free`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/droplet_filesystem_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/filesystem_free?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_filesystem_free_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/filesystem_size: + get: + operationId: monitoring_get_dropletFilesystemSizeMetrics + summary: Get Droplet Filesystem Size Metrics + description: >- + To retrieve filesystem size metrics for a given droplet, send a GET + request to `/v2/monitoring/metrics/droplet/filesystem_size`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/droplet_filesystem_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/filesystem_size?host_id=222651441&interface=public&direction=outbound&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_filesystem_size_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/load_1: + get: + operationId: monitoring_get_dropletLoad1Metrics + summary: Get Droplet Load1 Metrics + description: >- + To retrieve 1 minute load average metrics for a given droplet, send a + GET request to `/v2/monitoring/metrics/droplet/load_1`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/load_1?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_load1_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/load_5: + get: + operationId: monitoring_get_dropletLoad5Metrics + summary: Get Droplet Load5 Metrics + description: >- + To retrieve 5 minute load average metrics for a given droplet, send a + GET request to `/v2/monitoring/metrics/droplet/load_5`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/load_5?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_load5_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/load_15: + get: + operationId: monitoring_get_dropletLoad15Metrics + summary: Get Droplet Load15 Metrics + description: >- + To retrieve 15 minute load average metrics for a given droplet, send a + GET request to `/v2/monitoring/metrics/droplet/load_15`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/load_15?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_load15_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/memory_cached: + get: + operationId: monitoring_get_dropletMemoryCachedMetrics + summary: Get Droplet Cached Memory Metrics + description: >- + To retrieve cached memory metrics for a given droplet, send a GET + request to `/v2/monitoring/metrics/droplet/memory_cached`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/memory_cached?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_memory_cached_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/memory_free: + get: + operationId: monitoring_get_dropletMemoryFreeMetrics + summary: Get Droplet Free Memory Metrics + description: >- + To retrieve free memory metrics for a given droplet, send a GET request + to `/v2/monitoring/metrics/droplet/memory_free`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/memory_free?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_memory_free_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/memory_total: + get: + operationId: monitoring_get_dropletMemoryTotalMetrics + summary: Get Droplet Total Memory Metrics + description: >- + To retrieve total memory metrics for a given droplet, send a GET request + to `/v2/monitoring/metrics/droplet/memory_total`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/memory_total?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_memory_total_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet/memory_available: + get: + operationId: monitoring_get_dropletMemoryAvailableMetrics + summary: Get Droplet Available Memory Metrics + description: >- + To retrieve available memory metrics for a given droplet, send a GET + request to `/v2/monitoring/metrics/droplet/memory_available`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_droplet_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet/memory_available?host_id=222651441&start=1636051668&end=1636051668" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.monitoring.get_droplet_memory_available_metrics(host_id="17209102", + start="1620683817", end="1620705417") + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/apps/memory_percentage: + get: + operationId: monitoring_get_appMemoryPercentageMetrics + summary: Get App Memory Percentage Metrics + description: >- + To retrieve memory percentage metrics for a given app, send a GET + request to `/v2/monitoring/metrics/apps/memory_percentage`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/app_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_app_id' + - $ref: '#/components/parameters/app_component' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/apps/memory_percentage?app_id=2db3c021-15ad-4088-bfe8-99dc972b9cf6&app_component=sample-application&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/apps/cpu_percentage: + get: + operationId: monitoring_get_appCPUPercentageMetrics + summary: Get App CPU Percentage Metrics + description: >- + To retrieve cpu percentage metrics for a given app, send a GET request + to `/v2/monitoring/metrics/apps/cpu_percentage`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/app_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_app_id' + - $ref: '#/components/parameters/app_component' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/apps/cpu_percentage?app_id=2db3c021-15ad-4088-bfe8-99dc972b9cf6&app_component=sample-application&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/apps/restart_count: + get: + operationId: monitoring_get_appRestartCountMetrics.yml + summary: Get App Restart Count Metrics + description: >- + To retrieve restart count metrics for a given app, send a GET request to + `/v2/monitoring/metrics/apps/restart_count`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/app_metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_app_id' + - $ref: '#/components/parameters/app_component' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/apps/restart_count?app_id=2db3c021-15ad-4088-bfe8-99dc972b9cf6&app_component=sample-application&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_connections_current: + get: + operationId: monitoring_get_lb_frontend_connections_current + summary: Get Load Balancer Frontend Total Current Active Connections Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_connections_current?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_connections_limit: + get: + operationId: monitoring_get_lb_frontend_connections_limit + summary: Get Load Balancer Frontend Max Connections Limit Metrics + description: >- + To retrieve frontend max connections limit for a given load balancer, + send a GET request to + `/v2/monitoring/metrics/load_balancer/frontend_connections_limit`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_connections_limit?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_cpu_utilization: + get: + operationId: monitoring_get_lb_frontend_cpu_utilization + summary: Get Load Balancer Frontend Average Percentage CPU Utilization Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_cpu_utilization?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_bytes: + get: + operationId: monitoring_get_lb_frontend_firewall_dropped_bytes + summary: Get Load Balancer Frontend Firewall Dropped Bytes Metrics + description: >- + 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. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_bytes?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_packets: + get: + operationId: monitoring_get_lb_frontend_firewall_dropped_packets + summary: Get Load Balancer Frontend Firewall Dropped Packets Metrics + description: >- + 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. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_firewall_dropped_packets?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_http_responses: + get: + operationId: monitoring_get_lb_frontend_http_responses + summary: Get Load Balancer Frontend HTTP Rate Of Response Code Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_http_responses?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_http_requests_per_second: + get: + operationId: monitoring_get_lb_frontend_http_requests_per_second + summary: Get Load Balancer Frontend HTTP Requests Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_http_requests_per_second?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_network_throughput_http: + get: + operationId: monitoring_get_lb_frontend_network_throughput_http + summary: Get Load Balancer Frontend HTTP Throughput Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_network_throughput_http?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_network_throughput_udp: + get: + operationId: monitoring_get_lb_frontend_network_throughput_udp + summary: Get Load Balancer Frontend UDP Throughput Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_network_throughput_udp?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_network_throughput_tcp: + get: + operationId: monitoring_get_lb_frontend_network_throughput_tcp + summary: Get Load Balancer Frontend TCP Throughput Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_network_throughput_tcp?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_nlb_tcp_network_throughput: + get: + operationId: monitoring_get_lb_frontend_nlb_tcp_network_throughput + summary: Get Network Load Balancer Frontend TCP Throughput Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_nlb_tcp_network_throughput?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_nlb_udp_network_throughput: + get: + operationId: monitoring_get_lb_frontend_nlb_udp_network_throughput + summary: Get Network Load Balancer Frontend UDP Throughput Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_nlb_udp_network_throughput?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_tls_connections_current: + get: + operationId: monitoring_get_lb_frontend_tls_connections_current + summary: Get Load Balancer Frontend Current TLS Connections Rate Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_tls_connections_current?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_tls_connections_limit: + get: + operationId: monitoring_get_lb_frontend_tls_connections_limit + summary: Get Load Balancer Frontend Max TLS Connections Limit Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_tls_connections_limit?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/frontend_tls_connections_exceeding_rate_limit: + get: + operationId: monitoring_get_lb_frontend_tls_connections_exceeding_rate_limit + summary: >- + Get Load Balancer Frontend Closed TLS Connections For Exceeded Rate + Limit Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/frontend_tls_connections_exceeding_rate_limit?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_avg: + get: + operationId: monitoring_get_lb_droplets_http_session_duration_avg + summary: Get Load Balancer Droplets Average HTTP Session Duration Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_avg?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_50p: + get: + operationId: monitoring_get_lb_droplets_http_session_duration_50p + summary: Get Load Balancer Droplets 50th Percentile HTTP Session Duration Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_50p?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_session_duration_95p: + get: + operationId: monitoring_get_lb_droplets_http_session_duration_95p + summary: Get Load Balancer Droplets 95th Percentile HTTP Session Duration Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_session_duration_95p?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_response_time_avg: + get: + operationId: monitoring_get_lb_droplets_http_response_time_avg + summary: Get Load Balancer Droplets Average HTTP Response Time Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_response_time_avg?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_response_time_50p: + get: + operationId: monitoring_get_lb_droplets_http_response_time_50p + summary: Get Load Balancer Droplets 50th Percentile HTTP Response Time Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_response_time_50p?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_response_time_95p: + get: + operationId: monitoring_get_lb_droplets_http_response_time_95p + summary: Get Load Balancer Droplets 95th Percentile HTTP Response Time Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_response_time_95p?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_response_time_99p: + get: + operationId: monitoring_get_lb_droplets_http_response_time_99p + summary: Get Load Balancer Droplets 99th Percentile HTTP Response Time Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_response_time_99p?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_queue_size: + get: + operationId: monitoring_get_lb_droplets_queue_size + summary: Get Load Balancer Droplets Queue Size Metrics + description: >- + To retrieve Droplets queue size for a given load balancer, send a GET + request to `/v2/monitoring/metrics/load_balancer/droplets_queue_size`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_queue_size?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_http_responses: + get: + operationId: monitoring_get_lb_droplets_http_responses + summary: Get Load Balancer Droplets HTTP Rate Of Response Code Metrics + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_http_responses?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_connections: + get: + operationId: monitoring_get_lb_droplets_connections + summary: Get Load Balancer Droplets Active Connections Metrics + description: >- + To retrieve Droplets active connections for a given load balancer, send + a GET request to + `/v2/monitoring/metrics/load_balancer/droplets_connections`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_connections?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_health_checks: + get: + operationId: monitoring_get_lb_droplets_health_checks + summary: Get Load Balancer Droplets Health Check Status Metrics + description: >- + To retrieve Droplets health check status for a given load balancer, send + a GET request to + `/v2/monitoring/metrics/load_balancer/droplets_health_checks`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_health_checks?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/load_balancer/droplets_downtime: + get: + operationId: monitoring_get_lb_droplets_downtime + summary: Get Load Balancer Droplets Downtime Status Metrics + description: >- + To retrieve Droplets downtime status for a given load balancer, send a + GET request to `/v2/monitoring/metrics/load_balancer/droplets_downtime`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_load_balancer_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/load_balancer/droplets_downtime?lb_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/current_instances: + get: + operationId: monitoring_get_droplet_autoscale_current_instances + summary: Get Droplet Autoscale Pool Current Size + description: >- + To retrieve the current size for a given Droplet Autoscale Pool, send a + GET request to + `/v2/monitoring/metrics/droplet_autoscale/current_instances`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/current_instances?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/target_instances: + get: + operationId: monitoring_get_droplet_autoscale_target_instances + summary: Get Droplet Autoscale Pool Target Size + description: >- + To retrieve the target size for a given Droplet Autoscale Pool, send a + GET request to + `/v2/monitoring/metrics/droplet_autoscale/target_instances`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/target_instances?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/current_cpu_utilization: + get: + operationId: monitoring_get_droplet_autoscale_current_cpu_utilization.yml + summary: Get Droplet Autoscale Pool Current Average CPU utilization + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/current_cpu_utilization?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/target_cpu_utilization: + get: + operationId: monitoring_get_droplet_autoscale_target_cpu_utilization + summary: Get Droplet Autoscale Pool Target Average CPU utilization + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/target_cpu_utilization?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/current_memory_utilization: + get: + operationId: monitoring_get_droplet_autoscale_current_memory_utilization + summary: Get Droplet Autoscale Pool Current Average Memory utilization + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/current_memory_utilization?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/droplet_autoscale/target_memory_utilization: + get: + operationId: monitoring_get_droplet_autoscale_target_memory_utilization + summary: Get Droplet Autoscale Pool Target Average Memory utilization + description: >- + 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`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + parameters: + - $ref: '#/components/parameters/parameters_autoscale_pool_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/metrics/droplet_autoscale/target_memory_utilization?autoscale_pool_id=4de7ac8b-495b-4884-9a69-1050c6793cd6&start=1636051668&end=1636051668" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/cpu_usage: + get: + operationId: monitoring_get_database_mysql_cpu_usage + summary: Get Database MySQL CPU Usage Metrics + description: >- + 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. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/aggregate_avg_max_min' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/load: + get: + operationId: monitoring_get_database_mysql_load + summary: Get Database MySQL Load Average Metrics + description: >- + 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. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_load' + - $ref: '#/components/parameters/aggregate_avg_max' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/memory_usage: + get: + operationId: monitoring_get_database_mysql_memory_usage + summary: Get Database MySQL Memory Usage Metrics + description: >- + Retrieve memory usage (percent) for a MySQL cluster. Use **aggregate** + (avg, max, or min) over the time range. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/aggregate_avg_max_min' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/disk_usage: + get: + operationId: monitoring_get_database_mysql_disk_usage + summary: Get Database MySQL Disk Usage Metrics + description: >- + Retrieve disk usage (percent) for a MySQL cluster. Use **aggregate** + (avg, max, or min) over the time range. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/aggregate_avg_max_min' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/threads_connected: + get: + operationId: monitoring_get_database_mysql_threads_connected + summary: Get Database MySQL Threads Connected Metrics + description: Retrieve current threads connected for a MySQL service (gauge). + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/threads_created_rate: + get: + operationId: monitoring_get_database_mysql_threads_created_rate + summary: Get Database MySQL Threads Created Rate Metrics + description: Retrieve threads created rate for a MySQL service (per second). + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/threads_active: + get: + operationId: monitoring_get_database_mysql_threads_active + summary: Get Database MySQL Threads Active Metrics + description: Retrieve active (running) threads for a MySQL service. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/index_vs_sequential_reads: + get: + operationId: monitoring_get_database_mysql_index_vs_sequential_reads + summary: Get Database MySQL Index vs Sequential Reads Metrics + description: >- + Retrieve index vs sequential reads ratio (percent) for a MySQL service — + i.e. percentage of reads using an index. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/op_rates: + get: + operationId: monitoring_get_database_mysql_op_rates + summary: Get Database MySQL Operations Throughput Metrics + description: >- + Retrieve operations rate (per second) for a MySQL service. Use + **metric** to choose select, insert, update, or delete. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/metric_op_rates' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/schema_throughput: + get: + operationId: monitoring_get_database_mysql_schema_throughput + summary: Get Database MySQL Schema Throughput Metrics + description: >- + Retrieve table I/O throughput (rows per second) for a schema. Requires + **schema** and **metric** (insert, fetch, update, delete). + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/schema' + - $ref: '#/components/parameters/metric_schema_io' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/metrics/database/mysql/schema_latency: + get: + operationId: monitoring_get_database_mysql_schema_latency + summary: Get Database MySQL Schema Latency Metrics + description: >- + Retrieve table I/O latency (seconds) for a schema. Requires **schema** + and **metric** (insert, fetch, update, delete). + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/db_id' + - $ref: '#/components/parameters/schema' + - $ref: '#/components/parameters/metric_schema_io' + - $ref: '#/components/parameters/metric_timestamp_start' + - $ref: '#/components/parameters/metric_timestamp_end' + responses: + '200': + $ref: '#/components/responses/metric_response' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/sinks/destinations: + post: + operationId: monitoring_create_destination + summary: Create Logging Destination + description: >- + To create a new destination, send a POST request to + `/v2/monitoring/sinks/destinations`. + tags: + - Monitoring + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/destination_request' + examples: + Managed OpenSearch Cluster: + value: + name: managed_opensearch_cluster + type: opensearch_dbaas + config: + endpoint: >- + db-opensearch-nyc3-123456-do-user-123456-0.g.db.ondigitalocean.com + cluster_uuid: 85148069-7e35-4999-80bd-6fa1637ca385 + cluster_name: managed_dbaas_cluster + index_name: logs + retention_days: 14 + External OpenSearch Cluster: + value: + name: external_opensearch + type: opensearch_ext + config: + endpoint: example.com + credentials: + username: username + password: password + index_name: logs + retention_days: 14 + responses: + '200': + $ref: '#/components/responses/destination' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/destinations" \ + --data '{"name":"cluster", "type":"opensearch_dbaas", "config": {"endpoint": "example.com", "credentials": {"username": "username", "password": "password"}}}' + security: + - bearer_auth: + - monitoring:create + get: + operationId: monitoring_list_destinations + summary: List Logging Destinations + description: >- + To list all logging destinations, send a GET request to + `/v2/monitoring/sinks/destinations`. + tags: + - Monitoring + responses: + '200': + $ref: '#/components/responses/monitoring_list_destinations' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/destinations" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/sinks/destinations/{destination_uuid}: + get: + operationId: monitoring_get_destination + summary: Get Logging Destination + description: >- + To get the details of a destination, send a GET request to + `/v2/monitoring/sinks/destinations/${destination_uuid}`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/destination_uuid' + responses: + '200': + $ref: '#/components/responses/destination' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514" + security: + - bearer_auth: + - monitoring:read + post: + operationId: monitoring_update_destination + summary: Update Logging Destination + description: >- + To update the details of a destination, send a PATCH request to + `/v2/monitoring/sinks/destinations/${destination_uuid}`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/destination_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/destination_request' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514" \ + --data '{"index_name": "logs", "retention_days": 30}' + security: + - bearer_auth: + - monitoring:update + delete: + operationId: monitoring_delete_destination + summary: Delete Logging Destination + description: >- + To delete a destination and all associated sinks, send a DELETE request + to `/v2/monitoring/sinks/destinations/${destination_uuid}`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/destination_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/destinations/01f30bfa-319a-4769-ba95-9d43971fb514" + security: + - bearer_auth: + - monitoring:delete + /v2/monitoring/sinks: + post: + operationId: monitoring_create_sink + summary: Create Sink + description: > + 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. + tags: + - Monitoring + responses: + '202': + $ref: '#/components/responses/accepted' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + requestBody: + required: true + content: + application/json: + schema: + properties: + destination_uuid: + type: string + example: 9df2b7e9-3fb2-4577-b60a-e9c0d53f9a99 + description: A unique identifier for an already-existing destination. + resources: + type: array + description: List of resources identified by their URNs. + items: + $ref: '#/components/schemas/sink_resource' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks" \ + --data '{"destination_uuid": "f2fcd5d9-f410-4f3a-8015-130ada94b1fe", "resources": [{"name": "fra_kubernetes_cluster", "urn":"do:kubernetes:8463c9db-150c-4b44-830c-fca7f68d005b"}]}' + security: + - bearer_auth: + - monitoring:create + get: + operationId: monitoring_list_sinks + summary: Lists all sinks + description: To list all sinks, send a GET request to `/v2/monitoring/sinks`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/resource_id' + responses: + '200': + $ref: '#/components/responses/list_sinks' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks?resource_id=do:kubernetes:f2fcd5d9-f410-4f3a-8015-130ada94b1fe" + security: + - bearer_auth: + - monitoring:read + /v2/monitoring/sinks/{sink_uuid}: + get: + operationId: monitoring_get_sink + summary: Get Sink + description: >- + To get the details of a sink (resources and destination), send a GET + request to `/v2/monitoring/sinks/${sink_uuid}`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/sink_uuid' + responses: + '200': + $ref: '#/components/responses/sinks' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/f945d774-86e8-4dc8-8f60-cfc76dd3d098" + security: + - bearer_auth: + - monitoring:read + delete: + operationId: monitoring_delete_sink + summary: Delete Sink + description: >- + To delete a sink, send a DELETE request to + `/v2/monitoring/sinks/${sink_uuid}`. + tags: + - Monitoring + parameters: + - $ref: '#/components/parameters/sink_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/monitoring/sinks/aef7ff4a-f1be-4d9e-b886-650fcb5bdfe3" + security: + - bearer_auth: + - monitoring:delete + /v2/nfs: + post: + operationId: nfs_create + summary: Create a new NFS share + description: | + To create a new NFS share, send a POST request to `/v2/nfs`. + tags: + - NFS + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_request' + examples: + Basic NFS Share: + value: + name: sammy-share-drive + size_gib: 1024 + region: atl1 + vpc_ids: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + performance_tier: standard + responses: + '201': + $ref: '#/components/responses/nfs_create' + '400': + $ref: '#/components/responses/bad_request-2' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "sammy-share-drive", "size_gib": 1024, "region": "atl1", "vpc_ids": ["796c6fe3-2a1d-4da2-9f3e-38239827dc91"]}' \ + "https://api.digitalocean.com/v2/nfs" + security: + - bearer_auth: + - nfs:create + get: + operationId: nfs_list + summary: List NFS shares per region + description: > + 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. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/parameters_region' + responses: + '200': + $ref: '#/components/responses/nfs_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs?region=atl1" + security: + - bearer_auth: + - nfs:list + /v2/nfs/{nfs_id}: + get: + operationId: nfs_get + summary: Get an NFS share + description: > + To get an NFS share, send a GET request to + `/v2/nfs/{nfs_id}?region=${region}`. + + + A successful request will return the NFS share. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/nfs_id' + - $ref: '#/components/parameters/parameters_region' + responses: + '200': + $ref: '#/components/responses/nfs_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs/{share_id}?region=atl1" + security: + - bearer_auth: + - nfs:read + delete: + operationId: nfs_delete + summary: Delete an NFS share + description: > + 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. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/nfs_id' + - $ref: '#/components/parameters/parameters_region' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs/{share_id}?region=atl1" + security: + - bearer_auth: + - nfs:delete + /v2/nfs/{nfs_id}/actions: + post: + operationId: nfs_create_action + summary: Initiate an NFS action + description: > + 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 | + + | -------------------------------- | ----------- | + + | `resize` | Resizes an NFS share. Set the + size_gib attribute to a desired value in GiB | + + | `snapshot` | Takes a snapshot of an NFS share | + + | `attach` | Attaches an NFS share to a VPC. Set + the vpc_id attribute to the desired VPC ID | + + | `detach` | Detaches an NFS share from a VPC. + Set the vpc_id attribute to the desired VPC ID | + + | `reassign` | Reassigns an NFS share from one VPC + to another. Set the old_vpc_id and new_vpc_id attributes to the desired + VPC IDs | + + | `switch_performance_tier` | Switches the performance tier + of an NFS share. Set the performance_tier attribute to the desired tier + (e.g., standard, high) | + tags: + - NFS Actions + parameters: + - $ref: '#/components/parameters/nfs_id' + requestBody: + required: true + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the NFS share. Some actions will require additional + + attributes to be set as well. + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/nfs_action_resize' + - $ref: '#/components/schemas/nfs_action_snapshot' + - $ref: '#/components/schemas/nfs_action_attach' + - $ref: '#/components/schemas/nfs_action_detach' + - $ref: '#/components/schemas/nfs_action_reassign' + - $ref: '#/components/schemas/nfs_action_switch_performance_tier' + discriminator: + propertyName: type + mapping: + resize: '#/components/schemas/nfs_action_resize' + snapshot: '#/components/schemas/nfs_action_snapshot' + attach: '#/components/schemas/nfs_action_attach' + detach: '#/components/schemas/nfs_action_detach' + reassign: '#/components/schemas/nfs_action_reassign' + switch_performance_tier: '#/components/schemas/nfs_action_switch_performance_tier' + responses: + '201': + $ref: '#/components/responses/nfs_actions' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type": "resize", "params": {"size_gib": 1024}, "region": "atl1"}' \ + "https://api.digitalocean.com/v2/nfs/${nfs_id}/actions" + security: + - bearer_auth: + - nfs:create + /v2/nfs/snapshots: + get: + operationId: nfs_list_snapshot + summary: List NFS snapshots per region + description: > + 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. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/parameters_region' + - $ref: '#/components/parameters/share_id' + responses: + '200': + $ref: '#/components/responses/nfs_snapshot_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs/snapshots?region=atl1" + security: + - bearer_auth: + - nfs:list + /v2/nfs/snapshots/{nfs_snapshot_id}: + get: + operationId: nfs_get_snapshot + summary: Get an NFS snapshot by ID + description: > + 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. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/nfs_snapshot_id' + - $ref: '#/components/parameters/parameters_region' + responses: + '200': + $ref: '#/components/responses/nfs_snapshot_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs/snapshots/{snapshot_id}?region=atl1" + security: + - bearer_auth: + - nfs:read + delete: + operationId: nfs_delete_snapshot + summary: Delete an NFS snapshot + description: > + 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. + tags: + - NFS + parameters: + - $ref: '#/components/parameters/nfs_snapshot_id' + - $ref: '#/components/parameters/parameters_region' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/nfs/snapshots/{snapshot_id}?region=atl1" + security: + - bearer_auth: + - nfs:delete + /v2/partner_network_connect/attachments: + get: + operationId: partnerAttachments_list + summary: List all partner attachments + description: >- + To list all of the Partner Attachments on your account, send a `GET` + request to `/v2/partner_network_connect/attachments`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_partner_attachments' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("$DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + + ListOptions := &godo.ListOptions{ Page: 1, PerPage: 20, WithProjects: true} + + response, _, err := client.PartnerAttachment.List(ctx, ListOptions) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("$DIGITALOCEAN_TOKEN")) + + partner_attachment_response = client.partner_attachments.list() + security: + - bearer_auth: + - partner_network_connect:read + post: + operationId: partnerAttachments_create + summary: Create a new partner attachment + description: > + 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. + tags: + - Partner Network Connect + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/partner_attachment_writable' + responses: + '202': + $ref: '#/components/responses/single_partner_attachment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X POST \ + + -H "Content-Type: application/json" \ + + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + + -d + '{"name":"c5pAqd-ped-007","connection_bandwidth_in_mbps":1000,"region":"NYC","naas_provider":"MEGAPORT","vpc_ids":["bafc1c1d-bac1-2412-7f5e-fezc832z213z"],"bgp":{"local_router_ip":"169.254.11.1/29","peer_router_ip":"169.254.11.2/29","peer_router_asn":133938,"auth_key":"0zzyTNuRZa00vqkzIToPG3q"}}' + \ + + "https://api.digitalocean.com/v2/partner_network_connect/attachments" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + createReq := &godo.PartnerAttachmentCreateRequest{ + Name:"c5pAqd-ped-007", + ConnectionBandwidthInMbps:1000, + Region:"NYC", + NaaSProvider:"MEGAPORT", + VPCIDs:[]string{"bafc1c1d-bac1-2412-7f5e-fezc832z213z"}, + BGP: godo.BGP{ + LocalRouterIP:"169.254.11.1/29", + PeerRouterIP:"169.254.11.2/29", + PeerASN:133938, + AuthKey:"0zzyTNuRZa00vqkzIToPG3q", + }, + } + + response, _, err := client.PartnerAttachment.Create(ctx, createReq) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + req = { + "connection_bandwidth_in_mbps": 1000, + "naas_provider": "MEGAPORT", + "name": "c5pAqd-ped-007", + "region": "NYC", + "vpc_ids": [ + "bafc1c1d-bac1-2412-7f5e-fezc832z213z" + ], + "bgp": { + "auth_key": "0zzyTNuRZa00vqkzIToPG3q", + "local_router_ip": "169.254.11.1/29", + "peer_router_asn": 133938, + "peer_router_ip": "169.254.11.2/29" + }, + } + + resp = client.partner_attachments.create(body=req) + security: + - bearer_auth: + - partner_network_connect:create + /v2/partner_network_connect/attachments/{pa_id}: + get: + operationId: partnerAttachments_get + summary: Retrieve an existing partner attachment + description: | + To get the details of a partner attachment, send a `GET` request to + `/v2/partner_network_connect/attachments/{pa_id}`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + responses: + '200': + $ref: '#/components/responses/single_partner_attachment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + partnerAttachmentResponse, _, err := client.PartnerAttachment.Get(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + + partner_attachment_response = + client.partner_attachments.get("5a4981aa-9653-4bd1-bef5-d6bff52042e4") + security: + - bearer_auth: + - partner_network_connect:read + patch: + operationId: partnerAttachments_patch + summary: Update an existing partner attachment + description: > + 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. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/partner_attachment_updatable' + responses: + '202': + $ref: '#/components/responses/single_partner_attachment' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/5a4981aa-9653-4bd1-bef5-d6bff52042e4" \ + -d '{ "name": "partner-network-test" }' + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + partnerAttachmentRequest := &godo.PartnerAttachmentUpdateRequest{ + Name: "partner-network-test-region", + } + + response, _, err := client.PartnerAttachment.Update(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4", partnerAttachmentRequest) + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + request = { + "Name": "partner-network-test" + } + + + print(client.partner_attachments.patch("5a4981aa-9653-4bd1-bef5-d6bff52042e4", + body = request)) + security: + - bearer_auth: + - partner_network_connect:read + delete: + operationId: partnerAttachments_delete + summary: Delete an existing partner attachment + description: | + To delete an existing partner attachment, send a `DELETE` request to + `/v2/partner_network_connect/attachments/{pa_id}`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + responses: + '202': + $ref: '#/components/responses/single_partner_attachment_deleting' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + response, err := client.PartnerAttachment.Delete(ctx,"5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + + response = + client.partner_attachments.delete("5a4981aa-9653-4bd1-bef5-d6bff52042e4") + security: + - bearer_auth: + - partner_network_connect:read + /v2/partner_network_connect/attachments/{pa_id}/bgp_auth_key: + get: + operationId: partnerAttachments_get_bgp_auth_key + summary: Get current BGP auth key for the partner attachment + description: > + 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`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + responses: + '200': + $ref: '#/components/responses/single_partner_attachment_bgp_auth_key' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/5a4981aa-9653-4bd1-bef5-d6bff52042e4/bgp_auth_key" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + response, _, err := client.PartnerAttachment.GetBGPAuthKey(ctx,"5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + + response = + client.partner_attachments.get_bgp_auth_key("5a4981aa-9653-4bd1-bef5-d6bff52042e4") + security: + - bearer_auth: + - partner_network_connect:read + /v2/partner_network_connect/attachments/{pa_id}/remote_routes: + get: + operationId: partnerAttachments_list_remote_routes + summary: List remote routes for a partner attachment + description: > + To list all remote routes associated with a partner attachment, send a + `GET` request to + + `/v2/partner_network_connect/attachments/{pa_id}/remote_routes`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_partner_attachment_remote_routes' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/9ddccad8-a6d2-42f1-84e7-c92916193978/remote_routes" + security: + - bearer_auth: + - partner_network_connect:read + /v2/partner_network_connect/attachments/{pa_id}/service_key: + get: + operationId: partnerAttachments_get_service_key + summary: Get the current service key for the partner attachment + description: > + To get the current service key for a partner attachment, send a `GET` + request to + + `/v2/partner_network_connect/attachments/{pa_id}/service_key`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + responses: + '200': + $ref: '#/components/responses/single_partner_attachment_service_key' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/1cf0aad8-292b-40f8-9d32-1fbde6e04991/service_key" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + response, _, err := client.PartnerAttachment.GetServiceKey(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: >- + import os + + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + response = + client.partner_attachments.get_service_key("5a4981aa-9653-4bd1-bef5-d6bff52042e4") + security: + - bearer_auth: + - partner_network_connect:read + post: + operationId: partnerAttachments_create_service_key + summary: Regenerate the service key for the partner attachment + description: > + 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`. + tags: + - Partner Network Connect + parameters: + - $ref: '#/components/parameters/pa_id' + responses: + '202': + $ref: '#/components/responses/empty_json_object' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/partner_network_connect/attachments/1cf0aad8-292b-40f8-9d32-1fbde6e04991/service_key" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + response, _, err := client.PartnerAttachment.RegenerateServiceKey(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: >- + import os + + from pydo import Client + + client = Client(token=os.getenv("$DIGITALOCEAN_TOKEN")) + + response = + client.partner_attachments.create_service_key("5a4981aa-9653-4bd1-bef5-d6bff52042e4") + security: + - bearer_auth: + - partner_network_connect:write + /v2/projects: + get: + operationId: projects_list + summary: List All Projects + description: To list all your projects, send a GET request to `/v2/projects`. + tags: + - Projects + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/projects_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + PerPage: 10, + Page: 1, + } + + client.Projects.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + projects = client.projects.all + projects.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.list() + security: + - bearer_auth: + - project:read + post: + operationId: projects_create + summary: Create a Project + description: To create a project, send a POST request to `/v2/projects`. + tags: + - Projects + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/project_base' + required: + - name + - purpose + responses: + '201': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Production"}' \ + "https://api.digitalocean.com/v2/projects" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createReq := &godo.CreateProjectRequest{ + Name: "my-web-api", + Description: "My website API", + Purpose: "Service or API", + Environment: "Production", + } + + client.Projects.Create(ctx, createReq) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + project = DropletKit::Project.new( + name: 'my-api', + description: 'My website API', + purpose: 'Service or API', + environment: 'Production' + ) + client.projects.create(project) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "my-web-api", + "description": "My website API", + "purpose": "Service or API", + "environment": "Production" + } + + resp = client.projects.create(body=req) + security: + - bearer_auth: + - project:create + /v2/projects/default: + get: + operationId: projects_get_default + summary: Retrieve the Default Project + description: >- + To get your default project, send a GET request to + `/v2/projects/default`. + tags: + - Projects + responses: + '200': + $ref: '#/components/responses/default_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects/default" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + client.Projects.GetDefault(ctx) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.projects.find_default + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.get_default() + security: + - bearer_auth: + - project:read + put: + operationId: projects_update_default + summary: Update the Default Project + description: >- + To update you default project, send a PUT request to + `/v2/projects/default`. All of the following attributes must be sent. + tags: + - Projects + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/project' + required: + - name + - description + - purpose + - environment + - is_default + responses: + '200': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' \ + "https://api.digitalocean.com/v2/projects/default" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateReq := &godo.UpdateProjectRequest{ + Name: "my-web-api", + Description: "My website API", + Purpose: "Service or API", + Environment: "Staging", + IsDefault: false, + } + + client.Projects.Update(ctx, godo.DefaultProject, updateReq) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + project = client.projects.find_default + project.environment = 'Staging' + client.projects.update(project, id: 'default') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "my-web-api", + "description": "My website API", + "purpose": "Service or API", + "environment": "Production", + "is_default": False + } + + resp = client.projects.update_default(body=req) + security: + - bearer_auth: + - project:update + patch: + operationId: projects_patch_default + summary: Patch the Default Project + description: >- + 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. + tags: + - Projects + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/project' + example: + name: my-web-api + responses: + '200': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"environment": "Staging"}' \ + "https://api.digitalocean.com/v2/projects/default" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateReq := &godo.UpdateProjectRequest{ + Environment: "Staging", + } + + client.Projects.Update(ctx, godo.DefaultProject, updateReq) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + project = client.projects.find_default + project.environment = 'Staging' + client.projects.update(project, id: 'default') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "my-web-api" + } + + resp = client.projects.patch_default(body=req) + security: + - bearer_auth: + - project:update + /v2/projects/{project_id}: + get: + operationId: projects_get + summary: Retrieve an Existing Project + description: To get a project, send a GET request to `/v2/projects/$PROJECT_ID`. + tags: + - Projects + parameters: + - $ref: '#/components/parameters/project_id' + responses: + '200': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + client.Projects.Get(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + project = client.projects.find(id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.get(project_id="4e1bfbc3") + security: + - bearer_auth: + - project:read + put: + operationId: projects_update + summary: Update a Project + description: >- + To update a project, send a PUT request to `/v2/projects/$PROJECT_ID`. + All of the following attributes must be sent. + tags: + - Projects + parameters: + - $ref: '#/components/parameters/project_id' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/project' + required: + - name + - description + - purpose + - environment + - is_default + responses: + '200': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3\ + -dc3e-41f2-a18f-1b4d7ba71679" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateReq := &godo.UpdateProjectRequest{ + Name: "my-web-api", + Description: "My website API", + Purpose: "Service or API", + Environment: "Staging", + IsDefault: false, + } + + client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq) + + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + project = client.projects.find(id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + + project.environment = 'Staging' + + client.projects.update(project, id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "my-web-api", + "description": "My website API", + "purpose": "Service or API", + "environment": "Production", + "is_default": False + } + + resp = client.projects.update_default(body=req) + security: + - bearer_auth: + - project:update + patch: + operationId: projects_patch + summary: Patch a Project + description: >- + 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. + tags: + - Projects + parameters: + - $ref: '#/components/parameters/project_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/project' + example: + name: my-web-api + responses: + '200': + $ref: '#/components/responses/existing_project' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"environment": "Staging"}' \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3\ + -dc3e-41f2-a18f-1b4d7ba71679" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateReq := &godo.UpdateProjectRequest{ + Environment: "Staging", + } + + client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + project = client.projects.find(id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + + project.environment = 'Staging' + + client.projects.update(project, id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "my-web-api" + } + + resp = client.projects.patch(project_id="4e1bfbc3", body=req) + security: + - bearer_auth: + - project:update + delete: + operationId: projects_delete + summary: Delete an Existing Project + description: > + 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. + tags: + - Projects + parameters: + - $ref: '#/components/parameters/project_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '412': + $ref: '#/components/responses/precondition_failed' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -X DELETE -H 'Content-Type: application/json' -H + "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Projects.Delete(ctx, '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.projects.delete(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.delete(project_id="fda9fda") + security: + - bearer_auth: + - project:delete + /v2/projects/{project_id}/resources: + get: + operationId: projects_list_resources + summary: List Project Resources + description: > + 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. + tags: + - Project Resources + parameters: + - $ref: '#/components/parameters/project_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + PerPage: 10, + Page: 1, + } + + client.Projects.ListResources(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", opt) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.projects.list_resources(id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.list_resources(project_id="4e1bfbc3") + security: + - bearer_auth: + - project:read + post: + operationId: projects_assign_resources + summary: Assign Resources to a Project + description: > + To assign resources to a project, send a POST request to + `/v2/projects/$PROJECT_ID/resources`. + + + You must have both `project:update` and `:read` scopes to + assign new resources. For example, to assign a Droplet to a project, + include both the `project:update` and `droplet:read` scopes. + tags: + - Project Resources + parameters: + - $ref: '#/components/parameters/project_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/project_assignment' + examples: + assign_resources: + value: + resources: + - do:droplet:13457723 + - do:domain:example.com + responses: + '200': + $ref: '#/components/responses/assigned_resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"resources": ["do:droplet:1", "do:floatingip:192.168.99.100"]}' \ + "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + res := []interface{}{ + &godo.Droplet{ID: 1}, + "do:droplet:42", + &godo.FloatingIP{IP: "192.168.99.100"}, + } + + client.Projects.AssignResources(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", res...) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + resource = DropletKit::ProjectAssignment.new(urn: 'do:droplet:1') + + client.projects.assign_resources([resource], id: + '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "resources": [ + "do:droplet:13457723", + "do:domain:example.com" + ] + } + + + resp = client.projects.assign_resources(project_id="8dafda", + body=req) + security: + - bearer_auth: + - project:update + /v2/projects/default/resources: + get: + operationId: projects_list_resources_default + summary: List Default Project Resources + description: > + 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. + tags: + - Project Resources + responses: + '200': + $ref: '#/components/responses/resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/projects/default/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + PerPage: 10, + Page: 1, + } + + client.Projects.ListResources(ctx, godo.DefaultProject, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.projects.list_resources(id: 'default') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.projects.list_resources_default() + security: + - bearer_auth: + - project:read + post: + operationId: projects_assign_resources_default + summary: Assign Resources to Default Project + description: > + To assign resources to your default project, send a POST request to + `/v2/projects/default/resources`. + + + You must have both project:update and :read scopes to assign + new resources. For example, to assign a Droplet to the default project, + include both the `project:update` and `droplet:read` scopes. + tags: + - Project Resources + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/project_assignment' + examples: + assign_resources: + value: + resources: + - do:droplet:13457723 + - do:domain:example.com + responses: + '200': + $ref: '#/components/responses/assigned_resources_list' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"resources": ["do:droplet:1", "do:floatingip:192.168.99.100"]}' \ + "https://api.digitalocean.com/v2/projects/default/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + res := []interface{}{ + &godo.Droplet{ID: 1}, + "do:droplet:42", + &godo.FloatingIP{IP: "192.168.99.100"}, + } + + client.Projects.AssignResources(ctx, godo.DefaultProject, res...) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + resource = DropletKit::ProjectAssignment.new(urn: 'do:droplet:1') + client.projects.assign_resources([resource], id: 'default') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "resources": [ + "do:droplet:13457723", + "do:domain:example.com" + ] + } + + resp = client.projects.assign_resources_default(body=req) + security: + - bearer_auth: + - project:update + /v2/regions: + get: + operationId: regions_list + summary: List All Data Center Regions + description: >- + 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. + tags: + - Regions + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_regions' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/regions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + regions, _, err := client.Regions.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + regions = client.regions.all + regions.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.regions.list() + security: + - bearer_auth: + - regions:read + /v2/registries: + get: + operationId: registries_list + summary: List All Container Registries + description: >- + To get information about any container registry in your account, send a + GET request to `/v2/registries/`. + tags: + - Container Registries + responses: + '200': + $ref: '#/components/responses/all_registries_info' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registries.get() + security: + - bearer_auth: + - registry:read + post: + operationId: registries_create + summary: Create Container Registry + description: > + 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`. + tags: + - Container Registries + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/multiregistry_create' + responses: + '201': + $ref: '#/components/responses/multiregistry_info' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example", "subscription_tier_slug": "basic", "region": "fra1"}' \ + "https://api.digitalocean.com/v2/registries" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example", + "region": "fra1", + "subscription_tier_slug": "basic" + } + + resp = client.registries.create(body=req) + security: + - bearer_auth: + - registry:create + /v2/registries/{registry_name}: + get: + operationId: registries_get + summary: Get a Container Registry By Name + description: >- + To get information about any container registry in your account, send a + GET request to `/v2/registries/{registry_name}`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/multiregistry_info' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registries.get(registry_name="example") + security: + - bearer_auth: + - registry:read + delete: + operationId: registries_delete + summary: Delete Container Registry By Name + description: >- + To delete your container registry, destroying all container image data + stored in it, send a DELETE request to `/v2/registries/{registry_name}`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registries.delete(registry_name="example") + security: + - bearer_auth: + - registry:delete + /v2/registries/{registry_name}/docker-credentials: + get: + operationId: registries_get_dockerCredentials + summary: Get Docker Credentials By Registry Name + description: > + 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. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/docker_credentials' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/docker-credentials" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.get_docker_credentials(registry_name="example") + security: + - bearer_auth: + - registry:read + - registry:update + /v2/registries/subscription: + get: + operationId: registries_get_subscription + summary: Get Subscription Information + description: >- + 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`. + tags: + - Container Registries + responses: + '200': + $ref: '#/components/responses/subscription_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/subscription" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registries.get_subscription() + security: + - bearer_auth: + - registry:read + post: + operationId: registries_update_subscription + summary: Update Subscription Tier + description: >- + 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`. + tags: + - Container Registries + requestBody: + content: + application/json: + schema: + type: object + properties: + tier_slug: + type: string + enum: + - starter + - basic + - professional + example: basic + description: The slug of the subscription tier to sign up for. + responses: + '200': + $ref: '#/components/responses/subscription_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tier_slug": "professional"}' \ + "https://api.digitalocean.com/v2/registries/subscription" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "tier_slug": "basic" + } + + resp = client.registries.update_subscription(body=req) + security: + - bearer_auth: + - registry:update + /v2/registries/options: + get: + operationId: registries_get_options + summary: List Registry Options (Subscription Tiers and Available Regions) + description: >- + 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`. + tags: + - Container Registries + responses: + '200': + $ref: '#/components/responses/registry_options_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/options" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registries.get_options() + security: + - bearer_auth: + - registry:read + /v2/registries/{registry_name}/garbage-collection: + get: + operationId: registries_get_garbageCollection + summary: Get Active Garbage Collection + description: >- + To get information about the currently-active garbage collection for a + registry, send a GET request to + `/v2/registry/$REGISTRY_NAME/garbage-collection`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/garbage-collection" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.get_garbage_collection(registry_name="example") + security: + - bearer_auth: + - registry:read + post: + operationId: registries_run_garbageCollection + summary: Start Garbage Collection + description: > + 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. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '201': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/garbage-collection" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.run_garbage_collection(registry_name="example") + security: + - bearer_auth: + - registry:update + /v2/registries/{registry_name}/garbage-collections: + get: + operationId: registries_list_garbageCollections + summary: List Garbage Collections + description: >- + To get information about past garbage collections for a registry, send a + GET request to `/v2/registry/$REGISTRY_NAME/garbage-collections`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/garbage_collections' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/garbage-collections" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.list_garbage_collections(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registries/{registry_name}/garbage-collection/{garbage_collection_uuid}: + put: + operationId: registries_update_garbageCollection + summary: Update Garbage Collection + description: >- + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/garbage_collection_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/update_registry' + responses: + '200': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/garbage-collection/example-gc-uuid" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.run_garbage_collection(registry_name="example") + security: + - bearer_auth: + - registry:update + /v2/registries/{registry_name}/repositoriesV2: + get: + operationId: registries_list_repositoriesV2 + summary: List All Container Registry Repositories (V2) + description: >- + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/token_pagination_page' + - $ref: '#/components/parameters/token_pagination_page_token' + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/all_repositories_v2' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositoriesV2?page_size=1" + - lang: cURL (next page) + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositoriesV2?page=2&page_token=JPZmZzZXQiOjB9&per_page=1" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.list_repositories_v2(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registries/{registry_name}/repositories/{repository_name}: + delete: + operationId: registries_delete_repository + summary: Delete Container Registry Repository + description: > + 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. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositories/repo-1" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.registries.delete_repository(registry_name="example", + repository_name="repo-1") + security: + - bearer_auth: + - registry:delete + /v2/registries/{registry_name}/repositories/{repository_name}/tags: + get: + operationId: registries_list_repositoryTags + summary: List All Container Registry Repository Tags + description: > + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + responses: + '200': + $ref: '#/components/responses/repository_tags' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositories/repo-1/tags" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.list_repository_tags(registry_name="example", + repository_name="repo01") + security: + - bearer_auth: + - registry:read + /v2/registries/{registry_name}/repositories/{repository_name}/tags/{repository_tag}: + delete: + operationId: registries_delete_repositoryTag + summary: Delete Container Registry Repository Tag + description: > + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + - $ref: '#/components/parameters/registry_repository_tag' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositories/repo-1/tags/mytag" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.delete_repository_tag(registry_name="example", + repository_name="repo-1", repository_tag="06a447a") + security: + - bearer_auth: + - registry:delete + /v2/registries/{registry_name}/repositories/{repository_name}/digests: + get: + operationId: registries_list_repositoryManifests + summary: List All Container Registry Repository Manifests + description: > + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + responses: + '200': + $ref: '#/components/responses/repository_manifests' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositories/repo-1/digests" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.list_repository_manifests(registry_name="example", + repository_name="repo01") + security: + - bearer_auth: + - registry:read + /v2/registries/{registry_name}/repositories/{repository_name}/digests/{manifest_digest}: + delete: + operationId: registries_delete_repositoryManifest + summary: Delete Container Registry Repository Manifest + description: > + 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`. + tags: + - Container Registries + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + - $ref: '#/components/parameters/registry_manifest_digest' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registries/example/repositories/repo-1/digests/sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registries.delete_repository_manifest(registry_name="example", + repository_name="repo-1", manifest_digest="sha256:cb8a924afd") + security: + - bearer_auth: + - registry:delete + /v2/registries/validate-name: + post: + operationId: registries_validate_name + summary: Validate a Container Registry Name + description: > + 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`. + tags: + - Container Registries + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/validate_registry' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example"}' \ + "https://api.digitalocean.com/v2/registries/validate-name" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example" + } + + resp = client.registries.validate_name(body=req) + security: + - bearer_auth: + - registry:create + /v2/registry: + get: + operationId: registry_get + deprecated: true + summary: Get Container Registry Information + description: > + **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. + tags: + - Container Registry + responses: + '200': + $ref: '#/components/responses/registry_info' + '401': + $ref: '#/components/responses/unauthorized' + '412': + $ref: '#/components/responses/registries_precondition_fail' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.get() + security: + - bearer_auth: + - registry:read + post: + operationId: registry_create + deprecated: true + summary: Create Container Registry + description: > + **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`. + tags: + - Container Registry + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/registry_create' + responses: + '201': + $ref: '#/components/responses/registry_info' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example", "subscription_tier_slug": "basic", "region": "fra1"}' \ + "https://api.digitalocean.com/v2/registry" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example", + "subscription_tier_slug": "basic", + "region": "fra1" + } + + resp = client.registry.create(body=req) + security: + - bearer_auth: + - registry:create + delete: + operationId: registry_delete + deprecated: true + summary: Delete Container Registry + description: > + **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. + tags: + - Container Registry + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '412': + $ref: '#/components/responses/registries_precondition_fail' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.delete() + security: + - bearer_auth: + - registry:delete + /v2/registry/subscription: + get: + operationId: registry_get_subscription + deprecated: true + summary: Get Subscription + description: > + **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`. + tags: + - Container Registry + responses: + '200': + $ref: '#/components/responses/subscription_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/subscription" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.get_subscription() + security: + - bearer_auth: + - registry:read + post: + operationId: registry_update_subscription + deprecated: true + summary: Update Subscription Tier + description: > + **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`. + tags: + - Container Registry + requestBody: + content: + application/json: + schema: + type: object + properties: + tier_slug: + type: string + enum: + - starter + - basic + - professional + example: basic + description: The slug of the subscription tier to sign up for. + responses: + '200': + $ref: '#/components/responses/subscription_response' + '401': + $ref: '#/components/responses/unauthorized' + '412': + $ref: '#/components/responses/registries_over_limit' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tier_slug": "professional"}' \ + "https://api.digitalocean.com/v2/registry/subscription" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "tier_slug": "basic" + } + + resp = client.registry.update_subscription(body=req) + security: + - bearer_auth: + - registry:update + /v2/registry/docker-credentials: + get: + operationId: registry_get_dockerCredentials + deprecated: true + summary: Get Docker Credentials for Container Registry + description: > + **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. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_expiry_seconds' + - $ref: '#/components/parameters/registry_read_write' + responses: + '200': + $ref: '#/components/responses/docker_credentials' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/docker-credentials" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.get_docker_credentials() + security: + - bearer_auth: + - registry:read + - registry:update + /v2/registry/validate-name: + post: + operationId: registry_validate_name + deprecated: true + summary: Validate a Container Registry Name + description: > + **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. + tags: + - Container Registry + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/validate_registry' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "example"}' \ + "https://api.digitalocean.com/v2/registry/validate-name" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "example" + } + + resp = client.registry.validate_name(body=req) + security: + - bearer_auth: + - registry:create + /v2/registry/{registry_name}/repositories: + get: + operationId: registry_list_repositories + deprecated: true + summary: List All Container Registry Repositories + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/all_repositories' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositories" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.list_repositories(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/repositoriesV2: + get: + operationId: registry_list_repositoriesV2 + deprecated: true + summary: List All Container Registry Repositories (V2) + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/token_pagination_page' + - $ref: '#/components/parameters/token_pagination_page_token' + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/all_repositories_v2' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositoriesV2?page_size=1" + - lang: cURL (next page) + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=2&page_token=JPZmZzZXQiOjB9&per_page=1" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.list_repositories_v2(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/repositories/{repository_name}/tags: + get: + operationId: registry_list_repositoryTags + deprecated: true + summary: List All Container Registry Repository Tags + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + responses: + '200': + $ref: '#/components/responses/repository_tags' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/tags" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.registry.list_repository_tags(registry_name="example", + repository_name="repo01") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/repositories/{repository_name}/tags/{repository_tag}: + delete: + operationId: registry_delete_repositoryTag + deprecated: true + summary: Delete Container Registry Repository Tag + description: > + **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. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + - $ref: '#/components/parameters/registry_repository_tag' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/tags/mytag" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.delete_repository_tag(registry_name="example", + repository_name="repo-1", repository_tag="06a447a") + security: + - bearer_auth: + - registry:delete + /v2/registry/{registry_name}/repositories/{repository_name}/digests: + get: + operationId: registry_list_repositoryManifests + deprecated: true + summary: List All Container Registry Repository Manifests + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + responses: + '200': + $ref: '#/components/responses/repository_manifests' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.list_repository_manifests(registry_name="example", + repository_name="repo01") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/repositories/{repository_name}/digests/{manifest_digest}: + delete: + operationId: registry_delete_repositoryManifest + deprecated: true + summary: Delete Container Registry Repository Manifest + description: > + **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. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/registry_repository_name' + - $ref: '#/components/parameters/registry_manifest_digest' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests/sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.delete_repository_manifest(registry_name="example", + repository_name="repo-1", manifest_digest="sha256:cb8a924afd") + security: + - bearer_auth: + - registry:delete + /v2/registry/{registry_name}/garbage-collection: + post: + operationId: registry_run_garbageCollection + deprecated: true + summary: Start Garbage Collection + description: > + **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. + tags: + - Container Registry + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/registry_run_gc' + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '201': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ "type": "unreferenced blobs only"}' \ + "https://api.digitalocean.com/v2/registry/example/garbage-collection" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "type": "unreferenced blobs only" + + } + + + resp = + client.registry.run_garbage_collection(registry_name="example",body=req) + security: + - bearer_auth: + - registry:update + get: + operationId: registry_get_garbageCollection + deprecated: true + summary: Get Active Garbage Collection + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_name' + responses: + '200': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/garbage-collection" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.get_garbage_collection(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/garbage-collections: + get: + operationId: registry_list_garbageCollections + deprecated: true + summary: List Garbage Collections + description: > + **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`. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/garbage_collections' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/garbage-collections" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.list_garbage_collections(registry_name="example") + security: + - bearer_auth: + - registry:read + /v2/registry/{registry_name}/garbage-collection/{garbage_collection_uuid}: + put: + operationId: registry_update_garbageCollection + deprecated: true + summary: Update Garbage Collection + description: > + **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. + tags: + - Container Registry + parameters: + - $ref: '#/components/parameters/registry_name' + - $ref: '#/components/parameters/garbage_collection_uuid' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/update_registry' + responses: + '200': + $ref: '#/components/responses/garbage_collection' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/example/garbage-collection/example-gc-uuid" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.registry.run_garbage_collection(registry_name="example") + security: + - bearer_auth: + - registry:update + /v2/registry/options: + get: + operationId: registry_get_options + deprecated: true + summary: List Registry Options (Subscription Tiers and Available Regions) + description: > + **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`. + tags: + - Container Registry + responses: + '200': + $ref: '#/components/responses/registry_options_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/registry/options" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.registry.get_options() + security: + - bearer_auth: + - registry:read + /v2/reports/droplet_neighbors_ids: + get: + operationId: droplets_list_neighborsIds + summary: List All Droplet Neighbors + description: > + 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. + tags: + - Droplets + responses: + '200': + $ref: '#/components/responses/droplet_neighbors_ids' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reports/droplet_neighbors_ids" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.droplets.list_neighbors_ids() + security: + - bearer_auth: + - droplet:read + /v2/reserved_ips: + get: + operationId: reservedIPs_list + summary: List All Reserved IPs + description: >- + To list all of the reserved IPs available on your account, send a GET + request to `/v2/reserved_ips`. + tags: + - Reserved IPs + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/reserved_ip_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ips?page=1&per_page=20" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + reservedIPs, _, err := client.ReservedIPs.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + reserved_ips = client.reserved_ips.all + reserved_ips.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ips.list() + security: + - bearer_auth: + - reserved_ip:read + post: + operationId: reservedIPs_create + summary: Create a New Reserved IP + description: >- + 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. + tags: + - Reserved IPs + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/reserved_ip_create' + responses: + '202': + $ref: '#/components/responses/reserved_ip_created' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"droplet_id": 123456}' \ + "https://api.digitalocean.com/v2/reserved_ips" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.ReservedIPCreateRequest{ + DropletID: 123456, + Region: "nyc3", + ProjectID: "1234a77a-12cd-11ed-909f-43c99lbf6030", + } + + reservedIP, _, err := client.ReservedIPs.Create(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + reserved_ip = DropletKit::ReservedIp.new(droplet_id: 123456) + client.reserved_ips.create(reserved_ip) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "droplet_id": 2457247 + } + + resp = client.reserved_ips.create(body=req) + security: + - bearer_auth: + - reserved_ip:create + /v2/reserved_ips/{reserved_ip}: + get: + operationId: reservedIPs_get + summary: Retrieve an Existing Reserved IP + description: >- + To show information about a reserved IP, send a GET request to + `/v2/reserved_ips/$RESERVED_IP_ADDR`. + tags: + - Reserved IPs + parameters: + - $ref: '#/components/parameters/reserved_ip' + responses: + '200': + $ref: '#/components/responses/reserved_ip' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + reservedIP, _, err := client.ReservedIPs.Get(ctx, "45.55.96.47") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.reserved_ips.find(ip: '45.55.96.47') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ips.get(reserved_ip="45.55.96.47") + security: + - bearer_auth: + - reserved_ip:read + delete: + operationId: reservedIPs_delete + summary: Delete a Reserved IP + description: > + 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. + tags: + - Reserved IPs + parameters: + - $ref: '#/components/parameters/reserved_ip' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.ReservedIPs.Delete(ctx, "45.55.96.34") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.reserved_ips.delete(ip: '45.55.96.47') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ips.delete(reserved_ip="45.55.96.47") + security: + - bearer_auth: + - reserved_ip:delete + /v2/reserved_ips/{reserved_ip}/actions: + get: + operationId: reservedIPsActions_list + summary: List All Actions for a Reserved IP + description: >- + To retrieve all actions that have been executed on a reserved IP, send a + GET request to `/v2/reserved_ips/$RESERVED_IP/actions`. + tags: + - Reserved IP Actions + parameters: + - $ref: '#/components/parameters/reserved_ip' + responses: + '200': + $ref: '#/components/responses/reserved_ip_actions' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + actions, _, err := client.ReservedIPActions.List(ctx, '45.55.96.47', opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + actions = client.reserved_ip_actions.all(ip: '45.55.96.47') + actions.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ips_actions.list(reserved_ip="45.55.96.47") + security: + - bearer_auth: + - reserved_ip:read + post: + operationId: reservedIPsActions_post + summary: Initiate a Reserved IP Action + description: > + 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 + tags: + - Reserved IP Actions + parameters: + - $ref: '#/components/parameters/reserved_ip' + requestBody: + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the reserved IP. + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/reserved_ip_action_unassign' + - $ref: '#/components/schemas/reserved_ip_action_assign' + discriminator: + propertyName: type + mapping: + unassign: '#/components/schemas/reserved_ip_action_unassign' + assign: '#/components/schemas/reserved_ip_action_assign' + responses: + '201': + $ref: '#/components/responses/reserved_ip_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Assign a Reserved IP to a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"assign","droplet_id":8219222}' \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47/actions" + + # Unassign a Reserved IP + # curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"unassign"}' \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47/actions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Assign a Reserved IP to a Droplet + action, _, err := client.ReservedIPActions.Assign(ctx, "45.55.96.47", 8219222) + + // Unassign a Reserved IP + action, _, err := client.ReservedIPActions.Unassign(ctx, "45.55.96.47") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + # Assign a Reserved IP to a Droplet + + client.reserved_ip_actions.assign(ip: '45.55.96.47', droplet_id: + 8219222) + + + # Unassign a Reserved IP + + # client.reserved_ip_actions.unassign(ip: '45.55.96.47') + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req={ + "type": "unassign" + } + + + resp = client.reserved_ips_actions.post(reserved_ip="49.32.13.21", + body=req) + security: + - bearer_auth: + - reserved_ip:update + /v2/reserved_ips/{reserved_ip}/actions/{action_id}: + get: + operationId: reservedIPsActions_get + summary: Retrieve an Existing Reserved IP Action + description: >- + To retrieve the status of a reserved IP action, send a GET request to + `/v2/reserved_ips/$RESERVED_IP/actions/$ACTION_ID`. + tags: + - Reserved IP Actions + parameters: + - $ref: '#/components/parameters/reserved_ip' + - $ref: '#/components/parameters/action_id' + responses: + '200': + $ref: '#/components/responses/reserved_ip_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ips/45.55.96.47/actions/72531856" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.ReservedIPActions.Get(ctx, "45.55.96.47", 72531856) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.reserved_ip_actions.find(ip: '45.55.96.47', id: 72531856) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ips_actions.get(reserved_ip="45.55.96.47") + security: + - bearer_auth: + - reserved_ip:read + /v2/reserved_ipv6: + get: + operationId: reservedIPv6_list + summary: List All Reserved IPv6s + description: >- + To list all of the reserved IPv6s available on your account, send a GET + request to `/v2/reserved_ipv6`. + tags: + - Reserved IPv6 + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/reserved_ipv6_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ipv6?page=1&per_page=20" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + reservedIPs, _, err := client.ReservedIPV6s.List(ctx, opt) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.reserved_ipv6s.list() + security: + - bearer_auth: + - reserved_ip:read + post: + operationId: reservedIPv6_create + summary: Create a New Reserved IPv6 + description: >- + 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. + tags: + - Reserved IPv6 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/reserved_ipv6_create' + responses: + '201': + $ref: '#/components/responses/reserved_ipv6_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"region_slug": "nyc3"}' \ + "https://api.digitalocean.com/v2/reserved_ipv6" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.ReservedIPV6CreateRequest{ + RegionSlug: "nyc3", + } + + reservedIPV6, _, err := client.ReservedIPV6s.Create(ctx, createRequest) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "region_slug": nyc3 + } + + resp = client.reserved_ipv6s.create(body=req) + security: + - bearer_auth: + - reserved_ip:create + /v2/reserved_ipv6/{reserved_ipv6}: + get: + operationId: reservedIPv6_get + summary: Retrieve an Existing Reserved IPv6 + description: >- + To show information about a reserved IPv6, send a GET request to + `/v2/reserved_ipv6/$RESERVED_IPV6`. + tags: + - Reserved IPv6 + parameters: + - $ref: '#/components/parameters/reserved_ipv6' + responses: + '200': + $ref: '#/components/responses/reserved_ipv6' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ipv6/2409:40d0:f7:1017:74b4:3a96:105e:4c6e" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + reservedIP, _, err := client.ReservedIPV6s.Get(ctx, "2409:40d0:f7:1017:74b4:3a96:105e:4c6e") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.reserved_ipv6s.get(reserved_ipv6="2409:40d0:f7:1017:74b4:3a96:105e:4c6e") + security: + - bearer_auth: + - reserved_ip:read + delete: + operationId: reservedIPv6_delete + summary: Delete a Reserved IPv6 + description: > + 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. + tags: + - Reserved IPv6 + parameters: + - $ref: '#/components/parameters/reserved_ipv6' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/reserved_ipv6/2409:40d0:f7:1017:74b4:3a96:105e:4c6e" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.ReservedIPV6s.Delete(ctx, "2409:40d0:f7:1017:74b4:3a96:105e:4c6e") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.reserved_ipv6s.delete(reserved_ipv6="2409:40d0:f7:1017:74b4:3a96:105e:4c6e") + security: + - bearer_auth: + - reserved_ip:delete + /v2/reserved_ipv6/{reserved_ipv6}/actions: + post: + operationId: reservedIPv6Actions_post + summary: Initiate a Reserved IPv6 Action + description: > + 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 + tags: + - Reserved IPv6 Actions + parameters: + - $ref: '#/components/parameters/reserved_ipv6' + requestBody: + description: > + The `type` attribute set in the request body will specify the action + that + + will be taken on the reserved IPv6. + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/reserved_ipv6_action_unassign' + - $ref: '#/components/schemas/reserved_ipv6_action_assign' + discriminator: + propertyName: type + mapping: + unassign: '#/components/schemas/reserved_ipv6_action_unassign' + assign: '#/components/schemas/reserved_ipv6_action_assign' + responses: + '201': + $ref: '#/components/responses/reserved_ipv6_action' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Assign a Reserved IPv6 to a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"assign","droplet_id":8219222}' \ + "https://api.digitalocean.com/v2/reserved_ipv6/2409:40d0:f7:1017:74b4:3a96:105e:4c6e/actions" + + # Unassign a Reserved IPv6 from a Droplet + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"unassign"}' \ + "https://api.digitalocean.com/v2/reserved_ipv6/2409:40d0:f7:1017:74b4:3a96:105e:4c6e/actions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Assign a Reserved IPv6 to a Droplet + action, _, err := client.ReservedIPV6Actions.Assign(ctx, "2409:40d0:f7:1017:74b4:3a96:105e:4c6e", 8219222) + + // Unassign a Reserved IPv6 + action, _, err := client.ReservedIPV6Actions.Unassign(ctx, "2409:40d0:f7:1017:74b4:3a96:105e:4c6e") + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req={ + "type": "unassign" + } + + + resp = + client.reserved_ipv6s_actions.post(reserved_ipv6="2409:40d0:f7:1017:74b4:3a96:105e:4c6e", + body=req) + security: + - bearer_auth: + - reserved_ip:update + /v2/byoip_prefixes: + post: + operationId: byoipPrefixes_create + summary: Create a BYOIP Prefix + description: > + 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. + tags: + - BYOIP Prefixes + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/byoip_prefix_create' + responses: + '202': + $ref: '#/components/responses/byoip_prefix_create' + '401': + $ref: '#/components/responses/unauthorized' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"prefix": "203.0.113.0/24", "region": "nyc3", "signature": "$SIGNATURE"}' \ + "https://api.digitalocean.com/v2/byoip_prefixes" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + signatureHash := "" + + createRequest := &godo.BYOIPPrefixCreateReq{ + Prefix: "203.0.113.0/24", + Region: "nyc3", + Signature: signatureHash, + } + + byoipPrefix, _, err := client.BYOIPPrefixes.Create(ctx, createRequest) + if err != nil { + panic(err) + } + // use byoipPrefix + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "prefix": "203.0.113.0/24", + "region": "nyc3", + "signature": "", + } + + resp = client.byoip_prefixes.create(body=req) + security: + - bearer_auth: + - byoip_prefix:create + get: + operationId: byoipPrefixes_list + summary: List BYOIP Prefixes + description: > + 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. + tags: + - BYOIP Prefixes + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/byoip_prefix_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/byoip_prefixes" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + + byoipPrefixes, _, err := client.BYOIPPrefixes.List(ctx, &godo.ListOptions{ + Page: 1, + PerPage: 10, + }) + if err != nil { + panic(err) + } + // use byoipPrefixes + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.byoip_prefixes.list() + security: + - bearer_auth: + - byoip_prefix:read + /v2/byoip_prefixes/{byoip_prefix_uuid}: + get: + operationId: byoipPrefixes_get + summary: Get a BYOIP Prefix + description: > + 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. + tags: + - BYOIP Prefixes + parameters: + - $ref: '#/components/parameters/byoip_prefix' + responses: + '200': + $ref: '#/components/responses/byoip_prefix_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/byoip_prefixes/fa3b-1234-5678-90ab-cdef01234567" + - lang: Go + source: |- + import ( + "context" + "os" + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + + byoipPrefix, _, err := client.BYOIPPrefixes.Get(ctx, "fa3b-1234-5678-90ab-cdef01234567") + if err != nil { + panic(err) + } + // use byoipPrefix + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.byoip_prefixes.get(byoip_prefix_uuid="fa3b-1234-5678-90ab-cdef01234567") + security: + - bearer_auth: + - byoip_prefix:read + delete: + operationId: byoipPrefixes_delete + summary: Delete a BYOIP Prefix + description: > + 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. + tags: + - BYOIP Prefixes + parameters: + - $ref: '#/components/parameters/byoip_prefix' + responses: + '202': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/byoip_prefixes/fa3b-1234-5678-90ab-cdef01234567" + - lang: Go + source: |- + import ( + "context" + "os" + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.BYOIPPrefixes.Delete(ctx, "fa3b-1234-5678-90ab-cdef01234567") + if err != nil { + panic(err) + } + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.byoip_prefixes.delete(byoip_prefix_uuid="fa3b-1234-5678-90ab-cdef01234567") + security: + - bearer_auth: + - byoip_prefix:delete + patch: + operationId: byoipPrefixes_patch + summary: Update a BYOIP Prefix + description: > + 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. + tags: + - BYOIP Prefixes + parameters: + - in: path + name: byoip_prefix_uuid + schema: + type: string + format: uuid + required: true + description: A unique identifier for a BYOIP prefix. + example: f47ac10b-58cc-4372-a567-0e02b2c3d479 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/byoip_prefix_update' + responses: + '202': + $ref: '#/components/responses/byoip_prefix_update' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"advertise": true}' \ + "https://api.digitalocean.com/v2/byoip_prefixes/$BYOIP_PREFIX_UUID" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + byoipPrefixUUID := "f47ac10b-58cc-4372-a567-0e02b2c3d479" + + advertise := true + updateRequest := &godo.BYOIPPrefixUpdateReq{ + Advertise: &advertise, + } + + byoipPrefix, _, err := client.BYOIPPrefixes.Update(ctx, byoipPrefixUUID, updateRequest) + if err != nil { + panic(err) + } + // use byoipPrefix + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + byoip_prefix_uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479" + + + req = { + "advertise": True, + } + + + resp = + client.byoip_prefixes.update(byoip_prefix_uuid=byoip_prefix_uuid, + body=req) + security: + - bearer_auth: + - byoip_prefix:write + /v2/byoip_prefixes/{byoip_prefix_uuid}/ips: + get: + operationId: byoipPrefixes_list_resources + summary: List BYOIP Prefix Resources + description: > + 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. + tags: + - BYOIP Prefixes + parameters: + - $ref: '#/components/parameters/byoip_prefix' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/byoip_prefix_list_resources' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/byoip_prefixes/fa3b-1234-5678-90ab-cdef01234567/ips" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + client := godo.NewFromToken(token) + ctx := context.TODO() + + resources, _, err := client.BYOIPPrefixes.GetResources(ctx, "fa3b-1234-5678-90ab-cdef01234567", &godo.ListOptions{ + Page: 1, + PerPage: 20, + }) + if err != nil { + panic(err) + } + // use resources + } + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = + client.byoip_prefixes.resources_list(byoip_prefix_uuid="fa3b-1234-5678-90ab-cdef01234567") + security: + - bearer_auth: + - byoip_prefix:read + /v2/security/scans: + get: + operationId: security_list_scans + summary: List Scans + description: To list all CSPM scans, send a GET request to `/v2/security/scans`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/scans' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/scans" + security: + - bearer_auth: + - security:read + post: + operationId: security_create_scan + summary: Create Scan + description: To create a CSPM scan, send a POST request to `/v2/security/scans`. + tags: + - Security + responses: + '201': + $ref: '#/components/responses/scan' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/scans" + security: + - bearer_auth: + - security:create + /v2/security/scans/{scan_id}: + get: + operationId: security_get_scan + summary: Get Scan + description: >- + To get a CSPM scan by ID, send a GET request to + `/v2/security/scans/{scan_id}`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/scan_id' + - $ref: '#/components/parameters/severity' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - in: query + name: type + required: false + description: The finding type to include. + schema: + type: string + example: CSPM + responses: + '200': + $ref: '#/components/responses/scan' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/scans/497dcba3-ecbf-4587-a2dd-5eb0665e6880" + security: + - bearer_auth: + - security:read + /v2/security/scans/latest: + get: + operationId: security_get_latest_scan + summary: Get Latest Scan + description: >- + To get the latest CSPM scan, send a GET request to + `/v2/security/scans/latest`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/severity' + - in: query + name: type + required: false + description: The finding type to include. + schema: + type: string + example: CSPM + responses: + '200': + $ref: '#/components/responses/scan' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/scans/latest" + security: + - bearer_auth: + - security:read + /v2/security/scans/rules: + post: + operationId: security_create_scan_rule + summary: Create Scan Rule + description: |- + To mark a scan finding as a false positive, send a POST request to + `/v2/security/scans/rules` to create a new scan rule. + tags: + - Security + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + resource: + type: string + example: do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + description: The URN of a resource to exclude from future scans. + responses: + '201': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"resource": "do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"}' \ + "https://api.digitalocean.com/v2/security/scans/rules" + security: + - bearer_auth: + - security:create + /v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources: + get: + operationId: security_list_scan_finding_affected_resources + summary: List Finding Affected Resources + description: >- + To get affected resources for a scan finding, send a GET request to + `/v2/security/scans/{scan_id}/findings/{finding_uuid}/affected_resources`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/scan_id' + - $ref: '#/components/parameters/finding_uuid' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/affected_resources' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/scans/497dcba3-ecbf-4587-a2dd-5eb0665e6880/findings/50e14f43-dd4e-412f-864d-78943ea28d91/affected_resources" + security: + - bearer_auth: + - security:read + /v2/security/settings: + get: + operationId: security_list_settings + summary: List Settings + description: >- + To list CSPM scan settings, send a GET request to + `/v2/security/settings`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/settings' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/settings" + security: + - bearer_auth: + - security:read + /v2/security/settings/plan: + put: + operationId: security_update_settings_plan + summary: Update Plan + description: >- + To update CSPM plan coverage, send a PUT request to + `/v2/security/settings/plan`. + tags: + - Security + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + tier_coverage: + type: object + description: Scan coverage for each available plan tier. + additionalProperties: + type: object + properties: + resources: + type: array + items: + type: string + description: The URNs of resources to scan for the tier. + default: [] + example: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + tags: + type: array + items: + type: string + description: Resource tags to scan for the tier. + default: [] + example: + - production + example: + basic: + resources: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + tags: + - production + responses: + '200': + $ref: '#/components/responses/tier_coverage' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"tier_coverage":{"basic":{"resources":["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"],"tags":["production"]}}}' \ + "https://api.digitalocean.com/v2/security/settings/plan" + security: + - bearer_auth: + - security:update + /v2/security/settings/suppressions: + post: + operationId: security_create_suppression + summary: Create Suppression + description: >- + To suppress scan findings, send a POST request to + `/v2/security/settings/suppressions`. + tags: + - Security + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + rule_uuid: + type: string + description: The rule UUID to suppress for the listed resources. + resources: + type: array + items: + type: string + example: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + description: The URNs of resources to suppress for the rule. + responses: + '201': + $ref: '#/components/responses/suppressed_resources' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"rule_uuid":"497dcba3-ecbf-4587-a2dd-5eb0665e6880","resources":["do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d"]}' \ + "https://api.digitalocean.com/v2/security/settings/suppressions" + security: + - bearer_auth: + - security:create + /v2/security/settings/suppressions/{suppression_uuid}: + delete: + operationId: security_delete_suppression + summary: Delete Suppression + description: >- + To remove a suppression, send a DELETE request to + `/v2/security/settings/suppressions/{suppression_uuid}`. + tags: + - Security + parameters: + - $ref: '#/components/parameters/suppression_uuid' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/security/settings/suppressions/5b3b2b2d-5c9c-4a61-9e2f-4d8f80f30a12" + security: + - bearer_auth: + - security:delete + /v2/sizes: + get: + operationId: sizes_list + summary: List All Droplet Sizes + description: >- + 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. + tags: + - Sizes + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_sizes' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/sizes" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + sizes, _, err := client.Sizes.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + sizes = client.sizes.all + sizes.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.sizes.list() + security: + - bearer_auth: + - sizes:read + - regions:read + /v2/snapshots: + get: + operationId: snapshots_list + summary: List All Snapshots + description: > + 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`. + tags: + - Snapshots + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/snapshot_resource_type' + responses: + '200': + $ref: '#/components/responses/snapshots' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # List all snapshots + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1" + + # List all Droplet snapshots + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=droplet" + + # List volume snapshots + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=volume" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + // List all snapshots + snapshots, _, err := client.Snapshots.List(ctx, opt) + + // List all Droplet snapshots + // snapshots, _, err := client.Snapshots.ListDroplet(ctx, opt) + + // List all volume snapshots + // snapshots, _, err := client.Snapshots.ListVolume(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + # List all snapshots + snapshots = client.snapshots.all + snapshots.each + + # List all Droplet snapshots + # snapshots = client.snapshots.all(resource_type: 'droplet') + # snapshots.each + + # List volume snapshots + # snapshots = client.snapshots.all(resource_type: 'volume') + # snapshots.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.snapshots.list() + security: + - bearer_auth: + - snapshot:read + /v2/snapshots/{snapshot_id}: + get: + operationId: snapshots_get + summary: Retrieve an Existing Snapshot + description: > + 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. + tags: + - Snapshots + parameters: + - $ref: '#/components/parameters/snapshot_id' + responses: + '200': + $ref: '#/components/responses/snapshots_existing' + '400': + $ref: '#/components/responses/not_a_snapshot' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + snapshot, _, err := client.Snapshots.Get(ctx, 'fbe805e8-866b-11e6-96bf-000f53315a41') + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + snapshot = client.snapshots.find(id: + 'fbe805e8-866b-11e6-96bf-000f53315a41') + - lang: cURL + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.snapshots.get(snapshot_id="fbe805e8") + security: + - bearer_auth: + - snapshot:read + - block_storage_snapshot:read + delete: + operationId: snapshots_delete + summary: Delete a Snapshot + description: > + 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. + tags: + - Snapshots + parameters: + - $ref: '#/components/parameters/snapshot_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '400': + $ref: '#/components/responses/not_a_snapshot' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Snapshots.Delete(ctx, 'fbe805e8-866b-11e6-96bf-000f53315a41') + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.snapshots.delete(id: 'fbe805e8-866b-11e6-96bf-000f53315a41') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.snapshots.delete(snapshot_id="fbe805e8") + security: + - bearer_auth: + - image:delete + - snapshot:delete + /v2/spaces/keys: + get: + operationId: spacesKey_list + summary: List Spaces Access Keys + description: > + To list Spaces Access Key, send a GET request to `/v2/spaces/keys`. Sort + parameter must be used with Sort Direction. + tags: + - Spaces Keys + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/sort_direction' + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/bucket' + - $ref: '#/components/parameters/permission' + responses: + '200': + $ref: '#/components/responses/key_list' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/spaces/keys" + security: + - bearer_auth: + - spaces_key:read + post: + operationId: spacesKey_create + summary: Create a New Spaces Access Key + description: > + 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. + tags: + - Spaces Keys + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/key' + examples: + Read Only Key: + value: + name: read-only-key + grants: + - bucket: my-bucket + permission: read + Read Write Key: + value: + name: read-write-key + grants: + - bucket: my-bucket + permission: readwrite + Full Access Key: + value: + name: full-access-key + grants: + - bucket: '' + permission: fullaccess + Mixed Permissions Key: + value: + name: mixed-permissions-key + grants: + - bucket: my-bucket + permission: read + - bucket: my-bucket2 + permission: readwrite + No Grant Key: + value: + name: no-grant-key + grants: [] + responses: + '201': + $ref: '#/components/responses/key_create' + '400': + $ref: '#/components/responses/bad_request-3' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "test-key", "grants": [{"bucket": "test-bucket", "permission": "read"}]}' \ + "https://api.digitalocean.com/v2/spaces/keys" + security: + - bearer_auth: + - spaces_key:create_credentials + /v2/spaces/keys/{access_key}: + get: + operationId: spacesKey_get + summary: Get a Spaces Access Key + description: > + To get a Spaces Access Key, send a GET request to + `/v2/spaces/keys/$ACCESS_KEY`. + + + A successful request will return the Access Key. + tags: + - Spaces Keys + parameters: + - $ref: '#/components/parameters/access_key_id' + responses: + '200': + $ref: '#/components/responses/key_get' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/spaces/keys/DOACCESSKEYEXAMPLE" + security: + - bearer_auth: + - spaces_key:read + delete: + operationId: spacesKey_delete + summary: Delete a Spaces Access Key + description: > + 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. + tags: + - Spaces Keys + parameters: + - $ref: '#/components/parameters/access_key_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/spaces/keys/DOACCESSKEYEXAMPLE" + security: + - bearer_auth: + - spaces_key:delete + put: + operationId: spacesKey_update + summary: Update Spaces Access Keys + description: > + 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. + tags: + - Spaces Keys + parameters: + - $ref: '#/components/parameters/access_key_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/key' + examples: + Update Key Name: + value: + name: new-key-name + responses: + '200': + $ref: '#/components/responses/key_update' + '400': + $ref: '#/components/responses/bad_request-3' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "new-key-name"}' \ + "https://api.digitalocean.com/v2/spaces/keys/DOACCESSKEYEXAMPLE" + security: + - bearer_auth: + - spaces_key:update + patch: + operationId: spacesKey_patch + summary: Update Spaces Access Keys + description: > + 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. + tags: + - Spaces Keys + parameters: + - $ref: '#/components/parameters/access_key_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/key' + examples: + Update Key Name: + value: + name: new-key-name + responses: + '200': + $ref: '#/components/responses/key_update' + '400': + $ref: '#/components/responses/bad_request-3' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "new-key-name"}' \ + "https://api.digitalocean.com/v2/spaces/keys/DOACCESSKEYEXAMPLE" + security: + - bearer_auth: + - spaces_key:update + /v2/tags: + get: + operationId: tags_list + summary: List All Tags + description: > + 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`). + tags: + - Tags + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/tags_all' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/tags" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + tags, _, err := client.Tags.List(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + tags = client.tags.all + tags.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.tags.list() + security: + - bearer_auth: + - tag:read + post: + operationId: tags_create + summary: Create a New Tag + description: >- + To create a tag you can send a POST request to `/v2/tags` with a `name` + attribute. + tags: + - Tags + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/tags' + responses: + '201': + $ref: '#/components/responses/tags_new' + '400': + $ref: '#/components/responses/tags_bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"awesome"}' \ + "https://api.digitalocean.com/v2/tags" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &TagCreateRequest{ + Name: "testing-1", + } + client.Tags.Create(ctx, request) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + tag = DropletKit::Tag.new(name: 'awesome') + client.tags.create(tag) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = {"name": "extra-awesome"} + + resp = client.tags.create(body=req) + security: + - bearer_auth: + - tag:create + /v2/tags/{tag_id}: + get: + operationId: tags_get + summary: Retrieve a Tag + description: > + 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. + tags: + - Tags + parameters: + - $ref: '#/components/parameters/tag_id' + responses: + '200': + $ref: '#/components/responses/tags_existing' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/tags/awesome" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + tag, _, err := client.Tags.Get(ctx, "awesome") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.tags.find(name: 'awesome') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.tags.get(tag_id="awesome") + security: + - bearer_auth: + - tag:read + delete: + operationId: tags_delete + summary: Delete a Tag + description: >- + 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 + tags: + - Tags + parameters: + - $ref: '#/components/parameters/tag_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/tags/awesome" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + client.Tags.Delete(ctx, "awesome") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.tags.delete(name: 'awesome') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.tags.delete(tag_id="awesome") + security: + - bearer_auth: + - tag:delete + /v2/tags/{tag_id}/resources: + post: + operationId: tags_assign_resources + summary: Tag a Resource + description: > + 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 + `:update` scopes. For example, + + to tag a Droplet, you must have `tag:create` and `droplet:update`. + tags: + - Tags + parameters: + - $ref: '#/components/parameters/tag_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/tags_resource' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"resources":[{"resource_id":"9569411","resource_type":"droplet"},{"resource_id":"7555620","resource_type":"image"},{"resource_id":"3d80cb72-342b-4aaa-b92e-4e4abb24a933","resource_type":"volume"}]}' \ + "https://api.digitalocean.com/v2/tags/awesome/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + tags, _, err := client.Tags.List(ctx, opt) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.tags.tag_resources(name: 'awesome', resources: [{ + resource_id: '9569411', resource_type: 'droplet' },{ resource_id: + '7555620', resource_type: 'image' },{ resource_id: + '3d80cb72-342b-4aaa-b92e-4e4abb24a933', resource_type: 'volume'}]) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "resources": [ + { + "resource_id": "9569411", + "resource_type": "droplet" + }, + { + "resource_id": "7555620", + "resource_type": "image" + }, + { + "resource_id": "3d80cb72-342b-4aaa-b92e-4e4abb24a933", + "resource_type": "volume" + } + ] + } + + resp = client.tags.assign_resources(tag_id="awesome", body=req) + security: + - bearer_auth: + - tag:create + delete: + operationId: tags_unassign_resources + summary: Untag a Resource + description: > + 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 + `:update` scopes. For example, + + to untag a Droplet, you must have `tag:delete` and `droplet:update`. + tags: + - Tags + parameters: + - $ref: '#/components/parameters/tag_id' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/tags_resource' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"resources":[{"resource_id":"9569411","resource_type":"droplet"},{"resource_id":"7555620","resource_type":"image"},{"resource_id":"3d80cb72-342b-4aaa-b92e-4e4abb24a933","resource_type":"volume"}]}' \ + "https://api.digitalocean.com/v2/tags/awesome/resources" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + untagResourcesRequest := &godo.UntagResourcesRequest{ + Resources: []Resource{{ID: "11457573", Type: "droplet"},{ID: "7555620", Type: "image"},{ID: "3d80cb72-342b-4aaa-b92e-4e4abb24a933", Type: "volume"}}, + } + client.Tags.UntagResources(ctx, "awesome", untagResourcesRequest) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.tags.untag_resources(name: 'awesome', resources: [{ + resource_id: '9569411', resource_type: 'droplet' },{ resource_id: + '7555620', resource_type: 'image' },{ resource_id: + '3d80cb72-342b-4aaa-b92e-4e4abb24a933', resource_type: 'volume' }]) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "resources": [ + { + "resource_id": "9569411", + "resource_type": "droplet" + }, + { + "resource_id": "7555620", + "resource_type": "image" + }, + { + "resource_id": "3d80cb72-342b-4aaa-b92e-4e4abb24a933", + "resource_type": "volume" + } + ] + } + + resp = client.tags.unassign_resources(tag_id="awesome", body=req) + security: + - bearer_auth: + - tag:delete + /v2/volumes: + get: + operationId: volumes_list + summary: List All Block Storage Volumes + description: >+ + To list all of the block storage volumes available on your account, send + a GET request to `/v2/volumes`. + + ## Filtering Results + + ### By Region + + The `region` may be provided as query parameter in order to restrict + results to volumes available in a specific region. For example: + `/v2/volumes?region=nyc1` + + ### By Name + + It is also possible to list volumes on your account that match a + specified name. To do so, send a GET request with the volume's name as a + query parameter to `/v2/volumes?name=$VOLUME_NAME`. + + **Note:** You can only create one volume per region with the same name. + + ### By Name and Region + + It is also possible to retrieve information about a block storage volume + by name. To do so, send a GET request with the volume's name and the + region slug for the region it is located in as query parameters to + `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. + + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_name' + - $ref: '#/components/parameters/parameters_region-2' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/volumes' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # List all volumes + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes?region=nyc1" + + # List volumes filtered by name + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes?name=example" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + volumes, _, err := client.Storage.ListVolumes(ctx, opt) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + volumes = client.volumes.all + volumes.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volumes.list(region="nyc3") + security: + - bearer_auth: + - api:read + - api:write + - block_storage:read + post: + operationId: volumes_create + summary: Create a New Block Storage Volume + description: >- + 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. + tags: + - Block Storage + requestBody: + required: true + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/volumes_ext4' + - $ref: '#/components/schemas/volumes_xfs' + examples: + ext4 volume: + value: + size_gigabytes: 10 + name: ext4-example + description: Block store for examples + region: nyc1 + filesystem_type: ext4 + filesystem_label: ext4_volume_01 + xfs volume: + value: + size_gigabytes: 10 + name: xfs_example + description: Block store for examples + region: nyc1 + filesystem_type: xfs + filesystem_label: xfs_volume01 + Volume from a snapshot: + value: + size_gigabytes: 10 + name: snapshot_example + snapshot_id: b0798135-fb76-11eb-946a-0a58ac146f33 + region: nyc1 + description: A new volume based on a snapshot + filesystem_type: ext4 + filesystem_label: ext4_volume_01 + responses: + '201': + $ref: '#/components/responses/volume' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"size_gigabytes":10, "name": "example", "description": "Block store for examples", "region": "nyc1", "filesystem_type": "ext4", "filesystem_label": "example"}' \ + "https://api.digitalocean.com/v2/volumes" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &VolumeCreateRequest{ + Region: "nyc1", + Name: "example", + Description: "Block store for examples", + SizeGigaBytes: 10, + } + + volume, _, err := client.Storage.CreateVolume(ctx, createRequest) + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + volume = DropletKit::Volume.new( + size_gigabytes: 10, + name: 'Example', + description: 'Block store for examples', + region: 'nyc1' + ) + client.volumes.create(volume) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "size_gigabytes": 10, + "name": "ext4-example", + "description": "Block store for examples", + "region": "nyc1", + "filesystem_type": "ext4", + "filesystem_label": "ext4_volume_01" + } + + resp = client.volumes.create(body=req) + security: + - bearer_auth: + - api:write + - block_storage:create + delete: + operationId: volumes_delete_byName + summary: Delete a Block Storage Volume by Name + description: >+ + Block storage volumes may also be deleted by name by sending a DELETE + request with the volume's **name** and the **region slug** for the + region it is located in as query parameters to + `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. + + No response body will be sent back, but the response code will indicate + success. Specifically, the response code will be a 204, which means that + the action was successful with no returned body data. + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_name' + - $ref: '#/components/parameters/parameters_region-2' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes?name=example®ion=nyc1" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volumes.delete_by_name(name="ext4-ex") + security: + - bearer_auth: + - block_storage:delete + - api:write + /v2/volumes/actions: + post: + operationId: volumeActions_post + summary: Initiate A Block Storage Action By Volume Name + description: > + 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 | + tags: + - Block Storage Actions + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + requestBody: + required: true + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/volume_action_post_attach' + - $ref: '#/components/schemas/volume_action_post_detach' + discriminator: + propertyName: type + mapping: + attach: '#/components/schemas/volume_action_post_attach' + detach: '#/components/schemas/volume_action_post_detach' + examples: + VolumeActionAttach: + value: + type: attach + volume_name: example + droplet_id: 11612190 + region: nyc1 + tags: + - aninterestingtag + VolumeActionDetach: + value: + type: detach + volume_name: example + droplet_id: 11612190 + region: nyc1 + responses: + '202': + $ref: '#/components/responses/volumeAction' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Attach a volume to a Droplet by name + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type": "attach", "volume_name": "example", "region": "nyc1", "droplet_id": "11612190","tags":["aninterestingtag"] }' \ + "https://api.digitalocean.com/v2/volumes/actions" + + # Remove a volume from a Droplet by name + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type": "detach", "droplet_id": "11612190", "volume_name": "example", "region": "nyc1"}' \ + "https://api.digitalocean.com/v2/volumes/actions" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "type": "attach", + "volume_name": "example", + "droplet_id": 11612190, + "region": "nyc1", + "tags": [ + "aninterestingtag" + ] + } + + resp = client.volume_actions.post(body=req) + security: + - bearer_auth: + - block_storage_action:create + - api:write + /v2/volumes/snapshots/{snapshot_id}: + get: + operationId: volumeSnapshots_get_byId + summary: Retrieve an Existing Volume Snapshot + description: >+ + 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`. + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_snapshot_id' + responses: + '200': + $ref: '#/components/responses/volumeSnapshot' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "big-data-snapshot1475261774" + } + + resp = client.volume_snapshots.get_by_id(snapshot_id="da3aa3a") + security: + - bearer_auth: + - block_storage_snapshot:read + delete: + operationId: volumeSnapshots_delete_byId + summary: Delete a Volume Snapshot + description: > + 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. + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_snapshot_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Storage.DeleteSnapshot(ctx, "82a48a18-873f-11e6-96bf-000f53315a41") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.snapshots.delete(id: "fbe805e8-866b-11e6-96bf-000f53315a41") + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "big-data-snapshot1475261774" + } + + resp = client.volume_snapshots.delete_by_id(snapshot_id="da3aa3a") + security: + - bearer_auth: + - block_storage_snapshot:delete + /v2/volumes/{volume_id}: + get: + operationId: volumes_get + summary: Retrieve an Existing Block Storage Volume + description: >+ + To show information about a block storage volume, send a GET request to + `/v2/volumes/$VOLUME_ID`. + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_id' + responses: + '200': + $ref: '#/components/responses/volume' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Retrieve an existing volume + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51" + + # Retrieve and existing volume by name + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes?name=example®ion=nyc1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + volume, _, err := client.Storage.GetVolume(ctx, "7724db7c-e098-11e5-b522-000f53304e51") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.volumes.find(id: '7724db7c-e098-11e5-b522-000f53304e51') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volumes.get(volume_id="7724db7c") + security: + - bearer_auth: + - block_storage:read + delete: + operationId: volumes_delete + summary: Delete a Block Storage Volume + description: >+ + 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. + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + _, err := client.Storage.DeleteVolume(ctx, "7724db7c-e098-11e5-b522-000f53304e51") + } + - lang: Ruby + source: |- + require 'droplet_kit' + token = ENV['DIGITALOCEAN_TOKEN'] + client = DropletKit::Client.new(access_token: token) + + client.volumes.delete(id: '7724db7c-e098-11e5-b522-000f53304e51') + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volumes.delete(volume_id="7724db7c") + security: + - bearer_auth: + - block_storage:delete + /v2/volumes/{volume_id}/actions: + get: + operationId: volumeActions_list + summary: List All Actions for a Volume + description: >+ + To retrieve all actions that have been executed on a volume, send a GET + request to `/v2/volumes/$VOLUME_ID/actions`. + + tags: + - Block Storage Actions + parameters: + - $ref: '#/components/parameters/volume_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/volumeActions' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + actions, _, err := client.StorageActions(ctx, "7724db7c-e098-11e5-b522-000f53304e51", opt) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + actions = client.volume.actions(id: + '7724db7c-e098-11e5-b522-000f53304e51') + + actions.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volume_actions.list(volume_id="7724db7c") + security: + - bearer_auth: + - block_storage_action:read + post: + operationId: volumeActions_post_byId + summary: Initiate A Block Storage Action By Volume Id + description: > + 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. + tags: + - Block Storage Actions + parameters: + - $ref: '#/components/parameters/volume_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + requestBody: + required: true + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/volume_action_post_attach' + - $ref: '#/components/schemas/volume_action_post_detach' + - $ref: '#/components/schemas/volume_action_post_resize' + discriminator: + propertyName: type + mapping: + attach: '#/components/schemas/volume_action_post_attach' + detach: '#/components/schemas/volume_action_post_detach' + resize: '#/components/schemas/volume_action_post_resize' + examples: + VolumeActionAttach: + value: + type: attach + droplet_id: 11612190 + region: nyc1 + tags: + - aninterestingtag + VolumeActionDetach: + value: + type: detach + droplet_id: 11612190 + region: nyc1 + VolumeActionResize: + value: + type: resize + size_gigabytes: 100 + region: nyc1 + responses: + '202': + $ref: '#/components/responses/volumeAction' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Attach a Volume to a Droplet by ID + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type": "attach", "droplet_id": 11612190, "region": "nyc1", "tags":["aninterestingtag"]}' \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions" + + # Remove a Volume from a Droplet by ID + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type": "detach", "droplet_id": "11612190", "region": "nyc1"}' \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions" + + # Resize a Volume + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"type":"resize","size_gigabytes": 100, "region":"nyc1"}' \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + // Attach a Volume to a Droplet by ID + action, _, err := client.StorageActions.Attach(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 11612190) + + // Remove a Volume from a Droplet by ID + // action, _, err := client.StorageActions.Detach(ctx, "7724db7c-e098-11e5-b522-000f53304e51") + + // Resize a Volume + // action, _, err := client.StorageActions.Resize(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 100, "nyc1") + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + # Attach a Volume to a Droplet by ID + + client.volume_actions.attach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', + droplet_id: 11612190, region: 'nyc1' + + + + # Remove a Volume from a Droplet by ID + + # + client.volume_actions.detach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', + droplet_id: 11612190, region: 'nyc1' + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "type": "attach", + "droplet_id": 11612190, + "region": "nyc1", + "tags": [ + "aninterestingtag" + ] + } + + + resp = client.volume_actions.post_by_id(volume_id="7724db7c", + body=req) + security: + - bearer_auth: + - block_storage_action:create + /v2/volumes/{volume_id}/actions/{action_id}: + get: + operationId: volumeActions_get + summary: Retrieve an Existing Volume Action + description: >+ + To retrieve the status of a volume action, send a GET request to + `/v2/volumes/$VOLUME_ID/actions/$ACTION_ID`. + + tags: + - Block Storage Actions + parameters: + - $ref: '#/components/parameters/volume_id' + - $ref: '#/components/parameters/action_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/volumeAction' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions/72531856" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + action, _, err := client.StorageActions.Get(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 72531856) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.volume.actions.find(volume_id: + '7724db7c-e098-11e5-b522-000f53304e51', id: 72531856) + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.volume_actions.get(volume_id="7724db7c") + security: + - bearer_auth: + - block_storage_action:read + /v2/volumes/{volume_id}/snapshots: + get: + operationId: volumeSnapshots_list + summary: List Snapshots for a Volume + description: >+ + To retrieve the snapshots that have been created from a volume, send a + GET request to `/v2/volumes/$VOLUME_ID/snapshots`. + + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/volumeSnapshots' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots?page=1&per_page=1" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opt := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + volumes, _, err := client.Storage.ListSnapshots(ctx, '82a48a18-873f-11e6-96bf-000f53315a41', opt) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + snapshots = client.volumes.snapshots(id: + '82a48a18-873f-11e6-96bf-000f53315a41') + + snapshots.each + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "big-data-snapshot1475261774" + } + + resp = client.volume_snapshots.list(snapshot_id="da3aa3a") + security: + - bearer_auth: + - block_storage_snapshot:read + post: + operationId: volumeSnapshots_create + summary: Create Snapshot from a Volume + description: >- + To create a snapshot from a volume, sent a POST request to + `/v2/volumes/$VOLUME_ID/snapshots`. + tags: + - Block Storage + parameters: + - $ref: '#/components/parameters/volume_id' + requestBody: + required: true + content: + application/json: + schema: + properties: + name: + type: string + description: A human-readable name for the volume snapshot. + example: big-data-snapshot1475261774 + tags: + $ref: '#/components/schemas/tags_array' + required: + - name + example: + name: big-data-snapshot1475261774 + responses: + '201': + $ref: '#/components/responses/volumeSnapshot' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"big-data-snapshot1475261774", "tags":["aninterestingtag"]}' \ + "https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + snapshot, _, err := client.Storage.CreateSnapshot(ctx, &godo.SnapshotCreateRequest{ + VolumeID: "82a48a18-873f-11e6-96bf-000f53315a41", + Name: "my snapshot", + Description: "my description", + Tags: []string{"one", "two"}, + }) + } + - lang: Ruby + source: >- + require 'droplet_kit' + + token = ENV['DIGITALOCEAN_TOKEN'] + + client = DropletKit::Client.new(access_token: token) + + + client.volumes.create_snapshot(id: + "82a48a18-873f-11e6-96bf-000f53315a41", name: + "big-data-snapshot1475261774") + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "big-data-snapshot1475261774" + } + + resp = client.volume_snapshots.create(volume_id="da3aa3a", body=req) + security: + - bearer_auth: + - block_storage_snapshot:create + /v2/vpcs: + get: + operationId: vpcs_list + summary: List All VPCs + description: >- + To list all of the VPCs on your account, send a GET request to + `/v2/vpcs`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_vpcs' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpcs" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + opts := &godo.ListOptions{ + Page: 1, + PerPage: 200, + } + + vpcs, _, err := client.VPCs.List(ctx, opts) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.vpcs.list() + security: + - bearer_auth: + - vpc:read + post: + operationId: vpcs_create + summary: Create a New VPC + description: > + 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. + tags: + - VPCs + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/vpc_updatable' + - $ref: '#/components/schemas/vpc_create' + required: + - name + - region + responses: + '201': + $ref: '#/components/responses/existing_vpc' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"my-new-vpc", "region":"nyc1", "ip_range": "10.10.10.0/24"}' \ + "https://api.digitalocean.com/v2/vpcs" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + createRequest := &godo.VPCCreateRequest{ + Name: "my-new-vpc", + RegionSlug: "nyc1", + IPRange: "10.10.10.0/24", + } + + vpc, _, err := client.VPCs.Create(ctx, createRequest) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "env.prod-vpc", + "description": "VPC for production environment", + "region": "nyc1", + "ip_range": "10.10.10.0/24" + } + + resp = client.vpcs.create(body=req) + security: + - bearer_auth: + - vpc:create + /v2/vpcs/{vpc_id}: + get: + operationId: vpcs_get + summary: Retrieve an Existing VPC + description: >- + To show information about an existing VPC, send a GET request to + `/v2/vpcs/$VPC_ID`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + responses: + '200': + $ref: '#/components/responses/existing_vpc' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + vpc, _, err := client.VPCs.Get(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.vpcs.get(vpc_id="e0fe0f4d") + security: + - bearer_auth: + - vpc:read + put: + operationId: vpcs_update + summary: Update a VPC + description: > + To update information about a VPC, send a PUT request to + `/v2/vpcs/$VPC_ID`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/vpc_updatable' + - $ref: '#/components/schemas/vpc_default' + required: + - name + responses: + '200': + $ref: '#/components/responses/existing_vpc' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"renamed-new-vpc", "description": "A new description", "default": true}' \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + updateRequest := &godo.VPCUpdateRequest{ + Name: "renamed-new-vpc", + Description: "A new description", + } + + _, _, err := client.VPCs.Update(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4", updateRequest) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "env.prod-vpc", + "description": "VPC for production environment", + "default": True + } + + resp = client.vpcs.update(vpc_id="8fdsfa", body=req) + security: + - bearer_auth: + - vpc:update + patch: + operationId: vpcs_patch + summary: Partially Update a VPC + description: | + To update a subset of information about a VPC, send a PATCH request to + `/v2/vpcs/$VPC_ID`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + requestBody: + required: true + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/vpc_updatable' + - $ref: '#/components/schemas/vpc_default' + responses: + '200': + $ref: '#/components/responses/existing_vpc' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"description": "An updated description"}' \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + vpcDesc := "An updated description" + _, _, err := client.VPCs.Set(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4", godo.VPCSetDescription(vpcDesc)) + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "env.prod-vpc", + "description": "VPC for production environment", + "default": True + } + + resp = client.vpcs.patch(vpc_id="8fdsfa", body=req) + security: + - bearer_auth: + - vpc:update + delete: + operationId: vpcs_delete + summary: Delete a VPC + description: > + 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. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpcs/e0fe0f4d-596a-465e-a902-571ce57b79fa" + - lang: Go + source: |- + import ( + "context" + "os" + + "github.com/digitalocean/godo" + ) + + func main() { + token := os.Getenv("DIGITALOCEAN_TOKEN") + + client := godo.NewFromToken(token) + ctx := context.TODO() + + resp, err := client.VPCs.Delete(ctx, "5a4981aa-9653-4bd1-bef5-d6bff52042e4") + } + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.vpcs.delete(vpc_id="e0fe0f4d") + security: + - bearer_auth: + - vpc:delete + /v2/vpcs/{vpc_id}/members: + get: + operationId: vpcs_list_members + summary: List the Member Resources of a VPC + description: > + 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`). + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + - $ref: '#/components/parameters/vpc_resource_type' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/vpc_members' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4/members" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.vpcs.list_members(vpc_id="e0fe0f4d") + security: + - bearer_auth: + - vpc:read + /v2/vpcs/{vpc_id}/peerings: + get: + operationId: vpcs_list_peerings + summary: List the Peerings of a VPC + description: | + To list all of a VPC's peerings, send a GET request to + `/v2/vpcs/$VPC_ID/peerings`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/vpc_peerings' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4/peerings" + security: + - bearer_auth: + - vpc_peering:read + post: + operationId: vpcs_create_peerings + summary: Create a Peering with a VPC + description: | + To create a new VPC peering for a given VPC, send a POST request to + `/v2/vpcs/$VPC_ID/peerings`. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + pattern: ^[a-zA-Z0-9\-\.]+$ + example: nyc1-blr1-peering + description: >- + The name of the VPC peering. Must be unique and may only + contain alphanumeric characters, dashes, and periods. + vpc_id: + type: string + format: uuid + example: c140286f-e6ce-4131-8b7b-df4590ce8d6a + description: The ID of the VPC to peer with. + required: + - name + - vpc_id + responses: + '202': + $ref: '#/components/responses/vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"example-vpc-peering", "vpc_id": "e51aed59-3bb1-4a6a-8de0-9d1329e9c997"}' \ + "https://api.digitalocean.com/v2/vpcs/5a4981aa-9653-4bd1-bef5-d6bff52042e4/peerings" + security: + - bearer_auth: + - vpc_peering:create + /v2/vpcs/{vpc_id}/peerings/{vpc_peering_id}: + patch: + operationId: vpcs_patch_peerings + summary: Update a VPC Peering + description: > + 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. + tags: + - VPCs + parameters: + - $ref: '#/components/parameters/vpc_id' + - $ref: '#/components/parameters/vpc_peering_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/vpc_peering_updatable' + required: + - name + responses: + '200': + $ref: '#/components/responses/vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "renamed-my-first-vpc-peering"}' \ + "https://api.digitalocean.com/v2/vpcs/997615ce-132d-4bae-9270-9ee21b395e5d/peerings/6b5c619c-359c-44ca-87e2-47e98170c01d" + security: + - bearer_auth: + - vpc_peering:update + /v2/vpc_peerings: + get: + operationId: vpcPeerings_list + summary: List All VPC Peerings + description: >- + To list all of the VPC peerings on your account, send a GET request to + `/v2/vpc_peerings`. + tags: + - VPC Peerings + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/parameters_region-2' + responses: + '200': + $ref: '#/components/responses/all_vpc_peerings' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_peerings?region=sfo3&page=1&per_page=20" + security: + - bearer_auth: + - vpc_peering:read + post: + operationId: vpcPeerings_create + summary: Create a New VPC Peering + description: > + 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. + tags: + - VPC Peerings + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/vpc_peering_updatable' + - $ref: '#/components/schemas/vpc_peering_create' + required: + - name + - vpc_ids + responses: + '202': + $ref: '#/components/responses/provisioning_vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name": "my-first-vpc-peering", "vpc_ids": [ "997615ce-132d-4bae-9270-9ee21b395e5d", "e51aed59-3bb1-4a6a-8de0-9d1329e9c997"]}' \ + "https://api.digitalocean.com/v2/vpc_peerings" + security: + - bearer_auth: + - vpc_peering:create + /v2/vpc_peerings/{vpc_peering_id}: + get: + operationId: vpcPeerings_get + summary: Retrieve an Existing VPC Peering + description: > + To show information about an existing VPC Peering, send a GET request to + `/v2/vpc_peerings/$VPC_PEERING_ID`. + tags: + - VPC Peerings + parameters: + - $ref: '#/components/parameters/vpc_peering_id' + responses: + '200': + $ref: '#/components/responses/active_vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_peerings/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + security: + - bearer_auth: + - vpc_peering:read + patch: + operationId: vpcPeerings_patch + summary: Update a VPC peering + description: > + 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. + tags: + - VPC Peerings + parameters: + - $ref: '#/components/parameters/vpc_peering_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/vpc_peering_updatable' + required: + - name + responses: + '200': + $ref: '#/components/responses/active_vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"renamed-vpc-peering"}' \ + "https://api.digitalocean.com/v2/vpc_peerings/5a4981aa-9653-4bd1-bef5-d6bff52042e4" + security: + - bearer_auth: + - vpc_peering:update + delete: + operationId: vpcPeerings_delete + summary: Delete a VPC peering + description: > + To delete a VPC peering, send a DELETE request to + `/v2/vpc_peerings/$VPC_PEERING_ID`. + tags: + - VPC Peerings + parameters: + - $ref: '#/components/parameters/vpc_peering_id' + responses: + '202': + $ref: '#/components/responses/deleting_vpc_peering' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_peerings/6b5c619c-359c-44ca-87e2-47e98170c01d" + security: + - bearer_auth: + - vpc_peering:delete + /v2/vpc_nat_gateways: + get: + operationId: vpcnatgateways_list + summary: List All VPC NAT Gateways + description: > + 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. + tags: + - VPC NAT Gateways + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + - $ref: '#/components/parameters/vpc_nat_gateway_state' + - $ref: '#/components/parameters/vpc_nat_gateway_region' + - $ref: '#/components/parameters/vpc_nat_gateway_type' + - $ref: '#/components/parameters/vpc_nat_gateway_name' + responses: + '200': + $ref: '#/components/responses/vpc_nat_gateways' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_nat_gateways?page=1&per_page=10" + security: + - bearer_auth: + - nat_gateway:read + post: + operationId: vpcnatgateways_create + summary: Create a New VPC NAT Gateway + description: > + 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. + tags: + - VPC NAT Gateways + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/vpc_nat_gateway_create' + examples: + VPC NAT Gateway Create Request: + $ref: '#/components/examples/vpc_nat_gateway_create_request' + responses: + '202': + $ref: '#/components/responses/vpc_nat_gateway_create' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "test-vpc-nat-gateways", + "type": "PUBLIC", + "region": "tor1", + "size": 1, + "vpcs": [ + { + "vpc_uuid": "0eb1752f-807b-4562-a077-8018e13ab1fb", + "default_gateway": true + } + ], + "udp_timeout_seconds": 30, + "icmp_timeout_seconds": 30, + "tcp_timeout_seconds": 30 + }' \ + "https://api.digitalocean.com/v2/vpc_nat_gateways" + security: + - bearer_auth: + - nat_gateway:create + /v2/vpc_nat_gateways/{id}: + get: + operationId: vpcnatgateways_get + summary: Retrieve an Existing VPC NAT Gateway + description: > + To show information about an individual VPC NAT gateway, send a GET + request to + + `/v2/vpc_nat_gateways/$VPC_NAT_GATEWAY_ID`. + tags: + - VPC NAT Gateways + parameters: + - $ref: '#/components/parameters/vpc_nat_gateway_id' + responses: + '200': + $ref: '#/components/responses/vpc_nat_gateway' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_nat_gateways/a21d90fe-dc75-4097-993a-2dc7d1a8a438" + security: + - bearer_auth: + - nat_gateway:read + put: + operationId: vpcnatgateways_update + summary: Update VPC NAT Gateway + description: > + 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. + tags: + - VPC NAT Gateways + parameters: + - $ref: '#/components/parameters/vpc_nat_gateway_id' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/vpc_nat_gateway_update' + examples: + VPC NAT Gateway Update Request: + $ref: '#/components/examples/vpc_nat_gateway_update_request' + responses: + '200': + $ref: '#/components/responses/vpc_nat_gateway_update' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{ + "name": "test-vpc-nat-gateways", + "size": 2, + "vpcs": [ + { + "vpc_uuid": "0eb1752f-807b-4562-a077-8018e13ab1fb", + "default_gateway": false + } + ], + "udp_timeout_seconds": 30, + "icmp_timeout_seconds": 30, + "tcp_timeout_seconds": 300 + }' \ + "https://api.digitalocean.com/v2/vpc_nat_gateways/a21d90fe-dc75-4097-993a-2dc7d1a8a438" + security: + - bearer_auth: + - nat_gateway:update + delete: + operationId: vpcnatgateways_delete + summary: Delete VPC NAT Gateway + description: > + 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. + tags: + - VPC NAT Gateways + parameters: + - $ref: '#/components/parameters/vpc_nat_gateway_id' + responses: + '202': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/vpc_nat_gateways/a21d90fe-dc75-4097-993a-2dc7d1a8a438" + security: + - bearer_auth: + - nat_gateway:delete + /v2/uptime/checks: + get: + operationId: uptime_list_checks + summary: List All Checks + description: >- + To list all of the Uptime checks on your account, send a GET request to + `/v2/uptime/checks`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_checks' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.uptime.checks_list() + security: + - bearer_auth: + - uptime:read + post: + operationId: uptime_create_check + summary: Create a New Check + description: > + To create an Uptime check, send a POST request to `/v2/uptime/checks` + specifying the attributes + + in the table below in the JSON body. + tags: + - Uptime + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/check_updatable' + required: + - name + - method + - target + - regions + - type + - enabled + responses: + '201': + $ref: '#/components/responses/existing_check' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"Landing page check","type":"https","target":"https://www.landingpage.com","regions":["us_east","eu_west"],"enabled":true}' \ + "https://api.digitalocean.com/v2/uptime/checks" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "Landing page check", + "type": "https", + "target": "https://www.landingpage.com", + "regions": [ + "us_east", + "eu_west" + ], + "enabled": True + } + + resp = client.uptime.check_create(body=req) + security: + - bearer_auth: + - uptime:create + /v2/uptime/checks/{check_id}: + get: + operationId: uptime_get_check + summary: Retrieve an Existing Check + description: >- + To show information about an existing check, send a GET request to + `/v2/uptime/checks/$CHECK_ID`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + responses: + '200': + $ref: '#/components/responses/existing_check' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.uptime.check_get(check_id="fd9dfa") + security: + - bearer_auth: + - uptime:read + put: + operationId: uptime_update_check + summary: Update a Check + description: > + To update the settings of an Uptime check, send a PUT request to + `/v2/uptime/checks/$CHECK_ID`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/check_updatable' + responses: + '200': + $ref: '#/components/responses/existing_check' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"Landing page check","type":"https","target":"https://www.newlandingpage.com","regions":["us_east","eu_west"],"enabled":true}' \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "Landing page check", + "type": "https", + "target": "https://www.landingpage.com", + "regions": [ + "us_east", + "eu_west" + ], + "enabled": True + } + + resp = client.uptime.check_update(check_id="fd9fda", body=req) + security: + - bearer_auth: + - uptime:update + delete: + operationId: uptime_delete_check + summary: Delete a Check + description: > + 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. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.uptime.check_delete(check_id="fd9dfa") + security: + - bearer_auth: + - uptime:delete + /v2/uptime/checks/{check_id}/state: + get: + operationId: uptime_get_checkState + summary: Retrieve Check State + description: >- + To show information about an existing check's state, send a GET request + to `/v2/uptime/checks/$CHECK_ID/state`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + responses: + '200': + $ref: '#/components/responses/existing_check_state' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/state" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.uptime.check_state_get(check_id="fd9fda") + security: + - bearer_auth: + - uptime:read + /v2/uptime/checks/{check_id}/alerts: + get: + operationId: uptime_list_alerts + summary: List All Alerts + description: >- + To list all of the alerts for an Uptime check, send a GET request to + `/v2/uptime/checks/$CHECK_ID/alerts`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + - $ref: '#/components/parameters/per_page' + - $ref: '#/components/parameters/page' + responses: + '200': + $ref: '#/components/responses/all_alerts' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/alerts" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.uptime.check_alerts_list(check_id="4de7ac8b") + security: + - bearer_auth: + - uptime:read + post: + operationId: uptime_create_alert + summary: Create a New Alert + description: > + 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. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + requestBody: + required: true + description: > + The ''type'' field dictates the type of alert, and hence what type of + value to pass into the threshold property. + + Type | Description | Threshold Value + + -----|-------------|-------------------- + + `latency` | alerts on the response latency | milliseconds + + `down` | alerts on a target registering as down in any region | N/A + (Not required) + + `down_global` | alerts on a target registering as down globally | N/A + (Not required) + + `ssl_expiry` | alerts on a SSL certificate expiring within $threshold + days | days + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/alert' + required: + - name + - type + - notifications + - period + responses: + '201': + $ref: '#/components/responses/existing_alert' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"Landing page degraded performance","type":"latency","threshold":300,"comparison":"greater_than","notifications":{"email":["bob@example.com"],"slack":[{"channel":"Production Alerts","url":"https://example.invalid/redacted-slack-webhook"}]},"period":"2m"}' \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/alerts" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + req = { + "name": "Landing page degraded performance", + "type": "latency", + "threshold": 300, + "comparison": "greater_than", + "notifications": { + "email": [ + "bob@example.com" + ], + "slack": [ + { + "channel": "Production Alerts", + "url": "https://example.invalid/redacted-slack-webhook" + } + ] + }, + "period": "2m" + } + + resp = client.uptime.alert_create(check_id="4de7ac8b", body=req) + security: + - bearer_auth: + - uptime:create + - uptime:update + /v2/uptime/checks/{check_id}/alerts/{alert_id}: + get: + operationId: uptime_get_alert + summary: Retrieve an Existing Alert + description: >- + To show information about an existing alert, send a GET request to + `/v2/uptime/checks/$CHECK_ID/alerts/$ALERT_ID`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + - $ref: '#/components/parameters/parameters_alert_id' + responses: + '200': + $ref: '#/components/responses/existing_alert' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/alerts/{alert_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.uptime.alert_get(check_id="4de7ac8b", + alert_id="da9da9") + security: + - bearer_auth: + - uptime:read + put: + operationId: uptime_update_alert + summary: Update an Alert + description: > + To update the settings of an Uptime alert, send a PUT request to + `/v2/uptime/checks/$CHECK_ID/alerts/$ALERT_ID`. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + - $ref: '#/components/parameters/parameters_alert_id' + requestBody: + required: true + content: + application/json: + schema: + type: object + allOf: + - $ref: '#/components/schemas/alert_updatable' + required: + - name + - type + - notifications + - period + responses: + '200': + $ref: '#/components/responses/existing_alert' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"name":"Landing page down globally","type":"down_global","notifications":{"email":["bob@example.com"],"slack":[{"channel":"Production Alerts","url":"https://example.invalid/redacted-slack-webhook"}]},"period":"2m"}' \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/alerts/{alert_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + req = { + "name": "Landing page degraded performance", + "type": "latency", + "threshold": 300, + "comparison": "greater_than", + "notifications": { + "email": [ + "bob@example.com" + ], + "slack": [ + { + "channel": "Production Alerts", + "url": "https://example.invalid/redacted-slack-webhook" + } + ] + }, + "period": "2m" + } + + + resp = client.uptime.alert_update(check_id="4de7ac8b", + alert_id="da9da9", body=req) + security: + - bearer_auth: + - uptime:update + delete: + operationId: uptime_delete_alert + summary: Delete an Alert + description: > + 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. + tags: + - Uptime + parameters: + - $ref: '#/components/parameters/check_id' + - $ref: '#/components/parameters/parameters_alert_id' + responses: + '204': + $ref: '#/components/responses/no_content' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/uptime/checks/{check_id}/alerts/{alert_id}" + - lang: Python + source: >- + import os + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + resp = client.uptime.alert_delete(check_id="4de7ac8b", + alert_id="da9da9") + security: + - bearer_auth: + - uptime:delete + - uptime:update + /v2/gen-ai/agents: + get: + description: To list all agents, send a GET request to `/v2/gen-ai/agents`. + operationId: genai_list_agents + parameters: + - description: Only list agents that are deployed. + example: true + in: query + name: only_deployed + schema: + type: boolean + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentsOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Agents + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents" + post: + description: >- + 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. + operationId: genai_create_agent + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAgentInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents" \ + -d '{ + "name": "api-create", + "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4", + "instruction": "be a weather reporter", + "description": "weather-agent", + "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e", + "tags": [ + "tag1" + ], + "region": "tor1", + "knowledge_base_uuid": [ + "9758a232-b351-11ef-bf8f-4e013e2ddde4" + ] + }' + /v2/gen-ai/agents/{agent_uuid}/api_keys: + get: + description: >- + To list all agent API keys, send a GET request to + `/v2/gen-ai/agents/{agent_uuid}/api_keys`. + operationId: genai_list_agent_api_keys + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentAPIKeysOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Agent API Keys + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/api_keys" + post: + description: >- + To create an agent API key, send a POST request to + `/v2/gen-ai/agents/{agent_uuid}/api_keys`. + operationId: genai_create_agent_api_key + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAgentAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAgentAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create an Agent API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "name": "test-key" + }' + /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}: + put: + description: >- + To update an agent API key, send a PUT request to + `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`. + operationId: genai_update_agent_api_key + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update API Key for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", + "name": "test-key2" + }' + delete: + description: >- + To delete an API key for an agent, send a DELETE request to + `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}`. + operationId: genai_delete_agent_api_key + parameters: + - description: A unique identifier for your agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: API key for an agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteAgentAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: 'Delete API Key for an Agent ' + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + /v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate: + put: + description: >- + To regenerate an agent API key, send a PUT request to + `/v2/gen-ai/agents/{agent_uuid}/api_keys/{api_key_uuid}/regenerate`. + operationId: genai_regenerate_agent_api_key + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiRegenerateAgentAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Regenerate API Key for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate" + /v2/gen-ai/agents/{agent_uuid}/functions: + post: + description: >- + To create a function route for an agent, send a POST request to + `/v2/gen-ai/agents/{agent_uuid}/functions`. + operationId: genai_attach_agent_function + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentFunctionInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentFunctionOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Add Function Route to an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "function_name": "funzip", + "description": "Use when you need the zipcode for a city", + "input_schema": { + "city": { + "description": "the city you want a zipcode for", + "required": true, + "type": "string" + } + }, + "output_schema": { + "zip_code": { + "description": "The zipcode of the desired city", + "type": "number" + } + }, + "faas_namespace": "fn-2014dc98-faa1-45f4-ba1f-59910cb3d399", + "faas_name": "default/get-zipcode" + }' + + /v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}: + put: + description: >- + To update the function route, send a PUT request to + `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`. + operationId: genai_update_agent_function + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: Function id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: function_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentFunctionInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentFunctionOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update Function Route for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/functions/b00e74f6-985c-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "function_uuid": "6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4", + "function_name": "func-rename" + }' + delete: + description: >- + To delete a function route from an agent, send a DELETE request to + `/v2/gen-ai/agents/{agent_uuid}/functions/{function_uuid}`. + operationId: genai_detach_agent_function + parameters: + - description: The id of the agent the function route belongs to. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: >- + The function route to be destroyed. This does not destroy the + function itself. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: function_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUnlinkAgentFunctionOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete Function Route for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/functions/6cc5cda5-9ac3-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/agents/{agent_uuid}/guardrails: + post: + description: >- + To attach guardrails to an agent, send a POST request to + `/v2/gen-ai/agents/{agent_uuid}/guardrails`. + operationId: genai_attach_agent_guardrails + parameters: + - description: The UUID of the agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentGuardrailsInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentGuardrailOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Attach Guardrails to an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b05c/guardrails" \ + -d '{ + "guardrails": [ + { + "guardrail_uuid": "69bcc61c-2bb2-49fd-b6ed-7c1bd73d6442", + "priority": 1 + }, + { + "guardrail_uuid": "dc72b12b-bd45-46c9-bca1-00a6624aac3a", + "priority": 2 + } + ] + }' + /v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}: + delete: + description: >- + To detach a guardrail from an agent, send a DELETE request to + `/v2/gen-ai/agents/{agent_uuid}/guardrails/{guardrail_uuid}`. + operationId: genai_detach_agent_guardrail + parameters: + - description: The UUID of the agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: The UUID of the guardrail to detach. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: guardrail_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUnlinkAgentGuardrailOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Detach a Guardrail from an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1c8be326-00fe-11f1-b542-ca68c578b04c/guardrails/69bcc61c-2bb2-49fd-b6ed-7c1bd73d6572" + /v2/gen-ai/agents/{agent_uuid}/knowledge_bases: + post: + description: >- + To attach knowledge bases to an agent, send a POST request to + `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases` + operationId: genai_attach_knowledge_bases + parameters: + - description: A unique identifier for an agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Attach Knowledge Bases to an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "knowledge_base_uuids": [ + "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4", + "683c3100-7c18-4c94-aea4-5ac5875cc87c", + "4887a78b-74af-46b3-98f4-451a48f9cc5e" + ] + }' + /v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}: + post: + description: >- + To attach a knowledge base to an agent, send a POST request to + `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}` + operationId: genai_attach_knowledge_base + parameters: + - description: A unique identifier for an agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: A unique identifier for a knowledge base. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Attach Knowledge Base to an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "agent_uuid": "9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4" + }' + + + delete: + description: >- + To detach a knowledge base from an agent, send a DELETE request to + `/v2/gen-ai/agents/{agent_uuid}/knowledge_bases/{knowledge_base_uuid}`. + operationId: genai_detach_knowledge_base + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: agent_uuid + required: true + schema: + type: string + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUnlinkKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Detach Knowledge Base from an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/agents/{parent_agent_uuid}/child_agents/{child_agent_uuid}: + post: + description: >- + 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}`. + operationId: genai_attach_agent + parameters: + - description: A unique identifier for the parent agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: parent_agent_uuid + required: true + schema: + type: string + - description: Routed agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: child_agent_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiLinkAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Add Agent Route to an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/6a09d603-b68d-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "child_agent_uuid": "6a09d603-b68d-11ef-bf8f-4e013e2ddde4", + "route_name": "route-token-stat", + "if_case": "for any token related statistics, use this route" + }' + + put: + description: >- + 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}`. + operationId: genai_update_attached_agent + parameters: + - description: A unique identifier for the parent agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: parent_agent_uuid + required: true + schema: + type: string + - description: Routed agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: child_agent_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateLinkedAgentInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateLinkedAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update Agent Route for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/child_agents/18c4c90c-cc40-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "parent_agent_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "child_agent_uuid": "18c4c90c-cc40-11ef-bf8f-4e013e2ddde4", + "route_name": "route-rename-api", + "if_case": "if any token related statistics, use this route only", + "uuid":"a22d2004-bbaa-11ef-bf8f-4e013e2ddde4" + }' + delete: + description: >- + 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}`. + operationId: genai_detach_agent + parameters: + - description: Pagent agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: parent_agent_uuid + required: true + schema: + type: string + - description: Routed agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: child_agent_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUnlinkAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete Agent Route for an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/ff47f5b7-96e5-11ef-bf8f-4e013e2ddde4/child_agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/agents/{uuid}: + get: + description: >- + To retrieve details of an agent, GET request to + `/v2/gen-ai/agents/{uuid}`. The response body is a JSON object + containing the agent. + operationId: genai_get_agent + parameters: + - description: Unique agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve an Existing Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" + + put: + description: >- + To update an agent, send a PUT request to `/v2/gen-ai/agents/{uuid}`. + The response body is a JSON object containing the agent. + operationId: genai_update_agent + parameters: + - description: Unique agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "name": "rename-agent-api", + "instruction": "be a weather reporter and act like you are a pro", + "description": "weather-agent2", + "model_uuid": "95ea6652-75ed-11ef-bf8f-4e013e2ddde4", + "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e", + "tags": [ + "tag2" + ], + "k": 5, + "temperature": 1, + "top_p": 1, + "max_tokens": 250 + }' + delete: + description: To delete an agent, send a DELETE request to `/v2/gen-ai/agents/{uuid}`. + operationId: genai_delete_agent + parameters: + - description: Unique agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteAgentOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete an Agent + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agent/5581a586-a745-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/agents/{uuid}/child_agents: + get: + description: >- + To view agent routes for an agent, send a GET requtest to + `/v2/gen-ai/agents/{uuid}/child_agents`. + operationId: genai_get_agent_children + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetChildrenOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: View Agent Routes + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/child_agents" + /v2/gen-ai/agents/{uuid}/deployment_visibility: + put: + description: >- + 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`. + operationId: genai_update_agent_deployment_visibility + parameters: + - description: Unique id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiUpdateAgentDeploymentVisibilityInputPublic + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAgentDeploymentVisbilityOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update Agent Status + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/deployment_visibility" \ + -d '{ + "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "visibility": "VISIBILITY_PUBLIC" + }' + /v2/gen-ai/agents/{uuid}/usage: + get: + description: >- + 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. + operationId: genai_get_agent_usage + parameters: + - description: Agent id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + - description: Return all usage data from this date. + example: '"example string"' + in: query + name: start + schema: + type: string + - description: >- + Return all usage data up to this date, if omitted, will return up to + the current date. + example: '"example string"' + in: query + name: stop + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetAgentUsageOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Agent Usage + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/genai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/usage?start=2024-01-01T00:00:00Z&stop=2024-01-31T23:59:59Z" + /v2/gen-ai/agents/{uuid}/versions: + get: + description: >- + To list all agent versions, send a GET request to + `/v2/gen-ai/agents/{uuid}/versions`. + operationId: genai_list_agent_versions + parameters: + - description: Agent uuid + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentVersionsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Agent Versions + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/c441bf77-81d6-11ef-bf8f-4e013e2ddde4/versions" + put: + description: >- + To update to a specific agent version, send a PUT request to + `/v2/gen-ai/agents/{uuid}/versions`. + operationId: genai_rollback_to_agent_version + parameters: + - description: Agent unique identifier + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiRollbackToAgentVersionInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiRollbackToAgentVersionOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Rollback to Agent Version + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/agents/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/versions" \ + -d '{ + "uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "version_hash": "c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73" + }' + /v2/gen-ai/anthropic/keys: + get: + description: >- + To list all Anthropic API keys, send a GET request to + `/v2/gen-ai/anthropic/keys`. + operationId: genai_list_anthropic_api_keys + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAnthropicAPIKeysOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Anthropic API Keys + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys" + post: + description: >- + To create an Anthropic API key, send a POST request to + `/v2/gen-ai/anthropic/keys`. + operationId: genai_create_anthropic_api_key + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAnthropicAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateAnthropicAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Anthropic API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys" \ + -d '{ + "api_key": "sk-ant-12345678901234567890123456789012", + "name": "test-key" + }' + /v2/gen-ai/anthropic/keys/{api_key_uuid}: + get: + description: >- + To retrieve details of an Anthropic API key, send a GET request to + `/v2/gen-ai/anthropic/keys/{api_key_uuid}`. + operationId: genai_get_anthropic_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetAnthropicAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Anthropic API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + put: + description: >- + To update an Anthropic API key, send a PUT request to + `/v2/gen-ai/anthropic/keys/{api_key_uuid}`. + operationId: genai_update_anthropic_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAnthropicAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateAnthropicAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update Anthropic API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ + -d '{ + "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", + "name": "test-key2" + }' + delete: + description: >- + To delete an Anthropic API key, send a DELETE request to + `/v2/gen-ai/anthropic/keys/{api_key_uuid}`. + operationId: genai_delete_anthropic_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteAnthropicAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete Anthropic API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + /v2/gen-ai/anthropic/keys/{uuid}/agents: + get: + description: List Agents by Anthropic Key. + operationId: genai_list_agents_by_anthropic_key + parameters: + - description: Unique ID of Anthropic key + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentsByAnthropicKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List agents by Anthropic key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/anthropic/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" + /v2/gen-ai/custom_models: + get: + description: To list custom models, send a GET request to `/v2/gen-ai/custom_models`. + operationId: genai_list_custom_models + parameters: + - description: Page number for pagination. + example: 1 + in: query + name: page + schema: + type: integer + - description: Number of items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + - description: Filter by model status. + example: STATUS_UNSPECIFIED + in: query + name: status + schema: + default: STATUS_UNSPECIFIED + enum: + - STATUS_UNSPECIFIED + - STATUS_IMPORTING + - STATUS_READY + - STATUS_FAILED + - STATUS_DELETED + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListCustomModelsOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Custom Models + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/custom_models" \ + /v2/gen-ai/custom_models/import: + post: + description: >- + To import a custom model, send a POST request to + `/v2/gen-ai/custom_models/import`. + operationId: genai_import_custom_model + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiImportCustomModelInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiImportCustomModelOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Import Custom Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/custom_models/import" \ + -d '{ + "name": "mymodelssss", + "source_type": "SOURCE_TYPE_HUGGINGFACE", + "source_ref": { + "repo_id": "Qwen/Qwen3-1.7B", + "access_type": "ACCESS_TYPE_PUBLIC" + }, + "description": "qwen base model", + "preferred_gpu_region": null, + "accept_terms_and_conditions": true, + "tags": { + "tags": ["base-model"] + } + }' + /v2/gen-ai/custom_models/{uuid}: + get: + description: >- + To retrieve details of a custom model, send a GET request to + `/v2/gen-ai/custom_models/{uuid}`. + operationId: genai_get_custom_model + parameters: + - description: UUID of the custom model to retrieve + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetCustomModelOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Custom Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13e07-1e4f-1325-b542-ca68c578b04b" + delete: + description: >- + To delete a custom model, send a DELETE request to + `/v2/genai/custom_models/{uuid}`. + operationId: genai_delete_custom_model + parameters: + - description: UUID of the custom model to delete + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteCustomModelOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete Custom Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + --header "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13e07-1e4f-1325-b542-ca68c578b04b" + /v2/gen-ai/custom_models/{uuid}/metadata: + patch: + description: >- + To update custom model metadata, send a PATCH request to + `/v2/gen-ai/custom_models/{uuid}/metadata`. + operationId: genai_update_custom_model_metadata + parameters: + - description: UUID of the custom model to update + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateCustomModelMetadataInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateCustomModelMetadataOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:default + summary: Update Custom Model Metadata + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PATCH \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/custom_models/11f13d93-a879-c342-b542-ca68c578b04b/metadata" \ + -d '{ + "description": "finetuned model with olympiad math data", + "tags": { + "tags": ["finetuned", "new"] + } + }' + /v2/gen-ai/evaluation_datasets: + post: + description: >- + To create an evaluation dataset, send a POST request to + `/v2/gen-ai/evaluation_datasets`. + operationId: genai_create_evaluation_dataset + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateEvaluationDatasetInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateEvaluationDatasetOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Evaluation Dataset + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets" \ + -d '{ + "name": "dataset.csv", + "file_upload_dataset": { + "original_file_name": "dataset.csv", + "stored_object_key": "123abc", + "size_in_bytes": 255 + } + }' + /v2/gen-ai/evaluation_datasets/file_upload_presigned_urls: + post: + description: >- + To create presigned URLs for evaluation dataset file upload, send a POST + request to `/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls`. + operationId: genai_create_evaluation_dataset_file_upload_presigned_urls + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateDataSourceFileUploadPresignedUrlsInputPublic + responses: + '200': + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateDataSourceFileUploadPresignedUrlsOutput + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Presigned URLs for Evaluation Dataset File Upload + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/file_upload_presigned_urls" \ + -d '{ + "files": [{ + "file_name": "dataset.csv", + "file_size": 2048 + }] + }' + /v2/gen-ai/evaluation_datasets/{dataset_uuid}/download_url: + get: + description: >- + To get a presigned download URL for an evaluation dataset, send a GET + request to `/v2/genai/evaluation_datasets/{dataset_uuid}/download_url`. + operationId: genai_get_evaluation_dataset_download_url + parameters: + - description: UUID of the evaluation dataset. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: dataset_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetEvaluationDatasetDownloadURLOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Download URL for Evaluation Dataset + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_datasets/123e4567-e89b-12d3-a456-426614174000/download_url" + /v2/gen-ai/evaluation_metrics: + get: + description: >- + To list all evaluation metrics, send a GET request to + `/v2/gen-ai/evaluation_metrics`. + operationId: genai_list_evaluation_metrics + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListEvaluationMetricsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Evaluation Metrics + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_metrics" + /v2/gen-ai/evaluation_runs: + post: + description: >- + To run an evaluation test case, send a POST request to + `/v2/gen-ai/evaluation_runs`. + operationId: genai_run_evaluation_test_case + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiRunEvaluationTestCaseInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiRunEvaluationTestCaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Run an Evaluation Test Case + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_runs" \ + -d '{ + "test_case_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "agent_uuids": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], + "run_name": "My Evaluation Run", + }' + /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}: + get: + description: >- + To retrive information about an existing evaluation run, send a GET + request to `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}`. + operationId: genai_get_evaluation_run + parameters: + - description: Evaluation run UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: evaluation_run_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetEvaluationRunOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Information About an Existing Evaluation Run + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results: + get: + description: >- + To retrieve results of an evaluation run, send a GET request to + `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results`. + operationId: genai_get_evaluation_run_results + parameters: + - description: Evaluation run UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: evaluation_run_uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetEvaluationRunResultsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Results of an Evaluation Run + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results" + /v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}: + get: + description: >- + To retrieve results of an evaluation run, send a GET request to + `/v2/gen-ai/evaluation_runs/{evaluation_run_uuid}/results/{prompt_id}`. + operationId: genai_get_evaluation_run_prompt_results + parameters: + - description: Evaluation run UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: evaluation_run_uuid + required: true + schema: + type: string + - description: Prompt ID to get results for. + example: 1 + in: path + name: prompt_id + required: true + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetEvaluationRunPromptResultsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Results of an Evaluation Run Prompt + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_runs/9758a232-b351-11ef-bf8f-4e013e2ddde4/results/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/evaluation_test_cases: + get: + description: >- + To list all evaluation test cases, send a GET request to + `/v2/gen-ai/evaluation_test_cases`. + operationId: genai_list_evaluation_test_cases + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListEvaluationTestCasesOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Evaluation Test Cases + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases" + post: + description: >- + To create an evaluation test-case send a POST request to + `/v2/gen-ai/evaluation_test_cases`. + operationId: genai_create_evaluation_test_case + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateEvaluationTestCaseInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateEvaluationTestCaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Evaluation Test Case. + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases" \ + -d '{ + "name": "Test Case", + "description": "Description of the test case", + "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], + "star_metric": { + "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "name": "Retrieved chunk usage", + "success_threshold_pct": 80 + }, + "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4" + }' + /v2/gen-ai/evaluation_test_cases/{evaluation_test_case_uuid}/evaluation_runs: + get: + description: >- + 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`. + operationId: genai_list_evaluation_runs_by_test_case + parameters: + - description: Evaluation run UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: evaluation_test_case_uuid + required: true + schema: + type: string + - description: Version of the test case. + example: 1 + in: query + name: evaluation_test_case_version + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListEvaluationRunsByTestCaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Evaluation Runs by Test Case + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_runs" + /v2/gen-ai/evaluation_test_cases/{test_case_uuid}: + get: + description: >- + To retrive information about an existing evaluation test case, send a + GET request to `/v2/gen-ai/evaluation_test_case/{test_case_uuid}`. + operationId: genai_get_evaluation_test_case + parameters: + - description: The test case uuid to retrieve. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: test_case_uuid + required: true + schema: + type: string + - description: Version of the test case. + example: 1 + in: query + name: evaluation_test_case_version + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetEvaluationTestCaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Information About an Existing Evaluation Test Case + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/9758a232-b351-11ef-bf8f-4e013e2ddde4" + put: + description: >- + To update an evaluation test-case send a PUT request to + `/v2/gen-ai/evaluation_test_cases/{test_case_uuid}`. + operationId: genai_update_evaluation_test_case + parameters: + - description: Test-case UUID to update + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: test_case_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateEvaluationTestCaseInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateEvaluationTestCaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update an Evaluation Test Case. + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/evaluation_test_cases/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "test_case_uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4", + "name": "Updated Test Case", + "description": "Updated description of the test case", + "dataset_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "metrics": ["1b418231-b7d6-11ef-bf8f-4e013e2ddde4", "2b418231-b7d6-11ef-bf8f-4e013e2ddde4"], + "star_metric": { + "metric_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "name": "Retrieved chunk usage", + "success_threshold_pct": 80 + } + }' + /v2/gen-ai/indexing_jobs: + get: + description: >- + To list all indexing jobs for a knowledge base, send a GET request to + `/v2/gen-ai/indexing_jobs`. + operationId: genai_list_indexing_jobs + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListKnowledgeBaseIndexingJobsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Indexing Jobs for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/indexing_jobs" + post: + description: >- + To start an indexing job for a knowledge base, send a POST request to + `/v2/gen-ai/indexing_jobs`. + operationId: genai_create_indexing_job + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiStartKnowledgeBaseIndexingJobInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiStartKnowledgeBaseIndexingJobOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Start Indexing Job for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/indexing_jobs" \ + -d '{ + "knowledge_base_uuid": "9758a232-b351-11ef-bf8f-4e013e2ddde4", + "data_source_uuids": [ + "9a825ee0-bbb1-11ef-bf8f-4e013e2ddde4" + ] + }' + /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources: + get: + description: >- + To list all datasources for an indexing job, send a GET request to + `/v2/gen-ai/indexing_jobs/{indexing_job_uuid}/data_sources`. + operationId: genai_list_indexing_job_data_sources + parameters: + - description: Uuid of the indexing job + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: indexing_job_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListIndexingJobDataSourcesOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Data Sources for Indexing Job for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4" + + + /v2/gen-ai/indexing_jobs/{indexing_job_uuid}/details_signed_url: + get: + description: >- + To get a signed URL for indexing job details, send a GET request to + `/v2/gen-ai/indexing_jobs/{uuid}/details_signed_url`. + operationId: genai_get_indexing_job_details_signed_url + parameters: + - description: The uuid of the indexing job + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: indexing_job_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetIndexingJobDetailsSignedURLOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Signed URL for Indexing Job Details + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: >- + curl --location --request GET + 'https://api.digitalocean.com/v2/gen-ai/indexing_jobs/6b090372-a8c3-11f0-b542-ca68c578b04b/details_signed_url' + \ + + --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ + + --header 'Content-Type: application/json' + /v2/gen-ai/indexing_jobs/{uuid}: + get: + description: >- + To get status of an indexing Job for a knowledge base, send a GET + request to `/v2/gen-ai/indexing_jobs/{uuid}`. + operationId: genai_get_indexing_job + parameters: + - description: Indexing job id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetKnowledgeBaseIndexingJobOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Status of Indexing Job for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/9758a232-b351-11ef-bf8f-4e013e2ddde4" + + /v2/gen-ai/indexing_jobs/{uuid}/cancel: + put: + description: >- + To cancel an indexing job for a knowledge base, send a PUT request to + `/v2/gen-ai/indexing_jobs/{uuid}/cancel`. + operationId: genai_cancel_indexing_job + parameters: + - description: A unique identifier for an indexing job. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCancelKnowledgeBaseIndexingJobInputPublic + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCancelKnowledgeBaseIndexingJobOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Cancel Indexing Job for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/indexing_jobs/79ca9798-cf7d-11ef-bf8f-4e013e2ddde4/cancel" \ + -d '{ + "uuid": "79ca9798-cf7d-11ef-bf8f-4e013e2ddde4" + }' + /v2/gen-ai/knowledge_bases: + get: + description: >- + To list all knowledge bases, send a GET request to + `/v2/gen-ai/knowledge_bases`. + operationId: genai_list_knowledge_bases + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListKnowledgeBasesOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Knowledge Bases + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases" + post: + description: >- + To create a knowledge base, send a POST request to + `/v2/gen-ai/knowledge_bases`. + operationId: genai_create_knowledge_base + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateKnowledgeBaseInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases" \ + -d '{ + "name": "kb-api-create", + "embedding_model_uuid": "05700391-7aa8-11ef-bf8f-4e013e2ddde4", + "project_id": "37455431-84bd-4fa2-94cf-e8486f8f8c5e", + "tags": [ + "tag1" + ], + "database_id": "abf1055a-745d-4c24-a1db-1959ea819264", + "datasources": [ + { + "spaces_data_source": { + "bucket_name": "test-public-gen-ai", + "region": "tor1" + }, + "chunking_algorithm": "CHUNKING_ALGORITHM_HIERARCHICAL", + "chunking_options": { + "parent_chunk_size": 1000, + "child_chunk_size": 350 + } + }, + { + "web_crawler_data_source": { + "base_url": "https://example.com", + "crawling_option": "SCOPED", + "embed_media": false, + "exclude_tags": ["nav","footer","header","aside","script","style","form","iframe", "noscript"] + }, + "chunking_algorithm": "CHUNKING_ALGORITHM_SEMANTIC", + "chunking_options": { + "max_chunk_size": 500, + "semantic_threshold": 0.6 + } + }, + { + "spaces_data_source": { + "bucket_name": "test-public-gen-ai-2", + "region": "tor1" + }, + "chunking_algorithm": "CHUNKING_ALGORITHM_FIXED_LENGTH", + "chunking_options": { + "max_chunk_size": 400 + } + }, + ], + "region": "tor1", + "vpc_uuid": "f7176e0b-8c5e-4e32-948e-79327e56225a", + "reranking_config": { + "enabled": true, + "model": "bge-reranker-v2-m3" + } + }' + /v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls: + post: + description: >- + 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`. + operationId: genai_create_data_source_file_upload_presigned_urls + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateDataSourceFileUploadPresignedUrlsInputPublic + responses: + '200': + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateDataSourceFileUploadPresignedUrlsOutput + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Presigned URLs for Data Source File Upload + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/data_sources/file_upload_presigned_urls" \ + -d '{ + "files": [{ + "file_name": "dataset.csv", + "file_size": 2048 + }] + }' + /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources: + get: + description: >- + To list all data sources for a knowledge base, send a GET request to + `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources`. + operationId: genai_list_knowledge_base_data_sources + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListKnowledgeBaseDataSourcesOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Data Sources for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4/data_sources" + post: + description: >- + To add a data source to a knowledge base, send a POST request to + `/v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources`. + operationId: genai_create_knowledge_base_data_source + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateKnowledgeBaseDataSourceInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateKnowledgeBaseDataSourceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Add Data Source to a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/20cd8434-6ea1-11f0-bf8f-4e013e2ddde4/data_sources" \ + -d '{ + "knowledge_base_uuid": "20cd8434-6ea1-11f0-bf8f-4e013e2ddde4", + "web_crawler_data_source": { + "base_url": "https://example.com", + "crawling_option": "SCOPED", + "embed_media": false, + "exclude_tags": ["nav","footer","header","aside","script","style","form","iframe", "noscript"] + }, + "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED", + "chunking_options": { + "max_chunk_size": 500 + } + }' + /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/data_sources/{data_source_uuid}: + put: + description: >- + 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}`. + operationId: genai_update_knowledge_base_data_source + parameters: + - description: Knowledge Base ID (Path Parameter) + example: 123e4567-e89b-12d3-a456-426614174000 + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + - description: Data Source ID (Path Parameter) + example: 123e4567-e89b-12d3-a456-426614174000 + in: path + name: data_source_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateKnowledgeBaseDataSourceInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateKnowledgeBaseDataSourceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update Data Source options + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/12345678-1234-1234-1234-123456789012/data_sources/98765432-1234-1234-1234-123456789012" \ + -d '{ + "chunking_algorithm": "CHUNKING_ALGORITHM_SECTION_BASED", + "chunking_options": { + "max_chunk_size": 500 + } + }' + delete: + description: >- + 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}`. + operationId: genai_delete_knowledge_base_data_source + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + - description: Data source id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: data_source_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteKnowledgeBaseDataSourceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete a Data Source from a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9a6e3975-b0c6-11ef-bf8f-4e013e2ddde4/data_sources/bd2a2db5-b8b0-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/knowledge_bases/{knowledge_base_uuid}/indexing_jobs: + get: + description: >- + 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`. + operationId: genai_list_indexing_jobs_by_knowledge_base + parameters: + - description: Knowledge base uuid in string + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListKnowledgeBaseIndexingJobsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Indexing Jobs for a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: >- + curl --location --request GET + 'https://api.digitalocean.com/v2/gen-ai/knowledge_bases/1139121f-a860-11f0-b542-ca68c578b04b/indexing_jobs' + \ + + --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ + + --header 'Content-Type: application/json' + /v2/gen-ai/knowledge_bases/{uuid}: + get: + description: >- + To retrive information about an existing knowledge base, send a GET + request to `/v2/gen-ai/knowledge_bases/{uuid}`. + operationId: genai_get_knowledge_base + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Information About an Existing Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/9758a232-b351-11ef-bf8f-4e013e2ddde4" + + put: + description: >- + To update a knowledge base, send a PUT request to + `/v2/gen-ai/knowledge_bases/{uuid}`. + operationId: genai_update_knowledge_base + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateKnowledgeBaseInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/e51dba65-cf7a-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "uuid": "e51dba65-cf7a-11ef-bf8f-4e013e2ddde4", + "name": "kb-api-rename", + "reranking_config": { + "enabled": true, + "model": "bge-reranker-v2-m3" + } + }' + delete: + description: >- + To delete a knowledge base, send a DELETE request to + `/v2/gen-ai/knowledge_bases/{uuid}`. + operationId: genai_delete_knowledge_base + parameters: + - description: Knowledge base id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteKnowledgeBaseOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete a Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/knowledge_bases/8241f44e-b0da-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/model_evaluation/datasets/file_upload_presigned_urls: + post: + description: >- + To create presigned URLs for model evaluation dataset file upload, send + a POST request to + `/v2/genai/model_evaluation/datasets/file_upload_presigned_urls`. + operationId: genai_create_model_eval_dataset_upload_presigned_urls + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateModelEvalDatasetUploadPresignedUrlsInputPublic + responses: + '200': + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiCreateDataSourceFileUploadPresignedUrlsOutput + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Presigned URLs for Model Evaluation Dataset File Upload + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation/datasets/file_upload_presigned_urls" \ + -d '{ + "files": [{ + "file_name": "dataset.jsonl", + "file_size": 2048 + }] + }' + /v2/gen-ai/model_evaluation_metrics: + get: + description: >- + To list all available metrics for model evaluation, send a GET request + to `/v2/genai/model_evaluation_metrics`. + operationId: genai_list_model_evaluation_metrics + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelEvaluationMetricsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Evaluation Metrics + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation_metrics" + /v2/gen-ai/model_evaluation_runs: + get: + description: >- + To list model evaluation runs, send a GET request to + `/v2/genai/model_evaluation_runs`. + operationId: genai_list_model_evaluation_runs + parameters: + - description: UUID of the evaluation preset to filter by. + example: 123e4567-e89b-12d3-a456-426614174000 + in: query + name: eval_preset_uuid + schema: + type: string + - description: Filter by evaluation run status. + example: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + in: query + name: status + schema: + default: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + enum: + - MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + - MODEL_EVALUATION_RUN_QUEUED + - MODEL_EVALUATION_RUN_RUNNING_DATASET + - MODEL_EVALUATION_RUN_EVALUATING_RESULTS + - MODEL_EVALUATION_RUN_CANCELLING + - MODEL_EVALUATION_RUN_CANCELLED + - MODEL_EVALUATION_RUN_SUCCESSFUL + - MODEL_EVALUATION_RUN_PARTIALLY_SUCCESSFUL + - MODEL_EVALUATION_RUN_FAILED + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelEvaluationRunsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Evaluation Runs + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs" + post: + description: >- + To create a model evaluation run, send a POST request to + `/v2/genai/model_evaluation_runs`. + operationId: genai_create_model_evaluation_run + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelEvaluationRunInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelEvaluationRunOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create Model Evaluation Run + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs" \ + -d '{ + "name": "my-evaluation-run", + "candidate_model_uuid": "123e4567-e89b-12d3-a456-426614174000", + "judge_model_uuid": "223e4567-e89b-12d3-a456-426614174001", + "dataset_uuid": "323e4567-e89b-12d3-a456-426614174002", + "metric_uuids": [ + "423e4567-e89b-12d3-a456-426614174003" + ] + }' + /v2/gen-ai/model_evaluation_runs/{eval_run_uuid}: + get: + description: >- + To retrieve a model evaluation run, send a GET request to + `/v2/genai/model_evaluation_runs/{eval_run_uuid}`. + operationId: genai_get_model_evaluation_run + parameters: + - description: UUID of the evaluation run. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: eval_run_uuid + required: true + schema: + type: string + - description: Page number for per-prompt results (defaults to 1). + example: 1 + in: query + name: page + schema: + type: integer + - description: Number of per-prompt results per page (defaults to 50). + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetModelEvaluationRunOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve Model Evaluation Run + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs/123e4567-e89b-12d3-a456-426614174000" + /v2/gen-ai/model_evaluation_runs/{eval_run_uuid}/results/download_url: + get: + description: >- + 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`. + operationId: genai_get_model_evaluation_run_results_download_url + parameters: + - description: UUID of the evaluation run. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: eval_run_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiGetModelEvaluationRunResultsDownloadURLOutput + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Download URL for Model Evaluation Run Results + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/model_evaluation_runs/123e4567-e89b-12d3-a456-426614174000/results/download_url" + /v2/gen-ai/models: + get: + description: To list all models, send a GET request to `/v2/gen-ai/models`. + operationId: genai_list_models + parameters: + - description: |- + Include only models defined for the listed usecases. + + - MODEL_USECASE_UNKNOWN: The use case of the model is unknown + - MODEL_USECASE_AGENT: The model maybe used in an agent + - MODEL_USECASE_FINETUNED: The model maybe used for fine tuning + - MODEL_USECASE_KNOWLEDGEBASE: The model maybe used for knowledge bases (embedding models) + - MODEL_USECASE_GUARDRAIL: The model maybe used for guardrails + - MODEL_USECASE_REASONING: The model usecase for reasoning + - MODEL_USECASE_SERVERLESS: The model usecase for serverless inference + example: + - MODEL_USECASE_UNKNOWN + in: query + name: usecases + schema: + items: + enum: + - MODEL_USECASE_UNKNOWN + - MODEL_USECASE_AGENT + - MODEL_USECASE_FINETUNED + - MODEL_USECASE_KNOWLEDGEBASE + - MODEL_USECASE_GUARDRAIL + - MODEL_USECASE_REASONING + - MODEL_USECASE_SERVERLESS + type: string + type: array + - description: Only include models that are publicly available. + example: true + in: query + name: public_only + schema: + type: boolean + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelsOutputPublic' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Available Models + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models" + /v2/gen-ai/models/api_keys: + get: + description: >- + To list all model API keys, send a GET request to + `/v2/gen-ai/models/api_keys`. + operationId: genai_list_model_api_keys + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelAPIKeysOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model API Keys + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/api_keys" + post: + description: >- + To create a model API key, send a POST request to + `/v2/gen-ai/models/api_keys`. + operationId: genai_create_model_api_key + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create a Model API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/api_keys" \ + -d '{ + "name": "test-key" + }' + /v2/gen-ai/models/api_keys/{api_key_uuid}: + put: + description: >- + To update a model API key, send a PUT request to + `/v2/gen-ai/models/api_keys/{api_key_uuid}`. + operationId: genai_update_model_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateModelAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateModelAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update API Key for a Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ + -d '{ + "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", + "name": "test-key2" + }' + delete: + description: >- + To delete an API key for a model, send a DELETE request to + `/v2/gen-ai/models/api_keys/{api_key_uuid}`. + operationId: genai_delete_model_api_key + parameters: + - description: API key for an agent. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteModelAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete API Key for a Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + /v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate: + put: + description: >- + To regenerate a model API key, send a PUT request to + `/v2/gen-ai/models/api_keys/{api_key_uuid}/regenerate`. + operationId: genai_regenerate_model_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiRegenerateModelAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Regenerate API Key for a Model + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/api_keys/11efcf7e-824d-2808-bf8f-4e013e2ddde4/regenerate" + /v2/gen-ai/models/catalog: + get: + description: Returns all available models. + operationId: genai_list_model_catalog + parameters: + - example: 1 + in: query + name: page + schema: + type: integer + - example: 1 + in: query + name: limit + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelCatalogOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Catalog + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + "https://api.digitalocean.com/v2/gen-ai/models/catalog" + /v2/gen-ai/models/catalog/{id}: + get: + description: >- + Returns detailed information for a specific model in the catalog + including capabilities, pricing, and code examples. + operationId: genai_get_model_catalog_card + parameters: + - example: '"example string"' + in: path + name: id + required: true + schema: + type: string + - description: >- + Model identifier used for API calls (e.g., "llama3.1-70b-instruct"). + Alternative to UUID lookup. + example: '"example string"' + in: query + name: model_id + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetModelCatalogCardOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Model Catalog Card + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + "https://api.digitalocean.com/v2/gen-ai/models/catalog/18bc9b8f-73c5-11f0-b074-4e013e2ddde4" + /v2/gen-ai/models/routers: + get: + description: >- + To list model routers, send a GET request to + `/v2/gen-ai/models/routers`. + operationId: genai_list_model_routers + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelRoutersOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Routers + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers?page=1&per_page=20" + post: + description: >- + To create a model router, send a POST request to + `/v2/gen-ai/models/routers`. + operationId: genai_create_model_router + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelRouterInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateModelRouterOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create a Model Router + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers" \ + -d '{ + "name": "My Model Router", + "description": "Routes chat traffic across multiple models", + "regions": ["tor1"], + "fallback_models": ["openai-gpt-5.4", "kimi-k2.5"], + "policies": [ + { + "task_slug": "summarization", + "models": ["openai-gpt-5.4", "kimi-k2.5"], + "selection_policy": { + "prefer": "cheapest" + } + } + ] + }' + /v2/gen-ai/models/routers/presets: + get: + description: >- + To list model router presets, send a GET request to + `/v2/gen-ai/models/routers/presets`. + operationId: genai_list_model_router_presets + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelRouterPresetsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Router Presets + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers/presets?page=1&per_page=20" + /v2/gen-ai/models/routers/tasks/presets: + get: + description: >- + To list model router task presets, send a GET request to + `/v2/gen-ai/models/routers/tasks/presets`. + operationId: genai_list_model_router_task_presets + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListModelRouterTaskPresetsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Model Router Task Presets + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers/tasks/presets?page=1&per_page=20" + /v2/gen-ai/models/routers/{uuid}: + get: + description: >- + To retrieve details of a model router, send a GET request to + `/v2/gen-ai/models/routers/{uuid}`. + operationId: genai_get_model_router + parameters: + - description: Model router id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetModelRouterOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve an Existing Model Router + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012" + put: + description: >- + To update a model router, send a PUT request to + `/v2/gen-ai/models/routers/{uuid}`. + operationId: genai_update_model_router + parameters: + - description: Model router id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateModelRouterInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateModelRouterOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update a Model Router + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012" \ + -d '{ + "name": "My Model Router", + "description": "Updated router description", + "regions": ["tor1"], + "fallback_models": ["openai-gpt-5.4", "kimi-k2.5"], + "policies": [ + { + "task_slug": "summarization", + "models": ["openai-gpt-5.4"], + "selection_policy": { + "prefer": "cheapest" + } + } + ] + }' + delete: + description: >- + To delete a model router, send a DELETE request to + `/v2/gen-ai/models/routers/{uuid}`. + operationId: genai_delete_model_router + parameters: + - description: Model router id + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteModelRouterOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete a Model Router + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/models/routers/12345678-1234-1234-1234-123456789012" + /v2/gen-ai/oauth2/dropbox/tokens: + post: + description: >- + 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' + operationId: genai_create_oauth2_dropbox_tokens + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiDropboxOauth2GetTokensInput' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDropboxOauth2GetTokensOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Get Oauth2 Dropbox Tokens + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/oauth2/dropbox/tokens?code=" + /v2/gen-ai/oauth2/url: + get: + description: >- + 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 + operationId: genai_get_oauth2_url + parameters: + - description: Type "google" / "dropbox". + example: '"example string"' + in: query + name: type + schema: + type: string + - description: The redirect url. + example: '"example string"' + in: query + name: redirect_url + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGenerateOauth2URLOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Oauth2 URL + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/oauth2/url?type=google&redirect_uri=http://localhost:3000" + /v2/gen-ai/openai/keys: + get: + description: >- + To list all OpenAI API keys, send a GET request to + `/v2/gen-ai/openai/keys`. + operationId: genai_list_openai_api_keys + parameters: + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListOpenAIAPIKeysOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List OpenAI API Keys + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys" + post: + description: >- + To create an OpenAI API key, send a POST request to + `/v2/gen-ai/openai/keys`. + operationId: genai_create_openai_api_key + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateOpenAIAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateOpenAIAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create OpenAI API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys" \ + -d '{ + "api_key": "sk-proj--12345678901234567890123456789012", + "name": "test-key" + }' + /v2/gen-ai/openai/keys/{api_key_uuid}: + get: + description: >- + To retrieve details of an OpenAI API key, send a GET request to + `/v2/gen-ai/openai/keys/{api_key_uuid}`. + operationId: genai_get_openai_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetOpenAIAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get OpenAI API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + put: + description: >- + To update an OpenAI API key, send a PUT request to + `/v2/gen-ai/openai/keys/{api_key_uuid}`. + operationId: genai_update_openai_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateOpenAIAPIKeyInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateOpenAIAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update OpenAI API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" \ + -d '{ + "api_key_uuid": "11efb7d6-cdb5-6388-bf8f-4e013e2ddde4", + "name": "test-key2" + }' + delete: + description: >- + To delete an OpenAI API key, send a DELETE request to + `/v2/gen-ai/openai/keys/{api_key_uuid}`. + operationId: genai_delete_openai_api_key + parameters: + - description: API key ID + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: api_key_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteOpenAIAPIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete OpenAI API Key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4" + /v2/gen-ai/openai/keys/{uuid}/agents: + get: + description: List Agents by OpenAI Key. + operationId: genai_list_agents_by_openai_key + parameters: + - description: Unique ID of OpenAI key + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentsByOpenAIKeyOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List agents by OpenAI key + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/openai/keys/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" + /v2/gen-ai/regions: + get: + description: >- + To list all datacenter regions, send a GET request to + `/v2/gen-ai/regions`. + operationId: genai_list_datacenter_regions + parameters: + - description: Include datacenters that serve inference. + example: true + in: query + name: serves_inference + schema: + type: boolean + - description: Include datacenters that are capable of running batch jobs. + example: true + in: query + name: serves_batch + schema: + type: boolean + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListRegionsOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Datacenter Regions + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/regions" + /v2/gen-ai/scheduled-indexing: + post: + description: >- + To create scheduled indexing for a knowledge base, send a POST request + to `/v2/gen-ai/scheduled-indexing`. + operationId: genai_create_scheduled_indexing + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateScheduledIndexingInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateScheduledIndexingOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create scheduled indexing for knowledge base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: >- + curl --location --request POST + 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing' \ + + --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN"' \ + + --header 'Content-Type: application/json' \ + + --data '{ + "knowledge_base_uuid": "knowledge_base_uuid", + "time": "18:00", + "days": [ + 1, + 2, + 3 + ] + }' + /v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}: + get: + description: >- + 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}`. + operationId: genai_get_scheduled_indexing + parameters: + - description: UUID of the scheduled indexing entry + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: knowledge_base_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetScheduledIndexingOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Get Scheduled Indexing for Knowledge Base + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: >- + curl --location --request GET + 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/knowledge-base/{knowledge_base_uuid}' + \ + + --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' \ + + --header 'Content-Type: application/json' + /v2/gen-ai/scheduled-indexing/{uuid}: + delete: + description: >- + Delete Scheduled Indexing for knowledge base, send a DELETE request to + `/v2/gen-ai/scheduled-indexing/{uuid}`. + operationId: genai_delete_scheduled_indexing + parameters: + - description: UUID of the scheduled indexing + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteScheduledIndexingOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete Scheduled Indexing + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: >- + curl --location --request DELETE + 'https://api.digitalocean.com/v2/gen-ai/scheduled-indexing/{scheduled_indexing_id}' + \ + --header 'Authorization: Bearer $DIGITALOCEAN_TOKEN' + /v2/gen-ai/workspaces: + get: + description: To list all workspaces, send a GET request to `/v2/gen-ai/workspaces`. + operationId: genai_list_workspaces + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListWorkspacesOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Workspaces + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces" + post: + description: >- + 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. + operationId: genai_create_workspace + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateWorkspaceInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiCreateWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:create + summary: Create a Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces" \ + -d '{ + "name": "api-create", + "description": "This is a test workspace created via the API", + "agent_uuids": [ + "9758a232-b351-11ef-bf8f-4e013e2ddde4" + ] + }' + /v2/gen-ai/workspaces/{workspace_uuid}: + get: + description: >- + 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. + operationId: genai_get_workspace + parameters: + - description: Workspace UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiGetWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: Retrieve an Existing Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/c441bf77-81d6-11ef-bf8f-4e013e2ddde4" + put: + description: >- + 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. + operationId: genai_update_workspace + parameters: + - description: Workspace UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateWorkspaceInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiUpdateWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Update a Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4" \ + -d '{ + "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "name": "rename-agent-api", + "description": "workspace description" + }' + delete: + description: >- + To delete a workspace, send a DELETE request to + `/v2/gen-ai/workspace/{workspace_uuid}`. + operationId: genai_delete_workspace + parameters: + - description: Workspace UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiDeleteWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:delete + summary: Delete a Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/5581a586-a745-11ef-bf8f-4e013e2ddde4" + /v2/gen-ai/workspaces/{workspace_uuid}/agents: + get: + description: >- + To list all agents by a Workspace, send a GET request to + `/v2/gen-ai/workspaces/{workspace_uuid}/agents`. + operationId: genai_list_agents_by_workspace + parameters: + - description: Workspace UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + - description: Only list agents that are deployed. + example: true + in: query + name: only_deployed + schema: + type: boolean + - description: Page number. + example: 1 + in: query + name: page + schema: + type: integer + - description: Items per page. + example: 1 + in: query + name: per_page + schema: + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiListAgentsByWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List agents by Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/agents" + put: + description: >- + To move all listed agents a given workspace, send a PUT request to + `/v2/gen-ai/workspaces/{workspace_uuid}/agents`. + operationId: genai_update_agents_workspace + parameters: + - description: Workspace uuid to move agents to + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/apiMoveAgentsToWorkspaceInputPublic' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/apiMoveAgentsToWorkspaceOutput' + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:update + summary: Move Agents to a Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X PUT \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/1b418231-b7d6-11ef-bf8f-4e013e2ddde4/agents" \ + -d '{ + "workspace_uuid": "1b418231-b7d6-11ef-bf8f-4e013e2ddde4", + "agent_uuids": ["95ea6652-75ed-11ef-bf8f-4e013e2ddde4", "37455431-84bd-4fa2-94cf-e8486f8f8c5e"] + }' + /v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases: + get: + description: >- + To list all evaluation test cases by a workspace, send a GET request to + `/v2/gen-ai/workspaces/{workspace_uuid}/evaluation_test_cases`. + operationId: genai_list_evaluation_test_cases_by_workspace + parameters: + - description: Workspace UUID. + example: '"123e4567-e89b-12d3-a456-426614174000"' + in: path + name: workspace_uuid + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: >- + #/components/schemas/apiListEvaluationTestCasesByWorkspaceOutput + description: A successful response. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + security: + - bearer_auth: + - genai:read + summary: List Evaluation Test Cases by Workspace + tags: + - GradientAI Platform + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/gen-ai/workspaces/11efb7d6-cdb5-6388-bf8f-4e013e2ddde4/evaluation_test_cases" + /v1/chat/completions: + post: + operationId: inference_create_chat_completion + summary: Create a model response for the given chat conversation + description: Creates a model response for the given chat conversation. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/chat_completion_request' + responses: + '200': + description: >- + Successful chat completion. When stream is true, response is sent as + Server-Sent Events (text/event-stream); otherwise a single JSON + object (application/json) is returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/chat_completion_response' + text/event-stream: + schema: + $ref: '#/components/schemas/chat_completion_chunk' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"messages": [{"role": "user", "content": "What is the capital of Portugal?"}], "model": "meta-llama/Meta-Llama-3.1-8B-Instruct"}' \ + "https://inference.do-ai.run/v1/chat/completions" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.chat.completions.create( + model="llama3.3-70b-instruct", + messages=[ + {"role": "user", "content": "What is the capital of Portugal?"}, + ], + ) + + print(resp.choices[0].message.content) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const completion = await client.chat.completions.create({ + model: "llama3.3-70b-instruct", + messages: [ + { role: "user", content: "What is the capital of Portugal?" }, + ], + }); + + console.log(completion.choices[0].message.content); + security: + - inference_bearer_auth: [] + /v1/messages: + post: + operationId: inference_create_messages + summary: Create the next assistant message + description: > + Send a structured list of input messages with text and/or image content, + and the model will generate the next message in the conversation. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/messages_create_request' + responses: + '200': + description: > + Successful generation. When `stream` is true, the body is + `text/event-stream` with server-sent event (SSE) payloads; otherwise + `application/json` with `CreateMessageResponse`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/messages_create_response' + text/event-stream: + schema: + $ref: '#/components/schemas/messages_stream_event' + '400': + description: Invalid request body, validation error, or policy rejection. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/messages_create_error_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"model": "claude-opus-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "What is the capital of Portugal?"}]}' \ + "https://inference.do-ai.run/v1/messages" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[ + {"role": "user", "content": "What is the capital of Portugal?"}, + ], + ) + + print(resp.content[0].text) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const resp = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { role: "user", content: "What is the capital of Portugal?" }, + ], + }); + + console.log(resp.content[0].text); + security: + - inference_bearer_auth: [] + /v1/embeddings: + post: + operationId: inference_create_embedding + summary: Create embedding + description: > + 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. + tags: + - Serverless Inference + - Embeddings + servers: + - url: https://inference.do-ai.run + description: production + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/embeddings_request' + responses: + '200': + description: Embeddings and usage for the given `input` or `inputs`, in order. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/embeddings_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"model":"qwen3-embedding-0.6b","input":["hello world","goodbye world"],"encoding_format":"float","user":"user-1234"}' \ + "https://inference.do-ai.run/v1/embeddings" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.embeddings.create( + model="qwen3-embedding-0.6b", + input=["hello world", "goodbye world"], + encoding_format="float", + user="user-1234", + ) + + for item in resp.data: + print(item.index, item.embedding[:8]) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const resp = await client.embeddings.create({ + model: "qwen3-embedding-0.6b", + input: ["hello world", "goodbye world"], + encoding_format: "float", + user: "user-1234", + }); + + for (const item of resp.data) { + console.log(item.index, item.embedding.slice(0, 8)); + } + security: + - inference_bearer_auth: [] + /api/v1/chat/completions: + post: + operationId: agentInference_create_chat_completion + summary: Create a model response for the given chat conversation + description: >- + Creates a model response for the given chat conversation via a + customer-provisioned + + agent endpoint. + tags: + - Agent Inference + servers: + - url: https://{agent_url} + description: production + variables: + agent_url: + default: '{your-agent-url}' + description: >- + The agent URL assigned to your provisioned agent (e.g. + fuauiziwb5xm6xka4c7aer5k.agents.do-ai.run). + parameters: + - name: agent + in: query + required: true + schema: + type: boolean + default: true + description: Must be set to true for agent-based completion behavior. + example: true + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/chat_completion_request' + responses: + '200': + description: >- + Successful chat completion. When stream is true, response is sent as + Server-Sent Events (text/event-stream); otherwise a single JSON + object (application/json) is returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/chat_completion_response' + text/event-stream: + schema: + $ref: '#/components/schemas/chat_completion_chunk' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $AGENT_ACCESS_KEY" \ + -d '{"messages": [{"role": "user", "content": "What is the capital of Portugal?"}], "model": "ignored"}' \ + "https://$AGENT_URL/api/v1/chat/completions?agent=true" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client( + token=os.environ.get("AGENT_ACCESS_KEY"), + agent_endpoint=os.environ.get("AGENT_ENDPOINT"), + ) + + resp = client.agent.chat.completions.create( + model="llama3.3-70b-instruct", + messages=[ + {"role": "user", "content": "What is the capital of Portugal?"}, + ], + ) + + print(resp.choices[0].message.content) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.AGENT_ACCESS_KEY, + baseURL: `https://${process.env.AGENT_URL}/api`, + }); + + const completion = await client.chat.completions.create({ + model: "llama3.3-70b-instruct", + messages: [ + { role: "user", content: "What is the capital of Portugal?" }, + ], + }); + + console.log(completion.choices[0].message.content); + security: + - inference_bearer_auth: [] + /v1/images/generations: + post: + operationId: inference_create_image + summary: Generate images from text prompts + description: >- + Creates a high-quality image from a text prompt using GPT-IMAGE-1, the + latest image generation model with automatic prompt optimization and + enhanced visual capabilities. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/create_image_request' + responses: + '200': + description: >- + Successful image generation. When stream is true, response is sent + as Server-Sent Events (text/event-stream); otherwise a single JSON + object (application/json) is returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/images_response' + text/event-stream: + schema: + $ref: '#/components/schemas/image_gen_partial_image_event' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -d '{"prompt": "A cute baby sea otter floating on its back in calm blue water", "model": "openai-gpt-image-1", "size": "auto", "quality": "auto"}' \ + "https://inference.do-ai.run/v1/images/generations" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.images.generate( + model="openai-gpt-image-1", + prompt="A cute baby sea otter floating on its back in calm blue water", + size="auto", + quality="auto", + n=1, + ) + + print(resp.data[0].b64_json) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const resp = await client.images.generate({ + model: "openai-gpt-image-1", + prompt: "A cute baby sea otter floating on its back in calm blue water", + size: "auto", + quality: "auto", + n: 1, + }); + + console.log(resp.data[0].b64_json); + security: + - inference_bearer_auth: [] + /v1/models: + get: + operationId: inference_list_models + summary: List available models + description: >- + Lists the currently available models, and provides basic information + about each one such as the owner and availability. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + responses: + '200': + description: A list of available models. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/list_models_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://inference.do-ai.run/v1/models" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.models.list() + + for model in resp.data: + print(model.id) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const resp = await client.models.list(); + + for (const model of resp.data) { + console.log(model.id); + } + security: + - inference_bearer_auth: [] + /v1/responses: + post: + operationId: inference_create_response + summary: Send Prompt to a Model Using the Responses API + description: > + Generate text responses from text prompts. This endpoint supports both + streaming and non-streaming responses for supported text models. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/create_response_request' + responses: + '200': + description: >- + Successful response. When stream is true, response is sent as + Server-Sent Events (text/event-stream); otherwise a single JSON + object (application/json) is returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/create_response_response' + text/event-stream: + schema: + $ref: '#/components/schemas/create_response_stream_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -sS -X POST \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "openai-gpt-oss-20b", + "input": "What is the capital of France?", + "max_output_tokens": 50, + "temperature": 0.7, + "stream": false + }' \ + "https://inference.do-ai.run/v1/responses" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.responses.create( + model="openai-gpt-oss-20b", + input="What is the capital of France?", + max_output_tokens=50, + temperature=0.7, + ) + + print(resp.output[0].content[0].text) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const resp = await client.responses.create({ + model: "openai-gpt-oss-20b", + input: "What is the capital of France?", + max_output_tokens: 50, + temperature: 0.7, + }); + + console.log(resp.output_text); + security: + - inference_bearer_auth: [] + /v1/async-invoke: + post: + operationId: inference_create_async_invoke + summary: Generate Image, Audio, or Text-to-Speech Using fal Models + description: > + 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. + tags: + - Serverless Inference + servers: + - url: https://inference.do-ai.run + description: production + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/async_invoke_request' + examples: + Image Generation: + value: + model_id: fal-ai/flux/schnell + input: + prompt: A futuristic city at sunset + Generate Audio: + value: + model_id: fal-ai/stable-audio-25/text-to-audio + input: + prompt: Techno song with futuristic sounds + seconds_total: 60 + tags: + - key: type + value: test + Text-to-Speech: + value: + model_id: fal-ai/elevenlabs/tts/multilingual-v2 + input: + text: >- + This text-to-speech example uses DigitalOcean multilingual + voice. + tags: + - key: type + value: test + responses: + '200': + description: The async invocation completed synchronously. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/async_invoke_response' + '202': + description: The async invocation request was accepted. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/async_invoke_response' + '401': + $ref: '#/components/responses/unauthorized' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + # Image Generation + curl -X POST \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model_id": "fal-ai/flux/schnell", + "input": { + "prompt": "A futuristic city at sunset" + } + }' \ + "https://inference.do-ai.run/v1/async-invoke" + + # Audio Generation + curl -X POST \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model_id": "fal-ai/stable-audio-25/text-to-audio", + "input": { + "prompt": "Techno song with futuristic sounds", + "seconds_total": 60 + }, + "tags": [ + {"key": "type", "value": "test"} + ] + }' \ + "https://inference.do-ai.run/v1/async-invoke" + + # Text-to-Speech + curl -X POST \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model_id": "fal-ai/elevenlabs/tts/multilingual-v2", + "input": { + "text": "This text-to-speech example uses DigitalOcean multilingual voice." + }, + "tags": [ + {"key": "type", "value": "test"} + ] + }' \ + "https://inference.do-ai.run/v1/async-invoke" + - lang: Python + source: |- + import os + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + # Image Generation + resp = client.async_images.generate( + model_id="fal-ai/flux/schnell", + prompt="A futuristic city at sunset", + ) + print(resp.request_id, resp.status) + + # Audio Generation + resp = client.audio.generate( + model_id="fal-ai/stable-audio-25/text-to-audio", + prompt="Techno song with futuristic sounds", + seconds_total=60, + ) + print(resp.request_id, resp.status) + + # Text-to-Speech + resp = client.audio.speech.create( + input="This text-to-speech example uses DigitalOcean multilingual voice.", + model_id="fal-ai/elevenlabs/tts/multilingual-v2", + ) + print(resp.request_id, resp.status) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + // Image Generation + const imgResp = await client.async_images.generate({ + model_id: "fal-ai/flux/schnell", + prompt: "A futuristic city at sunset", + }); + console.log(imgResp.request_id, imgResp.status); + + // Audio Generation + const audioResp = await client.audio.generate({ + model_id: "fal-ai/stable-audio-25/text-to-audio", + prompt: "Techno song with futuristic sounds", + seconds_total: 60, + }); + console.log(audioResp.request_id, audioResp.status); + + // Text-to-Speech + const ttsResp = await client.audio.speech.create({ + model_id: "fal-ai/elevenlabs/tts/multilingual-v2", + input: "This text-to-speech example uses DigitalOcean multilingual voice.", + }); + console.log(ttsResp.request_id, ttsResp.status); + security: + - inference_bearer_auth: [] + /v1/batches/files: + post: + operationId: inference_create_batch_file + summary: Create a Batch Inference Input File + description: > + 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`. + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/batch_file_create_request' + examples: + Default: + value: + file_name: batch_requests.jsonl + responses: + '201': + description: File intent created. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch_file_create_response' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -sS -X POST "https://inference.do-ai.run/v1/batches/files" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "file_name": "batch_requests.jsonl" + }' | jq + - lang: Python + source: >- + import json + + import os + + from pathlib import Path + + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + input_path = Path("batch_requests.jsonl") + + requests = [ + { + "custom_id": "q-1", + "method": "POST", + "url": "/v1/chat/completions", + "body": { + "model": "llama3.3-70b-instruct", + "messages": [ + {"role": "user", "content": "One fun fact about octopuses."} + ], + "max_tokens": 128, + }, + }, + { + "custom_id": "q-2", + "method": "POST", + "url": "/v1/chat/completions", + "body": { + "model": "llama3.3-70b-instruct", + "messages": [ + {"role": "user", "content": "One fun fact about sharks."} + ], + "max_tokens": 128, + }, + }, + ] + + input_path.write_text("\n".join(json.dumps(r) for r in requests) + + "\n") + + + uploaded = client.files.create(file=input_path, purpose="batch") + + + print("file_id: ", uploaded.file_id) + + print("filename:", uploaded.filename) + + print("bytes: ", uploaded.bytes) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const intent = await client.files.create({ + file_name: "batch_requests.jsonl", + }); + + console.log("file_id: ", intent.file_id); + console.log("upload_url:", intent.upload_url); + security: + - inference_bearer_auth: [] + /: + put: + operationId: inference_upload_batch_file + summary: Upload a Batch Inference Input File + description: > + 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. + tags: + - Batch Inference + servers: + - url: https:// + description: > + Use the exact `upload_url` returned by `POST /v1/batches/files`. Do + not construct this URL — it is presigned, short-lived, and different + per request. + requestBody: + required: true + description: Raw JSONL bytes — one request per line. + content: + application/octet-stream: + schema: + type: string + format: binary + responses: + '200': + description: Upload accepted by object storage. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '401': + $ref: '#/components/responses/unauthorized' + '403': + description: > + Signature mismatch or URL expired. Create a new file intent with + `POST /v1/batches/files` and upload again. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + # UPLOAD_URL is the exact upload_url returned by POST + /v1/batches/files. + + # Use it verbatim; do not modify the host, path, or query string. + + # + + # Send the raw JSONL bytes with --data-binary so line endings and + UTF-8 + + # are preserved. The presigned URL is signature-sensitive: prefer + + # application/octet-stream (or omit Content-Type entirely) — a + custom + + # value such as application/jsonl can break signature matching + unless + + # the URL was signed for that exact header. + + curl -X PUT "$UPLOAD_URL" \ + -H "Content-Type: application/octet-stream" \ + --data-binary "@batch_requests.jsonl" + - lang: Python + source: >- + # Two-step upload flow: + + # 1. Reserve a file_id + presigned upload_url via + client.batches.files.create. + + # 2. PUT the raw JSONL bytes to upload_url. + + # + + # The presigned URL is short-lived (~15 minutes) and + signature-sensitive — + + # use it verbatim and prefer Content-Type application/octet-stream + (or + + # omit the header entirely). A custom value such as + application/jsonl + + # can break signature matching. + + import os + + from pathlib import Path + + + import requests + + from pydo import Client + + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + + input_path = Path("batch_requests.jsonl") + + + # Step 1: reserve the upload slot. + + intent = client.batches.files.create(file_name=input_path.name) + + upload_url = intent["upload_url"] + + file_id = intent["file_id"] + + + # Step 2: PUT the JSONL bytes to the presigned URL. + + with input_path.open("rb") as fh: + put = requests.put( + upload_url, + data=fh, + headers={"Content-Type": "application/octet-stream"}, + timeout=60, + ) + put.raise_for_status() + + + print("uploaded file_id:", file_id) + - lang: JavaScript + source: >- + // Two-step upload flow: + + // 1. Reserve a file_id + presigned upload_url via + client.files.create. + + // 2. PUT the raw JSONL bytes to upload_url. + + // + + // The presigned URL is short-lived (~15 minutes) and + signature-sensitive — + + // use it verbatim and prefer Content-Type application/octet-stream + (or + + // omit the header entirely). A custom value such as + application/jsonl + + // can break signature matching. + + import { readFile } from "node:fs/promises"; + + import { InferenceClient } from "@digitalocean/dots"; + + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + + // Step 1: reserve the upload slot. + + const intent = await client.files.create({ file_name: + "batch_requests.jsonl" }); + + + // Step 2: PUT the JSONL bytes to the presigned URL. + + const body = await readFile("batch_requests.jsonl"); + + const res = await fetch(intent.upload_url, { + method: "PUT", + headers: { "Content-Type": "application/octet-stream" }, + body, + }); + + if (!res.ok) { + throw new Error(`Upload failed: HTTP ${res.status} ${res.statusText}`); + } + + + console.log("uploaded file_id:", intent.file_id); + security: [] + /v1/batches: + post: + operationId: inference_create_batch + summary: Create a Batch Inference Job + description: > + 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`. + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/batch_create_request' + examples: + OpenAI Chat Completions: + value: + file_id: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + provider: openai + endpoint: /v1/chat/completions + completion_window: 24h + request_id: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11 + OpenAI Responses: + value: + file_id: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + provider: openai + endpoint: /v1/responses + completion_window: 24h + request_id: 9f7b9d4a-4e6c-4a27-8e35-1b0e4c5a9a12 + Anthropic Messages: + value: + file_id: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + provider: anthropic + completion_window: 24h + request_id: 2f1a7d9e-8c03-4d2c-9b7e-6f8e2b1a4c77 + metadata: + team: ml-eval + dataset: prompts_v1 + responses: + '201': + description: Batch job accepted. Poll `GET /v1/batches/{batch_id}` for status. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch' + '400': + $ref: '#/components/responses/bad_request' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '409': + $ref: '#/components/responses/conflict' + '422': + $ref: '#/components/responses/unprocessable_entity' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + # OpenAI provider — endpoint required (/v1/responses or + /v1/chat/completions) + + curl -sS -X POST "https://inference.do-ai.run/v1/batches" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "file_id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678", + "provider": "openai", + "endpoint": "/v1/chat/completions", + "completion_window": "24h", + "request_id": "c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11" + }' + + # Anthropic provider — DO NOT send endpoint + + curl -sS -X POST "https://inference.do-ai.run/v1/batches" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "file_id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678", + "provider": "anthropic", + "completion_window": "24h", + "request_id": "2f1a7d9e-8c03-4d2c-9b7e-6f8e2b1a4c77" + }' + - lang: Python + source: |- + import os + import uuid + + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + batch = client.batches.create( + file_id=os.environ["BATCH_INPUT_FILE_ID"], + provider="openai", + endpoint="/v1/chat/completions", + completion_window="24h", + request_id=str(uuid.uuid4()), + ) + + print("batch_id:", batch.get("batch_id")) + print("status: ", batch.get("status")) + - lang: JavaScript + source: |- + import { randomUUID } from "node:crypto"; + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const batch = await client.batches.create({ + file_id: process.env.BATCH_INPUT_FILE_ID, + provider: "openai", + endpoint: "/v1/chat/completions", + completion_window: "24h", + request_id: randomUUID(), + }); + + console.log("batch_id:", batch.batch_id); + console.log("status: ", batch.status); + security: + - inference_bearer_auth: [] + get: + operationId: inference_list_batches + summary: List Batch Inference Jobs + description: > + 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. + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + parameters: + - in: query + name: after + description: > + Cursor for pagination. Pass the `last_id` value from the previous + response to fetch the next page. Omit for the first page. + required: false + schema: + type: string + format: uuid + example: 7b2e9c1a-6f4d-4d9b-a0f1-5c4b7e2f8a12 + - in: query + name: limit + description: Maximum number of batches to return per page. + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + example: 20 + - in: query + name: status + description: > + Optional filter restricting results to batches in the given + lifecycle state. + required: false + schema: + type: string + enum: + - validating + - in_progress + - finalizing + - completed + - failed + - expired + - cancelling + - cancelled + example: in_progress + responses: + '200': + description: Page of batch jobs. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch_list_response' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: |- + curl -sS -X GET "https://inference.do-ai.run/v1/batches?limit=20" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" | jq + - lang: Python + source: |- + import os + + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + resp = client.batches.list(limit=20) + + for b in resp.get("data") or []: + print(f"{b.get('batch_id'):40} {b.get('status'):12} {b.get('created_at')}") + + print("has_more:", resp.get("has_more")) + print("last_id: ", resp.get("last_id")) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const page = await client.batches.list({ limit: 20 }); + + for (const b of page.data ?? []) { + console.log(`${b.batch_id}\t${b.status}\t${b.created_at}`); + } + + console.log("has_more:", page.has_more); + console.log("last_id: ", page.last_id); + security: + - inference_bearer_auth: [] + /v1/batches/{batch_id}: + get: + operationId: inference_get_batch + summary: Retrieve a Batch Inference Job + description: > + Returns the current state of a batch job. Poll until `status` reaches a + terminal value (`completed`, `failed`, `expired`, or `cancelled`). + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + parameters: + - in: path + name: batch_id + description: The batch job identifier. + required: true + schema: + type: string + format: uuid + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + responses: + '200': + description: The batch job. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -sS -X GET + "https://inference.do-ai.run/v1/batches/0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21" + \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" + - lang: Python + source: |- + import os + + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + batch = client.batches.retrieve(os.environ["BATCH_ID"]) + + print("batch_id: ", batch.get("batch_id")) + print("status: ", batch.get("status")) + print("request_counts:", batch.get("request_counts")) + print("output_file_id:", batch.get("output_file_id")) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const batch = await client.batches.retrieve(process.env.BATCH_ID); + + console.log("batch_id: ", batch.batch_id); + console.log("status: ", batch.status); + console.log("request_counts:", batch.request_counts); + console.log("output_file_id:", batch.output_file_id); + security: + - inference_bearer_auth: [] + /v1/batches/{batch_id}/results: + get: + operationId: inference_get_batch_results + summary: Get Batch Inference Results Download Links + description: > + 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. + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + parameters: + - in: path + name: batch_id + description: The batch job identifier. + required: true + schema: + type: string + format: uuid + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + responses: + '200': + description: Presigned download URLs. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch_results_response' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '412': + description: Results are not yet available. Poll batch status and retry. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: precondition_failed + message: >- + Batch results are not yet available. Retry once the job has + completed. + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -sS -X GET + "https://inference.do-ai.run/v1/batches/0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21/results" + \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" | jq + - lang: Python + source: |- + import os + from pathlib import Path + + import requests + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + batch_id = os.environ["BATCH_ID"] + + links = client.batches.results.retrieve(batch_id) + + if not links.get("result_available"): + print("results not ready yet; poll batch status and retry") + raise SystemExit(0) + + resp = requests.get(links["output_file_url"], timeout=60) + resp.raise_for_status() + + out = Path("batch_output.jsonl") + out.write_bytes(resp.content) + + print("wrote:", out) + print("----- preview -----") + print(resp.text[:500]) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const batchId = process.env.BATCH_ID; + + // client.files.content resolves the result envelope and follows the + // presigned URL for you, returning the raw fetch Response. + const resp = await client.files.content(batchId); + if (!resp.ok) { + throw new Error(`results not ready: HTTP ${resp.status}`); + } + + const body = await resp.text(); + const lines = body.split("\n").filter(Boolean); + + console.log(`got ${lines.length} line(s); first entry:`); + console.log(lines[0]); + security: + - inference_bearer_auth: [] + /v1/batches/{batch_id}/cancel: + post: + operationId: inference_cancel_batch + summary: Cancel a Batch Inference Job + description: > + 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`. + tags: + - Batch Inference + servers: + - url: https://inference.do-ai.run + description: production + x-inference-base-url: https://inference.do-ai.run + parameters: + - in: path + name: batch_id + description: The batch job identifier. + required: true + schema: + type: string + format: uuid + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + responses: + '200': + description: Cancellation accepted. Returns the updated batch job. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/batch' + '401': + $ref: '#/components/responses/unauthorized' + '403': + $ref: '#/components/responses/forbidden' + '404': + $ref: '#/components/responses/not_found' + '409': + $ref: '#/components/responses/conflict' + '429': + $ref: '#/components/responses/too_many_requests' + '500': + $ref: '#/components/responses/server_error' + default: + $ref: '#/components/responses/unexpected_error' + x-codeSamples: + - lang: cURL + source: >- + curl -sS -X POST + "https://inference.do-ai.run/v1/batches/0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21/cancel" + \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + -H "Content-Type: application/json" | jq + - lang: Python + source: |- + import os + + from pydo import Client + + client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) + + result = client.batches.cancel(os.environ["BATCH_ID"]) + + print("batch_id: ", result.get("batch_id")) + print("status: ", result.get("status")) + print("cancelled_at:", result.get("cancelled_at")) + - lang: JavaScript + source: |- + import { InferenceClient } from "@digitalocean/dots"; + + const client = new InferenceClient({ + apiKey: process.env.DIGITALOCEAN_TOKEN, + }); + + const result = await client.batches.cancel(process.env.BATCH_ID); + + console.log("batch_id: ", result.batch_id); + console.log("status: ", result.status); + console.log("cancelled_at:", result.cancelled_at); + security: + - inference_bearer_auth: [] +components: + securitySchemes: + bearer_auth: + type: http + scheme: bearer + description: > + ## OAuth Authentication + + + In order to interact with the DigitalOcean API, you or your application + must + + authenticate. + + + The DigitalOcean API handles this through OAuth, an open standard for + + authorization. OAuth allows you to delegate access to your account. + + Scopes can be used to grant full access, read-only access, or access to + + a specific set of endpoints. + + + You can generate an OAuth token by visiting the [Apps & + API](https://cloud.digitalocean.com/account/api/tokens) + + section of the DigitalOcean control panel for your account. + + + An OAuth token functions as a complete authentication request. In + effect, it + + acts as a substitute for a username and password pair. + + + Because of this, it is absolutely **essential** that you keep your OAuth + + tokens secure. In fact, upon generation, the web interface will only + display + + each token a single time in order to prevent the token from being + compromised. + + + DigitalOcean access tokens begin with an identifiable prefix in order to + + distinguish them from other similar tokens. + + + - `dop_v1_` for personal access tokens generated in the control panel + + - `doo_v1_` for tokens generated by applications using [the OAuth + flow](https://docs.digitalocean.com/reference/api/oauth-api/) + + - `dor_v1_` for OAuth refresh tokens + + + ### Scopes + + + Scopes act like permissions assigned to an API token. These permissions + + determine what actions the token can perform. You can create API + + tokens that grant read-only access, full access, or limited access to + + specific endpoints by using custom scopes. + + + Generally, scopes are designed to match HTTP verbs and common CRUD + + operations (Create, Read, Update, Delete). + + + | HTTP Verb | CRUD Operation | Scope | + + |---|---|---| + + | GET | Read | `:read` | + + | POST | Create | `:create` | + + | PUT/PATCH | Update | `:update` | + + | DELETE | Delete | `:delete` | + + + For example, creating a new Droplet by making a `POST` request to the + + `/v2/droplets` endpoint requires the `droplet:create` scope while + + listing Droplets by making a `GET` request to the `/v2/droplets` + + endpoint requires the `droplet:read` scope. + + + Each endpoint below specifies which scope is required to access it when + + using custom scopes. + + + ### How to Authenticate with OAuth + + + In order to make an authenticated request, include a bearer-type + + `Authorization` header containing your OAuth token. All requests must be + + made over HTTPS. + + + ### Authenticate with a Bearer Authorization Header + + + ``` + + curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" + "https://api.digitalocean.com/v2/$OBJECT" + + ``` + inference_bearer_auth: + type: http + scheme: bearer + description: > + ## OAuth Authentication + + + In order to interact with the DigitalOcean API, you or your application + must + + authenticate. + + + The DigitalOcean API handles this through OAuth, an open standard for + + authorization. OAuth allows you to delegate access to your account. + + Scopes can be used to grant full access, read-only access, or access to + + a specific set of endpoints. + + + You can generate an OAuth token by visiting the [Apps & + API](https://cloud.digitalocean.com/account/api/tokens) + + section of the DigitalOcean control panel for your account. + + + An OAuth token functions as a complete authentication request. In + effect, it + + acts as a substitute for a username and password pair. + + + Because of this, it is absolutely **essential** that you keep your OAuth + + tokens secure. In fact, upon generation, the web interface will only + display + + each token a single time in order to prevent the token from being + compromised. + + + DigitalOcean access tokens begin with an identifiable prefix in order to + + distinguish them from other similar tokens. + + + - `dop_v1_` for personal access tokens generated in the control panel + + - `doo_v1_` for tokens generated by applications using [the OAuth + flow](https://docs.digitalocean.com/reference/api/oauth-api/) + + - `dor_v1_` for OAuth refresh tokens + + + ### Authenticate with a Bearer Authorization Header + + + **Serverless Inference:** + + + ``` + + curl -X POST -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" + "https://inference.do-ai.run/v1/chat/completions" + + ``` + + + **Agent Inference:** + + + ``` + + curl -X POST -H "Authorization: Bearer $AGENT_ACCESS_KEY" + "https://{your-agent-url}.agents.do-ai.run/v1/chat/completions?agent=true" + + ``` + + + **Note:** Agent Inference APIs use an `agent_access_key` (endpoint + access + + key) instead of a DigitalOcean OAuth token. The `agent_access_key` is + + provided when you provision an agent endpoint and is scoped to that + + specific agent. It is not interchangeable with DigitalOcean OAuth tokens + + (`dop_v1_*`, `doo_v1_*`, `dor_v1_*`), which are used with Serverless + + Inference and the control-plane API at `https://api.digitalocean.com`. + parameters: + oneClicks_type: + in: query + name: type + description: Restrict results to a certain type of 1-Click. + required: false + schema: + type: string + enum: + - droplet + - kubernetes + example: kubernetes + per_page: + in: query + name: per_page + required: false + description: Number of items returned per page + schema: + type: integer + minimum: 1 + default: 20 + maximum: 200 + example: 2 + page: + in: query + name: page + required: false + description: Which 'page' of paginated results to return. + schema: + type: integer + minimum: 1 + default: 1 + example: 1 + ssh_key_identifier: + in: path + name: ssh_key_identifier + required: true + description: Either the ID or the fingerprint of an existing SSH key. + schema: + anyOf: + - $ref: '#/components/schemas/ssh_key_id' + - $ref: '#/components/schemas/ssh_key_fingerprint' + example: 512189 + action_id: + in: path + name: action_id + description: >- + A unique numeric ID that can be used to identify and reference an + action. + required: true + schema: + type: integer + minimum: 1 + example: 36804636 + resource_uuid: + name: resource_uuid + in: path + description: A unique identifier for the add-on resource. + required: true + schema: + type: string + format: uuid + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + with_projects: + description: Whether the project_id of listed apps should be fetched and included. + in: query + name: with_projects + schema: + type: boolean + example: true + accept: + description: >- + The content-type that should be used by the response. By default, the + response will be `application/json`. `application/yaml` is also + supported. + in: header + name: Accept + schema: + type: string + enum: + - application/json + - application/yaml + example: application/json + content-type: + description: >- + The content-type used for the request. By default, the requests are + assumed to use `application/json`. `application/yaml` is also supported. + in: header + name: Content-Type + schema: + type: string + enum: + - application/json + - application/yaml + example: application/json + id_app: + description: The ID of the app + in: path + name: id + required: true + schema: + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + app_name: + description: The name of the app to retrieve. + in: query + name: name + schema: + type: string + example: myApp + app_id: + description: The app ID + in: path + name: app_id + required: true + schema: + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + component: + description: >- + An optional component name. If set, logs will be limited to this + component only. + in: path + name: component_name + required: true + schema: + type: string + example: component + live_updates: + description: Whether the logs should follow live updates. + in: query + name: follow + schema: + type: boolean + example: true + log_type: + description: |- + The type of logs to retrieve + - BUILD: Build-time logs + - DEPLOY: Deploy-time logs + - RUN: Live run-time logs + - RUN_RESTARTED: Logs of crashed/restarted instances during runtime + - AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id) + in: query + name: type + required: true + schema: + default: UNSPECIFIED + enum: + - UNSPECIFIED + - BUILD + - DEPLOY + - RUN + - RUN_RESTARTED + - AUTOSCALE_EVENT + type: string + example: BUILD + time_wait: + description: >- + An optional time duration to wait if the underlying component instance + is not immediately available. Default: `3m`. + in: query + name: pod_connection_timeout + schema: + type: string + example: 3m + instance_name: + description: The name of the actively running ephemeral compute instance + in: query + name: instance_name + required: false + schema: + type: string + example: go-app-d768568df-zz77d + deployment_id: + description: The deployment ID + in: path + name: deployment_id + required: true + schema: + type: string + example: 3aa4d20e-5527-4c00-b496-601fbd22520a + job_names: + description: The job names to list job invocations for. + in: query + name: job_names + required: false + schema: + type: array + items: + $ref: '#/components/schemas/schema' + example: + - component1 + - component2 + job_invocation_id: + description: The ID of the job invocation to retrieve. + in: path + name: job_invocation_id + required: true + schema: + type: string + example: 123e4567-e89b-12d3-a456-426 + job_name: + description: The job name to list job invocations for. + in: query + name: job_name + required: false + schema: + type: string + example: component + number_lines: + description: The number of lines from the end of the logs to retrieve. + in: query + name: tail_lines + required: false + schema: + type: string + format: int64 + example: '100' + event_id: + description: The event ID + in: path + name: event_id + required: true + schema: + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + slug_size: + description: The slug of the instance size + in: path + name: slug + required: true + schema: + type: string + example: apps-s-1vcpu-0.5gb + alert_id: + description: The alert ID + in: path + name: alert_id + required: true + schema: + type: string + example: 5a624ab5-dd58-4b39-b7dd-8b7c36e8a91d + cdn_endpoint_id: + in: path + name: cdn_id + description: A unique identifier for a CDN endpoint. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: 19f06b6a-3ace-4315-b086-499a0e521b76 + certificate_name: + name: name + in: query + description: Name of expected certificate + required: false + schema: + type: string + default: '' + example: certificate-name + certificate_id: + in: path + name: certificate_id + description: A unique identifier for a certificate. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + invoice_uuid: + name: invoice_uuid + description: UUID of the invoice + in: path + schema: + type: string + example: 22737513-0ea7-4206-8ceb-98a575af7681 + required: true + account_urn: + name: account_urn + description: >- + URN of the customer account, can be a team (do:team:uuid) or an + organization (do:teamgroup:uuid) + in: path + schema: + type: string + example: do:team:12345678-1234-1234-1234-123456789012 + required: true + start_date: + name: start_date + description: Start date for billing insights in YYYY-MM-DD format + in: path + schema: + type: string + format: date + example: '2025-01-01' + required: true + end_date: + name: end_date + description: >- + End date for billing insights in YYYY-MM-DD format. Must be within 31 + days of start_date + in: path + schema: + type: string + format: date + example: '2025-01-31' + required: true + tag_name: + in: query + name: tag_name + description: >- + Limits the results to database clusters with a specific + tag.

Requires `tag:read` scope. + required: false + example: production + schema: + type: string + database_cluster_uuid: + in: path + name: database_cluster_uuid + description: A unique identifier for a database cluster. + required: true + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + schema: + type: string + format: uuid + migration_id: + in: path + name: migration_id + description: A unique identifier assigned to the online migration. + required: true + example: 77b28fc8-19ff-11eb-8c9c-c68e24557488 + schema: + type: string + replica_name: + in: path + name: replica_name + description: The name of the database replica. + required: true + example: read-nyc3-01 + schema: + type: string + username: + in: path + name: username + description: The name of the database user. + required: true + example: app-01 + schema: + type: string + database_name: + in: path + name: database_name + description: The name of the database. + required: true + example: alpha + schema: + type: string + pool_name: + in: path + name: pool_name + description: The name used to identify the connection pool. + required: true + example: backend-pool + schema: + type: string + kafka_topic_name: + in: path + name: topic_name + description: The name used to identify the Kafka topic. + required: true + example: customer-events + schema: + type: string + logsink_id: + in: path + name: logsink_id + description: A unique identifier for a logsink of a database cluster + required: true + example: 50484ec3-19d6-4cd3-b56f-3b0381c289a6 + schema: + type: string + kafka_schema_subject_name: + in: path + name: subject_name + description: The name of the Kafka schema subject. + required: true + example: customer-schema + schema: + type: string + kafka_schema_version: + in: path + name: version + description: The version of the Kafka schema subject. + required: true + example: '1' + schema: + type: string + opensearch_index_name: + in: path + name: index_name + description: The name of the OpenSearch index. + required: true + example: logs-* + schema: + type: string + dedicated_inference_id: + name: dedicated_inference_id + in: path + required: true + description: A unique identifier for a Dedicated Inference instance. + schema: + type: string + format: uuid + example: 6b5c619c-359c-44ca-87e2-47e98170c01d + region: + name: region + in: query + required: false + description: >- + Filter by region. Dedicated Inference is only available in nyc2, tor1, + and atl1. + schema: + type: string + enum: + - nyc2 + - tor1 + - atl1 + example: atl1 + accelerator_id: + name: accelerator_id + in: path + required: true + description: A unique identifier for a Dedicated Inference accelerator. + schema: + type: string + format: uuid + example: 5b5c619c-359c-44ca-87e2-47e98170c02f + token_id: + name: token_id + in: path + required: true + description: A unique identifier for a Dedicated Inference access token. + schema: + type: string + format: uuid + example: f11d4795-c1db-4ac3-9aa6-a0ea3c58877e + domain_name: + name: domain_name + description: The name of the domain itself. + in: path + schema: + type: string + example: example.com + required: true + domain_name_query: + name: name + description: >- + 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`. + in: query + schema: + type: string + example: sub.example.com + domain_type_query: + name: type + description: 'The type of the DNS record. For example: A, CNAME, TXT, ...' + in: query + schema: + type: string + enum: + - A + - AAAA + - CAA + - CNAME + - MX + - NS + - SOA + - SRV + - TXT + example: A + domain_record_id: + name: domain_record_id + description: The unique identifier of the domain record. + in: path + schema: + type: integer + example: 3352896 + required: true + droplet_tag_name: + in: query + name: tag_name + description: >- + Used to filter Droplets by a specific tag. Can not be combined with + `name` or `type`.
Requires `tag:read` scope. + required: false + schema: + type: string + example: env:prod + droplet_name: + in: query + name: name + description: >- + Used to filter list response by Droplet name returning only exact + matches. It is case-insensitive and can not be combined with `tag_name`. + required: false + schema: + type: string + example: web-01 + droplet_type: + in: query + name: type + description: >- + When `type` is set to `gpus`, only GPU Droplets will be returned. By + default, only non-GPU Droplets are returned. Can not be combined with + `tag_name`. + required: false + schema: + type: string + enum: + - droplets + - gpus + example: droplets + droplet_delete_tag_name: + in: query + name: tag_name + description: Specifies Droplets to be deleted by tag. + required: true + schema: + type: string + example: env:test + droplet_id: + in: path + name: droplet_id + description: A unique identifier for a Droplet instance. + required: true + schema: + type: integer + minimum: 1 + example: 3164444 + x_dangerous: + in: header + name: X-Dangerous + description: >- + Acknowledge this action will destroy the Droplet and all associated + resources and _can not_ be reversed. + schema: + type: boolean + example: true + required: true + autoscale_pool_name: + name: name + in: query + description: The name of the autoscale pool + schema: + type: string + example: my-autoscale-pool + autoscale_pool_id: + in: path + name: autoscale_pool_id + description: A unique identifier for an autoscale pool. + required: true + schema: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + parameters_x_dangerous: + in: header + name: X-Dangerous + description: >- + Acknowledge this action will destroy the autoscale pool and its + associated resources and _can not_ be reversed. + schema: + type: boolean + example: true + required: true + firewall_id: + name: firewall_id + description: A unique ID that can be used to identify and reference a firewall. + in: path + schema: + type: string + format: uuid + example: bb4b2611-3d72-467b-8602-280330ecd65c + required: true + floating_ip: + in: path + name: floating_ip + description: A floating IP address. + required: true + schema: + type: string + format: ipv4 + minimum: 1 + example: 45.55.96.47 + namespace_id: + name: namespace_id + description: The ID of the namespace to be managed. + in: path + schema: + type: string + example: fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + required: true + trigger_name: + name: trigger_name + description: The name of the trigger to be managed. + in: path + schema: + type: string + example: my trigger + required: true + key_id: + name: key_id + description: The ID of the access key to be managed. + in: path + schema: + type: string + example: dof-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + required: true + type: + in: query + name: type + description: >- + Filters results based on image type which can be either `application` or + `distribution`. + required: false + schema: + type: string + enum: + - application + - distribution + example: distribution + private: + in: query + name: private + description: Used to filter only user images. + required: false + schema: + type: boolean + example: true + tag: + in: query + name: tag_name + description: Used to filter images by a specific tag. + required: false + schema: + type: string + example: base-image + image_id: + in: path + name: image_id + description: >- + A unique number that can be used to identify and reference a specific + image. + required: true + schema: + type: integer + example: 62137902 + kubernetes_cluster_id: + in: path + name: cluster_id + description: A unique ID that can be used to reference a Kubernetes cluster. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: bd5f5959-5e1e-4205-a714-a914373942af + kubernetes_expiry_seconds: + in: query + name: expiry_seconds + required: false + description: >- + The duration in seconds that the returned Kubernetes credentials will be + valid. If not set or 0, the credentials will have a 7 day expiry. + schema: + type: integer + minimum: 0 + default: 0 + example: 300 + kubernetes_node_pool_id: + in: path + name: node_pool_id + description: A unique ID that can be used to reference a Kubernetes node pool. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: cdda885e-7663-40c8-bc74-3a036c66545d + kubernetes_node_id: + in: path + name: node_id + description: >- + A unique ID that can be used to reference a node in a Kubernetes node + pool. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + kubernetes_node_skip_drain: + in: query + name: skip_drain + required: false + description: >- + Specifies whether or not to drain workloads from a node before it is + deleted. Setting it to `1` causes node draining to be skipped. Omitting + the query parameter or setting its value to `0` carries out draining + prior to deletion. + schema: + type: integer + minimum: 0 + maximum: 1 + default: 0 + example: 1 + kubernetes_node_replace: + in: query + name: replace + required: false + description: >- + Specifies whether or not to replace a node after it has been deleted. + Setting it to `1` 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. + schema: + type: integer + minimum: 0 + maximum: 1 + default: 0 + example: 1 + clusterlint_run_id: + in: query + name: run_id + description: Specifies the clusterlint run whose results will be retrieved. + required: false + schema: + type: string + format: uuid + example: 50c2f44c-011d-493e-aee5-361a4a0d1844 + kubernetes_status_messages_since: + in: query + name: since + required: false + description: >- + A timestamp used to return status messages emitted since the specified + time. The timestamp should be in ISO8601 format. + schema: + type: string + format: date-time + example: '2018-11-15T16:00:11Z' + load_balancer_id: + in: path + name: lb_id + description: A unique identifier for a load balancer. + required: true + schema: + type: string + minimum: 1 + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + alert_uuid: + in: path + name: alert_uuid + description: A unique identifier for an alert policy. + required: true + schema: + type: string + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + parameters_droplet_id: + in: query + name: host_id + description: The droplet ID. + example: '17209102' + required: true + schema: + type: string + network_interface: + in: query + name: interface + description: The network interface. + required: true + example: private + schema: + type: string + enum: + - private + - public + network_direction: + in: query + name: direction + description: The traffic direction. + required: true + example: inbound + schema: + type: string + enum: + - inbound + - outbound + metric_timestamp_start: + in: query + name: start + description: UNIX timestamp to start metric window. + example: '1620683817' + required: true + schema: + type: string + metric_timestamp_end: + in: query + name: end + description: UNIX timestamp to end metric window. + example: '1620705417' + required: true + schema: + type: string + parameters_app_id: + in: query + name: app_id + description: The app UUID. + example: 2db3c021-15ad-4088-bfe8-99dc972b9cf6 + required: true + schema: + type: string + app_component: + in: query + name: app_component + description: The app component name. + example: sample-application + required: false + schema: + type: string + parameters_load_balancer_id: + in: query + name: lb_id + description: A unique identifier for a load balancer. + required: true + schema: + type: string + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + parameters_autoscale_pool_id: + in: query + name: autoscale_pool_id + description: A unique identifier for an autoscale pool. + required: true + schema: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + db_id: + in: query + name: db_id + required: true + description: The DBaaS cluster UUID (database ID). + schema: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + aggregate_avg_max_min: + in: query + name: aggregate + required: true + description: Aggregation over the time range (avg, max, or min). + schema: + type: string + enum: + - avg + - max + - min + example: avg + metric_load: + in: query + name: metric + required: true + description: >- + Load window: **load1** (1-minute), **load5** (5-minute), **load15** + (15-minute). The value is either average or max over that window, + depending on the **aggregate** parameter (avg or max). + schema: + type: string + enum: + - load1 + - load5 + - load15 + example: load1 + aggregate_avg_max: + in: query + name: aggregate + required: true + description: Aggregation over the time range (avg or max). + schema: + type: string + enum: + - avg + - max + example: avg + metric_op_rates: + in: query + name: metric + required: true + description: Operation type (select, insert, update, or delete). + schema: + type: string + enum: + - select + - insert + - update + - delete + example: select + schema: + in: query + name: schema + required: true + description: The schema (database) name. + schema: + type: string + example: defaultdb + metric_schema_io: + in: query + name: metric + required: true + description: Table I/O operation (insert, fetch, update, or delete). + schema: + type: string + enum: + - insert + - fetch + - update + - delete + example: insert + destination_uuid: + in: path + name: destination_uuid + description: A unique identifier for a destination. + required: true + schema: + type: string + example: 1a64809f-1708-48ee-a742-dec8d481b8d1 + resource_id: + in: query + name: resource_id + description: A unique URN for a resource. + schema: + $ref: '#/components/schemas/urn' + example: do:kubernetes:5ba4518b-b9e2-4978-aa92-2d4c727e8824 + sink_uuid: + in: path + name: sink_uuid + description: A unique identifier for a sink. + required: true + schema: + type: string + example: 78b172b6-52c3-4a4b-96d5-78d3f1a0b18c + parameters_region: + in: query + name: region + description: >- + The DigitalOcean region slug (e.g., nyc2, atl1) where the NFS share + resides. + schema: + type: string + example: atl1 + nfs_id: + in: path + name: nfs_id + description: The unique ID of the NFS share + required: true + schema: + type: string + example: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + share_id: + in: query + name: share_id + required: false + description: >- + The unique ID of an NFS share. If provided, only snapshots of this + specific share will be returned. + schema: + type: string + example: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + nfs_snapshot_id: + in: path + name: nfs_snapshot_id + description: The unique ID of the NFS snapshot + required: true + schema: + type: string + example: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + pa_id: + in: path + name: pa_id + description: A unique identifier for a partner attachment. + required: true + schema: + type: string + format: string + minimum: 1 + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + project_id: + in: path + name: project_id + description: A unique identifier for a project. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + registry_name: + in: path + name: registry_name + description: The name of a container registry. + required: true + schema: + type: string + example: example + garbage_collection_uuid: + in: path + name: garbage_collection_uuid + description: The UUID of a garbage collection run. + required: true + schema: + type: string + example: eff0feee-49c7-4e8f-ba5c-a320c109c8a8 + token_pagination_page: + in: query + name: page + required: false + description: >- + Which 'page' of paginated results to return. Ignored when 'page_token' + is provided. + schema: + type: integer + minimum: 1 + default: 1 + example: 1 + token_pagination_page_token: + in: query + name: page_token + required: false + description: >- + Token to retrieve of the next or previous set of results more quickly + than using 'page'. + schema: + type: string + example: eyJUb2tlbiI6IkNnZGpiMjlz + registry_repository_name: + in: path + name: repository_name + description: >- + The name of a container registry repository. If the name contains `/` + characters, they must be URL-encoded, e.g. `%2F`. + required: true + schema: + type: string + example: repo-1 + registry_repository_tag: + in: path + name: repository_tag + description: The name of a container registry repository tag. + required: true + schema: + type: string + example: 06a447a + registry_manifest_digest: + in: path + name: manifest_digest + description: The manifest digest of a container registry repository tag. + required: true + schema: + type: string + example: sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + registry_expiry_seconds: + in: query + name: expiry_seconds + required: false + description: >- + The duration in seconds that the returned registry credentials will be + valid. If not set or 0, the credentials will not expire. + schema: + type: integer + minimum: 0 + default: 0 + example: 3600 + registry_read_write: + in: query + name: read_write + required: false + description: >- + By default, the registry credentials allow for read-only access. Set + this query parameter to `true` to obtain read-write credentials. + schema: + type: boolean + default: false + example: true + reserved_ip: + in: path + name: reserved_ip + description: A reserved IP address. + required: true + schema: + type: string + format: ipv4 + minimum: 1 + example: 45.55.96.47 + reserved_ipv6: + in: path + name: reserved_ipv6 + description: A reserved IPv6 address. + required: true + schema: + type: string + format: ipv6 + minimum: 1 + example: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + byoip_prefix: + in: path + name: byoip_prefix_uuid + description: The unique identifier for the BYOIP Prefix. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: f47ac10b-58cc-4372-a567-0e02b2c3d479 + scan_id: + in: path + name: scan_id + description: The scan UUID. + required: true + schema: + type: string + format: uuid + example: 497dcba3-ecbf-4587-a2dd-5eb0665e6880 + severity: + in: query + name: severity + required: false + description: The finding severity level to include. + schema: + type: string + enum: + - LOW + - MEDIUM + - HIGH + - CRITICAL + example: CRITICAL + finding_uuid: + in: path + name: finding_uuid + description: The finding UUID. + required: true + schema: + type: string + format: uuid + example: 50e14f43-dd4e-412f-864d-78943ea28d91 + suppression_uuid: + in: path + name: suppression_uuid + description: The suppression UUID to remove. + required: true + schema: + type: string + format: uuid + example: 5b3b2b2d-5c9c-4a61-9e2f-4d8f80f30a12 + snapshot_resource_type: + in: query + name: resource_type + description: Used to filter snapshots by a resource type. + required: false + schema: + type: string + enum: + - droplet + - volume + example: droplet + snapshot_id: + in: path + name: snapshot_id + required: true + description: >- + Either the ID of an existing snapshot. This will be an integer for a + Droplet snapshot or a string for a volume snapshot. + schema: + anyOf: + - type: integer + description: The ID of a Droplet snapshot. + example: 6372321 + - type: string + description: The ID of a volume snapshot. + example: fbe805e8-866b-11e6-96bf-000f53315a41 + example: 6372321 + sort: + in: query + name: sort + required: false + description: The field to sort by. + schema: + type: string + default: created_at + example: created_at + sort_direction: + in: query + name: sort_direction + required: false + description: The direction to sort by. Possible values are `asc` or `desc`. + schema: + type: string + default: desc + example: desc + name: + in: query + name: name + required: false + description: The access key's name. + schema: + type: string + example: my-access-key + bucket: + in: query + name: bucket + required: false + description: The bucket's name. + schema: + type: string + example: my-bucket + permission: + in: query + name: permission + required: false + description: >- + The permission of the access key. Possible values are `read`, + `readwrite`, `fullaccess`, or an empty string. + schema: + type: string + example: read + access_key_id: + in: path + name: access_key + description: The access key's ID. + required: true + schema: + type: string + example: DOACCESSKEYEXAMPLE + tag_id: + in: path + name: tag_id + description: >- + The name of the tag. Tags may contain letters, numbers, colons, dashes, + and underscores. There is a limit of 255 characters per tag. + required: true + schema: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9_\-\:]+$ + example: awesome + volume_name: + name: name + in: query + description: The block storage volume's name. + schema: + type: string + example: example + parameters_region-2: + name: region + in: query + description: The slug identifier for the region where the resource is available. + schema: + $ref: '#/components/schemas/region_slug' + example: nyc3 + volume_snapshot_id: + name: snapshot_id + in: path + description: The unique identifier for the snapshot. + schema: + type: string + required: true + example: fbe805e8-866b-11e6-96bf-000f53315a41 + volume_id: + name: volume_id + in: path + required: true + description: The ID of the block storage volume. + schema: + type: string + format: uuid + example: 7724db7c-e098-11e5-b522-000f53304e51 + vpc_id: + in: path + name: vpc_id + description: A unique identifier for a VPC. + required: true + schema: + type: string + format: uuid + minimum: 1 + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + vpc_resource_type: + in: query + name: resource_type + description: Used to filter VPC members by a resource type. + required: false + schema: + type: string + example: droplet + vpc_peering_id: + in: path + name: vpc_peering_id + description: A unique identifier for a VPC peering. + required: true + schema: + type: string + format: uuid + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + vpc_nat_gateway_state: + in: query + name: state + description: The current state of the VPC NAT gateway. + schema: + type: string + enum: + - new + - provisioning + - active + - deleting + - error + - invalid + example: active + vpc_nat_gateway_region: + in: query + name: region + description: The region where the VPC NAT gateway is located. + schema: + type: string + enum: + - nyc1 + - nyc2 + - nyc3 + - ams2 + - ams3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - lon1 + - fra1 + - tor1 + - blr1 + - syd1 + - atl1 + example: tor1 + vpc_nat_gateway_type: + in: query + name: type + description: The type of the VPC NAT gateway. + schema: + type: string + enum: + - public + example: public + vpc_nat_gateway_name: + in: query + name: name + description: The name of the VPC NAT gateway. + schema: + type: string + example: my-vpc-nat-gateway + vpc_nat_gateway_id: + in: path + name: id + description: The unique identifier of the VPC NAT gateway. + required: true + schema: + type: string + example: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + check_id: + in: path + name: check_id + description: A unique identifier for a check. + required: true + schema: + type: string + format: uuid + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + parameters_alert_id: + in: path + name: alert_id + description: A unique identifier for an alert. + required: true + schema: + type: string + format: uuid + example: 17f0f0ae-b7e5-4ef6-86e3-aa569db58284 + headers: + ratelimit-limit: + schema: + type: integer + example: 5000 + description: >- + The default limit on number of requests that can be made per hour and + per minute. Current rate limits are 5000 requests per hour and 250 + requests per minute. + ratelimit-remaining: + schema: + type: integer + example: 4816 + description: >- + The number of requests in your hourly quota that remain before you hit + your request limit. See + https://developers.digitalocean.com/documentation/v2/#rate-limit for + information about how requests expire. + ratelimit-reset: + schema: + type: integer + example: 1444931833 + description: >- + The time when the oldest request will expire. The value is given in Unix + epoch time. See + https://developers.digitalocean.com/documentation/v2/#rate-limit for + information about how requests expire. + content-disposition: + description: >- + Indicates if the content is expected to be displayed *inline* in the + browser, that is, as a Web page or as part of a Web page, or as an + *attachment*, that is downloaded and saved locally. + schema: + type: string + example: >- + attachment; filename="DigitalOcean Invoice 2020 Jul + (6173678-418071234).csv" + content-type: + description: 'The type of data that is returned from a request. ' + schema: + type: string + example: application/json; charset=utf-8 + x-request-id: + description: >- + Optionally, some endpoints may include a request ID that should be + provided when reporting bugs or opening support tickets to help + identify the issue. + schema: + type: string + format: uuid + example: 515850a0-a812-50bf-aa3c-d0d21d287e40 + schemas: + error: + type: object + properties: + id: + description: >- + A short identifier corresponding to the HTTP status code returned. + For example, the ID for a response returning a 404 status code + would be "not_found." + type: string + example: not_found + message: + description: >- + A message providing additional information about the error, + including details to help resolve it when possible. + type: string + example: The resource you were accessing could not be found. + request_id: + description: >- + Optionally, some endpoints may include a request ID that should be + provided when reporting bugs or opening support tickets to help + identify the issue. + type: string + example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9 + required: + - id + - message + oneClicks: + type: object + properties: + slug: + title: slug + type: string + example: monitoring + description: The slug identifier for the 1-Click application. + type: + title: type + type: string + example: kubernetes + description: The type of the 1-Click application. + required: + - slug + - type + oneClicks_create: + type: object + properties: + addon_slugs: + title: addon_slugs + type: array + items: + type: string + example: + - kube-state-metrics + - loki + default: [] + description: >- + An array of 1-Click Application slugs to be installed to the + Kubernetes cluster. + cluster_uuid: + title: cluster_uuid + type: string + example: 50a994b6-c303-438f-9495-7e896cfe6b08 + description: >- + A unique ID for the Kubernetes cluster to which the 1-Click + Applications will be installed. + required: + - addon_slugs + - cluster_uuid + account: + type: object + properties: + droplet_limit: + description: > + The total number of Droplets current user or team may have active at + one time. + +

Requires `droplet:read` scope. + type: integer + example: 25 + floating_ip_limit: + description: | + The total number of Floating IPs the current user or team may have. +

Requires `reserved_ip:read` scope. + type: integer + example: 5 + email: + description: >- + The email address used by the current user to register for + DigitalOcean. + type: string + example: sammy@digitalocean.com + name: + description: The display name for the current user. + type: string + example: Sammy the Shark + uuid: + description: The unique universal identifier for the current user. + type: string + example: b6fr89dbf6d9156cace5f3c78dc9851d957381ef + email_verified: + description: >- + If true, the user has verified their account via email. False + otherwise. + type: boolean + default: false + example: true + status: + description: This value is one of "active", "warning" or "locked". + type: string + enum: + - active + - warning + - locked + default: active + example: active + status_message: + description: >- + A human-readable message giving more details about the status of the + account. + type: string + example: ' ' + team: + type: object + description: >- + When authorized in a team context, includes information about the + current team. + properties: + uuid: + description: The unique universal identifier for the current team. + type: string + example: 5df3e3004a17e242b7c20ca6c9fc25b701a47ece + name: + description: The name for the current team. + type: string + example: My Team + required: + - droplet_limit + - floating_ip_limit + - email + - uuid + - email_verified + - status + - status_message + ssh_key_id: + type: integer + description: >- + A unique identification number for this key. Can be used to embed a + specific SSH key into a Droplet. + readOnly: true + example: 512189 + ssh_key_fingerprint: + type: string + description: >- + A unique identifier that differentiates this key from other keys using + a format that SSH recognizes. The fingerprint is created when the key is + added to your account. + readOnly: true + example: 3b:16:bf:e4:8b:00:8b:b8:59:8c:a9:d3:f0:19:45:fa + ssh_key_name: + type: string + description: >- + A human-readable display name for this key, used to easily identify the + SSH keys when they are displayed. + example: My SSH Public Key + sshKeys: + type: object + properties: + id: + $ref: '#/components/schemas/ssh_key_id' + fingerprint: + $ref: '#/components/schemas/ssh_key_fingerprint' + public_key: + description: >- + The entire public key string that was uploaded. Embedded into the + root user's `authorized_keys` file if you include this key during + Droplet creation. + type: string + example: >- + ssh-rsa + AEXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V + example + name: + $ref: '#/components/schemas/ssh_key_name' + required: + - public_key + - name + link_to_last_page: + type: object + properties: + last: + description: URI of the last page of the results. + type: string + example: https://api.digitalocean.com/v2/images?page=2 + link_to_next_page: + type: object + properties: + next: + description: URI of the next page of the results. + type: string + example: https://api.digitalocean.com/v2/images?page=2 + forward_links: + allOf: + - $ref: '#/components/schemas/link_to_last_page' + - $ref: '#/components/schemas/link_to_next_page' + link_to_first_page: + type: object + properties: + first: + description: URI of the first page of the results. + type: string + example: https://api.digitalocean.com/v2/images?page=1 + link_to_prev_page: + type: object + properties: + prev: + description: URI of the previous page of the results. + type: string + example: https://api.digitalocean.com/v2/images?page=1 + backward_links: + allOf: + - $ref: '#/components/schemas/link_to_first_page' + - $ref: '#/components/schemas/link_to_prev_page' + page_links: + type: object + properties: + pages: + anyOf: + - $ref: '#/components/schemas/forward_links' + - $ref: '#/components/schemas/backward_links' + - {} + example: + pages: + first: https://api.digitalocean.com/v2/account/keys?page=1 + prev: https://api.digitalocean.com/v2/account/keys?page=2 + pagination: + type: object + properties: + links: + $ref: '#/components/schemas/page_links' + meta_properties: + type: object + description: Information about the response itself. + properties: + total: + description: Number of objects returned by the request. + type: integer + example: 1 + meta: + type: object + properties: + meta: + allOf: + - $ref: '#/components/schemas/meta_properties' + - required: + - total + required: + - meta + region: + type: object + properties: + name: + type: string + description: >- + The display name of the region. This will be a full name that is + used in the control panel and other interfaces. + example: New York 3 + slug: + type: string + description: >- + A human-readable string that is used as a unique identifier for each + region. + example: nyc3 + features: + type: array + items: + type: string + description: >- + This attribute is set to an array which contains features available + in this region + example: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: + type: boolean + description: >- + This is a boolean value that represents whether new Droplets can be + created in this region. + example: true + sizes: + type: array + items: + type: string + description: >- + This attribute is set to an array which contains the identifying + slugs for the sizes available in this region. sizes:read is required + to view. + example: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + required: + - available + - features + - name + - sizes + - slug + action: + type: object + properties: + id: + type: integer + description: >- + A unique numeric ID that can be used to identify and reference an + action. + example: 36804636 + status: + type: string + description: >- + The current status of the action. This can be "in-progress", + "completed", or "errored". + enum: + - in-progress + - completed + - errored + example: completed + default: in-progress + type: + type: string + description: >- + This is the type of action that the object represents. For example, + this could be "transfer" to represent the state of an image transfer + action. + example: create + started_at: + type: string + format: date-time + description: >- + A time value given in ISO8601 combined date and time format that + represents when the action was initiated. + example: '2020-11-14T16:29:21Z' + completed_at: + type: string + format: date-time + nullable: true + description: >- + A time value given in ISO8601 combined date and time format that + represents when the action was completed. + example: '2020-11-14T16:30:06Z' + resource_id: + type: integer + nullable: true + description: >- + A unique identifier for the resource that the action is associated + with. + example: 3164444 + resource_type: + type: string + description: The type of resource that the action is associated with. + example: droplet + region: + $ref: '#/components/schemas/region' + region_slug: + type: string + nullable: true + description: >- + A human-readable string that is used as a unique identifier for each + region. + example: nyc3 + addons_feature: + type: object + properties: + id: + title: id + type: integer + example: 1 + description: Unique identifier for the app feature. + name: + title: name + type: string + example: Support + description: Name of the feature. + type: + title: type + type: string + enum: + - unknown + - string + - boolean + - allowance + example: string + description: Feature type, indicating the kind of data it holds. + unit: + title: unit + type: string + enum: + - unit_unknown + - GB + - GIB + - count + - byte + - byte_second + example: GB + description: >- + Unit of measurement for the feature, if applicable. Units apply to + allowance features. + value: + example: Unlimited + oneOf: + - title: string_value + type: string + example: Unlimited + - title: boolean_value + type: boolean + example: true + - title: allowance_value + type: string + example: '1000' + description: Value of the feature, which can vary based on the type. + created_at: + title: created_at + type: string + format: date-time + example: '2023-10-01T12:00:00Z' + description: Timestamp when the feature was created. + updated_at: + title: updated_at + type: string + format: date-time + example: '2023-10-01T12:00:00Z' + description: Timestamp when the feature was last updated. + required: + - id + - name + - type + - value + - created_at + - updated_at + addons_dimension_volume_with_price: + type: object + properties: + id: + title: id + type: integer + example: 123 + description: Unique identifier for the addon. + low_volume: + title: low_volume + type: integer + example: 1 + description: The minimum volume for the volume pricing tier. + max_volume: + title: max_volume + type: integer + example: 100 + description: The maximum volume for the volume pricing tier. + price_per_unit: + title: price_per_unit + type: string + example: '0.10' + description: The price per unit for the volume tier in US dollars. + required: + - id + - low_volume + - max_volume + - price_per_unit + addons_dimension_with_price: + type: object + properties: + id: + title: id + type: integer + example: 1 + description: Unique identifier for the dimension. + sku: + title: sku + type: string + example: addon_sku_123 + description: Unique string identifier for the dimension, tied to a price. + slug: + title: slug + type: string + example: addon_dimension_slug + description: Slug identifier for the dimension. + display_name: + title: display_name + type: string + example: Addon Dimension Display Name + description: Display name for the dimension. + feature_name: + title: feature_name + type: string + example: Feature Name + description: Name of the feature associated with the dimension. + volumes: + title: volumes + type: array + description: >- + A list of volumes associated with the dimension, each with its own + price. + items: + $ref: '#/components/schemas/addons_dimension_volume_with_price' + required: + - id + - sku + - slug + - display_name + - feature_name + - volumes + addons_plan: + type: object + properties: + id: + title: id + type: integer + example: 1 + description: ID of a given plan. + app_id: + title: app_id + type: integer + example: 2 + description: ID of the app associated with this plan. + display_name: + title: display_name + type: string + example: Basic Plan + description: Display name for a given plan. + description: + title: description + type: string + example: Description of the app plan. + description: Description of an app plan. + slug: + title: slug + type: string + example: plan_basic + description: Slug identifier for the plan. + price_per_month: + title: price_per_month + type: integer + example: 10 + description: Price of a month's usage of the plan in US dollars. + active: + title: active + type: boolean + example: true + description: Indicates if the plan is currently active. + state: + title: state + type: string + enum: + - unknown + - draft + - in_review + - approved + - suspended + - archived + example: approved + description: Current state of the plan. + features: + title: features + type: array + items: + $ref: '#/components/schemas/addons_feature' + example: [] + description: List of features included in the plan. + created_at: + title: created_at + type: string + format: date-time + example: '2023-10-01T12:00:00Z' + description: Timestamp when the plan was created. + updated_at: + title: updated_at + type: string + format: date-time + example: '2023-10-01T12:00:00Z' + description: Timestamp when the plan was last updated. + available: + title: available + type: boolean + example: true + description: Indicates if the plan is available for selection. + uuid: + title: uuid + type: string + example: 123e4567-e89b-12d3-a456-426 614174000 + description: Unique identifier for the plan. + by_default: + title: by_default + type: boolean + example: false + description: Indicates if this plan is the default option for the app. + dimensions: + title: dimensions + type: array + description: >- + List of dimensions associated with the plan, each with its own + pricing. + items: + $ref: '#/components/schemas/addons_dimension_with_price' + required: + - id + - app_id + - display_name + - slug + - price_per_month + - active + - state + - created_at + - updated_at + - available + - uuid + - by_default + addons_app_info: + type: object + properties: + app_slug: + title: app_slug + type: string + example: example-app + description: >- + The slug identifier for the application associated with the + resource. + tos: + title: tos + type: string + example: https://example.com/tos + description: The Terms of Service URL for the resource. + eula: + title: eula + type: string + example: https://example.com/eula + description: The End User License Agreement URL for the resource. + plans: + title: plans + type: array + description: A list of plans available for the resource. + items: + $ref: '#/components/schemas/addons_plan' + required: + - app_slug + - tos + - eula + - plans + addons_app_metadata: + type: object + properties: + id: + title: id + type: integer + example: 1 + description: Unique identifier for the addon metadata item. + name: + title: name + type: string + example: country_of_origin + description: The name of the metadata item. + display_name: + title: display_name + type: string + example: Country of Origin + description: The display name of the metadata item. + description: + title: description + type: string + example: Country for localization + description: A brief description of the metadata item. + type: + title: type + type: string + enum: + - string + - boolean + example: string + description: The data type of the metadata value. + options: + title: options + type: array + example: + - US + - UK + - CA + items: + type: string + example: UK + description: An option available for the addon metadata, if applicable. + required: + - id + - name + - display_name + - description + - type + addons_resource_metadata: + type: object + properties: + name: + title: name + type: string + example: property_name + description: The name of the metadata item to be set. + value: + example: example_value + oneOf: + - title: string_value + type: string + example: example_value + - title: boolean_value + type: boolean + example: true + description: >- + The value to be set for the metadata item, which can be a string or + boolean. + required: + - name + - value + addons_resource: + type: object + properties: + uuid: + title: uuid + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: The unique identifier for the addon resource. + name: + title: name + type: string + example: my-resource-01 + description: The name of the addon resource. + state: + title: state + type: string + enum: + - pending + - provisioning + - provisioned + - deprovisioning + - deprovisioned + - provisioning-failed + - deprovisioning-failed + - suspended + example: provisioned + description: The state the resource is currently in. + app_name: + title: app_name + type: string + example: Example App + description: The name of the application associated with the resource. + app_slug: + title: app_slug + type: string + example: example_app + description: >- + The slug identifier for the application associated with the + resource. + plan_name: + title: plan_name + type: string + example: Basic Plan + description: The name of the plan associated with the resource. + plan_slug: + title: plan_slug + type: string + example: basic_plan + description: The slug identifier for the plan associated with the resource. + plan_price_per_month: + title: plan_price_per_month + type: integer + example: 10 + description: The price of the plan per month in US dollars. + has_config: + title: has_config + type: boolean + example: true + description: >- + Indicates if the resource has configuration values set by the + vendor. + metadata: + title: metadata + type: array + description: Metadata associated with the resource, set by the user. + items: + $ref: '#/components/schemas/addons_resource_metadata' + sso_url: + title: sso_url + type: string + example: https://example.com/sso + description: The Single Sign-On URL for the resource, if applicable. + message: + title: message + type: string + example: Resource is provisioned successfully. + description: A message related to the resource, if applicable. + required: + - uuid + - name + - state + - app_slug + - plan_slug + - has_config + addons_resource_new: + type: object + properties: + app_slug: + title: app_slug + type: string + example: example-app + description: >- + The slug identifier for the application associated with the + resource. + plan_slug: + title: plan_slug + type: string + example: basic_plan + description: The slug identifier for the plan associated with the resource. + name: + title: name + type: string + example: my-resource-01 + description: The name of the addon resource. + metadata: + title: metadata + type: array + items: + $ref: '#/components/schemas/addons_resource_metadata' + description: >- + Metadata associated with the resource, set by the user. Metadata + expected varies per app, and can be verified with a GET request to + "/v2/add-ons/apps/{app_slug}/metadata" + linked_droplet_id: + title: linked_droplet_id + type: integer + example: 12345678 + description: ID of the droplet to be linked to this resource, if applicable. + fleet_uuid: + title: fleet_uuid + type: string + example: f1234567-89ab-cdef-0123-456789abcdef01 + description: UUID of the fleet/project to which this resource will belong. + required: + - app_slug + - plan_slug + - name + - metadata + apps_deployment_job: + properties: + name: + title: The name of this job + type: string + example: migrate-db + source_commit_hash: + title: The commit hash of the repository that was used to build this job + type: string + example: 54d4a727f457231062439895000d45437c7bb405 + type: object + apps_deployment_functions: + type: object + properties: + name: + type: string + title: The name of this functions component + example: my-functions-component + source_commit_hash: + type: string + description: >- + The commit hash of the repository that was used to build this + functions component. + example: 54d4a727f457231062439895000d45437c7bb405 + namespace: + type: string + description: The namespace where the functions are deployed. + example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32 + apps_deployment_phase: + default: UNKNOWN + enum: + - UNKNOWN + - PENDING_BUILD + - BUILDING + - PENDING_DEPLOY + - DEPLOYING + - ACTIVE + - SUPERSEDED + - ERROR + - CANCELED + type: string + example: ACTIVE + apps_deployment_progress_step_reason: + properties: + code: + title: The error code + type: string + example: Title of Error + message: + title: The error message + type: string + example: This is an error + type: object + apps_deployment_progress_step_status: + default: UNKNOWN + enum: + - UNKNOWN + - PENDING + - RUNNING + - ERROR + - SUCCESS + type: string + example: SUCCESS + apps_deployment_progress_step: + properties: + component_name: + title: The component name that this step is associated with + type: string + example: component + ended_at: + format: date-time + title: The end time of this step + type: string + example: '2020-11-19T20:27:18Z' + message_base: + description: >- + The base of a human-readable description of the step intended to be + combined with the component name for presentation. For example: + + + `message_base` = "Building service" + + `component_name` = "api" + type: string + example: Building service + name: + title: The name of this step + type: string + example: example_step + reason: + $ref: '#/components/schemas/apps_deployment_progress_step_reason' + started_at: + format: date-time + title: The start time of this step + type: string + example: '2020-11-19T20:27:18Z' + status: + $ref: '#/components/schemas/apps_deployment_progress_step_status' + steps: + items: + type: object + title: Child steps of this step + type: array + title: A step that is run as part of the deployment's lifecycle + type: object + apps_deployment_progress: + properties: + error_steps: + format: int32 + title: Number of unsuccessful steps + type: integer + example: 3 + pending_steps: + format: int32 + title: Number of pending steps + type: integer + example: 2 + running_steps: + format: int32 + title: Number of currently running steps + type: integer + example: 2 + steps: + items: + $ref: '#/components/schemas/apps_deployment_progress_step' + title: The deployment's steps + type: array + success_steps: + format: int32 + title: Number of successful steps + type: integer + example: 4 + summary_steps: + items: + $ref: '#/components/schemas/apps_deployment_progress_step' + title: A flattened summary of the steps + type: array + total_steps: + format: int32 + title: Total number of steps + type: integer + example: 5 + type: object + apps_deployment_service: + properties: + name: + title: The name of this service + type: string + example: web + source_commit_hash: + title: >- + The commit hash of the repository that was used to build this + service + type: string + example: 54d4a727f457231062439895000d45437c7bb405 + type: object + app_domain_spec: + type: object + properties: + domain: + type: string + maxLength: 253 + minLength: 4 + pattern: ^((xn--)?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*\.)+[a-zA-Z]{2,}\.?$ + description: The hostname for the domain + example: app.example.com + type: + type: string + default: UNSPECIFIED + enum: + - UNSPECIFIED + - DEFAULT + - PRIMARY + - ALIAS + description: >- + - DEFAULT: The default `.ondigitalocean.app` domain assigned to this + app + + - PRIMARY: The primary domain for this app that is displayed as the + default in the control panel, used in bindable environment + variables, and any other places that reference an app's live URL. + Only one domain may be set as primary. + + - ALIAS: A non-primary domain + example: DEFAULT + wildcard: + type: boolean + description: >- + Indicates whether the domain includes all sub-domains, in addition + to the given domain + example: true + zone: + description: >- + Optional. If the domain uses DigitalOcean DNS and you would like App + + Platform to automatically manage it for you, set this to the name of + the + + domain on your account. + + + For example, If the domain you are adding is `app.domain.com`, the + zone + + could be `domain.com`. + type: string + format: hostname + example: example.com + minimum_tls_version: + type: string + maxLength: 3 + minLength: 3 + enum: + - '1.2' + - '1.3' + description: >- + The minimum version of TLS a client application can use to access + resources for the domain. Must be one of the following values + wrapped within quotations: `"1.2"` or `"1.3"`. + example: '1.3' + required: + - domain + apps_git_source_spec: + type: object + properties: + branch: + type: string + description: The name of the branch to use + example: main + repo_clone_url: + type: string + description: >- + The clone URL of the repo. Example: + `https://github.com/digitalocean/sample-golang.git` + example: https://github.com/digitalocean/sample-golang.git + apps_github_source_spec: + type: object + properties: + branch: + type: string + description: The name of the branch to use + example: main + deploy_on_push: + type: boolean + description: Whether to automatically deploy new commits made to the repo + example: true + repo: + type: string + description: >- + The name of the repo in the format owner/repo. Example: + `digitalocean/sample-golang` + example: digitalocean/sample-golang + apps_gitlab_source_spec: + type: object + properties: + branch: + type: string + description: The name of the branch to use + example: main + deploy_on_push: + type: boolean + description: Whether to automatically deploy new commits made to the repo + example: true + repo: + type: string + description: >- + The name of the repo in the format owner/repo. Example: + `digitalocean/sample-golang` + example: digitalocean/sample-golang + apps_bitbucket_source_spec: + type: object + properties: + branch: + type: string + description: The name of the branch to use + example: main + deploy_on_push: + type: boolean + description: Whether to automatically deploy new commits made to the repo + example: true + repo: + type: string + description: >- + The name of the repo in the format owner/repo. Example: + `digitalocean/sample-golang` + example: digitalocean/sample-golang + apps_image_source_spec: + type: object + properties: + registry: + type: string + description: The registry name. Must be left empty for the `DOCR` registry type. + example: registry.hub.docker.com + registry_type: + type: string + enum: + - DOCKER_HUB + - DOCR + - GHCR + description: |- + - DOCKER_HUB: The DockerHub container registry type. + - DOCR: The DigitalOcean container registry type. + - GHCR: The Github container registry type. + example: DOCR + registry_credentials: + type: string + description: >- + The credentials to be able to pull the image. The value will be + encrypted on first submission. On following submissions, the + encrypted value should be used. + + - "$username:$access_token" for registries of type `DOCKER_HUB`. + + - "$username:$access_token" for registries of type `GHCR`. + example: my-dockerhub-username:dckr_pat_the_access_token + repository: + type: string + description: The repository name. + example: origin/master + tag: + type: string + description: >- + The repository tag. Defaults to `latest` if not provided and no + digest is provided. Cannot be specified if digest is provided. + example: latest + default: latest + digest: + type: string + description: The image digest. Cannot be specified if tag is provided. + example: >- + sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac + deploy_on_push: + type: object + properties: + enabled: + type: boolean + description: >- + Whether to automatically deploy new images. Can only be used for + images hosted in DOCR and can only be used with an image tag, + not a specific digest. + example: true + app_variable_definition: + type: object + properties: + key: + type: string + pattern: ^[_A-Za-z][_A-Za-z0-9]*$ + description: The variable name + example: BASE_URL + scope: + type: string + enum: + - UNSET + - RUN_TIME + - BUILD_TIME + - RUN_AND_BUILD_TIME + description: |- + - RUN_TIME: Made available only at run-time + - BUILD_TIME: Made available only at build-time + - RUN_AND_BUILD_TIME: Made available at both build and run-time + default: RUN_AND_BUILD_TIME + example: BUILD_TIME + type: + type: string + enum: + - GENERAL + - SECRET + description: |- + - GENERAL: A plain-text environment variable + - SECRET: A secret encrypted environment variable + default: GENERAL + example: GENERAL + value: + description: >- + The value. If the type is `SECRET`, the value will be encrypted on + first submission. On following submissions, the encrypted value + should be used. + type: string + example: http://example.com + required: + - key + app_log_destination_papertrail_spec: + type: object + properties: + endpoint: + type: string + description: Papertrail syslog endpoint. + example: https://mypapertrailendpoint.com + description: Papertrail configuration. + required: + - endpoint + app_log_destination_datadog_spec: + type: object + properties: + endpoint: + type: string + description: Datadog HTTP log intake endpoint. + example: https://mydatadogendpoint.com + api_key: + type: string + description: Datadog API key. + example: abcdefghijklmnopqrstuvwxyz0123456789 + description: DataDog configuration. + required: + - api_key + app_log_destination_logtail_spec: + type: object + properties: + token: + type: string + description: Logtail token. + example: abcdefghijklmnopqrstuvwxyz0123456789 + description: Logtail configuration. + required: + - endpoint + app_log_destination_open_search_spec_basic_auth: + type: object + properties: + user: + type: string + description: |- + Username to authenticate with. Only required when `endpoint` is set. + Defaults to `doadmin` when `cluster_name` is set. + example: apps_user + password: + type: string + description: >- + Password for user defined in User. Is required when `endpoint` is + set. + + Cannot be set if using a DigitalOcean DBaaS OpenSearch cluster. + example: password1 + description: Configure Username and/or Password for Basic authentication. + app_log_destination_open_search_spec: + type: object + properties: + endpoint: + type: string + description: >- + OpenSearch API Endpoint. Only HTTPS is supported. Format: + https://:. + + Cannot be specified if `cluster_name` is also specified. + example: https://example.com:9300 + basic_auth: + $ref: '#/components/schemas/app_log_destination_open_search_spec_basic_auth' + index_name: + type: string + default: logs + description: >- + The index name to use for the logs. If not set, the default index + name is "logs". + example: logs + cluster_name: + type: string + description: >- + The name of a DigitalOcean DBaaS OpenSearch cluster to use as a log + forwarding destination. + + Cannot be specified if `endpoint` is also specified. + example: my-opensearch-cluster + description: OpenSearch configuration. + app_log_destination_definition: + type: object + properties: + name: + type: string + maxLength: 42 + minLength: 2 + pattern: >- + ^[A-Za-z0-9()\[\]'"][-A-Za-z0-9_. + \/()\[\]]{0,40}[A-Za-z0-9()\[\]'"]$ + example: my_log_destination + papertrail: + $ref: '#/components/schemas/app_log_destination_papertrail_spec' + datadog: + $ref: '#/components/schemas/app_log_destination_datadog_spec' + logtail: + $ref: '#/components/schemas/app_log_destination_logtail_spec' + open_search: + $ref: '#/components/schemas/app_log_destination_open_search_spec' + title: Configurations for external logging. + required: + - name + app_component_base: + type: object + properties: + name: + type: string + maxLength: 32 + minLength: 2 + pattern: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$ + description: The name. Must be unique across all components within the same app. + example: api + git: + $ref: '#/components/schemas/apps_git_source_spec' + github: + $ref: '#/components/schemas/apps_github_source_spec' + gitlab: + $ref: '#/components/schemas/apps_gitlab_source_spec' + bitbucket: + $ref: '#/components/schemas/apps_bitbucket_source_spec' + image: + $ref: '#/components/schemas/apps_image_source_spec' + dockerfile_path: + type: string + description: >- + The path to the Dockerfile relative to the root of the repo. If set, + it will be used to build this component. Otherwise, App Platform + will attempt to build it using buildpacks. + example: path/to/Dockerfile + build_command: + type: string + description: >- + An optional build command to run while building this component from + source. + example: npm run build + run_command: + type: string + description: An optional run command to override the component's default. + example: bin/api + source_dir: + type: string + description: >- + An optional path to the working directory to use for the build. For + Dockerfile builds, this will be used as the build context. Must be + relative to the root of the repo. + example: path/to/dir + envs: + type: array + items: + $ref: '#/components/schemas/app_variable_definition' + description: A list of environment variables made available to the component. + environment_slug: + type: string + description: >- + An environment slug describing the type of this app. For a full + list, please refer to [the product + documentation](https://docs.digitalocean.com/products/app-platform/). + example: node-js + log_destinations: + type: array + items: + $ref: '#/components/schemas/app_log_destination_definition' + description: A list of configured log forwarding destinations. + app_component_instance_base: + type: object + properties: + instance_count: + type: integer + format: int64 + minimum: 1 + description: >- + The amount of instances that this component should be scaled to. + Default: 1. Must not be set if autoscaling is used. + default: 1 + example: 2 + instance_size_slug: + description: >- + The instance size to use for this component. Default: + `apps-s-1vcpu-0.5gb` + oneOf: + - title: Size slug + type: string + enum: + - apps-s-1vcpu-0.5gb + - apps-s-1vcpu-1gb-fixed + - apps-s-1vcpu-1gb + - apps-s-1vcpu-2gb + - apps-s-2vcpu-4gb + - apps-d-1vcpu-0.5gb + - apps-d-1vcpu-1gb + - apps-d-1vcpu-2gb + - apps-d-1vcpu-4gb + - apps-d-2vcpu-4gb + - apps-d-2vcpu-8gb + - apps-d-4vcpu-8gb + - apps-d-4vcpu-16gb + - apps-d-8vcpu-32gb + default: apps-s-1vcpu-0.5gb + example: apps-s-1vcpu-0.5gb + - title: Deprecated + description: > + Deprecated size slugs for legacy plans. We strongly encourage + customers + + to use the new plans when creating or upgrading apps. + type: string + enum: + - basic-xxs + - basic-xs + - basic-s + - basic-m + - professional-xs + - professional-s + - professional-m + - professional-1l + - professional-l + - professional-xl + example: basic-xxs + deprecated: true + example: apps-s-1vcpu-0.5gb + app_autoscaling_spec: + description: Configuration for automatically scaling this component based on metrics. + type: object + properties: + min_instance_count: + description: The minimum amount of instances for this component. + type: integer + format: uint32 + minimum: 1 + example: 2 + max_instance_count: + description: >- + The maximum amount of instances for this component. Maximum 250. + Consider using a larger instance size if your application requires + more than 250 instances. + type: integer + format: uint32 + minimum: 1 + maximum: 250 + example: 3 + metrics: + description: The metrics that the component is scaled on. + type: object + properties: + cpu: + description: Settings for scaling the component based on CPU utilization. + type: object + properties: + percent: + description: The average target CPU utilization for the component. + type: integer + format: uint32 + minimum: 1 + maximum: 100 + default: 80 + example: 75 + app_autoscaling_spec_service: + allOf: + - $ref: '#/components/schemas/app_autoscaling_spec' + - type: object + properties: + metrics: + type: object + properties: + requests_per_second: + description: >- + Settings for scaling the component based on requests per + second. + type: object + properties: + per_instance: + description: >- + The target number of requests per second per instance + for the component. + type: integer + format: uint32 + minimum: 1 + example: 100 + request_duration: + description: >- + Settings for scaling the component based on request + duration. + type: object + properties: + p95_milliseconds: + description: >- + The p95 target request duration in milliseconds for the + component. + type: integer + format: uint32 + minimum: 1 + example: 500 + apps_string_match: + type: object + properties: + exact: + type: string + nullable: true + description: >- + Exact string match. Only 1 of `exact`, `prefix`, or `regex` must be + set. An empty string is a valid value and will be serialized + explicitly rather than being omitted from the payload. + maxLength: 256 + example: https://www.example.com + prefix: + type: string + nullable: true + description: >- + Prefix-based match. Only 1 of `exact`, `prefix`, or `regex` must be + set. + maxLength: 256 + example: https://www.example.com + deprecated: true + regex: + type: string + maxLength: 256 + minLength: 1 + description: >- + RE2 style regex-based match. Only 1 of `exact`, `prefix`, or `regex` + must be set. For more information about RE2 syntax, see: + https://github.com/google/re2/wiki/Syntax + example: ^.*example.com + apps_cors_policy: + type: object + properties: + allow_origins: + type: array + description: The set of allowed CORS origins. + items: + $ref: '#/components/schemas/apps_string_match' + example: + - exact: https://www.example.com + - regex: ^.*example.com + allow_methods: + type: array + items: + type: string + description: >- + The set of allowed HTTP methods. This configures the + `Access-Control-Allow-Methods` header. + example: + - GET + - OPTIONS + - POST + - PUT + - PATCH + - DELETE + allow_headers: + type: array + items: + type: string + description: >- + The set of allowed HTTP request headers. This configures the + `Access-Control-Allow-Headers` header. + example: + - Content-Type + - X-Custom-Header + expose_headers: + type: array + items: + type: string + description: >- + The set of HTTP response headers that browsers are allowed to + access. This configures the `Access-Control-Expose-Headers` header. + example: + - Content-Encoding + - X-Custom-Header + max_age: + type: string + description: >- + An optional duration specifying how long browsers can cache the + results of a preflight request. This configures the + `Access-Control-Max-Age` header. + example: 5h30m + allow_credentials: + type: boolean + description: >- + Whether browsers should expose the response to the client-side + JavaScript code when the request’s credentials mode is include. This + configures the `Access-Control-Allow-Credentials` header. + example: false + app_service_spec_health_check: + type: object + properties: + failure_threshold: + type: integer + format: int32 + description: The number of failed health checks before considered unhealthy. + example: 2 + port: + type: integer + format: int64 + description: >- + The port on which the health check will be performed. If not set, + the health check will be performed on the component's http_port. + example: 80 + maximum: 65535 + minimum: 1 + http_path: + type: string + description: >- + The route path used for the HTTP health check ping. If not set, the + HTTP health check will be disabled and a TCP health check used + instead. + example: /health + initial_delay_seconds: + type: integer + format: int32 + description: The number of seconds to wait before beginning health checks. + example: 30 + period_seconds: + type: integer + format: int32 + description: The number of seconds to wait between health checks. + example: 60 + success_threshold: + type: integer + format: int32 + description: The number of successful health checks before considered healthy. + example: 3 + timeout_seconds: + type: integer + format: int32 + description: The number of seconds after which the check times out. + example: 45 + app_health_check_spec: + type: object + properties: + failure_threshold: + type: integer + format: int32 + description: The number of failed health checks before considered unhealthy. + minimum: 1 + maximum: 50 + example: 18 + port: + type: integer + format: int64 + description: The port on which the health check will be performed. + example: 80 + maximum: 65535 + minimum: 1 + http_path: + type: string + description: >- + The route path used for the HTTP health check ping. If not set, the + HTTP health check will be disabled and a TCP health check used + instead. + example: /health + initial_delay_seconds: + type: integer + format: int32 + description: The number of seconds to wait before beginning health checks. + minimum: 0 + maximum: 3600 + example: 30 + period_seconds: + type: integer + format: int32 + description: The number of seconds to wait between health checks. + minimum: 1 + maximum: 300 + example: 10 + success_threshold: + type: integer + format: int32 + description: The number of successful health checks before considered healthy. + example: 1 + minimum: 1 + maximum: 1 + timeout_seconds: + type: integer + format: int32 + description: The number of seconds after which the check times out. + minimum: 1 + maximum: 120 + example: 1 + app_route_spec: + title: A criterion for routing HTTP traffic to a component. + type: object + properties: + path: + description: >- + (Deprecated - Use Ingress Rules instead). An HTTP path prefix. Paths + must start with / and must be unique across all components within an + app. + type: string + example: /api + preserve_path_prefix: + description: >- + An optional flag to preserve the path that is forwarded to the + backend service. By default, the HTTP request path will be trimmed + from the left when forwarded to the component. For example, a + component with `path=/api` will have requests to `/api/list` trimmed + to `/list`. If this value is `true`, the path will remain + `/api/list`. + type: boolean + example: true + app_service_spec_termination: + type: object + properties: + drain_seconds: + type: integer + format: int32 + description: >- + The number of seconds to wait between selecting a container instance + for termination and issuing the TERM signal. Selecting a container + instance for termination begins an asynchronous drain of new + requests on upstream load-balancers. (Default 15) + example: 15 + maximum: 110 + minimum: 1 + grace_period_seconds: + type: integer + format: int32 + description: >- + The number of seconds to wait between sending a TERM signal to a + container and issuing a KILL which causes immediate shutdown. + (Default 120) + example: 120 + maximum: 600 + minimum: 1 + app_service_spec: + allOf: + - $ref: '#/components/schemas/app_component_base' + - $ref: '#/components/schemas/app_component_instance_base' + - type: object + properties: + autoscaling: + $ref: '#/components/schemas/app_autoscaling_spec_service' + cors: + allOf: + - $ref: '#/components/schemas/apps_cors_policy' + - description: (Deprecated - Use Ingress Rules instead). + - deprecated: true + health_check: + $ref: '#/components/schemas/app_service_spec_health_check' + liveness_health_check: + $ref: '#/components/schemas/app_health_check_spec' + protocol: + type: string + description: > + The protocol which the service uses to serve traffic on the + http_port. + + + - `HTTP`: The app is serving the HTTP protocol. Default. + + - `HTTP2`: The app is serving the HTTP/2 protocol. Currently, + this needs to be implemented in the service by serving HTTP/2 + cleartext (h2c). + enum: + - HTTP + - HTTP2 + example: HTTP + http_port: + type: integer + description: >- + The internal port on which this service's run command will + listen. Default: 8080 + + If there is not an environment variable with the name `PORT`, + one will be automatically added with its value set to the value + of this field. + format: int64 + maximum: 65535 + minimum: 1 + example: 3000 + internal_ports: + type: array + description: >- + The ports on which this service will listen for internal + traffic. + items: + format: int64 + type: integer + example: + - 80 + - 443 + routes: + type: array + description: >- + (Deprecated - Use Ingress Rules instead). A list of HTTP routes + that should be routed to this component. + deprecated: true + items: + $ref: '#/components/schemas/app_route_spec' + termination: + $ref: '#/components/schemas/app_service_spec_termination' + required: + - name + app_static_site_spec: + allOf: + - $ref: '#/components/schemas/app_component_base' + - type: object + properties: + index_document: + type: string + description: >- + The name of the index document to use when serving this static + site. Default: index.html + default: index.html + example: main.html + error_document: + type: string + description: >- + The name of the error document to use when serving this static + site. Default: 404.html. If no such file exists within the built + assets, App Platform will supply one. + default: 404.html + example: error.html + catchall_document: + type: string + description: >- + The name of the document to use as the fallback for any requests + to documents that are not found when serving this static site. + Only 1 of `catchall_document` or `error_document` can be set. + example: index.html + output_dir: + type: string + description: >- + An optional path to where the built assets will be located, + relative to the build context. If not set, App Platform will + automatically scan for these directory names: `_static`, `dist`, + `public`, `build`. + example: dist/ + cors: + allOf: + - $ref: '#/components/schemas/apps_cors_policy' + - description: (Deprecated - Use Ingress Rules instead). + - deprecated: true + routes: + type: array + items: + $ref: '#/components/schemas/app_route_spec' + description: >- + (Deprecated - Use Ingress Rules instead). A list of HTTP routes + that should be routed to this component. + deprecated: true + required: + - name + app_job_spec_termination: + type: object + properties: + grace_period_seconds: + type: integer + format: int32 + description: >- + The number of seconds to wait between sending a TERM signal to a + container and issuing a KILL which causes immediate shutdown. + (Default 120) + example: 120 + maximum: 600 + minimum: 1 + app_job_spec: + allOf: + - $ref: '#/components/schemas/app_component_base' + - $ref: '#/components/schemas/app_component_instance_base' + - type: object + properties: + kind: + type: string + enum: + - UNSPECIFIED + - PRE_DEPLOY + - POST_DEPLOY + - FAILED_DEPLOY + description: >- + - UNSPECIFIED: Default job type, will auto-complete to + POST_DEPLOY kind. + + - PRE_DEPLOY: Indicates a job that runs before an app + deployment. + + - POST_DEPLOY: Indicates a job that runs after an app + deployment. + + - FAILED_DEPLOY: Indicates a job that runs after a component + fails to deploy. + default: UNSPECIFIED + example: PRE_DEPLOY + termination: + $ref: '#/components/schemas/app_job_spec_termination' + required: + - name + app_worker_spec_termination: + type: object + properties: + grace_period_seconds: + type: integer + format: int32 + description: >- + The number of seconds to wait between sending a TERM signal to a + container and issuing a KILL which causes immediate shutdown. + (Default 120) + example: 120 + maximum: 600 + minimum: 1 + app_worker_spec: + allOf: + - $ref: '#/components/schemas/app_component_base' + - $ref: '#/components/schemas/app_component_instance_base' + - type: object + properties: + autoscaling: + $ref: '#/components/schemas/app_autoscaling_spec' + termination: + $ref: '#/components/schemas/app_worker_spec_termination' + liveness_health_check: + $ref: '#/components/schemas/app_health_check_spec' + required: + - name + app_alert_spec_rule: + default: UNSPECIFIED_RULE + enum: + - UNSPECIFIED_RULE + - CPU_UTILIZATION + - MEM_UTILIZATION + - RESTART_COUNT + - DEPLOYMENT_FAILED + - DEPLOYMENT_LIVE + - DOMAIN_FAILED + - DOMAIN_LIVE + - AUTOSCALE_FAILED + - AUTOSCALE_SUCCEEDED + - FUNCTIONS_ACTIVATION_COUNT + - FUNCTIONS_AVERAGE_DURATION_MS + - FUNCTIONS_ERROR_RATE_PER_MINUTE + - FUNCTIONS_AVERAGE_WAIT_TIME_MS + - FUNCTIONS_ERROR_COUNT + - FUNCTIONS_GB_RATE_PER_SECOND + - REQUESTS_PER_SECOND + - REQUEST_DURATION_P95_MS + type: string + example: CPU_UTILIZATION + app_alert_spec_operator: + default: UNSPECIFIED_OPERATOR + enum: + - UNSPECIFIED_OPERATOR + - GREATER_THAN + - LESS_THAN + type: string + example: GREATER_THAN + app_alert_spec_window: + default: UNSPECIFIED_WINDOW + enum: + - UNSPECIFIED_WINDOW + - FIVE_MINUTES + - TEN_MINUTES + - THIRTY_MINUTES + - ONE_HOUR + type: string + example: FIVE_MINUTES + app_alert_spec: + properties: + rule: + $ref: '#/components/schemas/app_alert_spec_rule' + disabled: + description: Is the alert disabled? + type: boolean + example: false + operator: + $ref: '#/components/schemas/app_alert_spec_operator' + value: + description: Threshold value for alert + format: float + type: number + example: 2.32 + window: + $ref: '#/components/schemas/app_alert_spec_window' + type: object + app_functions_spec: + type: object + properties: + cors: + allOf: + - $ref: '#/components/schemas/apps_cors_policy' + - description: (Deprecated - Use Ingress Rules instead). + - deprecated: true + routes: + type: array + description: >- + (Deprecated - Use Ingress Rules instead). A list of HTTP routes that + should be routed to this component. + deprecated: true + items: + $ref: '#/components/schemas/app_route_spec' + name: + type: string + maxLength: 32 + minLength: 2 + pattern: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$ + description: The name. Must be unique across all components within the same app. + example: api + source_dir: + type: string + description: >- + An optional path to the working directory to use for the build. For + Dockerfile builds, this will be used as the build context. Must be + relative to the root of the repo. + example: path/to/dir + alerts: + type: array + items: + $ref: '#/components/schemas/app_alert_spec' + envs: + type: array + items: + $ref: '#/components/schemas/app_variable_definition' + description: A list of environment variables made available to the component. + git: + $ref: '#/components/schemas/apps_git_source_spec' + github: + $ref: '#/components/schemas/apps_github_source_spec' + gitlab: + $ref: '#/components/schemas/apps_gitlab_source_spec' + bitbucket: + $ref: '#/components/schemas/apps_bitbucket_source_spec' + log_destinations: + type: array + items: + $ref: '#/components/schemas/app_log_destination_definition' + description: A list of configured log forwarding destinations. + required: + - name + app_database_spec: + type: object + properties: + cluster_name: + description: >- + The name of the underlying DigitalOcean DBaaS cluster. This is + required for production databases. For dev databases, if + cluster_name is not set, a new cluster will be provisioned. + type: string + example: cluster_name + db_name: + description: The name of the MySQL or PostgreSQL database to configure. + type: string + example: my_db + db_user: + description: The name of the MySQL or PostgreSQL user to configure. + type: string + example: superuser + engine: + type: string + default: UNSET + enum: + - UNSET + - MYSQL + - PG + - REDIS + - MONGODB + - KAFKA + - OPENSEARCH + - VALKEY + description: |- + - MYSQL: MySQL + - PG: PostgreSQL + - REDIS: Caching + - MONGODB: MongoDB + - KAFKA: Kafka + - OPENSEARCH: OpenSearch + - VALKEY: ValKey + example: PG + name: + description: >- + The database's name. The name must be unique across all components + within the same app and cannot use capital letters. + maxLength: 32 + minLength: 2 + pattern: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$ + type: string + example: prod-db + production: + description: Whether this is a production or dev database. + type: boolean + example: true + version: + description: The version of the database engine + type: string + example: '12' + required: + - name + app_ingress_spec_rule_string_match_prefix: + type: object + properties: + prefix: + type: string + nullable: true + description: >- + Prefix-based match. For example, `/api` will match `/api`, `/api/`, + and any nested paths such as `/api/v1/endpoint`. + maxLength: 256 + example: /api + description: The path to match on. + required: + - prefix + app_ingress_spec_rule_string_match_exact: + type: object + properties: + exact: + type: string + nullable: true + maxLength: 256 + example: example.com + description: >- + Exact string match. An empty string is a valid value and will be + serialized explicitly rather than being omitted from the payload. + description: The authority to match on. + required: + - exact + app_ingress_spec_rule_match: + type: object + properties: + path: + $ref: '#/components/schemas/app_ingress_spec_rule_string_match_prefix' + authority: + $ref: '#/components/schemas/app_ingress_spec_rule_string_match_exact' + description: The match configuration for the rule. + app_ingress_spec_rule_routing_component: + type: object + properties: + name: + description: The name of the component to route to. + type: string + example: web + preserve_path_prefix: + description: >- + An optional flag to preserve the path that is forwarded to the + backend service. By default, the HTTP request path will be trimmed + from the left when forwarded to the component. For example, a + component with `path=/api` will have requests to `/api/list` trimmed + to `/list`. If this value is `true`, the path will remain + `/api/list`. Note: this is not applicable for Functions Components + and is mutually exclusive with `rewrite`. + type: string + example: 'true' + rewrite: + description: >- + An optional field that will rewrite the path of the component to be + what is specified here. By default, the HTTP request path will be + trimmed from the left when forwarded to the component. For example, + a component with `path=/api` will have requests to `/api/list` + trimmed to `/list`. If you specified the rewrite to be `/v1/`, + requests to `/api/list` would be rewritten to `/v1/list`. Note: this + is mutually exclusive with `preserve_path_prefix`. + type: string + example: /api/v1/ + description: >- + The component to route to. Only one of `component` or `redirect` may be + set. + required: + - name + app_ingress_spec_rule_routing_redirect: + type: object + properties: + uri: + description: >- + An optional URI path to redirect to. Note: if this is specified the + whole URI of the original request will be overwritten to this value, + irrespective of the original request URI being matched. + type: string + example: /about + authority: + description: >- + The authority/host to redirect to. This can be a hostname or IP + address. Note: use `port` to set the port. + type: string + example: example.com + port: + description: The port to redirect to. + type: integer + format: int64 + example: 443 + scheme: + description: >- + The scheme to redirect to. Supported values are `http` or `https`. + Default: `https`. + type: string + example: https + redirect_code: + description: >- + The redirect code to use. Defaults to `302`. Supported values are + 300, 301, 302, 303, 304, 307, 308. + type: integer + format: int64 + example: 302 + description: >- + The redirect configuration for the rule. Only one of `component` or + `redirect` may be set. + app_ingress_spec_rule: + type: object + properties: + match: + $ref: '#/components/schemas/app_ingress_spec_rule_match' + cors: + $ref: '#/components/schemas/apps_cors_policy' + component: + $ref: '#/components/schemas/app_ingress_spec_rule_routing_component' + redirect: + $ref: '#/components/schemas/app_ingress_spec_rule_routing_redirect' + app_ingress_spec: + type: object + properties: + rules: + description: >- + Rules for configuring HTTP ingress for component routes, CORS, + rewrites, and redirects. + type: array + items: + $ref: '#/components/schemas/app_ingress_spec_rule' + description: Specification for app ingress configurations. + app_egress_type_spec: + title: The app egress type. + type: string + default: AUTOASSIGN + example: AUTOASSIGN + enum: + - AUTOASSIGN + - DEDICATED_IP + app_egress_spec: + type: object + description: Specification for app egress configurations. + properties: + type: + $ref: '#/components/schemas/app_egress_type_spec' + app_maintenance_spec: + type: object + description: >- + Specification to configure maintenance settings for the app, such as + maintenance mode and archiving the app. + properties: + enabled: + type: boolean + description: Indicates whether maintenance mode should be enabled for the app. + example: true + archive: + type: boolean + description: >- + Indicates whether the app should be archived. Setting this to true + implies that enabled is set to true. + example: true + offline_page_url: + type: string + description: >- + A custom offline page to display when maintenance mode is enabled or + the app is archived. + example: https://example.com/offline.html + apps_vpc_egress_ip: + type: object + properties: + ip: + type: string + example: 10.0.0.1 + apps_vpc: + type: object + readOnly: true + properties: + id: + title: The ID of the VPC. + type: string + example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + title: The egress ips associated with the VPC. + type: array + items: + $ref: '#/components/schemas/apps_vpc_egress_ip' + app_spec: + title: AppSpec + type: object + description: The desired configuration of an application. + properties: + name: + description: >- + The name of the app. Must be unique across all apps in the same + account. + maxLength: 32 + minLength: 2 + pattern: ^[a-z][a-z0-9-]{0,30}[a-z0-9]$ + type: string + example: web-app-01 + region: + description: >- + The slug form of the geographical origin of the app. Default: + `nearest available` + type: string + enum: + - atl + - nyc + - sfo + - tor + - ams + - fra + - lon + - blr + - sgp + - syd + example: nyc + disable_edge_cache: + description: >- + If set to `true`, the app will **not** be cached at the edge (CDN). + Enable this option if you want to manage CDN configuration + yourself—whether by using an external CDN provider or by handling + static content and caching within your app. This setting is also + recommended for apps that require real-time data or serve dynamic + content, such as those using Server-Sent Events (SSE) over GET, or + hosting an MCP (Model Context Protocol) Server that utilizes SSE. + + **Note:** This feature is not available for static site + components. + + For more information, see [Disable CDN + Cache](https://docs.digitalocean.com/products/app-platform/how-to/cache-content/#disable-cdn-cache). + type: boolean + default: false + disable_email_obfuscation: + description: >- + If set to `true`, email addresses in the app will not be obfuscated. + This is + + useful for apps that require email addresses to be visible (in the + HTML markup). + type: boolean + default: false + enhanced_threat_control_enabled: + description: >- + If set to `true`, suspicious requests will go through additional + security checks to help mitigate layer 7 DDoS attacks. + type: boolean + default: false + domains: + description: A set of hostnames where the application will be available. + type: array + items: + $ref: '#/components/schemas/app_domain_spec' + services: + description: Workloads which expose publicly-accessible HTTP services. + type: array + items: + $ref: '#/components/schemas/app_service_spec' + static_sites: + description: Content which can be rendered to static web assets. + type: array + items: + $ref: '#/components/schemas/app_static_site_spec' + jobs: + description: >- + Pre and post deployment workloads which do not expose + publicly-accessible HTTP routes. + type: array + items: + $ref: '#/components/schemas/app_job_spec' + workers: + description: Workloads which do not expose publicly-accessible HTTP services. + items: + $ref: '#/components/schemas/app_worker_spec' + type: array + functions: + description: >- + Workloads which expose publicly-accessible HTTP services via + Functions Components. + items: + $ref: '#/components/schemas/app_functions_spec' + type: array + databases: + description: >- + Database instances which can provide persistence to workloads within + the + + application. + type: array + items: + $ref: '#/components/schemas/app_database_spec' + ingress: + $ref: '#/components/schemas/app_ingress_spec' + egress: + $ref: '#/components/schemas/app_egress_spec' + maintenance: + $ref: '#/components/schemas/app_maintenance_spec' + vpc: + $ref: '#/components/schemas/apps_vpc' + required: + - name + apps_deployment_static_site: + properties: + name: + title: The name of this static site + type: string + example: web + source_commit_hash: + title: >- + The commit hash of the repository that was used to build this static + site + type: string + example: 54d4a727f457231062439895000d45437c7bb405 + type: object + apps_deployment_worker: + properties: + name: + title: The name of this worker + type: string + example: queue-runner + source_commit_hash: + title: The commit hash of the repository that was used to build this worker + type: string + example: 54d4a727f457231062439895000d45437c7bb405 + type: object + apps_deployment: + properties: + cause: + title: What caused this deployment to be created + type: string + example: commit 9a4df0b pushed to github/digitalocean/sample-golang + cloned_from: + title: The ID of a previous deployment that this deployment was cloned from + type: string + example: 3aa4d20e-5527-4c00-b496-601fbd22520a + created_at: + format: date-time + title: The creation time of the deployment + type: string + example: '2020-07-28T18:00:00Z' + id: + title: The ID of the deployment + type: string + example: b6bdf840-2854-4f87-a36c-5f231c617c84 + jobs: + items: + $ref: '#/components/schemas/apps_deployment_job' + title: Job components that are part of this deployment + type: array + functions: + type: array + items: + $ref: '#/components/schemas/apps_deployment_functions' + title: Functions components that are part of this deployment + phase: + $ref: '#/components/schemas/apps_deployment_phase' + phase_last_updated_at: + format: date-time + title: When the deployment phase was last updated + type: string + example: '0001-01-01T00:00:00Z' + progress: + $ref: '#/components/schemas/apps_deployment_progress' + services: + items: + $ref: '#/components/schemas/apps_deployment_service' + title: Service components that are part of this deployment + type: array + spec: + $ref: '#/components/schemas/app_spec' + static_sites: + items: + $ref: '#/components/schemas/apps_deployment_static_site' + title: Static Site components that are part of this deployment + type: array + tier_slug: + readOnly: true + title: The current pricing tier slug of the deployment + type: string + example: basic + updated_at: + format: date-time + title: When the deployment was last updated + type: string + example: '2020-07-28T18:00:00Z' + workers: + items: + $ref: '#/components/schemas/apps_deployment_worker' + title: Worker components that are part of this deployment + type: array + title: An app deployment + type: object + apps_domain_phase: + default: UNKNOWN + enum: + - UNKNOWN + - PENDING + - CONFIGURING + - ACTIVE + - ERROR + type: string + example: ACTIVE + apps_domain_progress: + properties: + steps: + items: + type: object + title: The steps of the domain's progress + type: array + type: object + app_domain_validation: + properties: + txt_name: + title: TXT record name + type: string + readOnly: true + example: _acme-challenge.app.example.com + txt_value: + title: TXT record value + type: string + readOnly: true + example: lXLOcN6cPv0nproViNcUHcahD9TrIPlNgdwesj0pYpk + apps_domain: + properties: + id: + title: The ID of the domain + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + phase: + $ref: '#/components/schemas/apps_domain_phase' + progress: + $ref: '#/components/schemas/apps_domain_progress' + spec: + $ref: '#/components/schemas/app_domain_spec' + validations: + title: List of TXT validation records + type: array + items: + $ref: '#/components/schemas/app_domain_validation' + rotate_validation_records: + title: Validation values have changed and require manual intervention + type: boolean + readOnly: true + certificate_expires_at: + title: Current SSL certificate expiration time + type: string + format: date-time + readOnly: true + example: '2024-01-29T23:59:59Z' + type: object + apps_region: + properties: + continent: + readOnly: true + title: The continent that this region is in + type: string + example: europe + data_centers: + items: + type: string + example: ams + readOnly: true + title: Data centers that are in this region + type: array + example: + - ams + default: + description: Whether or not the region is presented as the default. + readOnly: true + type: boolean + example: true + disabled: + readOnly: true + title: Whether or not the region is open for new apps + type: boolean + example: true + flag: + readOnly: true + title: The flag of this region + type: string + example: ams + label: + readOnly: true + title: A human-readable name of the region + type: string + example: ams + reason: + readOnly: true + title: Reason that this region is not available + type: string + example: to crowded + slug: + readOnly: true + title: The slug form of the region name + type: string + example: basic + title: Geographical information about an app origin + type: object + apps_dedicated_egress_ip_status: + title: The status of the dedicated egress IP. + type: string + readOnly: true + default: UNKNOWN + enum: + - UNKNOWN + - ASSIGNING + - ASSIGNED + - REMOVED + example: ASSIGNED + apps_dedicated_egress_ip: + type: object + readOnly: true + properties: + ip: + title: The IP address of the dedicated egress IP. + type: string + example: 192.168.1.1 + id: + title: The ID of the dedicated egress IP. + type: string + example: 9e7bc2ac-205a-45d6-919c-e1ac5e73f962 + status: + $ref: '#/components/schemas/apps_dedicated_egress_ip_status' + app: + description: An application's configuration and status. + properties: + active_deployment: + $ref: '#/components/schemas/apps_deployment' + created_at: + format: date-time + readOnly: true + title: The creation time of the app + type: string + example: '2020-11-19T20:27:18Z' + default_ingress: + readOnly: true + title: The default hostname on which the app is accessible + type: string + example: digitalocean.com + domains: + items: + $ref: '#/components/schemas/apps_domain' + readOnly: true + title: Contains all domains for the app + type: array + id: + readOnly: true + title: The ID of the application + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + in_progress_deployment: + $ref: '#/components/schemas/apps_deployment' + last_deployment_created_at: + format: date-time + readOnly: true + title: The creation time of the last deployment + type: string + example: '2020-11-19T20:27:18Z' + live_domain: + readOnly: true + title: The live domain of the app + type: string + example: live_domain + live_url: + readOnly: true + title: The live URL of the app + type: string + example: google.com + live_url_base: + readOnly: true + title: The live URL base of the app, the URL excluding the path + type: string + example: digitalocean.com + owner_uuid: + readOnly: true + title: The ID of the account to which the application belongs + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + pending_deployment: + allOf: + - description: >- + The most recent pending deployment. For CreateApp and UpdateApp + transactions this is guaranteed to reflect the associated + deployment. + - $ref: '#/components/schemas/apps_deployment' + project_id: + readOnly: true + type: string + example: 88b72d1a-b78a-4d9f-9090-b53c4399073f + title: >- + The ID of the project the app is assigned to. This will be empty if + there is a lookup failure. + description: Requires `project:read` scope. + region: + $ref: '#/components/schemas/apps_region' + spec: + $ref: '#/components/schemas/app_spec' + tier_slug: + readOnly: true + title: The current pricing tier slug of the app + type: string + example: basic + updated_at: + format: date-time + readOnly: true + title: Time of the app's last configuration update + type: string + example: '2020-12-01T00:42:16Z' + pinned_deployment: + allOf: + - description: The deployment that the app is pinned to. + - $ref: '#/components/schemas/apps_deployment' + dedicated_ips: + readOnly: true + title: The dedicated egress IP addresses associated with the app. + type: array + items: + $ref: '#/components/schemas/apps_dedicated_egress_ip' + vpc: + $ref: '#/components/schemas/apps_vpc' + required: + - spec + type: object + apps_response: + allOf: + - type: object + properties: + apps: + title: A list of apps + type: array + items: + $ref: '#/components/schemas/app' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + apps_create_app_request: + properties: + spec: + $ref: '#/components/schemas/app_spec' + project_id: + type: string + description: > + The ID of the project the app should be assigned to. If omitted, it + will be assigned to your default project. + +

Requires `project:update` scope. + required: + - spec + type: object + app_response: + properties: + app: + $ref: '#/components/schemas/app' + type: object + apps_update_app_request: + type: object + properties: + spec: + $ref: '#/components/schemas/app_spec' + update_all_source_versions: + type: boolean + description: >- + Whether or not to update the source versions (for example fetching a + new commit or image digest) of all components. By default (when this + is false) only newly added sources will be updated to avoid changes + like updating the scale of a component from also updating the + respective code. + example: true + default: false + required: + - spec + apps_delete_app_response: + properties: + id: + title: The ID of the app that was deleted + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + type: object + apps_restart_request: + type: object + properties: + components: + title: >- + Optional list of components to restart. If not provided, all + components will be restarted. + type: array + items: + type: string + example: + - component1 + - component2 + apps_deployment_response: + properties: + deployment: + $ref: '#/components/schemas/apps_deployment' + type: object + apps_get_logs_response: + properties: + historic_urls: + items: + type: string + example: https://logs/build.log + title: A list of URLs to archived log files + type: array + live_url: + description: >- + A URL of the real-time live logs. This URL may use either the + `https://` or `wss://` protocols and will keep pushing live logs as + they become available. + type: string + example: ws://logs/build + type: object + apps_get_exec_response: + properties: + url: + description: >- + A websocket URL that allows sending/receiving console input and + receiving console output. + type: string + example: wss://exec/?token=xxx + type: object + app_instance: + type: object + properties: + component_name: + type: string + example: sample-golang + description: Name of the component, from the app spec. + component_type: + type: string + description: Supported compute component by DigitalOcean App Platform. + enum: + - SERVICE + - WORKER + - JOB + example: SERVICE + instance_name: + type: string + description: Name of the instance, which is a unique identifier for the instance. + example: sample-golang-76b84c7fb8-6p8kq + instance_alias: + type: string + description: >- + Readable identifier, an alias of the instance name, reference for + mapping insights to instance names. + example: sample-golang-0 + app_instances: + type: object + properties: + instances: + type: array + items: + $ref: '#/components/schemas/app_instance' + apps_deployments_response: + allOf: + - type: object + properties: + deployments: + title: A list of deployments + type: array + items: + $ref: '#/components/schemas/apps_deployment' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + apps_create_deployment_request: + type: object + properties: + force_build: + title: >- + Indicates whether to force a build of app from source even if an + existing cached build is suitable for re-use + type: boolean + example: true + schema: + type: string + app_job_invocation: + type: object + properties: + id: + type: string + title: The ID of the job invocation + example: ba32b134-569c-4c0c-ba02-8ffdb0492ece + job_name: + type: string + title: The name of the job this invocation belongs to. + example: good-job + deployment_id: + type: string + title: The deployment ID this job invocation belongs to. + example: c020763f-ddb7-4112-a0df-7f01c69fc00b + phase: + type: string + description: The phase of the job invocation + enum: + - UNKNOWN + - PENDING + - RUNNING + - SUCCEEDED + - FAILED + - CANCELED + - SKIPPED + example: SUCCEEDED + trigger: + title: The JobInvocation Trigger + type: object + properties: + type: + type: string + description: The type of trigger that initiated the job invocation. + default: UNKNOWN + enum: + - MANUAL + - SCHEDULE + - UNKNOWN + example: MANUAL + scheduled: + type: object + description: The schedule for the job + properties: + schedule: + type: object + properties: + cron: + type: string + description: The cron expression defining the schedule + example: 0 0 * * * + time_zone: + type: string + description: The time zone for the schedule + example: America/New_York + example: + schedule: + cron: 0 0 * * * + time_zone: America/New_York + manual: + type: object + description: Details about the manual trigger, if applicable + properties: + user: + type: object + properties: + uuid: + type: string + title: The ID of the user who triggered the job + example: 550e8400-e29b-41d4-a716-446655440000 + email: + type: string + format: email + title: The email of the user who triggered the job + example: user@example.com + full_name: + type: string + title: The name of the user who triggered the job + example: John Doe + description: The user who triggered the job + example: + user: + uuid: 550e8400-e29b-41d4-a716-446655440000 + email: user@example.com + full_name: John Doe + created_at: + type: string + format: date-time + title: The time when the job invocation was created + example: '2023-10-01T12:00:00Z' + started_at: + type: string + format: date-time + title: The time when the job invocation started + example: '2023-10-01T12:05:00Z' + completed_at: + type: string + format: date-time + title: The time when the job invocation completed + example: '2023-10-01T12:10:00Z' + app_job_invocations: + allOf: + - type: object + properties: + job_invocations: + title: A list of job invocations + type: array + items: + $ref: '#/components/schemas/app_job_invocation' + - $ref: '#/components/schemas/pagination' + app_event: + type: object + properties: + id: + type: string + title: The ID of the event (UUID) + example: ba32b134-569c-4c0c-ba02-8ffdb0492ece + type: + type: string + description: The type of event + enum: + - UNKNOWN + - DEPLOYMENT + - AUTOSCALING + example: DEPLOYMENT + created_at: + type: string + format: date-time + title: When the event was created + example: '2023-10-01T12:00:00Z' + deployment_id: + type: string + title: The deployment ID associated with this event + description: >- + For deployment events, this is the same as the deployment's ID. For + autoscaling events, this is the deployment that was autoscaled. + example: c020763f-ddb7-4112-a0df-7f01c69fc00b + deployment: + $ref: '#/components/schemas/apps_deployment' + autoscaling: + type: object + description: Autoscaling event details. Only present for autoscaling events. + properties: + phase: + type: string + description: The current phase of the autoscaling event + enum: + - UNKNOWN + - PENDING + - IN_PROGRESS + - SUCCEEDED + - FAILED + - CANCELED + example: SUCCEEDED + components: + type: object + description: Map of component names to their scale changes + additionalProperties: + type: object + properties: + from: + type: integer + format: int64 + description: The number of replicas before scaling + example: 1 + to: + type: integer + format: int64 + description: The number of replicas after scaling + example: 3 + triggering_metric: + type: string + description: >- + The metric that triggered the scale change. Known values + are "cpu", "requests_per_second", "request_duration". For + inactivity sleep, "scale_from_zero" and "scale_to_zero" + are used. + example: cpu + app_events: + allOf: + - type: object + properties: + events: + title: A list of events + type: array + items: + $ref: '#/components/schemas/app_event' + - $ref: '#/components/schemas/pagination' + instance_size_cpu_type: + default: UNSPECIFIED + enum: + - UNSPECIFIED + - SHARED + - DEDICATED + title: |- + - SHARED: Shared vCPU cores + - DEDICATED: Dedicated vCPU cores + type: string + example: SHARED + apps_instance_size: + properties: + bandwidth_allowance_gib: + format: int64 + title: The bandwidth allowance in GiB for the instance size + type: string + example: '1' + cpu_type: + $ref: '#/components/schemas/instance_size_cpu_type' + cpus: + format: int64 + title: The number of allotted vCPU cores + type: string + example: '3' + deprecation_intent: + title: Indicates if the instance size is intended for deprecation + type: boolean + example: true + memory_bytes: + format: int64 + title: The allotted memory in bytes + type: string + example: '1048' + name: + title: A human-readable name of the instance size + type: string + example: name + scalable: + title: Indicates if the instance size can enable autoscaling + type: boolean + example: false + single_instance_only: + title: Indicates if the instance size allows more than one instance + type: boolean + example: true + slug: + title: The slug of the instance size + type: string + example: apps-s-1vcpu-1gb + tier_downgrade_to: + title: >- + The slug of the corresponding downgradable instance size on the + lower tier + type: string + example: basic + deprecated: true + tier_slug: + title: The slug of the tier to which this instance size belongs + type: string + example: basic + tier_upgrade_to: + title: >- + The slug of the corresponding upgradable instance size on the higher + tier + type: string + example: basic + deprecated: true + usd_per_month: + title: The cost of this instance size in USD per month + type: string + example: '23' + usd_per_second: + title: The cost of this instance size in USD per second + type: string + example: '0.00000001232' + type: object + apps_list_instance_sizes_response: + properties: + discount_percent: + format: float + type: number + example: 2.32 + instance_sizes: + items: + $ref: '#/components/schemas/apps_instance_size' + type: array + type: object + apps_get_instance_size_response: + properties: + instance_size: + $ref: '#/components/schemas/apps_instance_size' + type: object + apps_list_regions_response: + properties: + regions: + items: + $ref: '#/components/schemas/apps_region' + type: array + type: object + app_propose: + type: object + properties: + spec: + $ref: '#/components/schemas/app_spec' + app_id: + type: string + description: >- + An optional ID of an existing app. If set, the spec will be treated + as a proposed update to the specified app. The existing app is not + modified using this method. + example: b6bdf840-2854-4f87-a36c-5f231c617c84 + required: + - spec + app_propose_response: + type: object + properties: + app_is_static: + type: boolean + description: Indicates whether the app is a static app. + example: true + app_name_available: + type: boolean + description: Indicates whether the app name is available. + example: true + app_name_suggestion: + type: string + description: The suggested name if the proposed app name is unavailable. + example: newName + existing_static_apps: + type: string + description: >- + The maximum number of free static apps the account can have. We will + charge you for any additional static apps. + example: '2' + spec: + $ref: '#/components/schemas/app_spec' + app_cost: + type: integer + format: int32 + description: The monthly cost of the proposed app in USD. + example: 5 + app_tier_downgrade_cost: + type: integer + format: int32 + description: >- + The monthly cost of the proposed app in USD using the previous + pricing plan tier. For example, if you propose an app that uses the + Professional tier, the `app_tier_downgrade_cost` field displays the + monthly cost of the app if it were to use the Basic tier. If the + proposed app already uses the lest expensive tier, the field is + empty. + example: 17 + deprecated: true + app_alert_email: + default: '' + type: string + example: sammy@digitalocean.com + app_alert_slack_webhook: + properties: + url: + title: URL of the Slack webhook + type: string + example: >- + https://example.invalid/redacted-slack-webhook + channel: + title: Name of the Slack Webhook Channel + type: string + example: Channel Name + type: object + app_alert_phase: + default: UNKNOWN + enum: + - UNKNOWN + - PENDING + - CONFIGURING + - ACTIVE + - ERROR + type: string + example: ACTIVE + app_alert_progress_step_status: + default: UNKNOWN + enum: + - UNKNOWN + - PENDING + - RUNNING + - ERROR + - SUCCESS + type: string + example: SUCCESS + app_alert_progress_step_reason: + properties: + code: + title: The error code + type: string + example: Title of Error + message: + title: The error message + type: string + example: This is an error + type: object + app_alert_progress_step: + properties: + name: + title: The name of this step + type: string + example: example_step + status: + $ref: '#/components/schemas/app_alert_progress_step_status' + started_at: + format: date-time + title: The start time of this step + type: string + example: '2020-11-19T20:27:18Z' + ended_at: + format: date-time + title: The start time of this step + type: string + example: '2020-11-19T20:27:18Z' + reason: + $ref: '#/components/schemas/app_alert_progress_step_reason' + type: object + app_alert_progress: + properties: + steps: + title: Steps of an alert's progress. + type: array + items: + $ref: '#/components/schemas/app_alert_progress_step' + type: object + app_alert: + properties: + id: + readOnly: true + title: The ID of the alert + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + component_name: + title: Name of component the alert belongs to + type: string + example: backend + spec: + $ref: '#/components/schemas/app_alert_spec' + emails: + title: Emails for alerts to go to + type: array + items: + $ref: '#/components/schemas/app_alert_email' + example: + - sammy@digitalocean.com + slack_webhooks: + title: Slack Webhooks to send alerts to + type: array + items: + $ref: '#/components/schemas/app_alert_slack_webhook' + phase: + $ref: '#/components/schemas/app_alert_phase' + progress: + $ref: '#/components/schemas/app_alert_progress' + type: object + apps_list_alerts_response: + properties: + alerts: + type: array + items: + $ref: '#/components/schemas/app_alert' + type: object + apps_assign_app_alert_destinations_request: + properties: + emails: + type: array + items: + $ref: '#/components/schemas/app_alert_email' + example: + - sammy@digitalocean.com + slack_webhooks: + type: array + items: + $ref: '#/components/schemas/app_alert_slack_webhook' + type: object + apps_alert_response: + properties: + alert: + $ref: '#/components/schemas/app_alert' + type: object + apps_rollback_app_request: + type: object + properties: + deployment_id: + type: string + description: The ID of the deployment to rollback to. + example: 3aa4d20e-5527-4c00-b496-601fbd22520a + skip_pin: + type: boolean + description: >- + Whether to skip pinning the rollback deployment. If false, the + rollback deployment will be pinned and any new deployments including + Auto Deploy on Push hooks will be disabled until the rollback is + either manually committed or reverted via the CommitAppRollback or + RevertAppRollback endpoints respectively. If true, the rollback will + be immediately committed and the app will remain unpinned. + example: false + app_rollback_validation_condition: + type: object + properties: + code: + type: string + enum: + - incompatible_phase + - incompatible_result + - exceeded_revision_limit + - app_pinned + - database_config_conflict + - region_conflict + - static_site_requires_rebuild + - image_source_missing_digest + example: exceeded_revision_limit + description: | + A code identifier that represents the failing condition. + + Failing conditions: + - `incompatible_phase` - indicates that the deployment's phase is not suitable for rollback. + - `incompatible_result` - indicates that the deployment's result is not suitable for rollback. + - `exceeded_revision_limit` - indicates that the app has exceeded the rollback revision limits for its tier. + - `app_pinned` - indicates that there is already a rollback in progress and the app is pinned. + - `database_config_conflict` - indicates that the deployment's database config is different than the current config. + - `region_conflict` - indicates that the deployment's region differs from the current app region. + + Warning conditions: + - `static_site_requires_rebuild` - indicates that the deployment contains at least one static site that will require a rebuild. + - `image_source_missing_digest` - indicates that the deployment contains at least one component with an image source that is missing a digest. + message: + type: string + description: A human-readable message describing the failing condition. + example: >- + the deployment is past the maximum historical revision limit of 0 + for the "starter" app tier + components: + type: array + items: + type: string + description: >- + If applicable, a list of components that are failing the + condition. + example: + - www + app_metrics_bandwidth_usage_details: + type: object + properties: + app_id: + type: string + description: The ID of the app. + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + bandwidth_bytes: + type: string + format: uint64 + description: The used bandwidth amount in bytes. + example: '513668' + description: Bandwidth usage for an app. + app_metrics_bandwidth_usage: + type: object + properties: + app_bandwidth_usage: + type: array + items: + $ref: '#/components/schemas/app_metrics_bandwidth_usage_details' + description: A list of bandwidth usage details by app. + date: + type: string + format: date-time + description: The date for the metrics data. + example: '2023-01-17T00:00:00Z' + app_metrics_bandwidth_usage_request: + type: object + properties: + app_ids: + type: array + items: + type: string + description: A list of app IDs to query bandwidth metrics for. + maxItems: 100 + example: + - 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + - c2a93513-8d9b-4223-9d61-5e7272c81cf5 + date: + type: string + format: date-time + description: >- + Optional day to query. Only the date component of the timestamp will + be considered. Default: yesterday. + example: '2023-01-17T00:00:00Z' + required: + - app_ids + app_component_health: + type: object + properties: + name: + type: string + example: sample_app + cpu_usage_percent: + type: number + format: double + example: 30 + memory_usage_percent: + type: number + format: double + example: 25 + replicas_desired: + type: integer + format: int64 + example: 1 + replicas_ready: + type: integer + format: int64 + example: 1 + state: + type: string + enum: + - UNKNOWN + - HEALTHY + - UNHEALTHY + default: UNKNOWN + example: HEALTHY + app_functions_component_health: + type: object + properties: + name: + type: string + example: sample_function + functions_component_health_metrics: + type: array + items: + type: object + properties: + metric_label: + type: string + example: activations_count + metric_value: + type: number + format: double + example: 100 + time_window: + type: string + example: 1h + app_health: + type: object + properties: + components: + type: array + items: + $ref: '#/components/schemas/app_component_health' + functions_components: + type: array + items: + $ref: '#/components/schemas/app_functions_component_health' + app_health_response: + properties: + app_health: + $ref: '#/components/schemas/app_health' + type: object + cdn_endpoint: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: >- + A unique ID that can be used to identify and reference a CDN + endpoint. + origin: + type: string + format: hostname + example: static-images.nyc3.digitaloceanspaces.com + description: >- + The fully qualified domain name (FQDN) for the origin server which + provides the content for the CDN. This is currently restricted to a + Space. + endpoint: + type: string + format: hostname + readOnly: true + example: static-images.nyc3.cdn.digitaloceanspaces.com + description: >- + The fully qualified domain name (FQDN) from which the CDN-backed + content is served. + ttl: + type: integer + example: 3600 + enum: + - 60 + - 600 + - 3600 + - 86400 + - 604800 + default: 3600 + description: >- + The amount of time the content is cached by the CDN's edge servers + in seconds. TTL must be one of 60, 600, 3600, 86400, or 604800. + Defaults to 3600 (one hour) when excluded. + certificate_id: + type: string + format: uuid + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: >- + The ID of a DigitalOcean managed TLS certificate used for SSL when a + custom subdomain is provided. + custom_domain: + type: string + format: hostname + example: static.example.com + description: >- + The fully qualified domain name (FQDN) of the custom subdomain used + with the CDN endpoint. + created_at: + type: string + format: date-time + readOnly: true + example: '2018-03-21T16:02:37Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the CDN endpoint was created. + required: + - origin + update_endpoint: + type: object + properties: + ttl: + type: integer + example: 3600 + enum: + - 60 + - 600 + - 3600 + - 86400 + - 604800 + default: 3600 + description: >- + The amount of time the content is cached by the CDN's edge servers + in seconds. TTL must be one of 60, 600, 3600, 86400, or 604800. + Defaults to 3600 (one hour) when excluded. + certificate_id: + type: string + format: uuid + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: >- + The ID of a DigitalOcean managed TLS certificate used for SSL when a + custom subdomain is provided. + custom_domain: + type: string + format: hostname + example: static.example.com + description: >- + The fully qualified domain name (FQDN) of the custom subdomain used + with the CDN endpoint. + purge_cache: + type: object + properties: + files: + type: array + items: + type: string + example: + - path/to/image.png + - path/to/css/* + description: >- + An array of strings containing the path to the content to be purged + from the CDN cache. + required: + - files + certificate: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: >- + A unique ID that can be used to identify and reference a + certificate. + name: + type: string + example: web-cert-01 + description: A unique human-readable name referring to a certificate. + not_after: + type: string + format: date-time + readOnly: true + example: '2017-02-22T00:23:00Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents the certificate's expiration date. + sha1_fingerprint: + type: string + readOnly: true + example: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + description: >- + A unique identifier generated from the SHA-1 fingerprint of the + certificate. + created_at: + type: string + format: date-time + readOnly: true + example: '2017-02-08T16:02:37Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the certificate was created. + dns_names: + type: array + items: + type: string + example: + - www.example.com + - example.com + description: >- + An array of fully qualified domain names (FQDNs) for which the + certificate was issued. + state: + type: string + enum: + - pending + - verified + - error + readOnly: true + example: verified + description: >- + A string representing the current state of the certificate. It may + be `pending`, `verified`, or `error`. + type: + type: string + enum: + - custom + - lets_encrypt + example: lets_encrypt + description: >- + A string representing the type of the certificate. The value will be + `custom` for a user-uploaded certificate or `lets_encrypt` for one + automatically generated with Let's Encrypt. + certificate_create_base: + type: object + properties: + name: + type: string + example: web-cert-01 + description: A unique human-readable name referring to a certificate. + type: + type: string + enum: + - custom + - lets_encrypt + example: lets_encrypt + description: >- + A string representing the type of the certificate. The value will be + `custom` for a user-uploaded certificate or `lets_encrypt` for one + automatically generated with Let's Encrypt. + required: + - name + certificate_request_lets_encrypt: + title: Let's Encrypt Certificate Request + allOf: + - $ref: '#/components/schemas/certificate_create_base' + - type: object + properties: + dns_names: + type: array + items: + type: string + example: + - www.example.com + - example.com + description: >- + An array of fully qualified domain names (FQDNs) for which the + certificate was issued. A certificate covering all subdomains + can be issued using a wildcard (e.g. `*.example.com`). + required: + - dns_names + certificate_request_custom: + title: Custom Certificate Request + allOf: + - $ref: '#/components/schemas/certificate_create_base' + - type: object + properties: + private_key: + type: string + example: |- + -----BEGIN PRIVATE KEY----- + MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52 + SVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1 + DwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X + wrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w + Z2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F + ZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX + fqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l + 9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm + cVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt + eRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF + 0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x + gtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh + GGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+ + P8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj + IntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49 + W1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ + 3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt + Nfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx + pxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG + RKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0 + o4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E + sAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW + JUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo + QbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/ + AangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg + eTuK2xNR0PIM8OI7pRpgyj1I + -----END PRIVATE KEY----- + description: >- + The contents of a PEM-formatted private-key corresponding to the + SSL certificate. + leaf_certificate: + type: string + example: |- + -----BEGIN CERTIFICATE----- + MIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA + MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD + ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x + NzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j + b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+ + CYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb + 8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4 + oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz + Z03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna + k/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb + QwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB + BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1 + MbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG + CCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl + dHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s + ZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu + Zy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW + MCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB + BQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1 + cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp + dGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl + bmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM + PKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e + iXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD + D3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7 + q9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/ + WyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu + UlF1zblDmg2Iaw== + -----END CERTIFICATE----- + description: The contents of a PEM-formatted public SSL certificate. + certificate_chain: + type: string + example: |- + -----BEGIN CERTIFICATE----- + MIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA + MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD + ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x + NzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j + b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz7tnK6V52SVf+ + CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb + 8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4 + oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz + Z03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna + k/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb + QwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB + BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1 + MbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG + CCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl + dHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s + ZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu + Zy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgEwgeWECysGAQQBgt8TAQEBMIHW + MCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB + BQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1 + cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp + dGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBsdHRwczovL2xldHNl + bmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM + PKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e + iXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD + D3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL3o+UIY39X0dV3WOboW2Re8nrkFXJ7 + q9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/ + WyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu + UlF1zblDmg2Iaw== + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/ + MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT + DkRTVCBSb290IENBIFgzMB4XDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0Nlow + SjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxldCdzIEVuY3J5cHQxIzAhBgNVBAMT + GkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkqhkiG9w0BAQEFAAOC + AQ8AMIIBCgKCAQEAnNMM8FrlLsd3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4S0EF + q6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8 + SMx+yk13EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0 + Z8h/pZq4UmEUEz9l6YKHy9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWA + a6xK8xuQSXgvopZPKiAlKQTGdMDQMc2PMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj + /PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIPOIUo4IBfTCCAXkwEgYDVR0T + AQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEEczBxMDIG + CCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNv + bTA7BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9k + c3Ryb290Y2F4My5wN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAw + VAYDVR0gBE0wSzAIBgZngQwBAgEwPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcC + ARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNyeXB0Lm9yZzA8BgNVHR8ENTAz + MDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9PVENBWDNDUkwu + Y3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF + AAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJo + uM2VcGfl96S8TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/ + wApIvJSwtmVi4MFU5aMqrSDE6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwu + X4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPMTZ+sOPAveyxindmjkW8lGy+QsRlG + PfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6 + KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg== + -----END CERTIFICATE----- + description: >- + The full PEM-formatted trust chain between the certificate + authority's certificate and your domain's SSL certificate. + required: + - private_key + - leaf_certificate + balance: + type: object + properties: + month_to_date_balance: + type: string + description: >- + Balance as of the `generated_at` time. This value includes the + `account_balance` and `month_to_date_usage`. + example: '23.44' + account_balance: + type: string + description: >- + Current balance of the customer's most recent billing activity. + Does not reflect `month_to_date_usage`. + example: '12.23' + month_to_date_usage: + type: string + description: >- + Amount used in the current billing period as of the `generated_at` + time. + example: '11.21' + generated_at: + type: string + format: date-time + description: The time at which balances were most recently generated. + example: '2019-07-09T15:01:12Z' + billing_history: + type: object + properties: + description: + type: string + description: Description of the billing history entry. + example: Invoice for May 2018 + amount: + type: string + description: Amount of the billing history entry. + example: '12.34' + invoice_id: + type: string + description: >- + ID of the invoice associated with the billing history entry, if + applicable. + example: '123' + invoice_uuid: + type: string + description: >- + UUID of the invoice associated with the billing history entry, if + applicable. + example: example-uuid + date: + type: string + format: date-time + description: Time the billing history entry occurred. + example: '2018-06-01T08:44:38Z' + type: + type: string + description: Type of billing history entry. + example: Invoice + enum: + - ACHFailure + - Adjustment + - AttemptFailed + - Chargeback + - Credit + - CreditExpiration + - Invoice + - Payment + - Refund + - Reversal + meta_optional_total: + type: object + properties: + meta: + $ref: '#/components/schemas/meta_properties' + required: + - meta + invoice_preview: + type: object + description: The invoice preview. + properties: + invoice_uuid: + type: string + description: The UUID of the invoice. The canonical reference for the invoice. + example: fdabb512-6faf-443c-ba2e-665452332a9e + invoice_id: + type: string + description: >- + ID of the invoice. Listed on the face of the invoice PDF as the + "Invoice number". + example: '123456789' + amount: + type: string + description: >- + Total amount of the invoice, in USD. This will reflect + month-to-date usage in the invoice preview. + example: '23.45' + invoice_period: + type: string + description: >- + Billing period of usage for which the invoice is issued, in + `YYYY-MM` format. + example: 2020-01 + updated_at: + type: string + description: >- + Time the invoice was last updated. This is only included with the + invoice preview. + example: '2020-01-23T06:31:50Z' + invoice_item: + type: object + properties: + product: + type: string + description: Name of the product being billed in the invoice item. + example: Kubernetes Clusters + resource_uuid: + type: string + description: UUID of the resource billing in the invoice item if available. + example: 711157cb-37c8-4817-b371-44fa3504a39c + resource_id: + type: string + description: ID of the resource billing in the invoice item if available. + example: '2353624' + group_description: + type: string + description: >- + Description of the invoice item when it is a grouped set of usage, + such as DOKS or databases. + example: my-doks-cluster + description: + type: string + description: Description of the invoice item. + example: a56e086a317d8410c8b4cfd1f4dc9f82 + amount: + type: string + description: Billed amount of this invoice item. Billed in USD. + example: '12.34' + duration: + type: string + description: Duration of time this invoice item was used and subsequently billed. + example: '744' + duration_unit: + type: string + description: Unit of time for duration. + example: Hours + start_time: + type: string + description: Time the invoice item began to be billed for usage. + example: '2020-01-01T00:00:00Z' + end_time: + type: string + description: Time the invoice item stopped being billed for usage. + example: '2020-02-01T00:00:00Z' + project_name: + type: string + description: Name of the DigitalOcean Project this resource belongs to. + example: web + billing_address: + type: object + properties: + address_line1: + type: string + description: Street address line 1 + example: 101 Shark Row + address_line2: + type: string + description: Street address line 2 + example: ' ' + city: + type: string + description: City + example: Atlantis + region: + type: string + description: Region + example: OC + postal_code: + type: string + description: Postal code + example: '12345' + country_iso2_code: + type: string + description: Country (ISO2) code + example: US + created_at: + type: string + description: Timestamp billing address was created + example: '2019-09-03T16:34:46.000+00:00' + updated_at: + type: string + description: Timestamp billing address was updated + example: '2019-09-03T16:34:46.000+00:00' + product_charge_item: + type: object + properties: + amount: + type: string + description: Amount of the charge + example: '10.00' + name: + type: string + description: Description of the charge + example: Spaces Subscription + count: + type: string + description: Number of times the charge was applied + example: '1' + product_usage_charges: + type: object + properties: + name: + type: string + description: Description of usage charges + example: Product usage charges + amount: + type: string + description: Total amount charged + example: '12.34' + items: + type: array + description: List of amount, and grouped aggregates by resource type. + items: + $ref: '#/components/schemas/product_charge_item' + example: + - amount: '10.00' + name: Spaces Subscription + count: '1' + - amount: '2.34' + name: Database Clusters + count: '1' + simple_charge: + type: object + properties: + name: + type: string + description: Name of the charge + example: Overages + amount: + type: string + description: Total amount charged in USD + example: '3.45' + invoice_summary: + type: object + properties: + invoice_uuid: + type: string + description: UUID of the invoice + example: 22737513-0ea7-4206-8ceb-98a575af7681 + invoice_id: + type: string + description: ID of the invoice + example: '123456789' + billing_period: + type: string + description: >- + Billing period of usage for which the invoice is issued, in + `YYYY-MM` format. + example: 2020-01 + amount: + type: string + description: >- + Total amount of the invoice, in USD. This will reflect + month-to-date usage in the invoice preview. + example: '27.13' + user_name: + type: string + description: Name of the DigitalOcean customer being invoiced. + example: Sammy Shark + user_billing_address: + allOf: + - description: The billing address of the customer being invoiced. + - $ref: '#/components/schemas/billing_address' + user_company: + type: string + description: Company of the DigitalOcean customer being invoiced, if set. + example: DigitalOcean + user_email: + type: string + description: Email of the DigitalOcean customer being invoiced. + example: sammy@digitalocean.com + product_charges: + allOf: + - description: >- + A summary of the product usage charges contributing to the + invoice. This will include an amount, and grouped aggregates by + resource type under the `items` key. + - $ref: '#/components/schemas/product_usage_charges' + overages: + allOf: + - description: A summary of the overages contributing to the invoice. + - $ref: '#/components/schemas/simple_charge' + taxes: + allOf: + - description: A summary of the taxes contributing to the invoice. + - $ref: '#/components/schemas/simple_charge' + credits_and_adjustments: + allOf: + - description: >- + A summary of the credits and adjustments contributing to the + invoice. + - $ref: '#/components/schemas/simple_charge' + billing_data_point: + type: object + properties: + usage_team_urn: + type: string + description: URN of the team that incurred the usage + example: do:team:12345678-1234-1234-1234-123456789012 + start_date: + type: string + format: date + description: Start date of the billing data point in YYYY-MM-DD format + example: '2025-01-15' + total_amount: + type: string + description: Total amount for this data point in USD + example: '12.45' + region: + type: string + description: Region where the usage occurred + example: nyc3 + sku: + type: string + description: Unique SKU identifier for the billed resource + example: 1-DO-DROP-0109 + description: + type: string + description: >- + Description of the billed resource or service as shown on an invoice + item + example: droplet name (c-2-4GiB) + group_description: + type: string + description: >- + Optional invoice item group name of the billed resource or service, + blank when not part an invoice item group + example: kubernetes cluster name + database_region_options: + type: object + properties: + regions: + type: array + items: + type: string + example: + - ams3 + - blr1 + readOnly: true + description: An array of strings containing the names of available regions + database_version_options: + type: object + properties: + versions: + type: array + items: + type: string + example: + - '4.4' + - '5.0' + readOnly: true + description: An array of strings containing the names of available regions + database_layout_option: + type: object + properties: + num_nodes: + type: integer + example: 1 + sizes: + type: array + items: + type: string + example: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + readOnly: true + description: >- + An array of objects containing the slugs available with various node + counts + database_layout_options: + type: object + properties: + layouts: + type: array + readOnly: true + description: >- + An array of objects, each indicating the node sizes (otherwise + referred to as slugs) that are available with various numbers of + nodes in the database cluster. Each slugs denotes the node's + identifier, CPU, and RAM (in that order). + items: + $ref: '#/components/schemas/database_layout_option' + database_version_availability: + type: object + properties: + end_of_life: + type: string + example: '2023-11-09T00:00:00Z' + nullable: true + description: >- + A timestamp referring to the date when the particular version will + no longer be supported. If null, the version does not have an end of + life timeline. + end_of_availability: + type: string + example: '2023-05-09T00:00:00Z' + nullable: true + description: >- + A timestamp referring to the date when the particular version will + no longer be available for creating new clusters. If null, the + version does not have an end of availability timeline. + version: + type: string + example: '8' + description: The engine version. + database_version_availabilities: + type: array + description: >- + An array of objects, each indicating the version end-of-life, + end-of-availability for various database engines + items: + $ref: '#/components/schemas/database_version_availability' + options: + type: object + properties: + options: + type: object + properties: + kafka: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + mongodb: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + pg: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + mysql: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + redis: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + valkey: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + opensearch: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + advanced_pg: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + advanced_mysql: + allOf: + - $ref: '#/components/schemas/database_region_options' + - $ref: '#/components/schemas/database_version_options' + - $ref: '#/components/schemas/database_layout_options' + version_availability: + type: object + properties: + kafka: + $ref: '#/components/schemas/database_version_availabilities' + pg: + $ref: '#/components/schemas/database_version_availabilities' + mysql: + $ref: '#/components/schemas/database_version_availabilities' + redis: + $ref: '#/components/schemas/database_version_availabilities' + valkey: + $ref: '#/components/schemas/database_version_availabilities' + mongodb: + $ref: '#/components/schemas/database_version_availabilities' + opensearch: + $ref: '#/components/schemas/database_version_availabilities' + advanced_pg: + $ref: '#/components/schemas/database_version_availabilities' + advanced_mysql: + $ref: '#/components/schemas/database_version_availabilities' + opensearch_connection: + type: object + properties: + uri: + type: string + description: >- + This is provided as a convenience and should be able to be + constructed by the other attributes. + example: >- + https://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060 + readOnly: true + host: + type: string + description: The FQDN pointing to the opensearch cluster's current primary node. + example: backend-do-user-19081923-0.db.ondigitalocean.com + readOnly: true + port: + type: integer + description: The port on which the opensearch dashboard is listening. + example: 25060 + readOnly: true + user: + type: string + description: >- + The default user for the opensearch dashboard.

Requires + `database:view_credentials` scope. + example: doadmin + readOnly: true + password: + type: string + description: >- + The randomly generated password for the default + user.

Requires `database:view_credentials` scope. + example: wv78n3zpz42xezdk + readOnly: true + ssl: + type: boolean + description: >- + A boolean value indicating if the connection should be made over + SSL. + example: true + readOnly: true + schema_registry_connection: + type: object + properties: + uri: + type: string + description: >- + This is provided as a convenience and should be able to be + constructed by the other attributes. + example: >- + https://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060 + readOnly: true + host: + type: string + description: The FQDN pointing to the schema registry connection uri. + example: backend-do-user-19081923-0.db.ondigitalocean.com + readOnly: true + port: + type: integer + description: The port on which the schema registry is listening. + example: 20835 + readOnly: true + user: + type: string + description: >- + The default user for the schema registry.

Requires + `database:view_credentials` scope. + example: doadmin + readOnly: true + password: + type: string + description: >- + The randomly generated password for the schema + registry.

Requires `database:view_credentials` scope. + example: wv78n3zpz42xezdk + readOnly: true + ssl: + type: boolean + description: >- + A boolean value indicating if the connection should be made over + SSL. + example: true + readOnly: true + database_connection: + type: object + properties: + uri: + type: string + description: >- + A connection string in the format accepted by the `psql` command. + This is provided as a convenience and should be able to be + constructed by the other attributes. + example: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + readOnly: true + database: + type: string + description: The name of the default database. + example: defaultdb + readOnly: true + host: + type: string + description: The FQDN pointing to the database cluster's current primary node. + example: backend-do-user-19081923-0.db.ondigitalocean.com + readOnly: true + port: + type: integer + description: The port on which the database cluster is listening. + example: 25060 + readOnly: true + user: + type: string + description: >- + The default user for the database.

Requires + `database:view_credentials` scope. + example: doadmin + readOnly: true + password: + type: string + description: >- + The randomly generated password for the default + user.

Requires `database:view_credentials` scope. + example: wv78n3zpz42xezdk + readOnly: true + ssl: + type: boolean + description: >- + A boolean value indicating if the connection should be made over + SSL. + example: true + readOnly: true + mysql_settings: + type: object + properties: + auth_plugin: + type: string + enum: + - mysql_native_password + - caching_sha2_password + example: mysql_native_password + description: > + A string specifying the authentication method to be used for + connections + + to the MySQL user account. The valid values are + `mysql_native_password` + + or `caching_sha2_password`. If excluded when creating a new user, + the + + default for the version of MySQL in use will be used. As of MySQL + 8.0, the + + default is `caching_sha2_password`. + required: + - auth_plugin + user_settings: + type: object + properties: + pg_allow_replication: + type: boolean + example: true + description: > + For Postgres clusters, set to `true` for a user with replication + rights. + + This option is not currently supported for other database engines. + opensearch_acl: + type: array + items: + type: object + properties: + index: + type: string + example: index-abc.* + description: >- + A regex for matching the indexes that this ACL should apply + to. + permission: + type: string + enum: + - deny + - admin + - read + - readwrite + - write + example: read + description: >- + Permission set applied to the ACL. 'read' allows user to read + from the index. 'write' allows for user to write to the index. + 'readwrite' allows for both 'read' and 'write' permission. + 'deny'(default) restricts user from performing any operation + over an index. 'admin' allows for 'readwrite' as well as any + operations to administer the index. + description: >- + ACLs (Access Control Lists) specifying permissions on index within a + OpenSearch cluster. + acl: + type: array + items: + type: object + properties: + id: + type: string + description: >- + An identifier for the ACL. Will be computed after the ACL is + created/updated. + example: aaa + topic: + type: string + example: topic-abc.* + description: >- + A regex for matching the topic(s) that this ACL should apply + to. + permission: + type: string + enum: + - admin + - consume + - produce + - produceconsume + example: consume + description: >- + Permission set applied to the ACL. 'consume' allows for + messages to be consumed from the topic. 'produce' allows for + messages to be published to the topic. 'produceconsume' allows + for both 'consume' and 'produce' permission. 'admin' allows + for 'produceconsume' as well as any operations to administer + the topic (delete, update). + required: + - topic + - permission + description: >- + ACLs (Access Control Lists) specifying permissions on topics within + a Kafka cluster. + mongo_user_settings: + type: object + properties: + databases: + type: array + items: + type: string + example: my-db + example: + - my-db + - my-db-2 + description: >- + A list of databases to which the user should have access. When + the database is set to `admin`, the user will have access to all + databases based on the user's role i.e. a user with the role + `readOnly` assigned to the `admin` database will have read + access to all databases. + role: + type: string + enum: + - readOnly + - readWrite + - dbAdmin + example: readOnly + description: >- + The role to assign to the user with each role mapping to a + MongoDB built-in role. `readOnly` maps to a + [read](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-read) + role. `readWrite` maps to a + [readWrite](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readWrite) + role. `dbAdmin` maps to a + [dbAdmin](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-dbAdmin) + role. + description: >- + MongoDB-specific settings for the user. This option is not currently + supported for other database engines. + database_user: + type: object + properties: + name: + type: string + example: app-01 + description: The name of a database user. + role: + type: string + enum: + - primary + - normal + example: normal + description: > + A string representing the database user's role. The value will be + either + + "primary" or "normal". + readOnly: true + password: + type: string + example: jge5lfxtzhx42iff + description: >- + A randomly generated password for the database user.
Requires + `database:view_credentials` scope. + readOnly: true + access_cert: + type: string + example: |- + -----BEGIN CERTIFICATE----- + MIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA + MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD + ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x + NzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j + b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+ + CYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb + 8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4 + oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz + Z03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna + k/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb + QwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB + BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1 + MbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG + CCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl + dHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s + ZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu + Zy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW + MCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB + BQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1 + cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp + dGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl + bmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM + PKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e + iXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD + D3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7 + q9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/ + WyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu + UlF1zblDmg2Iaw== + -----END CERTIFICATE----- + description: Access certificate for TLS client authentication. (Kafka only) + readOnly: true + access_key: + type: string + example: |- + -----BEGIN PRIVATE KEY----- + MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52 + SVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1 + DwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X + wrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w + Z2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F + ZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX + fqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l + 9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm + cVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt + eRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF + 0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x + gtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh + GGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+ + P8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj + IntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49 + W1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ + 3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt + Nfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx + pxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG + RKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0 + o4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E + sAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW + JUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo + QbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/ + AangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg + eTuK2xNR0PIM8OI7pRpgyj1I + -----END PRIVATE KEY----- + description: Access key for TLS client authentication. (Kafka only) + readOnly: true + mysql_settings: + $ref: '#/components/schemas/mysql_settings' + settings: + $ref: '#/components/schemas/user_settings' + required: + - name + database_maintenance_window: + type: object + nullable: true + properties: + day: + type: string + example: tuesday + description: The day of the week on which to apply maintenance updates. + hour: + type: string + example: '14:00' + description: >- + The hour in UTC at which maintenance updates will be applied in 24 + hour format. + pending: + type: boolean + example: true + description: >- + A boolean value indicating whether any maintenance is scheduled to + be performed in the next window. + readOnly: true + description: + type: array + items: + type: string + description: >- + A list of strings, each containing information about a pending + maintenance update. + example: + - Update TimescaleDB to version 1.2.1 + - Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases + readOnly: true + required: + - day + - hour + firewall_rule: + type: object + properties: + uuid: + type: string + pattern: ^$|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12} + example: 79f26d28-ea8a-41f2-8ad8-8cfcdd020095 + description: A unique ID for the firewall rule itself. + cluster_uuid: + type: string + pattern: ^$|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12} + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + readOnly: true + description: A unique ID for the database cluster to which the rule is applied. + type: + type: string + enum: + - droplet + - k8s + - ip_addr + - tag + - app + example: droplet + description: >- + The type of resource that the firewall rule allows to access the + database cluster. + value: + type: string + example: ff2a6c52-5a44-4b63-b99c-0e98e7a63d61 + description: >- + The ID of the specific resource, the name of a tag applied to a + group of resources, or the IP address that the firewall rule allows + to access the database cluster. + created_at: + type: string + format: date-time + example: '2019-01-11T18:37:36Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the firewall rule was created. + readOnly: true + description: + type: string + example: an IP address for local development + description: A human-readable description of the rule. + required: + - type + - value + database_service_endpoint: + type: object + properties: + host: + type: string + description: A FQDN pointing to the database cluster's node(s). + example: backend-do-user-19081923-0.db.ondigitalocean.com + readOnly: true + port: + type: integer + description: The port on which a service is listening. + example: 9273 + readOnly: true + do_settings: + type: object + description: DigitalOcean-specific settings for the database cluster. + properties: + service_cnames: + type: array + items: + type: string + pattern: >- + ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)+$ + maxLength: 253 + maxItems: 16 + example: + - db.example.com + - database.myapp.io + description: >- + An array of custom CNAMEs for the database cluster. Each CNAME must + be a valid RFC 1123 hostname (e.g., "db.example.com"). Maximum of 16 + CNAMEs allowed, each up to 253 characters. + database_cluster_read: + type: object + properties: + id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + A unique ID that can be used to identify and reference a database + cluster. + readOnly: true + name: + type: string + example: backend + description: A unique, human-readable name referring to a database cluster. + engine: + type: string + example: mysql + enum: + - pg + - mysql + - redis + - valkey + - mongodb + - kafka + - opensearch + - advanced_pg + - advanced_mysql + description: >- + A slug representing the database engine used for the cluster. The + possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" + for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" + for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL + Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. + Advanced Edition engines are currently in public preview. + version: + type: string + example: '8' + description: >- + A string representing the version of the database engine in use for + the cluster. + semantic_version: + type: string + example: 8.0.28 + description: >- + A string representing the semantic version of the database engine in + use for the cluster. + readOnly: true + num_nodes: + type: integer + example: 2 + description: The number of nodes in the database cluster. + size: + type: string + example: db-s-2vcpu-4gb + description: >- + The slug identifier representing the size of the nodes in the + database cluster. + region: + type: string + example: nyc3 + description: >- + The slug identifier for the region where the database cluster is + located. + status: + type: string + enum: + - creating + - online + - resizing + - migrating + - forking + example: creating + description: A string representing the current status of the database cluster. + readOnly: true + created_at: + type: string + format: date-time + example: '2019-01-11T18:37:36Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the database cluster was created. + readOnly: true + private_network_uuid: + type: string + pattern: ^$|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12} + example: d455e75d-4858-4eec-8c95-da2f0a5f93a7 + description: >- + A string specifying the UUID of the VPC to which the database + cluster will be assigned. If excluded, the cluster when creating a + new database cluster, it will be assigned to your account's default + VPC for the region.

Requires `vpc:read` scope. + tags: + type: array + items: + type: string + example: + - production + nullable: true + description: >- + An array of tags that have been applied to the database cluster. +

Requires `tag:read` scope. + db_names: + type: array + items: + type: string + example: + - doadmin + nullable: true + readOnly: true + description: >- + An array of strings containing the names of databases created in the + database cluster. + ui_connection: + allOf: + - $ref: '#/components/schemas/opensearch_connection' + - readOnly: true + description: 'The connection details for OpenSearch dashboard. ' + schema_registry_connection: + allOf: + - $ref: '#/components/schemas/schema_registry_connection' + - readOnly: true + description: The connection details for Schema Registry. + connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + users: + type: array + nullable: true + items: + $ref: '#/components/schemas/database_user' + readOnly: true + maintenance_window: + allOf: + - $ref: '#/components/schemas/database_maintenance_window' + - readOnly: true + project_id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + The ID of the project that the database cluster is assigned to. If + excluded when creating a new database cluster, it will be assigned + to your default project.

Requires `project:read` scope. + rules: + type: array + items: + $ref: '#/components/schemas/firewall_rule' + version_end_of_life: + type: string + example: '2023-11-09T00:00:00Z' + readOnly: true + description: >- + A timestamp referring to the date when the particular version will + no longer be supported. If null, the version does not have an end of + life timeline. + version_end_of_availability: + type: string + example: '2023-05-09T00:00:00Z' + readOnly: true + description: >- + A timestamp referring to the date when the particular version will + no longer be available for creating new clusters. If null, the + version does not have an end of availability timeline. + storage_size_mib: + type: integer + example: 61440 + description: >- + Additional storage added to the cluster, in MiB. If null, no + additional storage is added to the cluster, beyond what is provided + as a base amount from the 'size' and any previously added additional + storage. + metrics_endpoints: + type: array + items: + $ref: '#/components/schemas/database_service_endpoint' + description: >- + Public hostname and port of the cluster's metrics endpoint(s). + Includes one record for the cluster's primary node and a second + entry for the cluster's standby node(s). + readOnly: true + do_settings: + allOf: + - $ref: '#/components/schemas/do_settings' + - description: >- + DigitalOcean-specific settings for the database cluster, + including custom service CNAMEs. + required: + - name + - engine + - num_nodes + - size + - region + database_storage_autoscale_params: + type: object + description: Configuration for database cluster storage autoscaling + properties: + enabled: + type: boolean + description: Whether storage autoscaling is enabled for the cluster + example: true + threshold_percent: + type: integer + minimum: 15 + maximum: 95 + description: >- + The storage usage threshold percentage that triggers autoscaling. + When storage usage exceeds this percentage, additional storage will + be added automatically. + example: 80 + increment_gib: + type: integer + minimum: 10 + maximum: 500 + description: >- + The amount of additional storage to add (in GiB) when autoscaling is + triggered + example: 10 + required: + - enabled + database_autoscale_params: + type: object + description: Contains all autoscaling configuration for a database cluster + properties: + storage: + allOf: + - $ref: '#/components/schemas/database_storage_autoscale_params' + - description: Storage autoscaling configuration + database_cluster: + type: object + properties: + id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + A unique ID that can be used to identify and reference a database + cluster. + readOnly: true + name: + type: string + example: backend + description: A unique, human-readable name referring to a database cluster. + engine: + type: string + example: mysql + enum: + - pg + - mysql + - redis + - valkey + - mongodb + - kafka + - opensearch + - advanced_pg + - advanced_mysql + description: >- + A slug representing the database engine used for the cluster. The + possible values are: "pg" for PostgreSQL, "mysql" for MySQL, "redis" + for Caching, "mongodb" for MongoDB, "kafka" for Kafka, "opensearch" + for OpenSearch, "valkey" for Valkey, "advanced_pg" for PostgreSQL + Advanced Edition, and "advanced_mysql" for MySQL Advanced Edition. + Advanced Edition engines are currently in public preview. + version: + type: string + example: '8' + description: >- + A string representing the version of the database engine in use for + the cluster. + semantic_version: + type: string + example: 8.0.28 + description: >- + A string representing the semantic version of the database engine in + use for the cluster. + readOnly: true + num_nodes: + type: integer + example: 2 + description: The number of nodes in the database cluster. + size: + type: string + example: db-s-2vcpu-4gb + description: >- + The slug identifier representing the size of the nodes in the + database cluster. + region: + type: string + example: nyc3 + description: >- + The slug identifier for the region where the database cluster is + located. + status: + type: string + enum: + - creating + - online + - resizing + - migrating + - forking + example: creating + description: A string representing the current status of the database cluster. + readOnly: true + created_at: + type: string + format: date-time + example: '2019-01-11T18:37:36Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the database cluster was created. + readOnly: true + private_network_uuid: + type: string + pattern: ^$|[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12} + example: d455e75d-4858-4eec-8c95-da2f0a5f93a7 + description: >- + A string specifying the UUID of the VPC to which the database + cluster will be assigned. If excluded, the cluster when creating a + new database cluster, it will be assigned to your account's default + VPC for the region.

Requires `vpc:read` scope. + tags: + type: array + items: + type: string + example: + - production + nullable: true + description: >- + An array of tags (as strings) to apply to the database cluster. +

Requires `tag:create` scope. + db_names: + type: array + items: + type: string + example: + - doadmin + nullable: true + readOnly: true + description: >- + An array of strings containing the names of databases created in the + database cluster. + ui_connection: + allOf: + - $ref: '#/components/schemas/opensearch_connection' + - readOnly: true + description: 'The connection details for OpenSearch dashboard. ' + schema_registry_connection: + allOf: + - $ref: '#/components/schemas/schema_registry_connection' + - readOnly: true + description: The connection details for Schema Registry. + connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + users: + type: array + nullable: true + items: + $ref: '#/components/schemas/database_user' + readOnly: true + maintenance_window: + allOf: + - $ref: '#/components/schemas/database_maintenance_window' + - readOnly: true + project_id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + The ID of the project that the database cluster is assigned to. If + excluded when creating a new database cluster, it will be assigned + to your default project.

Requires `project:update` scope. + rules: + type: array + items: + $ref: '#/components/schemas/firewall_rule' + version_end_of_life: + type: string + example: '2023-11-09T00:00:00Z' + readOnly: true + description: >- + A timestamp referring to the date when the particular version will + no longer be supported. If null, the version does not have an end of + life timeline. + version_end_of_availability: + type: string + example: '2023-05-09T00:00:00Z' + readOnly: true + description: >- + A timestamp referring to the date when the particular version will + no longer be available for creating new clusters. If null, the + version does not have an end of availability timeline. + storage_size_mib: + type: integer + example: 61440 + description: >- + Additional storage added to the cluster, in MiB. If null, no + additional storage is added to the cluster, beyond what is provided + as a base amount from the 'size' and any previously added additional + storage. + metrics_endpoints: + type: array + items: + $ref: '#/components/schemas/database_service_endpoint' + description: >- + Public hostname and port of the cluster's metrics endpoint(s). + Includes one record for the cluster's primary node and a second + entry for the cluster's standby node(s). + readOnly: true + autoscale: + allOf: + - $ref: '#/components/schemas/database_autoscale_params' + description: >- + Autoscaling configuration for the database cluster. Currently only + supports storage autoscaling. If null, autoscaling is not configured + for the cluster. + do_settings: + allOf: + - $ref: '#/components/schemas/do_settings' + - description: >- + DigitalOcean-specific settings for the database cluster, + including custom service CNAMEs. + required: + - name + - engine + - num_nodes + - size + - region + database_backup: + type: object + properties: + database_name: + type: string + example: backend + description: >- + The name of an existing database cluster from which the backup will + be restored. + backup_created_at: + type: string + format: date-time + example: '2019-01-31T19:25:22Z' + description: >- + The timestamp of an existing database cluster backup in ISO8601 + combined date and time format. The most recent backup will be used + if excluded. + required: + - database_name + mysql_incremental_backup: + type: object + description: MySQL Incremental Backup configuration settings + properties: + enabled: + description: >- + Enable periodic incremental backups. When enabled, + full_backup_week_schedule must be set. Incremental backups only + store changes since the last backup, making them faster and more + storage-efficient than full backups. This is particularly useful for + large databases where daily full backups would be too time-consuming + or expensive. + type: boolean + full_backup_week_schedule: + description: >- + Comma-separated list of days of the week when full backups should be + created. Valid values: mon, tue, wed, thu, fri, sat, sun. Default is + null. Example : "mon,fri,sun". + type: string + example: mon,thu + mysql_advanced_config: + type: object + properties: + backup_hour: + description: >- + The hour of day (in UTC) when backup for the service starts. New + backup only starts if previous backup has already completed. + minimum: 0 + maximum: 23 + type: integer + example: 3 + backup_minute: + description: >- + The minute of the backup hour when backup for the service starts. + New backup only starts if previous backup has already completed. + minimum: 0 + maximum: 59 + type: integer + example: 30 + sql_mode: + description: >- + Global SQL mode. If empty, uses MySQL server defaults. Must only + include uppercase alphabetic characters, underscores, and commas. + type: string + pattern: ^[A-Z_]*(,[A-Z_]+)*$ + example: ANSI,TRADITIONAL + maxLength: 1024 + connect_timeout: + description: >- + The number of seconds that the mysqld server waits for a connect + packet before responding with bad handshake. + type: integer + minimum: 2 + maximum: 3600 + example: 10 + default_time_zone: + description: >- + Default server time zone, in the form of an offset from UTC (from + -12:00 to +12:00), a time zone name (EST), or 'SYSTEM' to use the + MySQL server default. + type: string + example: '+03:00' + minLength: 2 + maxLength: 100 + group_concat_max_len: + description: >- + The maximum permitted result length, in bytes, for the + GROUP_CONCAT() function. + type: integer + minimum: 4 + maximum: 18446744073709552000 + example: 1024 + information_schema_stats_expiry: + description: The time, in seconds, before cached statistics expire. + type: integer + minimum: 900 + maximum: 31536000 + example: 86400 + innodb_ft_min_token_size: + description: The minimum length of words that an InnoDB FULLTEXT index stores. + type: integer + minimum: 0 + maximum: 16 + example: 3 + innodb_ft_server_stopword_table: + description: The InnoDB FULLTEXT index stopword list for all InnoDB tables. + type: string + pattern: ^.+/.+$ + example: db_name/table_name + maxLength: 1024 + innodb_lock_wait_timeout: + description: >- + The time, in seconds, that an InnoDB transaction waits for a row + lock. before giving up. + type: integer + minimum: 1 + maximum: 3600 + example: 50 + innodb_log_buffer_size: + description: >- + The size of the buffer, in bytes, that InnoDB uses to write to the + log files. on disk. + type: integer + minimum: 1048576 + maximum: 4294967295 + example: 16777216 + innodb_online_alter_log_max_size: + description: >- + The upper limit, in bytes, of the size of the temporary log files + used during online DDL operations for InnoDB tables. + type: integer + minimum: 65536 + maximum: 1099511627776 + example: 134217728 + innodb_print_all_deadlocks: + description: >- + When enabled, records information about all deadlocks in InnoDB user + transactions in the error log. Disabled by default. + type: boolean + example: true + innodb_rollback_on_timeout: + description: >- + When enabled, transaction timeouts cause InnoDB to abort and roll + back the entire transaction. + type: boolean + example: true + interactive_timeout: + description: >- + The time, in seconds, the server waits for activity on an + interactive. connection before closing it. + type: integer + minimum: 30 + maximum: 604800 + example: 3600 + internal_tmp_mem_storage_engine: + description: The storage engine for in-memory internal temporary tables. + type: string + enum: + - TempTable + - MEMORY + example: TempTable + net_read_timeout: + description: >- + The time, in seconds, to wait for more data from an existing + connection. aborting the read. + type: integer + minimum: 1 + maximum: 3600 + example: 30 + net_write_timeout: + description: >- + The number of seconds to wait for a block to be written to a + connection before aborting the write. + type: integer + minimum: 1 + maximum: 3600 + example: 30 + sql_require_primary_key: + description: >- + Require primary key to be defined for new tables or old tables + modified with ALTER TABLE and fail if missing. It is recommended to + always have primary keys because various functionality may break if + any large table is missing them. + type: boolean + example: true + wait_timeout: + description: >- + The number of seconds the server waits for activity on a + noninteractive connection before closing it. + type: integer + minimum: 1 + maximum: 2147483 + example: 28800 + max_allowed_packet: + description: >- + The size of the largest message, in bytes, that can be received by + the server. Default is 67108864 (64M). + type: integer + minimum: 102400 + maximum: 1073741824 + example: 67108864 + max_heap_table_size: + description: >- + The maximum size, in bytes, of internal in-memory tables. Also set + tmp_table_size. Default is 16777216 (16M) + type: integer + minimum: 1048576 + maximum: 1073741824 + example: 16777216 + sort_buffer_size: + description: >- + The sort buffer size, in bytes, for ORDER BY optimization. Default + is 262144. (256K). + type: integer + minimum: 32768 + maximum: 1073741824 + example: 262144 + tmp_table_size: + description: >- + The maximum size, in bytes, of internal in-memory tables. Also set + max_heap_table_size. Default is 16777216 (16M). + type: integer + minimum: 1048576 + maximum: 1073741824 + example: 16777216 + slow_query_log: + description: >- + When enabled, captures slow queries. When disabled, also truncates + the mysql.slow_log table. Default is false. + type: boolean + example: true + long_query_time: + description: >- + The time, in seconds, for a query to take to execute before being + captured by slow_query_logs. Default is 10 seconds. + type: number + minimum: 0 + maximum: 3600 + example: 10 + binlog_retention_period: + description: >- + The minimum amount of time, in seconds, to keep binlog entries + before deletion. This may be extended for services that require + binlog entries for longer than the default, for example if using the + MySQL Debezium Kafka connector. + type: number + minimum: 600 + maximum: 604800 + example: 600 + innodb_change_buffer_max_size: + description: >- + Specifies the maximum size of the InnoDB change buffer as a + percentage of the buffer pool. + type: integer + minimum: 0 + maximum: 50 + example: 25 + innodb_flush_neighbors: + description: >- + Specifies whether flushing a page from the InnoDB buffer pool also + flushes other dirty pages in the same extent. + - 0 — disables this functionality, dirty pages in the same extent are not flushed. + - 1 — flushes contiguous dirty pages in the same extent. + - 2 — flushes dirty pages in the same extent. + type: integer + enum: + - 0 + - 1 + - 2 + example: 0 + innodb_read_io_threads: + description: >- + The number of I/O threads for read operations in InnoDB. Changing + this parameter will lead to a restart of the MySQL service. + type: integer + minimum: 1 + maximum: 64 + example: 16 + innodb_write_io_threads: + description: >- + The number of I/O threads for write operations in InnoDB. Changing + this parameter will lead to a restart of the MySQL service. + type: integer + minimum: 1 + maximum: 64 + example: 16 + innodb_thread_concurrency: + description: >- + Defines the maximum number of threads permitted inside of InnoDB. A + value of 0 (the default) is interpreted as infinite concurrency (no + limit). This variable is intended for performance tuning on high + concurrency systems. + type: integer + minimum: 0 + maximum: 1000 + example: 0 + net_buffer_length: + description: >- + Start sizes of connection buffer and result buffer, must be multiple + of 1024. Changing this parameter will lead to a restart of the MySQL + service. + type: integer + minimum: 1024 + maximum: 1048576 + example: 4096 + log_output: + description: >- + Defines the destination for logs. Can be `INSIGHTS`, `TABLE`, or + both (`INSIGHTS,TABLE`), or `NONE` to disable logs. To specify both + destinations, use `INSIGHTS,TABLE` (order matters). Default is NONE. + type: string + enum: + - INSIGHTS + - TABLE + - INSIGHTS,TABLE + - NONE + example: INSIGHTS + default: NONE + mysql_incremental_backup: + $ref: '#/components/schemas/mysql_incremental_backup' + pgbouncer_advanced_config: + type: object + description: PGBouncer connection pooling settings + properties: + server_reset_query_always: + description: Run server_reset_query (DISCARD ALL) in all pooling modes. + type: boolean + example: false + ignore_startup_parameters: + description: List of parameters to ignore when given in startup packet. + type: array + example: + - extra_float_digits + - search_path + items: + description: Enum of parameters to ignore when given in startup packet. + type: string + enum: + - extra_float_digits + - search_path + maxItems: 32 + min_pool_size: + description: >- + If current server connections are below this number, adds more. + Improves behavior when usual load comes suddenly back after period + of total inactivity. The value is effectively capped at the pool + size. + type: integer + minimum: 0 + maximum: 10000 + example: 1 + server_lifetime: + description: >- + The pooler closes any unused server connection that has been + connected longer than this amount of seconds. + type: integer + minimum: 60 + maximum: 86400 + example: 3600 + server_idle_timeout: + description: >- + Drops server connections if they have been idle more than this many + seconds. If 0, timeout is disabled. + type: integer + minimum: 0 + maximum: 86400 + example: 600 + autodb_pool_size: + description: >- + If non-zero, automatically creates a pool of that size per user when + a pool doesn't exist. + type: integer + minimum: 0 + maximum: 10000 + example: 1 + autodb_pool_mode: + enum: + - session + - transaction + - statement + example: session + description: PGBouncer pool mode + type: string + autodb_max_db_connections: + description: >- + Only allows a maximum this many server connections per database + (regardless of user). If 0, allows unlimited connections. + type: integer + minimum: 0 + maximum: 2147483647 + example: 1 + autodb_idle_timeout: + description: >- + If the automatically-created database pools have been unused this + many seconds, they are freed. If 0, timeout is disabled. + type: integer + minimum: 0 + maximum: 86400 + example: 3600 + timescaledb_advanced_config: + type: object + description: TimescaleDB extension configuration values + properties: + max_background_workers: + description: >- + The number of background workers for timescaledb operations. Set to + the sum of your number of databases and the total number of + concurrent background workers you want running at any given point in + time. + type: integer + minimum: 1 + maximum: 4096 + example: 8 + postgres_advanced_config: + type: object + properties: + autovacuum_freeze_max_age: + description: >- + Specifies the maximum age (in transactions) that a table's + pg_class.relfrozenxid field can attain before a VACUUM operation is + forced to prevent transaction ID wraparound within the table. Note + that the system will launch autovacuum processes to prevent + wraparound even when autovacuum is otherwise disabled. This + parameter will cause the server to be restarted. + type: integer + minimum: 200000000 + maximum: 1500000000 + example: 200000000 + autovacuum_max_workers: + description: >- + Specifies the maximum number of autovacuum processes (other than the + autovacuum launcher) that may be running at any one time. The + default is three. This parameter can only be set at server start. + type: integer + minimum: 1 + maximum: 20 + example: 5 + autovacuum_naptime: + description: >- + Specifies the minimum delay, in seconds, between autovacuum runs on + any given database. The default is one minute. + type: integer + minimum: 0 + maximum: 86400 + example: 43200 + autovacuum_vacuum_threshold: + description: >- + Specifies the minimum number of updated or deleted tuples needed to + trigger a VACUUM in any one table. The default is 50 tuples. + type: integer + minimum: 0 + maximum: 2147483647 + example: 50 + autovacuum_analyze_threshold: + description: >- + Specifies the minimum number of inserted, updated, or deleted tuples + needed to trigger an ANALYZE in any one table. The default is 50 + tuples. + type: integer + minimum: 0 + maximum: 2147483647 + example: 50 + autovacuum_vacuum_scale_factor: + description: >- + Specifies a fraction, in a decimal value, of the table size to add + to autovacuum_vacuum_threshold when deciding whether to trigger a + VACUUM. The default is 0.2 (20% of table size). + type: number + minimum: 0 + maximum: 1 + example: 0.2 + autovacuum_analyze_scale_factor: + description: >- + Specifies a fraction, in a decimal value, of the table size to add + to autovacuum_analyze_threshold when deciding whether to trigger an + ANALYZE. The default is 0.2 (20% of table size). + type: number + minimum: 0 + maximum: 1 + example: 0.2 + autovacuum_vacuum_cost_delay: + description: >- + Specifies the cost delay value, in milliseconds, that will be used + in automatic VACUUM operations. If -1, uses the regular + vacuum_cost_delay value, which is 20 milliseconds. + type: integer + minimum: -1 + maximum: 100 + example: 20 + autovacuum_vacuum_cost_limit: + description: >- + Specifies the cost limit value that will be used in automatic VACUUM + operations. If -1 is specified (which is the default), the regular + vacuum_cost_limit value will be used. + type: integer + minimum: -1 + maximum: 10000 + example: -1 + backup_hour: + description: >- + The hour of day (in UTC) when backup for the service starts. New + backup only starts if previous backup has already completed. + minimum: 0 + maximum: 23 + type: integer + example: 3 + backup_minute: + description: >- + The minute of the backup hour when backup for the service starts. + New backup is only started if previous backup has already completed. + minimum: 0 + maximum: 59 + type: integer + example: 30 + bgwriter_delay: + description: >- + Specifies the delay, in milliseconds, between activity rounds for + the background writer. Default is 200 ms. + type: integer + minimum: 10 + maximum: 10000 + example: 200 + bgwriter_flush_after: + description: >- + The amount of kilobytes that need to be written by the background + writer before attempting to force the OS to issue these writes to + underlying storage. Specified in kilobytes, default is 512. Setting + of 0 disables forced writeback. + type: integer + minimum: 0 + maximum: 2048 + example: 512 + bgwriter_lru_maxpages: + description: >- + The maximum number of buffers that the background writer can write. + Setting this to zero disables background writing. Default is 100. + type: integer + minimum: 0 + maximum: 1073741823 + example: 100 + bgwriter_lru_multiplier: + description: >- + The average recent need for new buffers is multiplied by + bgwriter_lru_multiplier to arrive at an estimate of the number that + will be needed during the next round, (up to bgwriter_lru_maxpages). + 1.0 represents a “just in time” policy of writing exactly the number + of buffers predicted to be needed. Larger values provide some + cushion against spikes in demand, while smaller values intentionally + leave writes to be done by server processes. The default is 2.0. + type: number + minimum: 0 + maximum: 10 + example: 2 + deadlock_timeout: + description: >- + The amount of time, in milliseconds, to wait on a lock before + checking to see if there is a deadlock condition. + type: integer + minimum: 500 + maximum: 1800000 + example: 1000 + default_toast_compression: + description: >- + Specifies the default TOAST compression method for values of + compressible columns (the default is lz4). + type: string + enum: + - lz4 + - pglz + example: lz4 + idle_in_transaction_session_timeout: + description: >- + Time out sessions with open transactions after this number of + milliseconds + type: integer + minimum: 0 + maximum: 604800000 + example: 10000 + jit: + description: >- + Activates, in a boolean, the system-wide use of Just-in-Time + Compilation (JIT). + type: boolean + example: true + log_autovacuum_min_duration: + description: >- + Causes each action executed by autovacuum to be logged if it ran for + at least the specified number of milliseconds. Setting this to zero + logs all autovacuum actions. Minus-one (the default) disables + logging autovacuum actions. + type: integer + minimum: -1 + maximum: 2147483647 + example: -1 + log_error_verbosity: + description: >- + Controls the amount of detail written in the server log for each + message that is logged. + type: string + enum: + - TERSE + - DEFAULT + - VERBOSE + example: VERBOSE + log_line_prefix: + description: >- + Selects one of the available log-formats. These can support popular + log analyzers like pgbadger, pganalyze, etc. + type: string + enum: + - pid=%p,user=%u,db=%d,app=%a,client=%h + - '%m [%p] %q[user=%u,db=%d,app=%a]' + - '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h' + example: pid=%p,user=%u,db=%d,app=%a,client=%h + log_min_duration_statement: + description: >- + Log statements that take more than this number of milliseconds to + run. If -1, disables. + type: integer + minimum: -1 + maximum: 86400000 + example: -1 + max_files_per_process: + description: PostgreSQL maximum number of files that can be open per process. + type: integer + minimum: 1000 + maximum: 4096 + example: 2048 + max_prepared_transactions: + description: >- + PostgreSQL maximum prepared transactions. Once increased, this + parameter cannot be lowered from its set value. + type: integer + minimum: 0 + maximum: 10000 + example: 20 + max_pred_locks_per_transaction: + description: PostgreSQL maximum predicate locks per transaction. + type: integer + minimum: 64 + maximum: 640 + example: 128 + max_locks_per_transaction: + description: >- + PostgreSQL maximum locks per transaction. Once increased, this + parameter cannot be lowered from its set value. + type: integer + minimum: 64 + maximum: 6400 + example: 128 + max_stack_depth: + description: Maximum depth of the stack in bytes. + type: integer + minimum: 2097152 + maximum: 6291456 + example: 2097152 + max_standby_archive_delay: + description: Max standby archive delay in milliseconds. + type: integer + minimum: 1 + maximum: 43200000 + example: 43200 + max_standby_streaming_delay: + description: Max standby streaming delay in milliseconds. + type: integer + minimum: 1 + maximum: 43200000 + example: 43200 + max_replication_slots: + description: PostgreSQL maximum replication slots. + type: integer + minimum: 8 + maximum: 64 + example: 16 + max_logical_replication_workers: + description: >- + PostgreSQL maximum logical replication workers (taken from the pool + of max_parallel_workers). + type: integer + minimum: 4 + maximum: 64 + example: 16 + max_parallel_workers: + description: >- + Sets the maximum number of workers that the system can support for + parallel queries. + type: integer + minimum: 0 + maximum: 96 + example: 12 + max_parallel_workers_per_gather: + description: >- + Sets the maximum number of workers that can be started by a single + Gather or Gather Merge node. + type: integer + minimum: 0 + maximum: 96 + example: 16 + max_worker_processes: + description: >- + Sets the maximum number of background processes that the system can + support. Once increased, this parameter cannot be lowered from its + set value. + type: integer + minimum: 8 + maximum: 96 + example: 16 + pg_partman_bgw.role: + type: string + pattern: ^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$ + maxLength: 64 + example: myrolename + description: >- + Controls which role to use for pg_partman's scheduled background + tasks. Must consist of alpha-numeric characters, dots, underscores, + or dashes. May not start with dash or dot. Maximum of 64 characters. + pg_partman_bgw.interval: + description: Sets the time interval to run pg_partman's scheduled tasks. + type: integer + minimum: 3600 + maximum: 604800 + example: 3600 + pg_stat_statements.track: + description: >- + Controls which statements are counted. Specify 'top' to track + top-level statements (those issued directly by clients), 'all' to + also track nested statements (such as statements invoked within + functions), or 'none' to disable statement statistics collection. + The default value is top. + type: string + enum: + - all + - top + - none + example: all + temp_file_limit: + description: PostgreSQL temporary file limit in KiB. If -1, sets to unlimited. + type: integer + example: 5000000 + minimum: -1 + maximum: 2147483647 + timezone: + description: PostgreSQL service timezone + type: string + example: Europe/Helsinki + maxLength: 64 + track_activity_query_size: + description: >- + Specifies the number of bytes reserved to track the currently + executing command for each active session. + type: integer + example: 1024 + minimum: 1024 + maximum: 10240 + track_commit_timestamp: + description: Record commit time of transactions. + type: string + enum: + - 'off' + - 'on' + example: 'off' + track_functions: + description: Enables tracking of function call counts and time used. + type: string + enum: + - all + - pl + - none + example: all + track_io_timing: + description: >- + Enables timing of database I/O calls. This parameter is off by + default, because it will repeatedly query the operating system for + the current time, which may cause significant overhead on some + platforms. + type: string + enum: + - 'off' + - 'on' + example: 'off' + max_wal_senders: + description: >- + PostgreSQL maximum WAL senders. Once increased, this parameter + cannot be lowered from its set value. + type: integer + minimum: 20 + maximum: 64 + example: 32 + wal_sender_timeout: + description: >- + Terminate replication connections that are inactive for longer than + this amount of time, in milliseconds. Setting this value to zero + disables the timeout. Must be either 0 or between 5000 and 10800000. + type: integer + minimum: 0 + maximum: 10800000 + example: 60000 + wal_writer_delay: + description: >- + WAL flush interval in milliseconds. Note that setting this value to + lower than the default 200ms may negatively impact performance + type: integer + minimum: 10 + maximum: 200 + example: 50 + shared_buffers_percentage: + description: >- + Percentage of total RAM that the database server uses for shared + memory buffers. Valid range is 20-60 (float), which corresponds to + 20% - 60%. This setting adjusts the shared_buffers configuration + value. + type: number + minimum: 20 + maximum: 60 + example: 41.5 + pgbouncer: + $ref: '#/components/schemas/pgbouncer_advanced_config' + work_mem: + description: >- + The maximum amount of memory, in MB, used by a query operation (such + as a sort or hash table) before writing to temporary disk files. + Default is 1MB + 0.075% of total RAM (up to 32MB). + type: integer + minimum: 1 + maximum: 1024 + example: 4 + timescaledb: + $ref: '#/components/schemas/timescaledb_advanced_config' + synchronous_replication: + description: >- + Synchronous replication type. Note that the service plan also needs + to support synchronous replication. + type: string + example: 'off' + enum: + - 'off' + - quorum + stat_monitor_enable: + description: >- + Enable the pg_stat_monitor extension. Enabling this extension + will cause the cluster to be restarted. When this extension is + enabled, pg_stat_statements results for utility commands are + unreliable. + type: boolean + example: false + max_failover_replication_time_lag: + description: >- + Number of seconds of master unavailability before triggering + database failover to standby. The default value is 60. + type: integer + minimum: 10 + maximum: 9223372036854776000 + example: 50 + max_connections: + description: >- + Sets the PostgreSQL maximum number of concurrent connections to the + database server. This is a limited-release parameter. Contact your + account team to confirm your eligibility. You cannot decrease this + parameter value when set. For services with a read replica, first + increase the read replica's value. After the change is applied to + the replica, you can increase the primary service's value. Changing + this parameter causes a service restart. + type: integer + minimum: 25 + example: 75 + max_slot_wal_keep_size: + description: >- + PostgreSQL maximum WAL size (MB) reserved for replication slots. If + -1 is specified, replication slots may retain an unlimited amount of + WAL files. The default is -1 (upstream default). wal_keep_size + minimum WAL size setting takes precedence over this. + type: integer + minimum: -1 + maximum: 2147483647 + example: 100 + redis_advanced_config: + type: object + properties: + redis_maxmemory_policy: + type: string + enum: + - noeviction + - allkeys-lru + - allkeys-random + - volatile-lru + - volatile-random + - volatile-ttl + description: >- + A string specifying the desired eviction policy for the Caching + cluster. + + + - `noeviction`: Don't evict any data, returns error when memory + limit is reached. + + - `allkeys-lru:` Evict any key, least recently used (LRU) first. + + - `allkeys-random`: Evict keys in a random order. + + - `volatile-lru`: Evict keys with expiration only, least recently + used (LRU) first. + + - `volatile-random`: Evict keys with expiration only in a random + order. + + - `volatile-ttl`: Evict keys with expiration only, shortest + time-to-live (TTL) first. + example: allkeys-lru + redis_pubsub_client_output_buffer_limit: + description: >- + Set output buffer limit for pub / sub clients in MB. The value is + the hard limit, the soft limit is 1/4 of the hard limit. When + setting the limit, be mindful of the available memory in the + selected service plan. + type: integer + minimum: 32 + maximum: 512 + example: 64 + redis_number_of_databases: + type: integer + minimum: 1 + maximum: 128 + description: >- + Set number of redis databases. Changing this will cause a restart of + redis service. + example: 16 + redis_io_threads: + description: Caching IO thread count + type: integer + minimum: 1 + maximum: 32 + example: 1 + redis_lfu_log_factor: + description: >- + Counter logarithm factor for volatile-lfu and allkeys-lfu + maxmemory-policies + type: integer + minimum: 0 + maximum: 100 + default: 10 + example: 10 + redis_lfu_decay_time: + description: LFU maxmemory-policy counter decay time in minutes + type: integer + minimum: 1 + maximum: 120 + default: 1 + example: 1 + redis_ssl: + description: > + Require SSL to access Caching. + + - When enabled, Caching accepts only SSL connections on port + `25061`. + + - When disabled, port `25060` is opened for non-SSL connections, + while port `25061` remains available for SSL connections. + type: boolean + default: true + example: true + redis_timeout: + description: Caching idle connection timeout in seconds + type: integer + minimum: 0 + maximum: 31536000 + default: 300 + example: 300 + redis_notify_keyspace_events: + description: >- + Set notify-keyspace-events option. Requires at least `K` or `E` and + accepts any combination of the following options. Setting the + parameter to `""` disables notifications. + + - `K` — Keyspace events + + - `E` — Keyevent events + + - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) + + - `$` — String commands + + - `l` — List commands + + - `s` — Set commands + + - `h` — Hash commands + + - `z` — Sorted set commands + + - `t` — Stream commands + + - `d` — Module key type events + + - `x` — Expired events + + - `e` — Evicted events + + - `m` — Key miss events + + - `n` — New key events + + - `A` — Alias for `"g$lshztxed"` + type: string + pattern: ^[KEg\$lshzxeA]*$ + default: '' + maxLength: 32 + example: K + redis_persistence: + type: string + enum: + - 'off' + - rdb + description: >- + Creates an RDB dump of the database every 10 minutes that can be + used to recover data after a node crash. The database does not + create the dump if no keys have changed since the last dump. When + set to `off`, the database cannot fork services, and data can be + lost if a service is restarted or powered off. DigitalOcean Managed + Caching databases do not support the Append Only File (AOF) + persistence method. + example: rdb + redis_acl_channels_default: + type: string + enum: + - allchannels + - resetchannels + description: >- + Determines default pub/sub channels' ACL for new users if ACL is not + supplied. When this option is not defined, all_channels is assumed + to keep backward compatibility. This option doesn't affect Caching + configuration acl-pubsub-default. + example: allchannels + eviction_policy_model: + type: string + enum: + - noeviction + - allkeys_lru + - allkeys_random + - volatile_lru + - volatile_random + - volatile_ttl + description: >- + A string specifying the desired eviction policy for a Caching or Valkey + cluster. + + + - `noeviction`: Don't evict any data, returns error when memory limit is + reached. + + - `allkeys_lru:` Evict any key, least recently used (LRU) first. + + - `allkeys_random`: Evict keys in a random order. + + - `volatile_lru`: Evict keys with expiration only, least recently used + (LRU) first. + + - `volatile_random`: Evict keys with expiration only in a random order. + + - `volatile_ttl`: Evict keys with expiration only, shortest time-to-live + (TTL) first. + example: allkeys_lru + valkey_advanced_config: + type: object + properties: + valkey_maxmemory_policy: + $ref: '#/components/schemas/eviction_policy_model' + valkey_pubsub_client_output_buffer_limit: + description: >- + Set output buffer limit for pub / sub clients in MB. The value is + the hard limit, the soft limit is 1/4 of the hard limit. When + setting the limit, be mindful of the available memory in the + selected service plan. + type: integer + minimum: 32 + maximum: 512 + example: 64 + valkey_number_of_databases: + type: integer + minimum: 1 + maximum: 128 + description: >- + Set number of valkey databases. Changing this will cause a restart + of valkey service. + example: 16 + valkey_io_threads: + description: Valkey IO thread count + type: integer + minimum: 1 + maximum: 32 + example: 1 + valkey_lfu_log_factor: + description: >- + Counter logarithm factor for volatile-lfu and allkeys-lfu + maxmemory-policies + type: integer + minimum: 0 + maximum: 100 + default: 10 + example: 10 + valkey_lfu_decay_time: + description: LFU maxmemory-policy counter decay time in minutes + type: integer + minimum: 1 + maximum: 120 + default: 1 + example: 1 + valkey_ssl: + description: Require SSL to access Valkey + type: boolean + default: true + example: true + valkey_timeout: + description: Valkey idle connection timeout in seconds + type: integer + minimum: 0 + maximum: 31536000 + default: 300 + example: 300 + valkey_notify_keyspace_events: + description: >- + Set notify-keyspace-events option. Requires at least `K` or `E` and + accepts any combination of the following options. Setting the + parameter to `""` disables notifications. + + - `K` — Keyspace events + + - `E` — Keyevent events + + - `g` — Generic commands (e.g. `DEL`, `EXPIRE`, `RENAME`, ...) + + - `$` — String commands + + - `l` — List commands + + - `s` — Set commands + + - `h` — Hash commands + + - `z` — Sorted set commands + + - `t` — Stream commands + + - `d` — Module key type events + + - `x` — Expired events + + - `e` — Evicted events + + - `m` — Key miss events + + - `n` — New key events + + - `A` — Alias for `"g$lshztxed"` + type: string + pattern: ^[KEg\$lshzxeA]*$ + default: '' + maxLength: 32 + example: K + valkey_persistence: + type: string + enum: + - 'off' + - rdb + description: >- + When persistence is 'rdb', Valkey does RDB dumps each 10 minutes if + any key is changed. Also RDB dumps are done according to backup + schedule for backup purposes. When persistence is 'off', no RDB + dumps and backups are done, so data can be lost at any moment if + service is restarted for any reason, or if service is powered off. + Also service can't be forked. + example: rdb + valkey_acl_channels_default: + type: string + enum: + - allchannels + - resetchannels + description: >- + Determines default pub/sub channels' ACL for new users if ACL is not + supplied. When this option is not defined, all_channels is assumed + to keep backward compatibility. This option doesn't affect Valkey + configuration acl-pubsub-default. + example: allchannels + frequent_snapshots: + type: boolean + default: true + description: > + Frequent RDB snapshots + + When enabled, Valkey will create frequent local RDB snapshots. When + disabled, Valkey will only take RDB snapshots when a backup is + created, based on the backup schedule. This setting is ignored when + valkey_persistence is set to off. + example: true + valkey_active_expire_effort: + type: integer + minimum: 1 + maximum: 10 + default: 1 + description: > + Active expire effort + + Valkey reclaims expired keys both when accessed and in the + background. The background process scans for expired keys to free + memory. Increasing the active-expire-effort setting (default 1, max + 10) uses more CPU to reclaim expired keys faster, reducing memory + usage but potentially increasing latency. + example: 1 + kafka_advanced_config: + type: object + properties: + compression_type: + description: >- + Specify the final compression type for a given topic. This + configuration accepts the standard compression codecs ('gzip', + 'snappy', 'lz4', 'zstd'). It additionally accepts 'uncompressed' + which is equivalent to no compression; and 'producer' which means + retain the original compression codec set by the producer. + type: string + enum: + - gzip + - snappy + - lz4 + - zstd + - uncompressed + - producer + example: gzip + group_initial_rebalance_delay_ms: + description: >- + The amount of time, in milliseconds, the group coordinator will wait + for more consumers to join a new group before performing the first + rebalance. A longer delay means potentially fewer rebalances, but + increases the time until processing begins. The default value for + this is 3 seconds. During development and testing it might be + desirable to set this to 0 in order to not delay test execution + time. + type: integer + example: 3000 + minimum: 0 + maximum: 300000 + group_min_session_timeout_ms: + description: >- + The minimum allowed session timeout for registered consumers. Longer + timeouts give consumers more time to process messages in between + heartbeats at the cost of a longer time to detect failures. + type: integer + example: 6000 + minimum: 0 + maximum: 60000 + group_max_session_timeout_ms: + description: >- + The maximum allowed session timeout for registered consumers. Longer + timeouts give consumers more time to process messages in between + heartbeats at the cost of a longer time to detect failures. + type: integer + example: 1800000 + minimum: 0 + maximum: 1800000 + connections_max_idle_ms: + description: >- + Idle connections timeout: the server socket processor threads close + the connections that idle for longer than this. + type: integer + minimum: 1000 + example: 540000 + maximum: 3600000 + max_incremental_fetch_session_cache_slots: + description: >- + The maximum number of incremental fetch sessions that the broker + will maintain. + type: integer + example: 1000 + minimum: 1000 + maximum: 10000 + message_max_bytes: + description: The maximum size of message that the server can receive. + type: integer + example: 1048588 + minimum: 0 + maximum: 100001200 + offsets_retention_minutes: + description: Log retention window in minutes for offsets topic + type: integer + example: 10080 + minimum: 1 + maximum: 2147483647 + log_cleaner_delete_retention_ms: + description: How long are delete records retained? + type: integer + minimum: 0 + maximum: 315569260000 + example: 86400000 + log_cleaner_min_cleanable_ratio: + description: >- + Controls log compactor frequency. Larger value means more frequent + compactions but also more space wasted for logs. Consider setting + log_cleaner_max_compaction_lag_ms to enforce compactions sooner, + instead of setting a very high value for this option. + type: number + minimum: 0.2 + maximum: 0.9 + example: 0.5 + log_cleaner_max_compaction_lag_ms: + description: >- + The maximum amount of time message will remain uncompacted. Only + applicable for logs that are being compacted + type: integer + minimum: 30000 + maximum: 9223372036854776000 + example: 60000 + log_cleaner_min_compaction_lag_ms: + description: >- + The minimum time a message will remain uncompacted in the log. Only + applicable for logs that are being compacted. + type: integer + minimum: 0 + maximum: 9223372036854776000 + example: 100000 + log_cleanup_policy: + description: The default cleanup policy for segments beyond the retention window + type: string + enum: + - delete + - compact + - compact,delete + example: delete + log_flush_interval_messages: + description: >- + The number of messages accumulated on a log partition before + messages are flushed to disk + type: integer + minimum: 1 + maximum: 9223372036854776000 + example: 9223372036854776000 + log_flush_interval_ms: + description: >- + The maximum time in ms that a message in any topic is kept in memory + before flushed to disk. If not set, the value in + log.flush.scheduler.interval.ms is used + type: integer + minimum: 0 + maximum: 9223372036854776000 + example: 1000000 + log_index_interval_bytes: + description: The interval with which Kafka adds an entry to the offset index + type: integer + minimum: 0 + maximum: 104857600 + example: 4096 + log_index_size_max_bytes: + description: The maximum size in bytes of the offset index + type: integer + minimum: 1048576 + maximum: 104857600 + example: 10485760 + log_message_downconversion_enable: + description: >- + This configuration controls whether down-conversion of message + formats is enabled to satisfy consume requests. + type: boolean + example: true + log_message_timestamp_type: + description: >- + Define whether the timestamp in the message is message create time + or log append time. + type: string + enum: + - CreateTime + - LogAppendTime + example: CreateTime + log_message_timestamp_difference_max_ms: + description: >- + The maximum difference allowed between the timestamp when a broker + receives a message and the timestamp specified in the message + type: integer + minimum: 0 + maximum: 9223372036854776000 + example: 1000000 + log_preallocate: + description: Controls whether to preallocate a file when creating a new segment + type: boolean + example: false + log_retention_bytes: + description: The maximum size of the log before deleting messages + type: integer + minimum: -1 + maximum: 9223372036854776000 + example: 1000000 + log_retention_hours: + description: The number of hours to keep a log file before deleting it + type: integer + minimum: -1 + maximum: 2147483647 + example: 1000000 + log_retention_ms: + description: >- + The number of milliseconds to keep a log file before deleting it (in + milliseconds), If not set, the value in log.retention.minutes is + used. If set to -1, no time limit is applied. + type: integer + minimum: -1 + maximum: 9223372036854776000 + example: 100000000 + log_roll_jitter_ms: + description: >- + The maximum jitter to subtract from logRollTimeMillis (in + milliseconds). If not set, the value in log.roll.jitter.hours is + used + type: integer + minimum: 0 + maximum: 9223372036854776000 + example: 10000000 + log_roll_ms: + description: >- + The maximum time before a new log segment is rolled out (in + milliseconds). + type: integer + minimum: 1 + maximum: 9223372036854776000 + example: 1000000 + log_segment_bytes: + description: The maximum size of a single log file + type: integer + minimum: 10485760 + maximum: 1073741824 + example: 100000000 + log_segment_delete_delay_ms: + description: >- + The amount of time to wait before deleting a file from the + filesystem + type: integer + minimum: 0 + maximum: 3600000 + example: 60000 + auto_create_topics_enable: + description: Enable auto creation of topics + type: boolean + example: true + default: false + min_insync_replicas: + description: >- + When a producer sets acks to 'all' (or '-1'), min_insync_replicas + specifies the minimum number of replicas that must acknowledge a + write for the write to be considered successful. + type: integer + minimum: 1 + maximum: 7 + example: 1 + num_partitions: + description: Number of partitions for autocreated topics + type: integer + minimum: 1 + maximum: 1000 + example: 10 + default_replication_factor: + description: Replication factor for autocreated topics + type: integer + minimum: 1 + maximum: 10 + example: 2 + replica_fetch_max_bytes: + description: >- + The number of bytes of messages to attempt to fetch for each + partition (defaults to 1048576). This is not an absolute maximum, if + the first record batch in the first non-empty partition of the fetch + is larger than this value, the record batch will still be returned + to ensure that progress can be made. + type: integer + minimum: 1048576 + maximum: 104857600 + example: 2097152 + replica_fetch_response_max_bytes: + description: >- + Maximum bytes expected for the entire fetch response (defaults to + 10485760). Records are fetched in batches, and if the first record + batch in the first non-empty partition of the fetch is larger than + this value, the record batch will still be returned to ensure that + progress can be made. As such, this is not an absolute maximum. + type: integer + minimum: 10485760 + maximum: 1048576000 + example: 20971520 + max_connections_per_ip: + description: >- + The maximum number of connections allowed from each ip address + (defaults to 2147483647). + type: integer + minimum: 256 + maximum: 2147483647 + example: 512 + producer_purgatory_purge_interval_requests: + description: >- + The purge interval (in number of requests) of the producer request + purgatory (defaults to 1000). + type: integer + minimum: 10 + maximum: 10000 + example: 100 + socket_request_max_bytes: + description: >- + The maximum number of bytes in a socket request (defaults to + 104857600). + type: integer + minimum: 10485760 + maximum: 209715200 + example: 20971520 + transaction_state_log_segment_bytes: + description: >- + The transaction topic segment bytes should be kept relatively small + in order to facilitate faster log compaction and cache loads + (defaults to 104857600 (100 mebibytes)). + type: integer + minimum: 1048576 + maximum: 2147483647 + example: 104857600 + transaction_remove_expired_transaction_cleanup_interval_ms: + description: >- + The interval at which to remove transactions that have expired due + to transactional.id.expiration.ms passing (defaults to 3600000 (1 + hour)). + type: integer + minimum: 600000 + maximum: 3600000 + example: 3600000 + schema_registry: + description: >- + Enable creation of schema registry for the Kafka cluster. + Schema_registry only works with General Purpose - Dedicated CPU + plans. + type: boolean + example: true + default: false + opensearch_advanced_config: + type: object + properties: + http_max_content_length_bytes: + description: >- + Maximum content length for HTTP requests to the OpenSearch HTTP API, + in bytes. + type: integer + example: 100000000 + minimum: 1 + maximum: 2147483647 + default: 100000000 + http_max_header_size_bytes: + description: Maximum size of allowed headers, in bytes. + type: integer + example: 8192 + minimum: 1024 + maximum: 262144 + default: 8192 + http_max_initial_line_length_bytes: + description: Maximum length of an HTTP URL, in bytes. + type: integer + example: 4096 + minimum: 1024 + maximum: 65536 + default: 4096 + indices_query_bool_max_clause_count: + description: >- + Maximum number of clauses Lucene BooleanQuery can have. Only + increase it if necessary, as it may cause performance issues. + type: integer + example: 1024 + minimum: 64 + maximum: 4096 + default: 1024 + indices_fielddata_cache_size_percentage: + description: >- + Maximum amount of heap memory used for field data cache, expressed + as a percentage. Decreasing the value too much will increase + overhead of loading field data. Increasing the value too much will + decrease amount of heap available for other operations. + type: integer + example: 3 + minimum: 3 + maximum: 100 + indices_memory_index_buffer_size_percentage: + description: >- + Total amount of heap used for indexing buffer before writing + segments to disk, expressed as a percentage. Too low value will slow + down indexing; too high value will increase indexing performance but + causes performance issues for query performance. + type: integer + example: 10 + minimum: 3 + maximum: 40 + default: 10 + indices_memory_min_index_buffer_size_mb: + description: >- + Minimum amount of heap used for indexing buffer before writing + segments to disk, in mb. Works in conjunction with + indices_memory_index_buffer_size_percentage, each being enforced. + type: integer + example: 48 + minimum: 3 + maximum: 2048 + default: 48 + indices_memory_max_index_buffer_size_mb: + description: >- + Maximum amount of heap used for indexing buffer before writing + segments to disk, in mb. Works in conjunction with + indices_memory_index_buffer_size_percentage, each being enforced. + The default is unbounded. + type: integer + example: 48 + minimum: 3 + maximum: 2048 + indices_queries_cache_size_percentage: + description: >- + Maximum amount of heap used for query cache. Too low value will + decrease query performance and increase performance for other + operations; too high value will cause issues with other + functionality. + type: integer + example: 10 + minimum: 3 + maximum: 40 + default: 10 + indices_recovery_max_mb_per_sec: + description: >- + Limits total inbound and outbound recovery traffic for each node, + expressed in mb per second. Applies to both peer recoveries as well + as snapshot recoveries (i.e., restores from a snapshot). + type: integer + example: 40 + minimum: 40 + maximum: 400 + default: 40 + indices_recovery_max_concurrent_file_chunks: + description: Maximum number of file chunks sent in parallel for each recovery. + type: integer + example: 2 + minimum: 2 + maximum: 5 + default: 2 + thread_pool_search_size: + description: >- + Number of workers in the search operation thread pool. Do note this + may have maximum value depending on CPU count - value is + automatically lowered if set to higher than maximum value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_search_throttled_size: + description: >- + Number of workers in the search throttled operation thread pool. + This pool is used for searching frozen indices. Do note this may + have maximum value depending on CPU count - value is automatically + lowered if set to higher than maximum value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_get_size: + description: >- + Number of workers in the get operation thread pool. Do note this + may have maximum value depending on CPU count - value is + automatically lowered if set to higher than maximum value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_analyze_size: + description: >- + Number of workers in the analyze operation thread pool. Do note + this may have maximum value depending on CPU count - value is + automatically lowered if set to higher than maximum value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_write_size: + description: >- + Number of workers in the write operation thread pool. Do note this + may have maximum value depending on CPU count - value is + automatically lowered if set to higher than maximum value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_force_merge_size: + description: >- + Number of workers in the force merge operation thread pool. This + pool is used for forcing a merge between shards of one or more + indices. Do note this may have maximum value depending on CPU count + - value is automatically lowered if set to higher than maximum + value. + type: integer + example: 1 + minimum: 1 + maximum: 128 + thread_pool_search_queue_size: + description: Size of queue for operations in the search thread pool. + type: integer + example: 10 + minimum: 10 + maximum: 2000 + thread_pool_search_throttled_queue_size: + description: Size of queue for operations in the search throttled thread pool. + type: integer + example: 10 + minimum: 10 + maximum: 2000 + thread_pool_get_queue_size: + description: Size of queue for operations in the get thread pool. + type: integer + example: 10 + minimum: 10 + maximum: 2000 + thread_pool_analyze_queue_size: + description: Size of queue for operations in the analyze thread pool. + type: integer + example: 10 + minimum: 10 + maximum: 2000 + thread_pool_write_queue_size: + description: Size of queue for operations in the write thread pool. + type: integer + example: 10 + minimum: 10 + maximum: 2000 + ism_enabled: + description: Specifies whether ISM is enabled or not. + type: boolean + example: true + default: true + ism_history_enabled: + description: >- + Specifies whether audit history is enabled or not. The logs from ISM + are automatically indexed to a logs document. + type: boolean + example: true + default: true + ism_history_max_age_hours: + description: Maximum age before rolling over the audit history index, in hours. + type: integer + example: 24 + minimum: 1 + maximum: 2147483647 + default: 24 + ism_history_max_docs: + description: >- + Maximum number of documents before rolling over the audit history + index. + type: integer + example: 2500000 + minimum: 1 + maximum: 9223372036854776000 + default: 2500000 + ism_history_rollover_check_period_hours: + description: >- + The time between rollover checks for the audit history index, in + hours. + type: integer + example: 8 + minimum: 1 + maximum: 2147483647 + default: 8 + ism_history_rollover_retention_period_days: + description: Length of time long audit history indices are kept, in days. + type: integer + example: 30 + minimum: 1 + maximum: 2147483647 + default: 30 + search_max_buckets: + description: Maximum number of aggregation buckets allowed in a single response. + type: integer + example: 10000 + minimum: 1 + maximum: 1000000 + default: 10000 + action_auto_create_index_enabled: + description: Specifices whether to allow automatic creation of indices. + type: boolean + example: true + default: true + enable_security_audit: + description: Specifies whether to allow security audit logging. + type: boolean + example: false + default: false + action_destructive_requires_name: + description: >- + Specifies whether to require explicit index names when deleting + indices. + type: boolean + example: false + cluster_max_shards_per_node: + description: Maximum number of shards allowed per data node. + type: integer + example: 100 + minimum: 100 + maximum: 10000 + override_main_response_version: + description: >- + Compatibility mode sets OpenSearch to report its version as 7.10 so + clients continue to work. + type: boolean + example: false + default: false + script_max_compilations_rate: + description: >- + Limits the number of inline script compilations within a period of + time. Default is use-context + type: string + example: 75/5m + default: use-context + cluster_routing_allocation_node_concurrent_recoveries: + description: >- + Maximum concurrent incoming/outgoing shard recoveries (normally + replicas) are allowed to happen per node . + type: integer + example: 2 + minimum: 2 + maximum: 16 + default: 2 + reindex_remote_whitelist: + description: >- + Allowlist of remote IP addresses for reindexing. Changing this value + will cause all OpenSearch instances to restart. + type: array + items: + type: string + example: + - 255.255.223.233:9200 + - 222.33.222.222:6300 + plugins_alerting_filter_by_backend_roles_enabled: + description: Enable or disable filtering of alerting by backend roles. + type: boolean + example: false + default: false + knn_memory_circuit_breaker_enabled: + description: Enable or disable KNN memory circuit breaker. + type: boolean + example: true + default: true + knn_memory_circuit_breaker_limit: + description: >- + Maximum amount of memory in percentage that can be used for the KNN + index. Defaults to 50% of the JVM heap size. 0 is used to set it to + null which can be used to invalidate caches. + type: integer + example: 60 + minimum: 0 + maximum: 100 + default: 50 + keep_index_refresh_interval: + description: >- + DigitalOcean automatically resets the `index.refresh_interval` to + the default value (once per second) to ensure that new documents + are quickly available for search queries. If you are setting your + own refresh intervals, you can disable this by setting this field + to true. + example: true + type: boolean + default: false + mongo_advanced_config: + type: object + properties: + default_read_concern: + description: >- + Specifies the default consistency behavior of reads from the + database. Data that is returned from the query with may or may not + have been acknowledged by all nodes in the replicaset depending on + this value. Learn more + [here](https://www.mongodb.com/docs/manual/reference/read-concern/). + type: string + enum: + - local + - available + - majority + default: local + example: local + default_write_concern: + description: >- + Describes the level of acknowledgment requested from MongoDB for + write operations clusters. This field can set to either `majority` + or a number `0...n` which will describe the number of nodes that + must acknowledge the write operation before it is fully accepted. + Setting to `0` will request no acknowledgement of the write + operation. Learn more + [here](https://www.mongodb.com/docs/manual/reference/write-concern/). + type: string + default: majority + example: majority + transaction_lifetime_limit_seconds: + description: >- + Specifies the lifetime of multi-document transactions. Transactions + that exceed this limit are considered expired and will be aborted + by a periodic cleanup process. The cleanup process runs every + `transactionLifetimeLimitSeconds/2 seconds` or at least once every + 60 seconds. *Changing this parameter will lead to a restart of the + MongoDB service.* Learn more + [here](https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.transactionLifetimeLimitSeconds). + type: integer + minimum: 1 + default: 60 + example: 100 + slow_op_threshold_ms: + description: >- + Operations that run for longer than this threshold are considered + slow which are then recorded to the diagnostic logs. Higher log + levels (verbosity) will record all operations regardless of this + threshold on the primary node. *Changing this parameter will lead + to a restart of the MongoDB service.* Learn more + [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-operationProfiling.slowOpThresholdMs). + type: integer + minimum: 0 + default: 100 + example: 200 + verbosity: + description: >- + The log message verbosity level. The verbosity level determines the + amount of Informational and Debug messages MongoDB outputs. 0 + includes informational messages while 1...5 increases the level to + include debug messages. *Changing this parameter will lead to a + restart of the MongoDB service.* Learn more + [here](https://www.mongodb.com/docs/manual/reference/configuration-options/#mongodb-setting-systemLog.verbosity). + type: integer + minimum: 0 + maximum: 5 + default: 0 + example: 3 + database_config: + type: object + properties: + config: + anyOf: + - $ref: '#/components/schemas/mysql_advanced_config' + - $ref: '#/components/schemas/postgres_advanced_config' + - $ref: '#/components/schemas/redis_advanced_config' + - $ref: '#/components/schemas/valkey_advanced_config' + - $ref: '#/components/schemas/mongo_advanced_config' + - $ref: '#/components/schemas/kafka_advanced_config' + - $ref: '#/components/schemas/opensearch_advanced_config' + ca: + type: object + properties: + certificate: + type: string + example: >- + LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVRVENDQXFtZ0F3SUJBZ0lVRUZZWTdBWFZQS0Raam9jb1lpMk00Y0dvcU0wd0RRWUpLb1pJaHZjTkFRRU0KQlFBd09qRTRNRFlHQTFVRUF3d3ZOek0zT1RaaE1XRXRaamhrTUMwME9HSmpMV0V4Wm1NdFpqbGhNVFZsWXprdwpORGhsSUZCeWIycGxZM1FnUTBFd0hoY05NakF3TnpFM01UVTFNREEyV2hjTk16QXdOekUxTVRVMU1EQTJXakE2Ck1UZ3dOZ1lEVlFRRERDODNNemM1Tm1FeFlTMW1PR1F3TFRRNFltTXRZVEZtWXkxbU9XRXhOV1ZqT1RBME9HVWcKVUhKdmFtVmpkQ0JEUVRDQ0FhSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnR1BBRENDQVlvQ2dnR0JBTVdScXhycwpMZnpNdHZyUmxKVEw4MldYMVBLZkhKbitvYjNYcmVBY3FZd1dBUUp2Q3IycmhxSXZieVZzMGlaU0NzOHI4c3RGClljQ0R1bkxJNmUwTy9laERZYTBIT2RrMkFFRzE1ckVOVmNha2NSczcyQWlHVHNrdkNXS2VkUjFTUWswVWt0WCsKQUg4S1ExS3F5bzNtZ2Y2cVV1WUpzc3JNTXFselk3YTN1RVpEb2ZqTjN5Q3MvM21pTVJKcVcyNm1JV0IrUUlEbAo5YzdLRVF5MTZvdCtjeHVnd0lLMm9oZHMzaFY1bjBKMFVBM0I3QWRBdXY5aUl5L3JHaHlTNm5CNTdaWm9JZnAyCnFybXdOY0UrVjlIdXhQSGtRVjFOQjUwOFFudWZ4Z0E5VCtqU2VrdGVUbWFORkxqNjFXL3BtcndrTytOaWFXUTIKaGgzVXBKOEozY1BoNkErbHRnUmpSV2NEb2lsYVNwRVVpU09WemNNYVFvalZKYVJlNk9NbnZYc29NaSs3ZzdneApWcittQ0lUcGcvck9DaXpBWWQ2UFAxLzdYTjk1ZXNmU2tBQnM5c3hJakpjTUFqbDBYTEFzRmtGZVdyeHNIajlVCmJnaDNWYXdtcnpUeXhZT0RQcXV1cS9JcGlwc0RRT3Fpb2ZsUStkWEJJL3NUT0NNbVp6K0pNcG5HYXdJREFRQUIKb3o4d1BUQWRCZ05WSFE0RUZnUVVSekdDRlE3WEtUdHRDN3JzNS8ydFlQcExTZGN3RHdZRFZSMFRCQWd3QmdFQgovd0lCQURBTEJnTlZIUThFQkFNQ0FRWXdEUVlKS29aSWh2Y05BUUVNQlFBRGdnR0JBSWFKQ0dSVVNxUExtcmcvCmk3MW10b0NHUDdzeG1BVXVCek1oOEdrU25uaVdaZnZGMTRwSUtqTlkwbzVkWmpHKzZqK1VjalZtK0RIdGE1RjYKOWJPeEk5S0NFeEI1blBjRXpMWjNZYitNOTcrellxbm9zUm85S21DVFJBb2JrNTZ0WU1FS1h1aVJja2tkMm1yUQo4cGw2N2xxdThjM1V4c0dHZEZVT01wMkk3ZTNpdUdWVm5UR0ZWM3JQZUdaQ0J3WGVyUUQyY0F4UjkzS3BnWVZ2ClhUUzk5dnpSbm1HOHhhUm9EVy9FbEdXZ2xWd0Q5a1JrbXhUUkdoYTdDWVZCcjFQVWY2dVVFVjhmVFIxc1hFZnIKLytMR1JoSVVsSUhWT3l2Yzk3YnZYQURPbWF1MWZDVE5lWGtRdTNyZnZFSlBmaFlLeVIwT0V3eWVvdlhRNzl0LwpTV2ZGTjBreU1Pc1UrNVNIdHJKSEh1eWNWcU0yQlVVK083VjM1UnNwOU9MZGRZMFFVbTZldFpEVEhhSUhYYzRRCnl1Rm1OL1NhSFZtNE0wL3BTVlJQdVd6TmpxMnZyRllvSDRtbGhIZk95TUNJMjc2elE2aWhGNkdDSHlkOUJqajcKUm1UWGEyNHM3NWhmSi9YTDV2bnJSdEtpVHJlVHF6V21EOVhnUmNMQ0gyS1hJaVRtSWc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg== + description: >- + base64 encoding of the certificate used to secure database + connections + readOnly: true + required: + - certificate + online_migration: + type: object + properties: + id: + type: string + description: The ID of the most recent migration. + example: 77b28fc8-19ff-11eb-8c9c-c68e24557488 + status: + type: string + description: The current status of the migration. + enum: + - running + - syncing + - canceled + - error + - done + example: running + created_at: + type: string + description: The time the migration was initiated, in ISO 8601 format. + example: '2020-10-29T15:57:38Z' + source_database: + type: object + required: + - source + properties: + source: + type: object + properties: + host: + type: string + description: >- + The FQDN pointing to the database cluster's current primary + node. + example: backend-do-user-19081923-0.db.ondigitalocean.com + port: + type: integer + description: The port on which the database cluster is listening. + example: 25060 + dbname: + type: string + description: The name of the default database. + example: defaultdb + username: + type: string + description: The default user for the database. + example: doadmin + password: + type: string + description: The randomly generated password for the default user. + example: wv78n3zpz42xezdk + disable_ssl: + type: boolean + description: Enables SSL encryption when connecting to the source database. + example: false + ignore_dbs: + type: array + items: + type: string + example: + - db0 + - db1 + default: [] + description: List of databases that should be ignored during migration. + database_cluster_resize: + type: object + properties: + size: + type: string + example: db-s-4vcpu-8gb + description: >- + A slug identifier representing desired the size of the nodes in the + database cluster. + num_nodes: + type: integer + format: int32 + example: 3 + description: >- + The number of nodes in the database cluster. Valid values are are + 1-3. In addition to the primary node, up to two standby nodes may be + added for highly available configurations. + storage_size_mib: + type: integer + example: 61440 + description: >- + Additional storage added to the cluster, in MiB. If null, no + additional storage is added to the cluster, beyond what is provided + as a base amount from the 'size' and any previously added additional + storage. + required: + - size + - num_nodes + backup: + type: object + properties: + created_at: + type: string + format: date-time + example: '2019-01-31T19:25:22Z' + description: >- + A time value given in ISO8601 combined date and time format at which + the backup was created. + size_gigabytes: + type: number + example: 0.03364864 + description: The size of the database backup in GBs. + incremental: + type: boolean + example: false + description: >- + Indicates if this backup is a full or an incremental one (available + only for MySQL). + required: + - created_at + - size_gigabytes + database_replica_read: + type: object + properties: + id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + A unique ID that can be used to identify and reference a database + replica. + readOnly: true + name: + type: string + example: read-nyc3-01 + description: The name to give the read-only replicating + region: + type: string + example: nyc3 + description: >- + A slug identifier for the region where the read-only replica will be + located. If excluded, the replica will be placed in the same region + as the cluster. + size: + type: string + example: db-s-2vcpu-4gb + description: >- + A slug identifier representing the size of the node for the + read-only replica. The size of the replica must be at least as large + as the node size for the database cluster from which it is + replicating. + status: + type: string + enum: + - creating + - online + - resizing + - migrating + - forking + example: creating + description: A string representing the current status of the database cluster. + readOnly: true + tags: + type: array + items: + type: string + example: + - production + description: >- + A flat array of tag names as strings applied to the read-only + replica.

Requires `tag:read` scope. + created_at: + type: string + format: date-time + example: '2019-01-11T18:37:36Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the database cluster was created. + readOnly: true + private_network_uuid: + type: string + example: 9423cbad-9211-442f-820b-ef6915e99b5f + description: >- + A string specifying the UUID of the VPC to which the read-only + replica will be assigned. If excluded, the replica will be assigned + to your account's default VPC for the region.

Requires + `vpc:read` scope. + connection: + allOf: + - readOnly: true + - $ref: '#/components/schemas/database_connection' + private_connection: + allOf: + - readOnly: true + - $ref: '#/components/schemas/database_connection' + storage_size_mib: + type: integer + example: 61440 + description: >- + Additional storage added to the cluster, in MiB. If null, no + additional storage is added to the cluster, beyond what is provided + as a base amount from the 'size' and any previously added additional + storage. + do_settings: + allOf: + - $ref: '#/components/schemas/do_settings' + - description: >- + DigitalOcean-specific settings for the read-only replica, + including custom service CNAMEs. + required: + - name + database_replica: + type: object + properties: + id: + type: string + format: uuid + example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + description: >- + A unique ID that can be used to identify and reference a database + replica. + readOnly: true + name: + type: string + example: read-nyc3-01 + description: The name to give the read-only replicating + region: + type: string + example: nyc3 + description: >- + A slug identifier for the region where the read-only replica will be + located. If excluded, the replica will be placed in the same region + as the cluster. + size: + type: string + example: db-s-2vcpu-4gb + description: >- + A slug identifier representing the size of the node for the + read-only replica. The size of the replica must be at least as large + as the node size for the database cluster from which it is + replicating. + status: + type: string + enum: + - creating + - online + - resizing + - migrating + - forking + example: creating + description: A string representing the current status of the database cluster. + readOnly: true + tags: + type: array + items: + type: string + example: + - production + description: >- + A flat array of tag names as strings to apply to the read-only + replica after it is created. Tag names can either be existing or new + tags.

Requires `tag:create` scope. + created_at: + type: string + format: date-time + example: '2019-01-11T18:37:36Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the database cluster was created. + readOnly: true + private_network_uuid: + type: string + example: 9423cbad-9211-442f-820b-ef6915e99b5f + description: >- + A string specifying the UUID of the VPC to which the read-only + replica will be assigned. If excluded, the replica will be assigned + to your account's default VPC for the region.

Requires + `vpc:read` scope. + connection: + allOf: + - readOnly: true + - $ref: '#/components/schemas/database_connection' + private_connection: + allOf: + - readOnly: true + - $ref: '#/components/schemas/database_connection' + storage_size_mib: + type: integer + example: 61440 + description: >- + Additional storage added to the cluster, in MiB. If null, no + additional storage is added to the cluster, beyond what is provided + as a base amount from the 'size' and any previously added additional + storage. + do_settings: + allOf: + - $ref: '#/components/schemas/do_settings' + - description: >- + DigitalOcean-specific settings for the read-only replica, + including custom service CNAMEs. + required: + - name + events_logs: + type: object + properties: + id: + type: string + description: ID of the particular event. + example: pe8u2huh + cluster_name: + type: string + description: The name of cluster. + example: sample_cluster + event_type: + type: string + enum: + - cluster_maintenance_perform + - cluster_master_promotion + - cluster_create + - cluster_update + - cluster_delete + - cluster_poweron + - cluster_poweroff + description: Type of the event. + example: cluster_create + create_time: + type: string + description: The time of the generation of a event. + example: '2020-10-29T15:57:38Z' + database: + type: object + properties: + name: + type: string + example: alpha + description: The name of the database. + required: + - name + connection_pool: + type: object + properties: + name: + type: string + description: >- + A unique name for the connection pool. Must be between 3 and 60 + characters. + example: backend-pool + mode: + type: string + description: >- + The PGBouncer transaction mode for the connection pool. The allowed + values are session, transaction, and statement. + example: transaction + size: + type: integer + format: int32 + description: >- + The desired size of the PGBouncer connection pool. The maximum + allowed size is determined by the size of the cluster's primary + node. 25 backend server connections are allowed for every 1GB of + RAM. Three are reserved for maintenance. For example, a primary node + with 1 GB of RAM allows for a maximum of 22 backend server + connections while one with 4 GB would allow for 97. Note that these + are shared across all connection pools in a cluster. + example: 10 + db: + type: string + description: The database for use with the connection pool. + example: defaultdb + user: + type: string + description: >- + The name of the user for use with the connection pool. When + excluded, all sessions connect to the database as the inbound user. + example: doadmin + connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + standby_private_connection: + allOf: + - $ref: '#/components/schemas/database_connection' + - readOnly: true + required: + - name + - mode + - size + - db + connection_pools: + type: object + properties: + pools: + type: array + readOnly: true + description: An array of connection pool objects. + items: + $ref: '#/components/schemas/connection_pool' + connection_pool_update: + type: object + properties: + mode: + type: string + description: >- + The PGBouncer transaction mode for the connection pool. The allowed + values are session, transaction, and statement. + example: transaction + size: + type: integer + format: int32 + description: >- + The desired size of the PGBouncer connection pool. The maximum + allowed size is determined by the size of the cluster's primary + node. 25 backend server connections are allowed for every 1GB of + RAM. Three are reserved for maintenance. For example, a primary node + with 1 GB of RAM allows for a maximum of 22 backend server + connections while one with 4 GB would allow for 97. Note that these + are shared across all connection pools in a cluster. + example: 10 + db: + type: string + description: The database for use with the connection pool. + example: defaultdb + user: + type: string + description: >- + The name of the user for use with the connection pool. When + excluded, all sessions connect to the database as the inbound user. + example: doadmin + required: + - mode + - size + - db + sql_mode: + type: object + properties: + sql_mode: + type: string + example: >- + ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES + description: A string specifying the configured SQL modes for the MySQL cluster. + required: + - sql_mode + version: + type: string + example: '8' + description: >- + A string representing the version of the database engine in use for the + cluster. + version-2: + type: object + properties: + version: + $ref: '#/components/schemas/version' + kafka_topic_base: + type: object + properties: + name: + type: string + description: The name of the Kafka topic. + example: events + replication_factor: + type: integer + example: 2 + description: The number of nodes to replicate data across the cluster. + partition_count: + type: integer + example: 3 + description: >- + The number of partitions available for the topic. On update, this + value can only be increased. + kafka_topic: + type: object + allOf: + - $ref: '#/components/schemas/kafka_topic_base' + - properties: + state: + type: string + enum: + - active + - configuring + - deleting + - unknown + example: active + description: The state of the Kafka topic. + kafka_topic_config: + type: object + properties: + cleanup_policy: + type: string + enum: + - delete + - compact + - compact_delete + example: delete + default: delete + description: >- + The cleanup_policy sets the retention policy to use on log segments. + 'delete' will discard old segments when retention time/size limits + are reached. 'compact' will enable log compaction, resulting in + retention of the latest value for each key. + compression_type: + type: string + enum: + - producer + - gzip + - snappy + - Iz4 + - zstd + - uncompressed + example: producer + default: producer + description: The compression_type specifies the compression type of the topic. + delete_retention_ms: + type: integer + example: 86400000 + default: 86400000 + description: >- + The delete_retention_ms specifies how long (in ms) to retain delete + tombstone markers for topics. + file_delete_delay_ms: + type: integer + example: 60000 + default: 60000 + description: >- + The file_delete_delay_ms specifies the time (in ms) to wait before + deleting a file from the filesystem. + flush_messages: + type: integer + example: 9223372036854776000 + default: 9223372036854776000 + description: >- + The flush_messages specifies the number of messages to accumulate on + a log partition before messages are flushed to disk. + flush_ms: + type: integer + example: 9223372036854776000 + default: 9223372036854776000 + description: >- + The flush_ms specifies the maximum time (in ms) that a message is + kept in memory before being flushed to disk. + index_interval_bytes: + type: integer + example: 4096 + default: 4096 + description: >- + The index_interval_bytes specifies the number of bytes between + entries being added into te offset index. + max_compaction_lag_ms: + type: integer + example: 9223372036854776000 + default: 9223372036854776000 + description: >- + The max_compaction_lag_ms specifies the maximum amount of time (in + ms) that a message will remain uncompacted. This is only applicable + if the logs are have compaction enabled. + max_message_bytes: + type: integer + example: 1048588 + default: 1048588 + description: >- + The max_messages_bytes specifies the largest record batch size (in + bytes) that can be sent to the server. This is calculated after + compression if compression is enabled. + message_down_conversion_enable: + type: boolean + example: true + default: true + description: >- + The message_down_conversion_enable specifies whether down-conversion + of message formats is enabled to satisfy consumer requests. When + 'false', the broker will not perform conversion for consumers + expecting older message formats. The broker will respond with an + `UNSUPPORTED_VERSION` error for consume requests from these older + clients. + message_format_version: + type: string + example: 3.0-IV1 + enum: + - 0.8.0 + - 0.8.1 + - 0.8.2 + - 0.9.0 + - 0.10.0-IV0 + - 0.10.0-IV1 + - 0.10.1-IV0 + - 0.10.1-IV1 + - 0.10.1-IV2 + - 0.10.2-IV0 + - 0.11.0-IV0 + - 0.11.0-IV1 + - 0.11.0-IV2 + - 1.0-IV0 + - 1.1-IV0 + - 2.0-IV0 + - 2.0-IV1 + - 2.1-IV0 + - 2.1-IV1 + - 2.1-IV2 + - 2.2-IV0 + - 2.2-IV1 + - 2.3-IV0 + - 2.3-IV1 + - 2.4-IV0 + - 2.4-IV1 + - 2.5-IV0 + - 2.6-IV0 + - 2.7-IV0 + - 2.7-IV1 + - 2.7-IV2 + - 2.8-IV0 + - 2.8-IV1 + - 3.0-IV0 + - 3.0-IV1 + - 3.1-IV0 + - 3.2-IV0 + - 3.3-IV0 + - 3.3-IV1 + - 3.3-IV2 + - 3.3-IV3 + default: 3.0-IV1 + description: >- + The message_format_version specifies the message format version used + by the broker to append messages to the logs. The value of this + setting is assumed to be 3.0-IV1 if the broker protocol version is + 3.0 or higher. By setting a particular message format version, all + existing messages on disk must be smaller or equal to the specified + version. + message_timestamp_type: + type: string + example: create_time + enum: + - create_time + - log_append_time + default: create_time + description: >- + The message_timestamp_type specifies whether to use the message + create time or log append time as the timestamp on a message. + min_cleanable_dirty_ratio: + type: number + format: float + default: 0.5 + example: 0.5 + minimum: 0 + maximum: 1 + description: >- + The min_cleanable_dirty_ratio specifies the frequency of log + compaction (if enabled) in relation to duplicates present in the + logs. For example, at 0.5, at most 50% of the log could be + duplicates before compaction would begin. + min_compaction_lag_ms: + type: integer + example: 0 + default: 0 + description: >- + The min_compaction_lag_ms specifies the minimum time (in ms) that a + message will remain uncompacted in the log. Only relevant if log + compaction is enabled. + min_insync_replicas: + type: integer + example: 1 + default: 1 + minimum: 1 + description: >- + The min_insync_replicas specifies the number of replicas that must + ACK a write for the write to be considered successful. + preallocate: + type: boolean + example: false + default: false + description: >- + The preallocate specifies whether a file should be preallocated on + disk when creating a new log segment. + retention_bytes: + type: integer + example: 1000000 + default: -1 + description: >- + The retention_bytes specifies the maximum size of the log (in bytes) + before deleting messages. -1 indicates that there is no limit. + retention_ms: + type: integer + example: 604800000 + default: 604800000 + description: >- + The retention_ms specifies the maximum amount of time (in ms) to + keep a message before deleting it. + segment_bytes: + type: integer + example: 209715200 + default: 209715200 + minimum: 14 + description: >- + The segment_bytes specifies the maximum size of a single log file + (in bytes). + segment_jitter_ms: + type: integer + example: 0 + default: 0 + description: >- + The segment_jitter_ms specifies the maximum random jitter subtracted + from the scheduled segment roll time to avoid thundering herds of + segment rolling. + segment_ms: + type: integer + example: 604800000 + default: 604800000 + minimum: 1 + description: >- + The segment_ms specifies the period of time after which the log will + be forced to roll if the segment file isn't full. This ensures that + retention can delete or compact old data. + kafka_topic_create: + type: object + allOf: + - $ref: '#/components/schemas/kafka_topic_base' + - properties: + config: + $ref: '#/components/schemas/kafka_topic_config' + kafka_topic_partition: + type: object + properties: + size: + type: integer + description: Size of the topic partition in bytes. + example: 4096 + id: + type: integer + description: An identifier for the partition. + example: 1 + in_sync_replicas: + type: integer + description: >- + The number of nodes that are in-sync (have the latest data) for the + given partition + example: 3 + earliest_offset: + type: integer + description: The earliest consumer offset amongst consumer groups. + example: 0 + consumer_groups: + type: array + nullable: true + items: + type: object + properties: + group_name: + type: string + description: Name of the consumer group. + example: consumer + offset: + type: integer + description: The current offset of the consumer group. + example: 0 + kafka_topic_verbose: + type: object + properties: + name: + type: string + description: The name of the Kafka topic. + example: events + state: + type: string + enum: + - active + - configuring + - deleting + - unknown + example: active + description: The state of the Kafka topic. + replication_factor: + type: integer + example: 2 + description: The number of nodes to replicate data across the cluster. + partitions: + type: array + items: + $ref: '#/components/schemas/kafka_topic_partition' + config: + $ref: '#/components/schemas/kafka_topic_config' + kafka_topic_update: + type: object + properties: + replication_factor: + type: integer + example: 2 + description: The number of nodes to replicate data across the cluster. + partition_count: + type: integer + example: 3 + description: >- + The number of partitions available for the topic. On update, this + value can only be increased. + config: + $ref: '#/components/schemas/kafka_topic_config' + logsink_base_verbose: + type: object + properties: + sink_id: + type: string + example: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + description: A unique identifier for Logsink + sink_name: + type: string + description: The name of the Logsink + example: prod-logsink + sink_type: + type: string + enum: + - rsyslog + - elasticsearch + - opensearch + example: rsyslog + rsyslog_logsink: + type: object + properties: + server: + type: string + example: 192.168.0.1 + description: DNS name or IPv4 address of the rsyslog server + port: + type: integer + example: 514 + maximum: 65535 + description: The internal port on which the rsyslog server is listening + tls: + type: boolean + example: false + description: >- + Use TLS (as the messages are not filtered and may contain sensitive + information, it is highly recommended to set this to true if the + remote server supports it) + format: + type: string + enum: + - rfc5424 + - rfc3164 + - custom + example: rfc5424 + description: >- + Message format used by the server, this can be either rfc3164 (the + old BSD style message format), `rfc5424` (current syslog message + format) or custom + logline: + type: string + example: <%pri%>%timestamp:::date-rfc3339% %HOSTNAME% %app-name% %msg% + description: > + Conditional (required if `format` == `custom`). + + + Syslog log line template for a custom format, supporting limited + rsyslog style templating (using `%tag%`). Supported tags are: + `HOSTNAME`, `app-name`, `msg`, `msgid`, `pri`, `procid`, + `structured-data`, `timestamp` and `timestamp:::date-rfc3339`. + + + --- + + **Datadog Integration Example for Non-Mongo clusters**: + + ``` + + DD_KEY <%pri%>1 %timestamp:::date-rfc3339% %HOSTNAME%.DB_NAME + %app-name% - - - %msg% + + ``` + + - Replace `DD_KEY` with your actual Datadog API key. + + - Replace `DB_NAME` with the actual name of your database cluster. + + - Configure the Server: + - US Region: Use `intake.logs.datadoghq.com` + - EU Region: Use `tcp-intake.logs.datadoghq.eu` + - Configure the Port: + - US Region: Use port `10516` + - EU Region: Use port `443` + - Enable TLS: + - Ensure the TLS checkbox is enabled. + - Note: This configuration applies to **non-Mongo clusters only**. + For **Mongo clusters**, use the `datadog_logsink` integration + instead. + sd: + type: string + example: TOKEN tag="LiteralValue" + description: content of the structured data block of rfc5424 message + ca: + type: string + example: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n' + description: PEM encoded CA certificate + key: + type: string + example: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n' + description: (PEM format) client key if the server requires client authentication + cert: + type: string + example: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n' + description: (PEM format) client cert to use + required: + - server + - port + - tls + - format + elasticsearch_logsink: + type: object + properties: + url: + type: string + example: https://user:passwd@192.168.0.1:9200 + description: Elasticsearch connection URL + index_prefix: + type: string + example: elastic-logs + description: Elasticsearch index prefix + index_days_max: + type: integer + default: 7 + example: 5 + maximum: 10000 + minimum: 1 + description: Maximum number of days of logs to keep + timeout: + type: number + format: float + example: 10 + default: 10 + minimum: 10 + maximum: 120 + description: Elasticsearch request timeout limit + ca: + type: string + example: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n' + description: PEM encoded CA certificate + required: + - url + - index_prefix + opensearch_logsink: + type: object + properties: + url: + type: string + example: https://user:passwd@192.168.0.1:9200 + description: Opensearch connection URL + index_prefix: + type: string + example: opensearch-logs + description: Opensearch index prefix + index_days_max: + type: integer + default: 7 + example: 5 + maximum: 10000 + minimum: 1 + description: Maximum number of days of logs to keep + timeout: + type: number + format: float + example: 10 + default: 10 + minimum: 10 + maximum: 120 + description: Opensearch request timeout limit + ca: + type: string + example: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n' + description: PEM encoded CA certificate + required: + - url + - index_prefix + datadog_logsink: + type: object + description: > + Configuration for Datadog integration **applicable only to MongoDB + clusters**. + properties: + site: + type: string + example: http-intake.logs.datadoghq.com + description: Datadog connection URL + datadog_api_key: + type: string + example: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + description: Datadog API key + required: + - site + - datadog_api_key + logsink_verbose: + type: object + allOf: + - $ref: '#/components/schemas/logsink_base_verbose' + - properties: + config: + anyOf: + - $ref: '#/components/schemas/rsyslog_logsink' + - $ref: '#/components/schemas/elasticsearch_logsink' + - $ref: '#/components/schemas/opensearch_logsink' + - $ref: '#/components/schemas/datadog_logsink' + example: + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc5424 + logsink_schema: + allOf: + - $ref: '#/components/schemas/logsink_verbose' + required: + - sink_id + - sink_name + - sink_type + - config + logsink_base: + type: object + properties: + sink_name: + type: string + description: The name of the Logsink + example: prod-logsink + sink_type: + type: string + enum: + - rsyslog + - elasticsearch + - opensearch + - datadog + description: > + Type of logsink integration. + + + - Use `datadog` for Datadog integration **only with MongoDB + clusters**. + + - For non-MongoDB clusters, use `rsyslog` for general syslog + forwarding. + + - Other supported types include `elasticsearch` and `opensearch`. + + + More details about the configuration can be found in the `config` + property. + example: rsyslog + logsink_create: + type: object + allOf: + - $ref: '#/components/schemas/logsink_base' + - properties: + config: + anyOf: + - $ref: '#/components/schemas/rsyslog_logsink' + - $ref: '#/components/schemas/elasticsearch_logsink' + - $ref: '#/components/schemas/opensearch_logsink' + - $ref: '#/components/schemas/datadog_logsink' + logsink_update: + type: object + properties: + config: + anyOf: + - $ref: '#/components/schemas/rsyslog_logsink' + - $ref: '#/components/schemas/elasticsearch_logsink' + - $ref: '#/components/schemas/opensearch_logsink' + - $ref: '#/components/schemas/datadog_logsink' + required: + - config + kafka_schema_verbose: + type: object + properties: + schema_id: + type: integer + description: The id for schema. + example: 12345 + subject_name: + type: string + description: The name of the schema subject. + example: customer-schema + schema_type: + type: string + enum: + - AVRO + - JSON + - PROTOBUF + description: The type of the schema. + example: AVRO + schema: + type: string + description: The schema definition in the specified format. + example: |- + { + "type": "record", + "name": "Customer", + "fields": [ + {"name": "id", "type": "int"}, + {"name": "name", "type": "string"} + ] + } + database_kafka_schema_create: + type: object + properties: + subject_name: + type: string + description: The name of the schema subject. + example: customer-schema + schema_type: + type: string + enum: + - AVRO + - JSON + - PROTOBUF + description: The type of the schema. + example: AVRO + schema: + type: string + description: The schema definition in the specified format. + example: |- + { + "type": "record", + "name": "Customer", + "fields": [ + {"name": "id", "type": "int"}, + {"name": "name", "type": "string"} + ] + } + kafka_schema_version_verbose: + type: object + properties: + schema_id: + type: integer + description: The id for schema. + example: 12345 + version: + type: string + description: The version of the schema. + example: '1' + subject_name: + type: string + description: The name of the schema subject. + example: customer-schema + schema_type: + type: string + enum: + - AVRO + - JSON + - PROTOBUF + description: The type of the schema. + example: AVRO + schema: + type: string + description: The schema definition in the specified format. + example: |- + { + "type": "record", + "name": "Customer", + "fields": [ + {"name": "id", "type": "int"}, + {"name": "name", "type": "string"} + ] + } + databases_basic_auth_credentials: + type: object + properties: + basic_auth_username: + type: string + example: username + description: basic authentication username for metrics HTTP endpoint + basic_auth_password: + type: string + example: password + description: basic authentication password for metrics HTTP endpoint + database_metrics_credentials: + type: object + properties: + credentials: + $ref: '#/components/schemas/databases_basic_auth_credentials' + opensearch_index_base: + type: object + properties: + index_name: + type: string + description: The name of the opensearch index. + example: events + number_of_shards: + type: integer + example: 2 + description: The number of shards for the index. + number_of_replicas: + type: integer + example: 3 + description: The number of replicas for the index. + size: + type: integer + example: 208 + description: The size of the index. + created_time: + type: string + format: date-time + example: '2021-01-01T00:00:00Z' + description: The date and time the index was created. + opensearch_index: + type: object + allOf: + - $ref: '#/components/schemas/opensearch_index_base' + - properties: + status: + type: string + enum: + - unknown + - open + - close + - none + example: open + description: The status of the OpenSearch index. + health: + type: string + enum: + - unknown + - green + - yellow + - red + - red* + example: green + description: The health of the OpenSearch index. + accelerator_config_spec: + type: object + required: + - scale + - type + - accelerator_slug + properties: + scale: + type: integer + minimum: 1 + example: 1 + description: Number of accelerator instances. + type: + type: string + example: prefill_decode + description: Accelerator type (e.g. prefill_decode). + accelerator_slug: + type: string + example: gpu-mi300x1-192gb + description: DigitalOcean GPU slug. + status: + type: string + enum: + - new + - provisioning + - active + readOnly: true + example: active + description: Current state of the Accelerator. + model_deployment_spec: + type: object + description: Configuration for a single model deployment. + properties: + model_id: + type: string + example: '' + description: >- + Used to identify an existing deployment when updating; empty means + create new. + model_slug: + type: string + example: mistral/mistral-7b-instruct-v3 + description: Model identifier (e.g. Hugging Face slug). + model_provider: + type: string + enum: + - hugging_face + example: hugging_face + description: Model provider. + workload_config: + type: object + description: Workload-specific configuration (e.g. ISL/OSL in future). + accelerators: + type: array + items: + $ref: '#/components/schemas/accelerator_config_spec' + description: Accelerator configuration for this deployment. + dedicated_inference_spec: + type: object + description: Structured configuration for a Dedicated Inference deployment. + required: + - version + - name + - region + - vpc + - enable_public_endpoint + - model_deployments + properties: + version: + type: integer + example: 1 + description: Spec version. + name: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9_-]+$ + example: new-dedicated-inference + description: Name of the Dedicated Inference. Must be unique within the team. + region: + type: string + enum: + - atl1 + - nyc2 + - tor1 + example: atl1 + description: DigitalOcean region where the Dedicated Inference is hosted. + vpc: + type: object + required: + - uuid + properties: + uuid: + type: string + format: uuid + example: 997615ce-132d-4bae-9270-9ee21b395e5d + description: VPC UUID for the Dedicated Inference. + enable_public_endpoint: + type: boolean + description: Whether to expose a public LLM endpoint. + model_deployments: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/model_deployment_spec' + description: At least one model deployment is required. + pending_deployment_spec: + type: object + description: Pending deployment when status is provisioning or updating. + properties: + id: + type: string + format: uuid + example: 7c6d729d-360d-44db-88e3-58e98281d12e + description: Deployment UUID. + version: + type: integer + example: 1 + description: Spec version. + name: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9_-]+$ + example: new-dedicated-inference + description: Name of the Dedicated Inference. Must be unique within the team. + status: + type: string + enum: + - provisioning + - updating + example: provisioning + vpc: + type: object + required: + - uuid + properties: + uuid: + type: string + format: uuid + example: 997615ce-132d-4bae-9270-9ee21b395e5d + description: VPC UUID for the Dedicated Inference. + enable_public_endpoint: + type: boolean + description: Whether to expose a public LLM endpoint. + model_deployments: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/model_deployment_spec' + description: At least one model deployment is required. + created_at: + type: string + format: date-time + example: '2024-01-09T20:44:32Z' + updated_at: + type: string + format: date-time + example: '2024-01-09T20:44:32Z' + dedicated_inference: + type: object + description: A Dedicated Inference instance. + properties: + id: + type: string + format: uuid + readOnly: true + example: 6b5c619c-359c-44ca-87e2-47e98170c01d + description: Unique ID of the Dedicated Inference. + status: + type: string + enum: + - active + - new + - provisioning + - updating + - deleting + - error + readOnly: true + example: active + description: Current state of the Dedicated Inference. + region: + type: string + readOnly: true + example: atl1 + description: DigitalOcean region where the Dedicated Inference is hosted. + vpc_uuid: + type: string + format: uuid + readOnly: true + example: 997615ce-132d-4bae-9270-9ee21b395e5d + description: VPC UUID of the Dedicated Inference. + spec: + $ref: '#/components/schemas/dedicated_inference_spec' + pending_deployment_spec: + $ref: '#/components/schemas/pending_deployment_spec' + endpoints: + type: object + readOnly: true + properties: + public_endpoint_fqdn: + type: string + format: uri + example: >- + https://b4bfug4jc41kts2ro54if91eo-public-dedicated-inference.do-infra.ai + description: Public FQDN of the Dedicated Inference instance. + private_endpoint_fqdn: + type: string + format: uri + example: >- + https://b4bfug4jc41kts2ro54if91eo-private-dedicated-inference.do-infra.ai + description: Private VPC FQDN of the Dedicated Inference instance. + created_at: + type: string + format: date-time + readOnly: true + example: '2024-01-09T20:44:32Z' + description: When the Dedicated Inference was created. + updated_at: + type: string + format: date-time + readOnly: true + example: '2024-01-09T20:44:32Z' + description: When the Dedicated Inference was last updated. + dedicated_inference_update_request: + type: object + properties: + spec: + $ref: '#/components/schemas/dedicated_inference_spec' + access_tokens: + type: object + description: Provider tokens for model access (e.g. gated Hugging Face models). + properties: + hugging_face_token: + type: string + example: $HF_TOKEN + description: Hugging Face token required for gated models. + additionalProperties: false + dedicated_inference_create_request: + type: object + required: + - spec + properties: + spec: + $ref: '#/components/schemas/dedicated_inference_spec' + access_tokens: + type: object + additionalProperties: + type: string + example: + hugging_face_token: $HF_TOKEN + description: Key-value pairs for provider tokens (e.g. Hugging Face). + dedicated_inference_access_token: + type: object + description: Access token for authenticating to Dedicated Inference endpoints. + properties: + id: + type: string + format: uuid + readOnly: true + example: 01333f14-a903-4b8e-92b3-363a767aa052 + description: Unique ID of the token. + name: + type: string + readOnly: true + example: first-token + description: Name of the token. + value: + type: string + readOnly: true + example: di_xxxxxxxxxxxxxxxxxxxxxxxx + description: Token value; only returned once on create. Store securely. + created_at: + type: string + format: date-time + readOnly: true + example: '2024-01-09T20:44:32Z' + is_managed: + type: boolean + readOnly: true + example: false + description: >- + When true, the token is managed by DigitalOcean (for example, + system-provisioned). When false, the token was created by the user. + dedicated_inference_accelerator: + type: object + description: A Dedicated Inference accelerator (GPU) in use by an instance. + properties: + id: + type: string + format: uuid + readOnly: true + example: 5b5c619c-359c-44ca-87e2-47e98170c02f + description: Unique ID of the accelerator. + name: + type: string + readOnly: true + example: mi300x1-ghfpsf + description: Name of the accelerator. + slug: + type: string + readOnly: true + example: gpu-mi300x1-192gb + description: DigitalOcean GPU slug. + role: + type: string + readOnly: true + example: prefill_decode + description: Role of the accelerator (e.g. prefill_decode). + status: + type: string + readOnly: true + example: active + description: Status of the accelerator. + created_at: + type: string + format: date-time + readOnly: true + example: '2024-01-09T20:44:32Z' + dedicated_inference_token_create_request: + type: object + required: + - name + properties: + name: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9_-]+$ + example: new-inference-token + description: Name for the new token. + dedicated_inference_size: + type: object + properties: + gpu_slug: + type: string + example: gpu-mi300x1-192gb + price_per_hour: + type: string + example: '2' + region: + type: string + example: nyc2 + currency: + type: string + example: USD + dedicated_inference_sizes_response: + type: object + description: Available Dedicated Inference sizes and pricing. + properties: + enabled_regions: + type: array + items: + type: string + example: + - nyc2 + - atl1 + description: Regions where Dedicated Inference is available. + sizes: + type: array + items: + $ref: '#/components/schemas/dedicated_inference_size' + dedicated_inference_gpu_model_config: + type: object + properties: + gpu_slugs: + type: array + items: + type: string + example: + - gpu-mi300x1-192gb + model_slug: + type: string + example: mistral/mistral-7b-instruct-v3 + model_name: + type: string + example: Mistral-7B-Instruct-v0.3 + is_gated_model: + type: boolean + description: Whether the model requires gated access (e.g. Hugging Face token). + dedicated_inference_gpu_model_configs_response: + type: object + description: Supported GPU and model configurations for Dedicated Inference. + properties: + gpu_model_configs: + type: array + items: + $ref: '#/components/schemas/dedicated_inference_gpu_model_config' + domain: + type: object + properties: + name: + type: string + description: >- + The name of the domain itself. This should follow the standard + domain format of domain.TLD. For instance, `example.com` is a valid + domain name. + example: example.com + ip_address: + type: string + writeOnly: true + description: >- + This optional attribute may contain an IP address. When provided, an + A record will be automatically created pointing to the apex domain. + example: 192.0.2.1 + ttl: + type: integer + readOnly: true + nullable: true + description: >- + This value is the time to live for the records on this domain, in + seconds. This defines the time frame that clients can cache queried + information before a refresh should be requested. + example: 1800 + zone_file: + type: string + readOnly: true + nullable: true + description: >- + This attribute contains the complete contents of the zone file for + the selected domain. Individual domain record resources should be + used to get more granular control over records. However, this + attribute can also be used to get information about the SOA record, + which is created automatically and is not accessible as an + individual record resource. + example: > + $ORIGIN example.com. + + $TTL 1800 + + example.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. + 1415982609 10800 3600 604800 1800 + + example.com. 1800 IN NS ns1.digitalocean.com. + + example.com. 1800 IN NS ns2.digitalocean.com. + + example.com. 1800 IN NS ns3.digitalocean.com. + + example.com. 1800 IN A 1.2.3.4 + domain_record: + type: object + required: + - type + properties: + id: + type: integer + description: A unique identifier for each domain record. + example: 28448429 + readOnly: true + type: + type: string + description: 'The type of the DNS record. For example: A, CNAME, TXT, ...' + example: NS + name: + type: string + description: The host name, alias, or service being defined by the record. + example: '@' + data: + type: string + description: >- + Variable data depending on record type. For example, the "data" + value for an A record would be the IPv4 address to which the domain + will be mapped. For a CAA record, it would contain the domain name + of the CA being granted permission to issue certificates. + example: ns1.digitalocean.com + priority: + type: integer + description: The priority for SRV and MX records. + nullable: true + example: null + port: + type: integer + description: The port for SRV records. + nullable: true + example: null + ttl: + type: integer + description: >- + This value is the time to live for the record, in seconds. This + defines the time frame that clients can cache queried information + before a refresh should be requested. + example: 1800 + weight: + type: integer + description: The weight for SRV records. + nullable: true + example: null + flags: + type: integer + description: An unsigned integer between 0-255 used for CAA records. + nullable: true + example: null + tag: + type: string + description: >- + The parameter tag for CAA records. Valid values are "issue", + "issuewild", or "iodef" + nullable: true + example: null + domain_record_a: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + domain_record_aaaa: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + domain_record_caa: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + - flags + - tag + domain_record_cname: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + domain_record_mx: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - data + - priority + domain_record_ns: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + - flags + - tag + domain_record_soa: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - ttl + domain_record_srv: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + - priority + - port + - flags + - tag + domain_record_txt: + allOf: + - $ref: '#/components/schemas/domain_record' + - required: + - type + - name + - data + - flags + - tag + disk_info: + type: object + properties: + type: + type: string + enum: + - local + - scratch + description: >- + The type of disk. All Droplets contain a `local` disk. Additionally, + GPU Droplets can also have a `scratch` disk for non-persistent data. + example: local + size: + type: object + properties: + amount: + type: integer + description: The amount of space allocated to the disk. + example: 25 + unit: + type: string + description: The unit of measure for the disk size. + example: gib + kernel: + type: object + description: > + **Note**: All Droplets created after March 2017 use internal kernels by + default. + + These Droplets will have this attribute set to `null`. + + + The current + [kernel](https://docs.digitalocean.com/products/droplets/how-to/kernel/) + + for Droplets with externally managed kernels. This will initially be set + to + + the kernel of the base image when the Droplet is created. + nullable: true + deprecated: true + properties: + id: + type: integer + example: 7515 + description: A unique number used to identify and reference a specific kernel. + name: + type: string + example: DigitalOcean GrubLoader v0.2 (20160714) + description: >- + The display name of the kernel. This is shown in the web UI and is + generally a descriptive title for the kernel in question. + version: + type: string + example: 2016.07.13-DigitalOcean_loader_Ubuntu + description: >- + A standard kernel version string representing the version, patch, + and release information. + droplet_next_backup_window: + type: object + nullable: true + properties: + start: + type: string + format: date-time + example: '2019-12-04T00:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format + specifying the start of the Droplet's backup window. + end: + type: string + format: date-time + example: '2019-12-04T23:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format + specifying the end of the Droplet's backup window. + image_name: + type: string + description: >- + The display name that has been given to an image. This is what is shown + in the control panel and is generally a descriptive title for the image + in question. + example: Nifty New Snapshot + distribution: + type: string + description: >- + The name of a custom image's distribution. Currently, the valid values + are `Arch Linux`, `CentOS`, `CoreOS`, `Debian`, `Fedora`, `Fedora + Atomic`, `FreeBSD`, `Gentoo`, `openSUSE`, `RancherOS`, `Rocky Linux`, + `Ubuntu`, and `Unknown`. Any other value will be accepted but ignored, + and `Unknown` will be used in its place. + enum: + - Arch Linux + - CentOS + - CoreOS + - Debian + - Fedora + - Fedora Atomic + - FreeBSD + - Gentoo + - openSUSE + - RancherOS + - Rocky Linux + - Ubuntu + - Unknown + example: Ubuntu + region_slug: + type: string + description: >- + The slug identifier for the region where the resource will initially be + available. + enum: + - ams1 + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + - syd1 + example: nyc3 + regions_array: + type: array + items: + $ref: '#/components/schemas/region_slug' + description: >- + This attribute is an array of the regions that the image is available + in. The regions are represented by their identifying slug values. + example: + - nyc1 + - nyc2 + image_description: + type: string + description: An optional free-form text field to describe an image. + example: ' ' + tags_array: + type: array + items: + type: string + nullable: true + description: >- + A flat array of tag names as strings to be applied to the resource. Tag + names may be for either existing or new tags.

Requires + `tag:create` scope. + example: + - base-image + - prod + image: + type: object + properties: + id: + type: integer + description: >- + A unique number that can be used to identify and reference a + specific image. + example: 7555620 + readOnly: true + name: + $ref: '#/components/schemas/image_name' + type: + type: string + description: >- + Describes the kind of image. It may be one of `base`, `snapshot`, + `backup`, `custom`, or `admin`. Respectively, this specifies whether + an image is a DigitalOcean base OS image, user-generated Droplet + snapshot, automatically created Droplet backup, user-provided + virtual machine image, or an image used for DigitalOcean managed + resources (e.g. DOKS worker nodes). + enum: + - base + - snapshot + - backup + - custom + - admin + example: snapshot + distribution: + $ref: '#/components/schemas/distribution' + slug: + type: string + nullable: true + description: >- + A uniquely identifying string that is associated with each of the + DigitalOcean-provided public images. These can be used to reference + a public image as an alternative to the numeric id. + example: nifty1 + public: + type: boolean + description: >- + This is a boolean value that indicates whether the image in question + is public or not. An image that is public is available to all + accounts. A non-public image is only accessible from your account. + example: true + regions: + $ref: '#/components/schemas/regions_array' + created_at: + type: string + format: date-time + description: >- + A time value given in ISO8601 combined date and time format that + represents when the image was created. + example: '2020-05-04T22:23:02Z' + min_disk_size: + type: integer + description: >- + The minimum disk size in GB required for a Droplet to use this + image. + example: 20 + nullable: true + minimum: 0 + size_gigabytes: + type: number + format: float + nullable: true + description: The size of the image in gigabytes. + example: 2.34 + description: + $ref: '#/components/schemas/image_description' + tags: + $ref: '#/components/schemas/tags_array' + status: + type: string + description: >- + A status string indicating the state of a custom image. This may be + `NEW`, + `available`, `pending`, `deleted`, or `retired`. + enum: + - NEW + - available + - pending + - deleted + - retired + example: NEW + error_message: + type: string + description: >- + A string containing information about errors that may occur when + importing + a custom image. + example: ' ' + gpu_info: + type: object + description: >- + An object containing information about the GPU capabilities of Droplets + created with this size. + properties: + count: + type: integer + description: The number of GPUs allocated to the Droplet. + example: 1 + model: + type: string + description: The model of the GPU. + example: nvidia_h100 + vram: + type: object + properties: + amount: + type: integer + description: The amount of VRAM allocated to the GPU. + example: 25 + unit: + type: string + description: The unit of measure for the VRAM. + example: gib + size: + type: object + properties: + slug: + type: string + example: s-1vcpu-1gb + description: A human-readable string that is used to uniquely identify each size. + memory: + type: integer + multipleOf: 8 + minimum: 8 + example: 1024 + description: >- + The amount of RAM allocated to Droplets created of this size. The + value is represented in megabytes. + vcpus: + type: integer + example: 1 + description: The number of CPUs allocated to Droplets of this size. + disk: + type: integer + example: 25 + description: >- + The amount of disk space set aside for Droplets of this size. The + value is represented in gigabytes. + transfer: + type: number + format: float + example: 1 + description: >- + The amount of transfer bandwidth that is available for Droplets + created in this size. This only counts traffic on the public + interface. The value is given in terabytes. + price_monthly: + type: number + format: float + example: 5 + description: >- + This attribute describes the monthly cost of this Droplet size if + the Droplet is kept for an entire month. The value is measured in US + dollars. + price_hourly: + type: number + format: float + example: 0.00743999984115362 + description: >- + This describes the price of the Droplet size as measured hourly. The + value is measured in US dollars. + regions: + type: array + items: + type: string + example: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + description: >- + An array containing the region slugs where this size is available + for Droplet creates. + available: + type: boolean + default: true + example: true + description: >- + This is a boolean value that represents whether new Droplets can be + created with this size. + description: + type: string + example: Basic + description: >- + A string describing the class of Droplets created from this size. + For example: Basic, General Purpose, CPU-Optimized, + Memory-Optimized, or Storage-Optimized. + disk_info: + type: array + description: >- + An array of objects containing information about the disks available + to Droplets created with this size. + items: + $ref: '#/components/schemas/disk_info' + gpu_info: + $ref: '#/components/schemas/gpu_info' + required: + - available + - disk + - memory + - price_hourly + - price_monthly + - regions + - slug + - transfer + - vcpus + - description + network_v4: + type: object + properties: + ip_address: + type: string + format: ipv4 + example: 104.236.32.182 + description: The IP address of the IPv4 network interface. + netmask: + type: string + format: ipv4 + example: 255.255.192.0 + description: The netmask of the IPv4 network interface. + gateway: + type: string + example: 104.236.0.1 + description: > + The gateway of the specified IPv4 network interface. + + + For private interfaces, a gateway is not provided. This is denoted + by + + returning `nil` as its value. + type: + type: string + enum: + - public + - private + example: public + description: The type of the IPv4 network interface. + network_v6: + type: object + properties: + ip_address: + type: string + format: ipv6 + example: 2604:a880:0:1010::18a:a001 + description: The IP address of the IPv6 network interface. + netmask: + type: integer + example: 64 + description: The netmask of the IPv6 network interface. + gateway: + type: string + format: ipv6 + example: 2604:a880:0:1010::1 + description: The gateway of the specified IPv6 network interface. + type: + type: string + enum: + - public + example: public + description: | + The type of the IPv6 network interface. + + **Note**: IPv6 private networking is not currently supported. + droplet: + type: object + properties: + id: + type: integer + example: 3164444 + description: >- + A unique identifier for each Droplet instance. This is automatically + generated upon Droplet creation. + name: + type: string + example: example.com + description: The human-readable name set for the Droplet instance. + memory: + type: integer + multipleOf: 8 + example: 1024 + description: Memory of the Droplet in megabytes. + vcpus: + type: integer + example: 1 + description: The number of virtual CPUs. + disk: + type: integer + example: 25 + description: The size of the Droplet's disk in gigabytes. + disk_info: + type: array + description: >- + An array of objects containing information about the disks available + to the Droplet. + items: + $ref: '#/components/schemas/disk_info' + locked: + type: boolean + example: false + description: >- + A boolean value indicating whether the Droplet has been locked, + preventing actions by users. + status: + type: string + enum: + - new + - active + - 'off' + - archive + example: active + description: >- + A status string indicating the state of the Droplet instance. This + may be "new", "active", "off", or "archive". + kernel: + $ref: '#/components/schemas/kernel' + created_at: + type: string + format: date-time + example: '2020-07-21T18:37:44Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the Droplet was created. + features: + type: array + items: + type: string + example: + - backups + - private_networking + - ipv6 + description: An array of features enabled on this Droplet. + backup_ids: + type: array + items: + type: integer + example: + - 53893572 + description: >- + An array of backup IDs of any backups that have been taken of the + Droplet instance. Droplet backups are enabled at the time of the + instance creation.
Requires `image:read` scope. + next_backup_window: + allOf: + - $ref: '#/components/schemas/droplet_next_backup_window' + - description: >- + The details of the Droplet's backups feature, if backups are + configured for the Droplet. This object contains keys for the + start and end times of the window during which the backup will + start. + snapshot_ids: + type: array + items: + type: integer + example: + - 67512819 + description: >- + An array of snapshot IDs of any snapshots created from the Droplet + instance.
Requires `image:read` scope. + image: + allOf: + - $ref: '#/components/schemas/image' + - description: The Droplet's image.
Requires `image:read` scope. + volume_ids: + type: array + items: + type: string + example: + - 506f78a4-e098-11e5-ad9f-000f53306ae1 + description: >- + A flat array including the unique identifier for each Block Storage + volume attached to the Droplet.
Requires `block_storage:read` + scope. + size: + $ref: '#/components/schemas/size' + size_slug: + type: string + example: s-1vcpu-1gb + description: The unique slug identifier for the size of this Droplet. + networks: + type: object + description: >- + The details of the network that are configured for the Droplet + instance. This is an object that contains keys for IPv4 and IPv6. + The value of each of these is an array that contains objects + describing an individual IP resource allocated to the Droplet. + These will define attributes like the IP address, netmask, and + gateway of the specific network depending on the type of network it + is. + properties: + v4: + type: array + items: + $ref: '#/components/schemas/network_v4' + v6: + type: array + items: + $ref: '#/components/schemas/network_v6' + region: + $ref: '#/components/schemas/region' + tags: + type: array + items: + type: string + example: + - web + - env:prod + description: >- + An array of Tags the Droplet has been tagged with.
Requires + `tag:read` scope. + vpc_uuid: + type: string + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: >- + A string specifying the UUID of the VPC to which the Droplet is + assigned.
Requires `vpc:read` scope. + gpu_info: + $ref: '#/components/schemas/gpu_info' + required: + - id + - name + - memory + - vcpus + - disk + - locked + - status + - created_at + - features + - backup_ids + - next_backup_window + - snapshot_ids + - image + - volume_ids + - size + - size_slug + - networks + - region + - tags + droplet_backup_policy: + type: object + properties: + plan: + type: string + enum: + - daily + - weekly + example: daily + description: >- + The backup plan used for the Droplet. The plan can be either `daily` + or `weekly`. + weekday: + type: string + enum: + - SUN + - MON + - TUE + - WED + - THU + - FRI + - SAT + example: SUN + description: The day of the week on which the backup will occur. + hour: + type: integer + enum: + - 0 + - 4 + - 8 + - 12 + - 16 + - 20 + example: 0 + description: The hour of the day that the backup window will start. + window_length_hours: + type: integer + readOnly: true + example: 4 + description: The length of the backup window starting from `hour`. + retention_period_days: + type: integer + readOnly: true + example: 7 + description: The number of days the backup will be retained. + droplet_create: + type: object + properties: + region: + type: string + example: nyc3 + description: >- + The slug identifier for the region that you wish to deploy the + Droplet in. If the specific datacenter is not not important, a slug + prefix (e.g. `nyc`) can be used to deploy the Droplet in any of the + that region's locations (`nyc1`, `nyc2`, or `nyc3`). If the region + is omitted from the create request completely, the Droplet may + deploy in any region. + size: + type: string + example: s-1vcpu-1gb + description: >- + The slug identifier for the size that you wish to select for this + Droplet. + image: + oneOf: + - type: string + - type: integer + example: ubuntu-20-04-x64 + description: >- + The image ID of a public or private image or the slug identifier for + a public image. This image will be the base image for your + Droplet.
Requires `image:read` scope. + ssh_keys: + type: array + items: + anyOf: + - type: string + - type: integer + example: + - 289794 + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + default: [] + description: >- + An array containing the IDs or fingerprints of the SSH keys that you + wish to embed in the Droplet's root account upon creation. You must + add the keys to your team before they can be embedded on a + Droplet.
Requires `ssh_key:read` scope. + backups: + type: boolean + example: true + default: false + description: >- + A boolean indicating whether automated backups should be enabled for + the Droplet. + backup_policy: + allOf: + - $ref: '#/components/schemas/droplet_backup_policy' + - description: >- + An object specifying the backup policy for the Droplet. If + omitted and `backups` is `true`, the backup plan will default to + daily. + ipv6: + type: boolean + example: true + default: false + description: A boolean indicating whether to enable IPv6 on the Droplet. + monitoring: + type: boolean + example: true + default: false + description: >- + A boolean indicating whether to install the DigitalOcean agent for + monitoring. + tags: + type: array + items: + type: string + nullable: true + example: + - env:prod + - web + default: [] + description: >- + A flat array of tag names as strings to apply to the Droplet after + it is created. Tag names can either be existing or new + tags.
Requires `tag:create` scope. + user_data: + type: string + example: | + #cloud-config + runcmd: + - touch /test.txt + description: >- + A string containing 'user data' which may be used to configure the + Droplet on first boot, often a 'cloud-config' file or Bash script. + It must be plain text and may not exceed 64 KiB in size. + private_networking: + type: boolean + example: true + default: false + deprecated: true + description: >- + This parameter has been deprecated. Use `vpc_uuid` instead to + specify a VPC network for the Droplet. If no `vpc_uuid` is provided, + the Droplet will be placed in your account's default VPC for the + region. + volumes: + type: array + items: + type: string + example: + - 12e97116-7280-11ed-b3d0-0a58ac146812 + default: [] + description: >- + An array of IDs for block storage volumes that will be attached to + the Droplet once created. The volumes must not already be attached + to an existing Droplet.
Requires `block_storage:read` scpoe. + vpc_uuid: + type: string + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: >- + A string specifying the UUID of the VPC to which the Droplet will be + assigned. If excluded, the Droplet will be assigned to your + account's default VPC for the region.
Requires `vpc:read` scope. + with_droplet_agent: + type: boolean + example: true + description: >- + A boolean indicating whether to install the DigitalOcean agent used + for providing access to the Droplet web console in the control + panel. By default, the agent is installed on new Droplets but + installation errors (i.e. OS not supported) are ignored. To prevent + it from being installed, set to `false`. To make installation errors + fatal, explicitly set it to `true`. + public_networking: + type: boolean + example: true + default: true + description: >- + An optional boolean indicating whether this Droplet should be + created with public networking or not. By default, all Droplets are + created with public networking available. If explicitly set to + `false`, only private networking will be enabled, and public + networking will be disabled; currently this means that it will not + have any public static or Reserved IPv4 or IPv6 address, nor can one + be assigned later. If explicitly set to `false`, `ipv6` must also be + `false`. + required: + - size + - image + droplet_single_create: + title: Single Droplet Request + allOf: + - type: object + properties: + name: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9]?[a-z0-9A-Z.\-]*[a-z0-9A-Z]$ + example: example.com + description: >- + The human-readable string you wish to use when displaying the + Droplet name. The name, if set to a domain name managed in the + DigitalOcean DNS management system, will configure a PTR record + for the Droplet. The name set during creation will also + determine the hostname for the Droplet in its internal + configuration. + required: + - name + - $ref: '#/components/schemas/droplet_create' + droplet_multi_create: + title: Multiple Droplet Request + allOf: + - type: object + properties: + names: + type: array + items: + type: string + maxLength: 255 + pattern: ^[a-zA-Z0-9]?[a-z0-9A-Z.\-]*[a-z0-9A-Z]$ + example: + - sub-01.example.com + - sub-02.example.com + description: >- + An array of human human-readable strings you wish to use when + displaying the Droplet name. Each name, if set to a domain name + managed in the DigitalOcean DNS management system, will + configure a PTR record for the Droplet. Each name set during + creation will also determine the hostname for the Droplet in its + internal configuration. + required: + - names + - $ref: '#/components/schemas/droplet_create' + action_link: + type: object + description: >- + The linked actions can be used to check the status of a Droplet's create + event. + properties: + id: + type: integer + example: 7515 + description: >- + A unique numeric ID that can be used to identify and reference an + action. + rel: + type: string + example: create + description: A string specifying the type of the related action. + href: + type: string + format: uri + example: https://api.digitalocean.com/v2/actions/7515 + description: A URL that can be used to access the action. + snapshots_base: + type: object + properties: + name: + type: string + example: web-01-1595954862243 + description: A human-readable name for the snapshot. + created_at: + type: string + format: date-time + example: '2020-07-28T16:47:44Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the snapshot was created. + regions: + type: array + items: + type: string + example: + - nyc3 + - sfo3 + description: >- + An array of the regions that the snapshot is available in. The + regions are represented by their identifying slug values. + min_disk_size: + type: integer + example: 25 + description: >- + The minimum size in GB required for a volume or Droplet to use this + snapshot. + size_gigabytes: + type: number + format: float + example: 2.34 + description: The billable size of the snapshot in gigabytes. + required: + - name + - created_at + - regions + - min_disk_size + - size_gigabytes + droplet_snapshot: + allOf: + - type: object + properties: + id: + type: integer + example: 6372321 + description: The unique identifier for the snapshot or backup. + required: + - id + - $ref: '#/components/schemas/snapshots_base' + - type: object + properties: + type: + type: string + enum: + - snapshot + - backup + example: snapshot + description: >- + Describes the kind of image. It may be one of `snapshot` or + `backup`. This specifies whether an image is a user-generated + Droplet snapshot or automatically created Droplet backup. + required: + - type + droplet_backup_policy_record: + type: object + properties: + droplet_id: + type: integer + example: 7101383 + description: The unique identifier for the Droplet. + backup_enabled: + type: boolean + example: true + description: >- + A boolean value indicating whether backups are enabled for the + Droplet. + backup_policy: + allOf: + - $ref: '#/components/schemas/droplet_backup_policy' + - description: An object specifying the backup policy for the Droplet. + next_backup_window: + allOf: + - $ref: '#/components/schemas/droplet_next_backup_window' + - description: >- + An object containing keys with the start and end times of the + window during which the backup will occur. + supported_droplet_backup_policy: + type: object + properties: + name: + type: string + example: daily + description: The name of the Droplet backup plan. + possible_window_starts: + type: array + items: + type: integer + description: > + An array of integers representing the hours of the day that a backup + can + + start. + example: + - 0 + - 4 + - 8 + - 12 + - 16 + - 20 + window_length_hours: + type: integer + example: 4 + description: The number of hours that a backup window is open. + retention_period_days: + type: integer + example: 7 + description: The number of days that a backup will be kept. + possible_days: + type: array + items: + type: string + example: + - SUN + - MON + - TUE + - WED + - THU + - FRI + - SAT + description: The day of the week the backup will occur. + droplet_action: + required: + - type + type: object + description: Specifies the action that will be taken on the Droplet. + properties: + type: + type: string + enum: + - enable_backups + - disable_backups + - reboot + - power_cycle + - shutdown + - power_off + - power_on + - restore + - password_reset + - resize + - rebuild + - rename + - change_kernel + - enable_ipv6 + - snapshot + example: reboot + description: The type of action to initiate for the Droplet. + droplet_action_enable_backups: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + backup_policy: + allOf: + - $ref: '#/components/schemas/droplet_backup_policy' + - description: >- + An object specifying the backup policy for the Droplet. If + omitted, the backup plan will default to daily. + example: + type: enable_backups + backup_policy: + plan: daily + hour: 20 + droplet_action_change_backup_policy: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + backup_policy: + allOf: + - $ref: '#/components/schemas/droplet_backup_policy' + - description: An object specifying the backup policy for the Droplet. + required: + - backup_policy + example: + type: enable_backups + backup_policy: + plan: weekly + day: SUN + hour: 20 + droplet_action_restore: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + image: + type: integer + example: 12389723 + description: >- + The ID of a backup of the current Droplet instance to restore + from. + droplet_action_resize: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + disk: + type: boolean + example: true + description: >- + When `true`, the Droplet's disk will be resized in addition to + its RAM and CPU. This is a permanent change and cannot be + reversed as a Droplet's disk size cannot be decreased. + size: + type: string + example: s-2vcpu-2gb + description: >- + The slug identifier for the size to which you wish to resize the + Droplet. + droplet_action_rebuild: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + image: + oneOf: + - type: string + - type: integer + example: ubuntu-20-04-x64 + description: >- + The image ID of a public or private image or the slug identifier + for a public image. The Droplet will be rebuilt using this image + as its base. + droplet_action_rename: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + name: + type: string + example: nifty-new-name + description: The new name for the Droplet. + droplet_action_change_kernel: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + kernel: + type: integer + example: 12389723 + description: >- + A unique number used to identify and reference a specific + kernel. + droplet_action_snapshot: + allOf: + - $ref: '#/components/schemas/droplet_action' + - type: object + properties: + name: + type: string + example: Nifty New Snapshot + description: The name to give the new snapshot of the Droplet. + existing_tags_array: + type: array + items: + type: string + nullable: true + description: >- + A flat array of tag names as strings to be applied to the resource. Tag + names must exist in order to be referenced in a request. +

Requires `tag:create` and `tag:read` scopes. + example: + - base-image + - prod + firewall_rule_base: + type: object + properties: + protocol: + type: string + enum: + - tcp + - udp + - icmp + description: >- + The type of traffic to be allowed. This may be one of `tcp`, `udp`, + or `icmp`. + example: tcp + ports: + type: string + description: >- + The ports on which traffic will be allowed specified as a string + containing a single port, a range (e.g. "8000-9000"), or "0" when + all ports are open for a protocol. For ICMP rules this parameter + will always return "0". + example: '8000' + required: + - protocol + - ports + firewall_rule_target: + type: object + properties: + addresses: + type: array + items: + type: string + description: >- + An array of strings containing the IPv4 addresses, IPv6 addresses, + IPv4 CIDRs, and/or IPv6 CIDRs to which the firewall will allow + traffic. + example: + - 1.2.3.4 + - 18.0.0.0/8 + droplet_ids: + type: array + items: + type: integer + description: >- + An array containing the IDs of the Droplets to which the firewall + will allow traffic. + example: + - 8043964 + load_balancer_uids: + type: array + items: + type: string + description: >- + An array containing the IDs of the load balancers to which the + firewall will allow traffic. + example: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + kubernetes_ids: + type: array + items: + type: string + description: >- + An array containing the IDs of the Kubernetes clusters to which the + firewall will allow traffic. + example: + - 41b74c5d-9bd0-5555-5555-a57c495b81a3 + tags: + allOf: + - $ref: '#/components/schemas/existing_tags_array' + - description: >- + An array containing the names of Tags corresponding to groups of + Droplets to which the firewall will allow traffic. + example: + - frontend + firewall_rules: + type: object + properties: + inbound_rules: + nullable: true + type: array + items: + allOf: + - $ref: '#/components/schemas/firewall_rule_base' + - properties: + sources: + allOf: + - $ref: '#/components/schemas/firewall_rule_target' + - description: >- + An object specifying locations from which inbound + traffic will be accepted. + required: + - sources + outbound_rules: + nullable: true + type: array + items: + allOf: + - $ref: '#/components/schemas/firewall_rule_base' + - properties: + destinations: + allOf: + - $ref: '#/components/schemas/firewall_rule_target' + - description: >- + An object specifying locations to which outbound + traffic that will be allowed. + required: + - destinations + firewall: + type: object + allOf: + - properties: + id: + type: string + description: >- + A unique ID that can be used to identify and reference a + firewall. + readOnly: true + example: bb4b2611-3d72-467b-8602-280330ecd65c + status: + type: string + description: >- + A status string indicating the current state of the firewall. + This can be "waiting", "succeeded", or "failed". + enum: + - waiting + - succeeded + - failed + readOnly: true + example: waiting + created_at: + type: string + format: date-time + description: >- + A time value given in ISO8601 combined date and time format that + represents when the firewall was created. + readOnly: true + example: '2020-05-23T21:24:00Z' + pending_changes: + type: array + description: >- + An array of objects each containing the fields "droplet_id", + "removing", and "status". It is provided to detail exactly which + Droplets are having their security policies updated. When empty, + all changes have been successfully applied. + items: + type: object + properties: + droplet_id: + type: integer + example: 8043964 + removing: + type: boolean + example: false + status: + type: string + example: waiting + readOnly: true + example: + - droplet_id: 8043964 + removing: false + status: waiting + name: + type: string + description: >- + A human-readable name for a firewall. The name must begin with + an alphanumeric character. Subsequent characters must either be + alphanumeric characters, a period (.), or a dash (-). + pattern: ^[a-zA-Z0-9][a-zA-Z0-9\.-]+$ + example: firewall + droplet_ids: + type: array + description: >- + An array containing the IDs of the Droplets assigned to the + firewall.

Requires `droplet:read` scope. + nullable: true + items: + type: integer + example: + - 8043964 + tags: + allOf: + - $ref: '#/components/schemas/existing_tags_array' + - description: >- + An array containing the names of the Tags assigned to the + firewall.

Requires `tag:read` scope. + example: gateway + - $ref: '#/components/schemas/firewall_rules' + associated_resource: + type: object + description: >- + An objects containing information about a resource associated with a + Droplet. + properties: + id: + type: string + example: '61486916' + description: The unique identifier for the resource associated with the Droplet. + name: + type: string + example: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 + description: The name of the resource associated with the Droplet. + cost: + type: string + example: '0.05' + description: >- + The cost of the resource in USD per month if the resource is + retained after the Droplet is destroyed. + selective_destroy_associated_resource: + type: object + description: >- + An object containing information about a resource to be scheduled for + deletion. + properties: + floating_ips: + type: array + deprecated: true + description: >- + An array of unique identifiers for the floating IPs to be scheduled + for deletion. + items: + type: string + example: + - '6186916' + reserved_ips: + type: array + description: >- + An array of unique identifiers for the reserved IPs to be scheduled + for deletion. + items: + type: string + example: + - '6186916' + snapshots: + type: array + description: >- + An array of unique identifiers for the snapshots to be scheduled for + deletion. + items: + type: string + example: + - '61486916' + volumes: + type: array + description: >- + An array of unique identifiers for the volumes to be scheduled for + deletion. + items: + type: string + example: + - ba49449a-7435-11ea-b89e-0a58ac14480f + volume_snapshots: + type: array + description: >- + An array of unique identifiers for the volume snapshots to be + scheduled for deletion. + items: + type: string + example: + - edb0478d-7436-11ea-86e6-0a58ac144b91 + destroyed_associated_resource: + type: object + description: >- + An object containing information about a resource scheduled for + deletion. + properties: + id: + type: string + example: '61486916' + description: The unique identifier for the resource scheduled for deletion. + name: + type: string + example: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 + description: The name of the resource scheduled for deletion. + destroyed_at: + type: string + format: date-time + example: '2020-04-01T18:11:49Z' + description: >- + A time value given in ISO8601 combined date and time format + indicating when the resource was destroyed if the request was + successful. + error_message: + type: string + example: ' ' + description: >- + A string indicating that the resource was not successfully destroyed + and providing additional information. + associated_resource_status: + type: object + description: >- + An objects containing information about a resources scheduled for + deletion. + properties: + droplet: + $ref: '#/components/schemas/destroyed_associated_resource' + resources: + type: object + description: >- + An object containing additional information about resource related + to a Droplet requested to be destroyed. + properties: + reserved_ips: + type: array + items: + $ref: '#/components/schemas/destroyed_associated_resource' + floating_ips: + type: array + items: + $ref: '#/components/schemas/destroyed_associated_resource' + snapshots: + type: array + items: + $ref: '#/components/schemas/destroyed_associated_resource' + volumes: + type: array + items: + $ref: '#/components/schemas/destroyed_associated_resource' + volume_snapshots: + type: array + items: + $ref: '#/components/schemas/destroyed_associated_resource' + completed_at: + type: string + format: date-time + example: '2020-04-01T18:11:49Z' + description: >- + A time value given in ISO8601 combined date and time format + indicating when the requested action was completed. + failures: + type: integer + example: 0 + description: >- + A count of the associated resources that failed to be destroyed, if + any. + autoscale_pool_static_config: + type: object + properties: + target_number_instances: + title: static config + type: integer + example: 3 + description: Fixed number of instances in an autoscale pool. + minimum: 1 + maximum: 1000 + required: + - target_number_instances + autoscale_pool_dynamic_config: + type: object + properties: + min_instances: + type: integer + example: 5 + description: The minimum number of Droplets in an autoscale pool. + minimum: 1 + maximum: 500 + max_instances: + type: integer + example: 10 + description: The maximum number of Droplets in an autoscale pool. + minimum: 1 + maximum: 1000 + target_cpu_utilization: + type: number + format: float + example: 0.6 + description: Target CPU utilization as a decimal. + minimum: 0.05 + maximum: 1 + target_memory_utilization: + type: number + format: float + example: 0.6 + description: Target memory utilization as a decimal. + minimum: 0.05 + maximum: 1 + cooldown_minutes: + type: integer + example: 5 + description: >- + The number of minutes to wait between scaling events in an autoscale + pool. Defaults to 10 minutes. + minimum: 5 + maximum: 20 + required: + - min_instances + - max_instances + autoscale_pool_droplet_template: + type: object + properties: + name: + type: string + example: my-droplet-name + description: The name(s) to be applied to all Droplets in the autoscale pool. + region: + type: string + example: tor1 + enum: + - nyc1 + - nyc2 + - nyc3 + - ams2 + - ams3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - lon1 + - fra1 + - tor1 + - blr1 + - syd1 + description: The datacenter in which all of the Droplets will be created. + size: + type: string + example: c-2 + description: The Droplet size to be used for all Droplets in the autoscale pool. + image: + type: string + example: ubuntu-20-04-x64 + description: >- + The Droplet image to be used for all Droplets in the autoscale pool. + You may specify the slug or the image ID. + ssh_keys: + type: array + items: + type: string + example: + - 88:66:90:d2:68:d5:b5:85:e3:26:26:11:31:57:e6:f8 + description: > + The SSH keys to be installed on the Droplets in the autoscale pool. + You can either specify the key ID or the fingerprint. + + Requires `ssh_key:read` scope. + tags: + type: array + items: + type: string + example: + - my-tag + description: | + The tags to apply to each of the Droplets in the autoscale pool. + Requires `tag:read` scope. + vpc_uuid: + type: string + description: > + The VPC where the Droplets in the autoscale pool will be created. + The VPC must be in the region where you want to create the Droplets. + + Requires `vpc:read` scope. + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + with_droplet_agent: + type: boolean + description: >- + Installs the Droplet agent. This must be set to true to monitor + Droplets for resource utilization scaling. + example: true + project_id: + type: string + description: | + The project that the Droplets in the autoscale pool will belong to. + Requires `project:read` scope. + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + ipv6: + type: boolean + description: >- + Assigns a unique IPv6 address to each of the Droplets in the + autoscale pool. + example: true + user_data: + type: string + example: | + #cloud-config + runcmd: + - touch /test.txt + description: >- + A string containing user data that cloud-init consumes to configure + a Droplet on first boot. User data is often a cloud-config file or + Bash script. It must be plain text and may not exceed 64 KiB in + size. + public_networking: + type: boolean + example: true + default: true + description: >- + An optional boolean indicating whether the Droplets should be + created with public networking or not. By default, all Droplets are + created with public networking available. If explicitly set to + `false`, only private networking will be enabled, and public + networking will be disabled; currently this means that it will not + have any public static or Reserved IPv4 or IPv6 address, nor can one + be assigned later. If explicitly set to `false`, `ipv6` must also be + `false`. + required: + - region + - image + - size + - ssh_keys + current_utilization: + type: object + properties: + memory: + type: number + format: float + example: 0.3588531587713522 + description: The average memory utilization of the autoscale pool. + minimum: 0 + maximum: 1 + cpu: + type: number + format: float + example: 0.0007338008770232183 + description: The average CPU utilization of the autoscale pool. + minimum: 0 + maximum: 1 + autoscale_pool: + type: object + properties: + id: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + description: >- + A unique identifier for each autoscale pool instance. This is + automatically generated upon autoscale pool creation. + name: + type: string + example: my-autoscale-pool + description: The human-readable name set for the autoscale pool. + config: + oneOf: + - $ref: '#/components/schemas/autoscale_pool_static_config' + - $ref: '#/components/schemas/autoscale_pool_dynamic_config' + type: object + description: >- + The scaling configuration for an autoscale pool, which is how the + pool scales up and down (either by resource utilization or static + configuration). + droplet_template: + $ref: '#/components/schemas/autoscale_pool_droplet_template' + current_utilization: + $ref: '#/components/schemas/current_utilization' + created_at: + format: date-time + title: The creation time of the autoscale pool + type: string + example: '2020-07-28T18:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the autoscale pool was created. + updated_at: + format: date-time + title: When the autoscale pool was last updated + type: string + example: '2020-07-28T18:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the autoscale pool was last updated. + status: + type: string + enum: + - active + - deleting + - error + description: The current status of the autoscale pool. + example: active + active_resources_count: + type: integer + example: 1 + description: The number of active Droplets in the autoscale pool. + required: + - id + - name + - config + - droplet_template + - created_at + - updated_at + - status + - active_resources_count + autoscale_pool_create: + type: object + properties: + name: + example: my-autoscale-pool + type: string + description: >- + The human-readable name of the autoscale pool. This field cannot be + updated + config: + oneOf: + - $ref: '#/components/schemas/autoscale_pool_static_config' + - $ref: '#/components/schemas/autoscale_pool_dynamic_config' + type: object + description: >- + The scaling configuration for an autoscale pool, which is how the + pool scales up and down (either by resource utilization or static + configuration). + droplet_template: + $ref: '#/components/schemas/autoscale_pool_droplet_template' + required: + - name + - config + - droplet_template + member_current_utilization: + type: object + properties: + memory: + type: number + format: float + example: 0.3588531587713522 + description: The memory utilization average of the individual Droplet. + cpu: + type: number + format: float + example: 0.0007338008770232183 + description: The CPU utilization average of the individual Droplet. + member: + type: object + properties: + droplet_id: + type: integer + example: 459903570 + description: The unique identifier of the Droplet. + created_at: + format: date-time + description: >- + The creation time of the Droplet in ISO8601 combined date and time + format. + type: string + example: '2020-07-28T18:00:00Z' + updated_at: + format: date-time + description: >- + The last updated time of the Droplet in ISO8601 combined date and + time format. + type: string + example: '2020-07-28T18:00:00Z' + health_status: + type: string + example: active + description: The health status of the Droplet. + status: + type: string + enum: + - provisioning + - active + - deleting + - 'off' + description: The power status of the Droplet. + example: active + current_utilization: + $ref: '#/components/schemas/member_current_utilization' + required: + - droplet_id + - created_at + - updated_at + - health_status + - status + - current_utilization + history: + type: object + properties: + history_event_id: + type: string + example: 01936530-4471-7b86-9634-32d8fcfecbc6 + description: The unique identifier of the history event. + current_instance_count: + type: integer + example: 2 + description: The current number of Droplets in the autoscale pool. + desired_instance_count: + type: integer + example: 2 + description: >- + The target number of Droplets for the autoscale pool after the + scaling event. + reason: + type: string + enum: + - CONFIGURATION_CHANGE + - SCALE_UP + - SCALE_DOWN + description: The reason for the scaling event. + example: CONFIGURATION_CHANGE + status: + type: string + enum: + - in_progress + - success + - error + description: The status of the scaling event. + example: success + created_at: + format: date-time + description: >- + The creation time of the history event in ISO8601 combined date and + time format. + type: string + example: '2020-07-28T18:00:00Z' + updated_at: + format: date-time + description: >- + The last updated time of the history event in ISO8601 combined date + and time format. + type: string + example: '2020-07-28T18:00:00Z' + required: + - history_event_id + - current_instance_count + - desired_instance_count + - reason + - status + - created_at + - updated_at + floating_ip: + type: object + properties: + ip: + type: string + format: ipv4 + example: 45.55.96.47 + description: >- + The public IP address of the floating IP. It also serves as its + identifier. + region: + allOf: + - $ref: '#/components/schemas/region' + - type: object + description: >- + The region that the floating IP is reserved to. When you query a + floating IP, the entire region object will be returned. + droplet: + description: >- + The Droplet that the floating IP has been assigned to. When you + query a floating IP, if it is assigned to a Droplet, the entire + Droplet object will be returned. If it is not assigned, the value + will be null.

Requires `droplet:read` scope. + anyOf: + - title: 'null' + type: object + nullable: true + description: >- + If the floating IP is not assigned to a Droplet, the value will + be null. + - $ref: '#/components/schemas/droplet' + example: null + locked: + type: boolean + example: true + description: >- + A boolean value indicating whether or not the floating IP has + pending actions preventing new ones from being submitted. + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the reserved IP currently + belongs.

Requires `project:read` scope. + floating_ip_create: + oneOf: + - title: Assign to Droplet + type: object + properties: + droplet_id: + type: integer + example: 2457247 + description: The ID of the Droplet that the floating IP will be assigned to. + required: + - droplet_id + - title: Reserve to Region + type: object + properties: + region: + type: string + example: nyc3 + description: >- + The slug identifier for the region the floating IP will be + reserved to. + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the floating IP will be + assigned. + required: + - region + floatingIPsAction: + type: object + required: + - type + properties: + type: + type: string + enum: + - assign + - unassign + description: The type of action to initiate for the floating IP. + discriminator: + propertyName: type + mapping: + assign: '#/components/schemas/floating_ip_action_assign' + unassign: '#/components/schemas/floating_ip_action_unassign' + floating_ip_action_assign: + allOf: + - $ref: '#/components/schemas/floatingIPsAction' + - type: object + required: + - type + - droplet_id + properties: + droplet_id: + type: integer + example: 758604968 + description: The ID of the Droplet that the floating IP will be assigned to. + floating_ip_action_unassign: + allOf: + - $ref: '#/components/schemas/floatingIPsAction' + - type: object + required: + - type + namespace_info: + type: object + properties: + api_host: + type: string + example: https://api_host.io + description: >- + The namespace's API hostname. Each function in a namespace is + provided an endpoint at the namespace's hostname. + namespace: + type: string + example: fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + description: A unique string format of UUID with a prefix fn-. + created_at: + type: string + example: '2022-09-14T04:16:45Z' + description: UTC time string. + updated_at: + type: string + example: '2022-09-14T04:16:45Z' + description: UTC time string. + label: + type: string + example: my namespace + description: The namespace's unique name. + region: + type: string + example: nyc1 + description: The namespace's datacenter region. + uuid: + type: string + example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + description: The namespace's Universally Unique Identifier. + key: + type: string + example: d1zcd455h01mqjfs4s2eaewyejehi5f2uj4etqq3h7cera8iwkub6xg5of1wdde2 + description: >- + A random alpha numeric string. This key is used in conjunction with + the namespace's UUID to authenticate + + a user to use the namespace via `doctl`, DigitalOcean's official + CLI. + create_namespace: + type: object + properties: + region: + type: string + example: nyc1 + description: >- + The [datacenter + region](https://docs.digitalocean.com/products/platform/availability-matrix/#available-datacenters) + in which to create the namespace. + label: + type: string + example: my namespace + description: The namespace's unique name. + required: + - region + - label + scheduled_details: + type: object + description: | + Trigger details for SCHEDULED type, where body is optional. + properties: + cron: + description: >- + valid cron expression string which is required for SCHEDULED type + triggers. + type: string + example: '* * * * *' + body: + description: Optional data to be sent to function while triggering the function. + type: object + nullable: true + properties: + name: + type: string + example: Welcome to DO! + required: + - cron + trigger_info: + type: object + properties: + namespace: + type: string + example: fn-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + description: A unique string format of UUID with a prefix fn-. + name: + type: string + example: my trigger + description: The trigger's unique name within the namespace. + function: + type: string + example: hello + description: Name of function(action) that exists in the given namespace. + type: + type: string + example: SCHEDULED + description: String which indicates the type of trigger source like SCHEDULED. + is_enabled: + type: boolean + example: true + description: Indicates weather the trigger is paused or unpaused. + created_at: + type: string + example: '2022-11-11T04:16:45Z' + description: UTC time string. + updated_at: + type: string + example: '2022-11-11T04:16:45Z' + description: UTC time string. + scheduled_details: + $ref: '#/components/schemas/scheduled_details' + scheduled_runs: + type: object + properties: + last_run_at: + description: >- + Indicates last run time. null value indicates trigger not run + yet. + type: string + nullable: true + example: '2022-11-11T04:16:45Z' + next_run_at: + description: >- + Indicates next run time. null value indicates trigger will not + run. + type: string + nullable: true + example: '2022-11-11T04:16:45Z' + create_trigger: + type: object + properties: + name: + type: string + example: my trigger + description: The trigger's unique name within the namespace. + function: + type: string + example: hello + description: Name of function(action) that exists in the given namespace. + type: + type: string + example: SCHEDULED + description: >- + One of different type of triggers. Currently only SCHEDULED is + supported. + is_enabled: + type: boolean + example: true + description: Indicates weather the trigger is paused or unpaused. + scheduled_details: + $ref: '#/components/schemas/scheduled_details' + required: + - name + - function + - type + - is_enabled + - scheduled_details + update_trigger: + type: object + properties: + is_enabled: + type: boolean + example: true + description: Indicates weather the trigger is paused or unpaused. + scheduled_details: + $ref: '#/components/schemas/scheduled_details' + access_key: + type: object + properties: + id: + type: string + description: The access key's unique identifier with prefix 'dof_v1_'. + example: dof_v1_d79e8aeb42e5476893c7d4c59a166264 + readOnly: true + name: + type: string + description: The access key's name. + example: my-function-access-key + expires_at: + type: string + format: date-time + nullable: true + description: When the key expires (null for non-expiring keys). + example: '2026-12-19T10:30:00Z' + readOnly: true + created_at: + type: string + format: date-time + description: The date and time the key was created. + example: '2025-12-19T10:30:00Z' + readOnly: true + updated_at: + type: string + format: date-time + description: The date and time the key was last updated. + example: '2025-12-19T10:30:00Z' + readOnly: true + access_key_create_request: + type: object + properties: + name: + type: string + description: The access key's name. + example: my-function-access-key + expires_in: + type: string + description: >- + The duration after which the access key expires, specified as a + human-readable duration string in the format `h` (hours) or + `d` (days). Minimum value is `1h`. If omitted, the key will + never expire. + example: 7d + required: + - name + access_key_create_response: + allOf: + - type: object + properties: + secret: + type: string + description: >- + The secret key used to authenticate. This is only returned once + upon creation. Make sure to copy and securely store it. + example: fn_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + readOnly: true + - $ref: '#/components/schemas/access_key' + image_update: + type: object + properties: + name: + $ref: '#/components/schemas/image_name' + distribution: + $ref: '#/components/schemas/distribution' + description: + $ref: '#/components/schemas/image_description' + image_new_custom: + type: object + allOf: + - $ref: '#/components/schemas/image_update' + - properties: + url: + type: string + description: >- + A URL from which the custom Linux virtual machine image may be + retrieved. The image it points to 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. + example: >- + http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img + region: + $ref: '#/components/schemas/region_slug' + tags: + $ref: '#/components/schemas/tags_array' + required: + - name + - url + - region + example: + name: ubuntu-18.04-minimal + url: >- + http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img + distribution: Ubuntu + region: nyc3 + description: Cloud-optimized image w/ small footprint + tags: + - base-image + - prod + images_post_account_transfer_create: + oneOf: + - title: Transfer To Email + type: object + properties: + recipient_email: + type: string + example: alice@example.com + description: >- + The email address of the user account that the image will be + transferred to. + required: + - recipient_email + - title: Transfer To Team + type: object + properties: + recipient_uuid: + type: string + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + description: The UUID of the team that the image will be transferred to. + required: + - recipient_uuid + transfer_id: + type: integer + description: > + A unique number that used to identify and reference an image account + transfer. + example: 3164444 + images_post_account_transfer_accept: + allOf: + - title: Transfer ID + type: object + properties: + transfer_id: + type: integer + description: >- + A unique number that used to identify and reference an image + account transfer. + example: 3164444 + required: + - transfer_id + - title: Recipient Team UUID + type: object + properties: + recipient_uuid: + type: string + description: The UUID of the team that the image will be transferred to. + example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + required: + - recipient_uuid + images_post_account_transfer_cancel: + type: object + properties: + transfer_id: + type: integer + description: >- + A unique number that used to identify and reference an image account + transfer. + example: 3164444 + required: + - transfer_id + images_post_account_transfer_decline: + type: object + properties: + transfer_id: + type: integer + description: >- + A unique number that used to identify and reference an image account + transfer. + example: 3164444 + required: + - transfer_id + image_action_base: + type: object + properties: + type: + type: string + description: >- + The action to be taken on the image. Can be either `convert` or + `transfer`. + enum: + - convert + - transfer + example: convert + required: + - type + image_action_transfer: + allOf: + - $ref: '#/components/schemas/image_action_base' + - type: object + properties: + region: + $ref: '#/components/schemas/region_slug' + required: + - type + - region + kubernetes_node_pool_size: + type: object + properties: + size: + type: string + example: s-1vcpu-2gb + description: >- + The slug identifier for the type of Droplet used as workers in the + node pool. + kubernetes_node_pool_taint: + type: object + properties: + key: + type: string + example: priority + description: >- + An arbitrary string. The `key` and `value` fields of the `taint` + object form a key-value pair. For example, if the value of the `key` + field is "special" and the value of the `value` field is "gpu", the + key value pair would be `special=gpu`. + value: + type: string + example: high + description: >- + An arbitrary string. The `key` and `value` fields of the `taint` + object form a key-value pair. For example, if the value of the `key` + field is "special" and the value of the `value` field is "gpu", the + key value pair would be `special=gpu`. + effect: + type: string + enum: + - NoSchedule + - PreferNoSchedule + - NoExecute + example: NoSchedule + description: >- + How the node reacts to pods that it won't tolerate. Available effect + values are `NoSchedule`, `PreferNoSchedule`, and `NoExecute`. + node: + type: object + properties: + id: + type: string + format: uuid + example: e78247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + description: A unique ID that can be used to identify and reference the node. + name: + type: string + example: adoring-newton-3niq + description: An automatically generated, human-readable name for the node. + status: + type: object + description: >- + An object containing a `state` attribute whose value is set to a + string indicating the current status of the node. + properties: + state: + type: string + enum: + - provisioning + - running + - draining + - deleting + example: provisioning + description: A string indicating the current status of the node. + droplet_id: + type: string + example: '205545370' + description: The ID of the Droplet used for the worker node. + created_at: + type: string + format: date-time + example: '2018-11-15T16:00:11Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the node was created. + updated_at: + type: string + format: date-time + example: '2018-11-15T16:00:11Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the node was last updated. + kubernetes_node_pool_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: cdda885e-7663-40c8-bc74-3a036c66545d + description: >- + A unique ID that can be used to identify and reference a specific + node pool. + name: + type: string + example: frontend-pool + description: A human-readable name for the node pool. + count: + type: integer + example: 3 + description: The number of Droplet instances in the node pool. + tags: + type: array + items: + type: string + example: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s-worker + - production + - web-team + description: >- + An array containing the tags applied to the node pool. All node + pools are automatically tagged `k8s`, `k8s-worker`, and + `k8s:$K8S_CLUSTER_ID`.

Requires `tag:read` scope. + labels: + type: object + nullable: true + example: null + description: >- + An object of key/value mappings specifying labels to apply to all + nodes in a pool. Labels will automatically be applied to all + existing nodes and any subsequent nodes added to the pool. Note that + when a label is removed, it is not deleted from the nodes in the + pool. + taints: + type: array + items: + $ref: '#/components/schemas/kubernetes_node_pool_taint' + description: >- + An array of taints to apply to all nodes in a pool. Taints will + automatically be applied to all existing nodes and any subsequent + nodes added to the pool. When a taint is removed, it is deleted from + all nodes in the pool. + auto_scale: + type: boolean + example: true + description: >- + A boolean value indicating whether auto-scaling is enabled for this + node pool. + min_nodes: + type: integer + example: 3 + description: >- + The minimum number of nodes that this node pool can be auto-scaled + to. The value will be `0` if `auto_scale` is set to `false`. + max_nodes: + type: integer + example: 6 + description: >- + The maximum number of nodes that this node pool can be auto-scaled + to. The value will be `0` if `auto_scale` is set to `false`. + nodes: + type: array + readOnly: true + description: >- + An object specifying the details of a specific worker node in a node + pool. + items: + $ref: '#/components/schemas/node' + kubernetes_node_pool: + type: object + allOf: + - $ref: '#/components/schemas/kubernetes_node_pool_size' + - $ref: '#/components/schemas/kubernetes_node_pool_base' + required: + - name + - size + - count + maintenance_policy: + type: object + nullable: true + description: >- + An object specifying the maintenance window policy for the Kubernetes + cluster. + properties: + start_time: + type: string + example: '12:00' + description: >- + The start time in UTC of the maintenance window policy in 24-hour + clock format / HH:MM notation (e.g., `15:00`). + duration: + type: string + readOnly: true + example: 4h0m0s + description: >- + The duration of the maintenance window policy in human-readable + format. + day: + type: string + enum: + - any + - monday + - tuesday + - wednesday + - thursday + - friday + - saturday + - sunday + example: any + description: >- + The day of the maintenance window policy. May be one of `monday` + through `sunday`, or `any` to indicate an arbitrary week day. + control_plane_firewall: + type: object + nullable: true + description: >- + An object specifying the control plane firewall for the Kubernetes + cluster. Control plane firewall is in early availability (invite only). + properties: + enabled: + type: boolean + description: Indicates whether the control plane firewall is enabled. + example: true + allowed_addresses: + type: array + description: >- + An array of public addresses (IPv4 or CIDR) allowed to access the + control plane. + items: + type: string + example: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + type: object + nullable: true + description: An object specifying custom cluster autoscaler configuration. + properties: + scale_down_utilization_threshold: + type: number + description: >- + Used to customize when cluster autoscaler scales down non-empty + nodes by setting the node utilization threshold. + example: 0.65 + scale_down_unneeded_time: + type: string + description: >- + Used to customize how long a node is unneeded before being scaled + down. + example: 1m0s + expanders: + type: array + items: + type: string + enum: + - random + - priority + - least_waste + description: > + Customizes expanders used by cluster-autoscaler. + + The autoscaler will apply each expander from the provided list to + narrow down the selection of node types created to scale up, + + until either a single node type is left, or the list of expanders is + exhausted. + + If this flag is unset, autoscaler will use its default expander + `random`. + + Passing an empty list (_not_ `null`) will unset any previous + expander customizations. + + + Available expanders: + + - `random`: Randomly selects a node group to scale. + + - `priority`: Selects the node group with the highest priority as + per [user-provided + configuration](https://docs.digitalocean.com/products/kubernetes/how-to/autoscale/#configuring-priority-expander) + + - `least_waste`: Selects the node group that will result in the + least amount of idle resources. + example: + - priority + - random + routing_agent: + type: object + nullable: true + description: >- + An object specifying whether the routing-agent component should be + enabled for the Kubernetes cluster. + properties: + enabled: + type: boolean + description: Indicates whether the routing-agent component is enabled. + example: true + amd_gpu_device_plugin: + type: object + nullable: true + description: >- + An object specifying whether the AMD GPU Device Plugin should be enabled + in the Kubernetes cluster. It's enabled by default for clusters with an + AMD GPU node pool. + properties: + enabled: + type: boolean + description: Indicates whether the AMD GPU Device Plugin is enabled. + example: true + amd_gpu_device_metrics_exporter_plugin: + type: object + nullable: true + description: >- + An object specifying whether the AMD Device Metrics Exporter should be + enabled in the Kubernetes cluster. + properties: + enabled: + type: boolean + description: Indicates whether the AMD Device Metrics Exporter is enabled. + example: true + nvidia_gpu_device_plugin: + type: object + nullable: true + description: >- + An object specifying whether the Nvidia GPU Device Plugin should be + enabled in the Kubernetes cluster. It's enabled by default for clusters + with an Nvidia GPU node pool. + properties: + enabled: + type: boolean + description: Indicates whether the Nvidia GPU Device Plugin is enabled. + example: true + rdma_shared_dev_plugin: + type: object + nullable: true + description: >- + An object specifying whether the RDMA shared device plugin should be + enabled in the Kubernetes cluster. + properties: + enabled: + type: boolean + description: Indicates whether the RDMA shared device plugin is enabled. + example: true + cluster_read: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: bd5f5959-5e1e-4205-a714-a914373942af + description: >- + A unique ID that can be used to identify and reference a Kubernetes + cluster. + name: + type: string + example: prod-cluster-01 + description: A human-readable name for a Kubernetes cluster. + region: + type: string + example: nyc1 + description: >- + The slug identifier for the region where the Kubernetes cluster is + located. + version: + type: string + example: 1.18.6-do.0 + description: >- + The slug identifier for the version of Kubernetes used for the + cluster. If set to a minor version (e.g. "1.14"), the latest version + within it will be used (e.g. "1.14.6-do.1"); if set to "latest", the + latest published version will be used. See the + `/v2/kubernetes/options` endpoint to find all currently available + versions. + cluster_subnet: + type: string + format: cidr + example: 192.168.0.0/20 + description: >- + The range of IP addresses for the overlay network of the Kubernetes + cluster in CIDR notation. + service_subnet: + type: string + format: cidr + example: 192.168.16.0/24 + description: >- + The range of assignable IP addresses for services running in the + Kubernetes cluster in CIDR notation. + vpc_uuid: + type: string + format: uuid + example: c33931f2-a26a-4e61-b85c-4e95a2ec431b + description: >- + A string specifying the UUID of the VPC to which the Kubernetes + cluster is assigned.

Requires `vpc:read` scope. + ipv4: + type: string + readOnly: true + example: 68.183.121.157 + description: >- + The public IPv4 address of the Kubernetes master node. This will not + be set if high availability is configured on the cluster (v1.21+) + endpoint: + type: string + readOnly: true + example: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + description: The base URL of the API server on the Kubernetes master node. + tags: + type: array + items: + type: string + example: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - production + - web-team + description: >- + An array of tags applied to the Kubernetes cluster. All clusters are + automatically tagged `k8s` and `k8s:$K8S_CLUSTER_ID`. +

Requires `tag:read` scope. + node_pools: + type: array + description: >- + An object specifying the details of the worker nodes available to + the Kubernetes cluster. + items: + $ref: '#/components/schemas/kubernetes_node_pool' + maintenance_policy: + $ref: '#/components/schemas/maintenance_policy' + auto_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether the cluster will be automatically + upgraded to new patch releases during its maintenance window. + status: + type: object + readOnly: true + description: >- + An object containing a `state` attribute whose value is set to a + string indicating the current status of the cluster. + properties: + state: + type: string + enum: + - running + - provisioning + - degraded + - error + - deleted + - upgrading + - deleting + example: provisioning + description: A string indicating the current status of the cluster. + message: + type: string + example: provisioning + description: >- + An optional message providing additional information about the + current cluster state. + created_at: + type: string + format: date-time + readOnly: true + example: '2018-11-15T16:00:11Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the Kubernetes cluster was created. + updated_at: + type: string + format: date-time + example: '2018-11-15T16:00:11Z' + readOnly: true + description: >- + A time value given in ISO8601 combined date and time format that + represents when the Kubernetes cluster was last updated. + surge_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether surge upgrade is enabled/disabled + for the cluster. Surge upgrade makes cluster upgrades fast and + reliable by bringing up new nodes before destroying the outdated + nodes. + ha: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether the control plane is run in a + highly available configuration in the cluster. Highly available + control planes incur less downtime. The property cannot be disabled. + When omitted on create, the default is version-dependent; for DOKS + 1.36.0 and later, the default is true; for earlier versions, the + default is false. + registry_enabled: + type: boolean + readOnly: true + example: true + description: >- + A read-only boolean value indicating if a container registry is + integrated with the cluster. + registries: + type: array + nullable: true + items: + type: string + example: + - registry-a + - registry-b + description: An array of integrated DOCR registries. + control_plane_firewall: + $ref: '#/components/schemas/control_plane_firewall' + cluster_autoscaler_configuration: + $ref: '#/components/schemas/cluster_autoscaler_configuration' + routing_agent: + $ref: '#/components/schemas/routing_agent' + amd_gpu_device_plugin: + $ref: '#/components/schemas/amd_gpu_device_plugin' + amd_gpu_device_metrics_exporter_plugin: + $ref: '#/components/schemas/amd_gpu_device_metrics_exporter_plugin' + nvidia_gpu_device_plugin: + $ref: '#/components/schemas/nvidia_gpu_device_plugin' + rdma_shared_dev_plugin: + $ref: '#/components/schemas/rdma_shared_dev_plugin' + required: + - name + - region + - version + - node_pools + cluster: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: bd5f5959-5e1e-4205-a714-a914373942af + description: >- + A unique ID that can be used to identify and reference a Kubernetes + cluster. + name: + type: string + example: prod-cluster-01 + description: A human-readable name for a Kubernetes cluster. + region: + type: string + example: nyc1 + description: >- + The slug identifier for the region where the Kubernetes cluster is + located. + version: + type: string + example: 1.18.6-do.0 + description: >- + The slug identifier for the version of Kubernetes used for the + cluster. If set to a minor version (e.g. "1.14"), the latest version + within it will be used (e.g. "1.14.6-do.1"); if set to "latest", the + latest published version will be used. See the + `/v2/kubernetes/options` endpoint to find all currently available + versions. + cluster_subnet: + type: string + format: cidr + example: 192.168.0.0/20 + description: >- + The range of IP addresses for the overlay network of the Kubernetes + cluster in CIDR notation. + service_subnet: + type: string + format: cidr + example: 192.168.16.0/24 + description: >- + The range of assignable IP addresses for services running in the + Kubernetes cluster in CIDR notation. + vpc_uuid: + type: string + format: uuid + example: c33931f2-a26a-4e61-b85c-4e95a2ec431b + description: >- + A string specifying the UUID of the VPC to which the Kubernetes + cluster is assigned.

Requires `vpc:read` scope. + ipv4: + type: string + readOnly: true + example: 68.183.121.157 + description: >- + The public IPv4 address of the Kubernetes master node. This will not + be set if high availability is configured on the cluster (v1.21+) + endpoint: + type: string + readOnly: true + example: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + description: The base URL of the API server on the Kubernetes master node. + tags: + type: array + items: + type: string + example: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - production + - web-team + description: >- + An array of tags to apply to the Kubernetes cluster. All clusters + are automatically tagged `k8s` and `k8s:$K8S_CLUSTER_ID`. +

Requires `tag:read` and `tag:create` scope, as well as + `tag:delete` if existing tags are getting removed. + node_pools: + type: array + description: >- + An object specifying the details of the worker nodes available to + the Kubernetes cluster. + items: + $ref: '#/components/schemas/kubernetes_node_pool' + maintenance_policy: + $ref: '#/components/schemas/maintenance_policy' + auto_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether the cluster will be automatically + upgraded to new patch releases during its maintenance window. + status: + type: object + readOnly: true + description: >- + An object containing a `state` attribute whose value is set to a + string indicating the current status of the cluster. + properties: + state: + type: string + enum: + - running + - provisioning + - degraded + - error + - deleted + - upgrading + - deleting + example: provisioning + description: A string indicating the current status of the cluster. + message: + type: string + example: provisioning + description: >- + An optional message providing additional information about the + current cluster state. + created_at: + type: string + format: date-time + readOnly: true + example: '2018-11-15T16:00:11Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the Kubernetes cluster was created. + updated_at: + type: string + format: date-time + example: '2018-11-15T16:00:11Z' + readOnly: true + description: >- + A time value given in ISO8601 combined date and time format that + represents when the Kubernetes cluster was last updated. + surge_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether surge upgrade is enabled/disabled + for the cluster. Surge upgrade makes cluster upgrades fast and + reliable by bringing up new nodes before destroying the outdated + nodes. + ha: + type: boolean + example: true + description: >- + A boolean value indicating whether the control plane is run in a + highly available configuration in the cluster. Highly available + control planes incur less downtime. The property cannot be disabled. + When omitted on create, the default is version-dependent; for DOKS + 1.36.0 and later, the default is true; for earlier versions, the + default is false. + registry_enabled: + type: boolean + readOnly: true + example: true + description: >- + A read-only boolean value indicating if a container registry is + integrated with the cluster. + control_plane_firewall: + $ref: '#/components/schemas/control_plane_firewall' + cluster_autoscaler_configuration: + $ref: '#/components/schemas/cluster_autoscaler_configuration' + routing_agent: + $ref: '#/components/schemas/routing_agent' + amd_gpu_device_plugin: + $ref: '#/components/schemas/amd_gpu_device_plugin' + amd_gpu_device_metrics_exporter_plugin: + $ref: '#/components/schemas/amd_gpu_device_metrics_exporter_plugin' + nvidia_gpu_device_plugin: + $ref: '#/components/schemas/nvidia_gpu_device_plugin' + rdma_shared_dev_plugin: + $ref: '#/components/schemas/rdma_shared_dev_plugin' + required: + - name + - region + - version + - node_pools + cluster_update: + type: object + properties: + name: + type: string + example: prod-cluster-01 + description: A human-readable name for a Kubernetes cluster. + tags: + type: array + items: + type: string + example: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - production + - web-team + description: >- + An array of tags applied to the Kubernetes cluster. All clusters are + automatically tagged `k8s` and `k8s:$K8S_CLUSTER_ID`. + maintenance_policy: + $ref: '#/components/schemas/maintenance_policy' + auto_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether the cluster will be automatically + upgraded to new patch releases during its maintenance window. + surge_upgrade: + type: boolean + default: false + example: true + description: >- + A boolean value indicating whether surge upgrade is enabled/disabled + for the cluster. Surge upgrade makes cluster upgrades fast and + reliable by bringing up new nodes before destroying the outdated + nodes. + ha: + type: boolean + example: true + description: >- + A boolean value indicating whether the control plane is run in a + highly available configuration in the cluster. Highly available + control planes incur less downtime. The property cannot be disabled. + When omitted on create, the default is version-dependent; for DOKS + 1.36.0 and later, the default is true; for earlier versions, the + default is false. + control_plane_firewall: + $ref: '#/components/schemas/control_plane_firewall' + cluster_autoscaler_configuration: + $ref: '#/components/schemas/cluster_autoscaler_configuration' + routing_agent: + $ref: '#/components/schemas/routing_agent' + amd_gpu_device_plugin: + $ref: '#/components/schemas/amd_gpu_device_plugin' + amd_gpu_device_metrics_exporter_plugin: + $ref: '#/components/schemas/amd_gpu_device_metrics_exporter_plugin' + nvidia_gpu_device_plugin: + $ref: '#/components/schemas/nvidia_gpu_device_plugin' + rdma_shared_dev_plugin: + $ref: '#/components/schemas/rdma_shared_dev_plugin' + required: + - name + associated_kubernetes_resource: + type: object + properties: + id: + type: string + description: The ID of a resource associated with a Kubernetes cluster. + example: edb0478d-7436-11ea-86e6-0a58ac144b91 + name: + type: string + description: The name of a resource associated with a Kubernetes cluster. + example: volume-001 + associated_kubernetes_resources: + type: object + description: >- + An object containing the IDs of resources associated with a Kubernetes + cluster. + properties: + load_balancers: + type: array + items: + $ref: '#/components/schemas/associated_kubernetes_resource' + example: + - id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: lb-001 + description: >- + A list of names and IDs for associated load balancers that can be + destroyed along with the cluster. + volumes: + type: array + items: + $ref: '#/components/schemas/associated_kubernetes_resource' + example: + - id: ba49449a-7435-11ea-b89e-0a58ac14480f + name: volume-001 + description: >- + A list of names and IDs for associated volumes that can be destroyed + along with the cluster. + volume_snapshots: + type: array + items: + $ref: '#/components/schemas/associated_kubernetes_resource' + example: + - id: edb0478d-7436-11ea-86e6-0a58ac144b91 + name: snapshot-001 + description: >- + A list of names and IDs for associated volume snapshots that can be + destroyed along with the cluster. + destroy_associated_kubernetes_resources: + type: object + description: >- + An object containing the IDs of resources to be destroyed along with + their associated with a Kubernetes cluster. + properties: + load_balancers: + type: array + items: + type: string + example: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + description: >- + A list of IDs for associated load balancers to destroy along with + the cluster. + volumes: + type: array + items: + type: string + example: + - ba49449a-7435-11ea-b89e-0a58ac14480f + description: >- + A list of IDs for associated volumes to destroy along with the + cluster. + volume_snapshots: + type: array + items: + type: string + example: + - edb0478d-7436-11ea-86e6-0a58ac144b91 + description: >- + A list of IDs for associated volume snapshots to destroy along with + the cluster. + credentials: + type: object + properties: + server: + type: string + format: uri + example: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + description: The URL used to access the cluster API server. + certificate_authority_data: + type: string + format: byte + example: >- + LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURKekNDQWcrZ0F3SUJBZ0lDQm5Vd0RRWUpLb1pJaHZjTkFRRUxCUUF3TXpFVk1CTUdBMVVFQ2hNTVJHbG4KYVhSaGJFOWpaV0Z1TVJvd0dBWURWUVFERXhGck9ITmhZWE1nUTJ4MWMzUmxjaUJEUVRBZUZ3MHlNREE0TURNeApOVEkxTWpoYUZ3MDBNREE0TURNeE5USTFNamhhTURNeEZUQVRCZ05WQkFvVERFUnBaMmwwWVd4UFkyVmhiakVhCk1CZ0dBMVVFQXhNUmF6aHpZV0Z6SUVOc2RYTjBaWElnUTBFd2dnRWlNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0SUIKRHdBd2dnRUtBb0lCQVFDc21oa2JrSEpUcGhZQlN0R05VVE1ORVZTd2N3bmRtajArelQvcUZaNGsrOVNxUnYrSgpBd0lCaGpBU0JnTlZIUk1CQWY4RUNEQUdBUUgvQWdFQU1CMEdBMVVkRGdRV0JCUlRzazhhZ1hCUnFyZXdlTXJxClhwa3E1NXg5dVRBTkJna3Foa2lHOXcwQkFRc0ZBQU9DQVFFQXB6V2F6bXNqYWxXTEx3ZjVpbWdDblNINDlKcGkKYWkvbzFMdEJvVEpleGdqZzE1ZVppaG5BMUJMc0lWNE9BZGM3UEFsL040L0hlbENrTDVxandjamRnNVdaYnMzYwozcFVUQ0g5bVVwMFg1SVdhT1VKV292Q1hGUlM1R2VKYXlkSDVPUXhqTURzR2N2UlNvZGQrVnQ2MXE3aWdFZ2I1CjBOZ1l5RnRnc2p0MHpJN3hURzZFNnlsOVYvUmFoS3lIQks2eExlM1RnUGU4SXhWa2RwT3QzR0FhSDRaK0pLR3gKYisyMVZia1NnRE1QQTlyR0VKNVZwVXlBV0FEVXZDRVFHV0hmNGpQN2ZGZlc3T050S0JWY3h3YWFjcVBVdUhzWApwRG5DZVR3V1NuUVp6L05xNmQxWUtsMFdtbkwzTEowemJzRVFGbEQ4MkkwL09MY2dZSDVxMklOZHhBPT0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo= + description: >- + A base64 encoding of bytes representing the certificate authority + data for accessing the cluster. + client_certificate_data: + type: string + format: byte + deprecated: true + nullable: true + example: null + description: > + A base64 encoding of bytes representing the x509 client + + certificate data for access the cluster. This is only returned for + clusters + + without support for token-based authentication. + + + Newly created Kubernetes clusters do not return credentials using + + certificate-based authentication. For additional information, + + [see + here](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/#authenticate). + client_key_data: + type: string + format: byte + deprecated: true + nullable: true + example: null + description: > + A base64 encoding of bytes representing the x509 client key + + data for access the cluster. This is only returned for clusters + without + + support for token-based authentication. + + + Newly created Kubernetes clusters do not return credentials using + + certificate-based authentication. For additional information, + + [see + here](https://docs.digitalocean.com/products/kubernetes/how-to/connect-to-cluster/#authenticate). + token: + type: string + example: $DIGITALOCEAN_TOKEN + description: >- + An access token used to authenticate with the cluster. This is only + returned for clusters with support for token-based authentication. + expires_at: + type: string + format: date-time + example: '2019-11-09T11:50:28.889080521Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the access token expires. + kubernetes_version: + type: object + properties: + slug: + type: string + example: 1.16.13-do.0 + description: >- + The slug identifier for an available version of Kubernetes for use + when creating or updating a cluster. The string contains both the + upstream version of Kubernetes as well as the DigitalOcean revision. + kubernetes_version: + type: string + example: 1.16.13 + description: >- + The upstream version string for the version of Kubernetes provided + by a given slug. + supported_features: + type: array + items: + type: string + example: + - cluster-autoscaler + - docr-integration + - token-authentication + description: >- + The features available with the version of Kubernetes provided by a + given slug. + kubernetes_node_pool_update: + type: object + allOf: + - $ref: '#/components/schemas/kubernetes_node_pool_base' + required: + - name + - count + user: + type: object + properties: + kubernetes_cluster_user: + type: object + properties: + username: + type: string + format: email + example: sammy@digitalocean.com + description: The username for the cluster admin user. + groups: + type: array + items: + type: string + example: + - k8saas:authenticated + description: A list of in-cluster groups that the user belongs to. + kubernetes_region: + type: object + properties: + name: + type: string + example: New York 3 + description: A DigitalOcean region where Kubernetes is available. + slug: + type: string + example: nyc3 + description: The identifier for a region for use when creating a new cluster. + kubernetes_size: + type: object + properties: + name: + type: string + example: s-1vcpu-2gb + description: A Droplet size available for use in a Kubernetes node pool. + slug: + type: string + example: s-1vcpu-2gb + description: The identifier for a size for use when creating a new cluster. + kubernetes_options: + type: object + properties: + options: + type: object + properties: + regions: + type: array + items: + $ref: '#/components/schemas/kubernetes_region' + versions: + type: array + items: + $ref: '#/components/schemas/kubernetes_version' + sizes: + type: array + items: + $ref: '#/components/schemas/kubernetes_size' + clusterlint_results: + type: object + properties: + run_id: + type: string + example: 50c2f44c-011d-493e-aee5-361a4a0d1844 + description: >- + Id of the clusterlint run that can be used later to fetch the + diagnostics. + requested_at: + type: string + format: date-time + example: '2019-10-30T05:34:07Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the schedule clusterlint run request was made. + completed_at: + type: string + format: date-time + example: '2019-10-30T05:34:11Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the schedule clusterlint run request was completed. + diagnostics: + description: >- + An array of diagnostics reporting potential problems for the given + cluster. + type: array + items: + type: object + properties: + check_name: + type: string + example: unused-config-map + description: The clusterlint check that resulted in the diagnostic. + severity: + type: string + example: warning + description: Can be one of error, warning or suggestion. + message: + type: string + example: Unused config map + description: Feedback about the object for users to fix. + object: + type: object + description: >- + Metadata about the Kubernetes API object the diagnostic is + reported on. + properties: + name: + type: string + example: foo + description: Name of the object + kind: + type: string + example: config map + description: The kind of Kubernetes API object + namespace: + type: string + example: kube-system + description: The namespace the object resides in the cluster. + clusterlint_request: + type: object + properties: + include_groups: + type: array + items: + type: string + example: + - basic + - doks + - security + description: >- + An array of check groups that will be run when clusterlint executes + checks. + include_checks: + type: array + items: + type: string + example: + - bare-pods + - resource-requirements + description: >- + An array of checks that will be run when clusterlint executes + checks. + exclude_groups: + type: array + items: + type: string + example: + - workload-health + description: >- + An array of check groups that will be omitted when clusterlint + executes checks. + exclude_checks: + type: array + items: + type: string + example: + - default-namespace + description: >- + An array of checks that will be run when clusterlint executes + checks. + cluster_registry: + type: object + properties: + cluster_uuids: + type: array + items: + type: string + example: + - bd5f5959-5e1e-4205-a714-a914373942af + - 50c2f44c-011d-493e-aee5-361a4a0d1844 + description: An array containing the UUIDs of Kubernetes clusters. + cluster_registries: + type: object + properties: + cluster_uuids: + type: array + items: + type: string + example: + - bd5f5959-5e1e-4205-a714-a914373942af + - 50c2f44c-011d-493e-aee5-361a4a0d1844 + description: An array containing the UUIDs of Kubernetes clusters. + registries: + type: array + items: + type: string + example: + - registry-a + - registry-b + description: An array containing the registry names. + status_messages: + type: object + properties: + message: + type: string + readOnly: true + example: >- + Resource provisioning may be delayed while our team resolves an + incident + description: Status information about the cluster which impacts it's lifecycle. + timestamp: + type: string + format: date-time + readOnly: true + example: '2018-11-15T16:00:11Z' + description: >- + A timestamp in ISO8601 format that represents when the status + message was emitted. + forwarding_rule: + type: object + description: An object specifying a forwarding rule for a load balancer. + properties: + entry_protocol: + type: string + enum: + - http + - https + - http2 + - http3 + - tcp + - udp + example: https + description: > + The protocol used for traffic to the load balancer. The possible + values are: `http`, `https`, `http2`, `http3`, `tcp`, or `udp`. If + you set the `entry_protocol` to `udp`, the `target_protocol` must + be set to `udp`. When using UDP, the load balancer requires that + you set up a health check with a port that uses TCP, HTTP, or HTTPS + to work properly. + entry_port: + type: integer + example: 443 + description: >- + An integer representing the port on which the load balancer instance + will listen. + target_protocol: + type: string + enum: + - http + - https + - http2 + - tcp + - udp + example: http + description: > + The protocol used for traffic from the load balancer to the backend + Droplets. The possible values are: `http`, `https`, `http2`, `tcp`, + or `udp`. If you set the `target_protocol` to `udp`, the + `entry_protocol` must be set to `udp`. When using UDP, the load + balancer requires that you set up a health check with a port that + uses TCP, HTTP, or HTTPS to work properly. + target_port: + type: integer + example: 80 + description: >- + An integer representing the port on the backend Droplets to which + the load balancer will send traffic. + certificate_id: + type: string + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: The ID of the TLS certificate used for SSL termination if enabled. + tls_passthrough: + type: boolean + example: false + description: >- + A boolean value indicating whether SSL encrypted traffic will be + passed through to the backend Droplets. + required: + - entry_protocol + - entry_port + - target_protocol + - target_port + health_check: + type: object + description: An object specifying health check settings for the load balancer. + properties: + protocol: + type: string + enum: + - http + - https + - tcp + default: http + example: http + description: >- + The protocol used for health checks sent to the backend Droplets. + The possible values are `http`, `https`, or `tcp`. + port: + type: integer + default: 80 + example: 80 + description: >- + An integer representing the port on the backend Droplets on which + the health check will attempt a connection. + path: + type: string + default: / + example: / + description: >- + The path on the backend Droplets to which the load balancer instance + will send a request. + check_interval_seconds: + type: integer + default: 10 + example: 10 + description: The number of seconds between between two consecutive health checks. + response_timeout_seconds: + type: integer + default: 5 + example: 5 + description: >- + The number of seconds the load balancer instance will wait for a + response until marking a health check as failed. + unhealthy_threshold: + type: integer + default: 5 + example: 5 + description: >- + The number of times a health check must fail for a backend Droplet + to be marked "unhealthy" and be removed from the pool. + healthy_threshold: + type: integer + default: 3 + example: 3 + description: >- + The number of times a health check must pass for a backend Droplet + to be marked "healthy" and be re-added to the pool. + sticky_sessions: + type: object + description: An object specifying sticky sessions settings for the load balancer. + properties: + type: + type: string + enum: + - cookies + - none + example: cookies + default: none + description: >- + An attribute indicating how and if requests from a client will be + persistently served by the same backend Droplet. The possible values + are `cookies` or `none`. + cookie_name: + type: string + example: DO-LB + description: >- + The name of the cookie sent to the client. This attribute is only + returned when using `cookies` for the sticky sessions type. + cookie_ttl_seconds: + type: integer + example: 300 + description: >- + The number of seconds until the cookie set by the load balancer + expires. This attribute is only returned when using `cookies` for + the sticky sessions type. + lb_firewall: + type: object + description: >- + An object specifying allow and deny rules to control traffic to the load + balancer. + properties: + deny: + type: array + items: + type: string + example: + - ip:1.2.3.4 + - cidr:2.3.0.0/16 + default: [] + description: >- + the rules for denying traffic to the load balancer (in the form + 'ip:1.2.3.4' or 'cidr:1.2.0.0/16') + allow: + type: array + items: + type: string + example: + - ip:1.2.3.4 + - cidr:2.3.0.0/16 + default: [] + description: >- + the rules for allowing traffic to the load balancer (in the form + 'ip:1.2.3.4' or 'cidr:1.2.0.0/16') + domains: + type: object + description: An object specifying domain configurations for a Global load balancer. + properties: + name: + type: string + example: example.com + description: FQDN to associate with a Global load balancer. + is_managed: + type: boolean + example: true + description: >- + A boolean value indicating if the domain is already managed by + DigitalOcean. If true, all A and AAAA records required to enable + Global load balancers will be automatically added. + certificate_id: + type: string + example: 892071a0-bb95-49bc-8021-3afd67a210bf + description: The ID of the TLS certificate used for SSL termination. + glb_settings: + type: object + description: >- + An object specifying forwarding configurations for a Global load + balancer. + properties: + target_protocol: + type: string + enum: + - http + - https + - http2 + example: http + description: >- + The protocol used for forwarding traffic from the load balancer to + the target backends. The possible values are `http`, `https` and + `http2`. + target_port: + type: integer + example: 80 + description: >- + An integer representing the port on the target backends which the + load balancer will forward traffic to. + cdn: + type: object + properties: + is_enabled: + type: boolean + example: true + description: A boolean flag to enable CDN caching. + description: An object specifying CDN configurations for a Global load balancer. + region_priorities: + type: object + additionalProperties: + type: integer + example: + nyc1: 1 + fra1: 2 + sgp1: 3 + description: >- + A map of region string to an integer priority value indicating + preference for which regional target a Global load balancer will + forward traffic to. A lower value indicates a higher priority. + failover_threshold: + type: integer + example: 50 + description: >- + An integer value as a percentage to indicate failure threshold to + decide how the regional priorities will take effect. A value of `50` + would indicate that the Global load balancer will choose a lower + priority region to forward traffic to once this failure threshold + has been reached for the higher priority region. + load_balancer_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + description: >- + A unique ID that can be used to identify and reference a load + balancer. + name: + type: string + example: example-lb-01 + description: A human-readable name for a load balancer instance. + project_id: + type: string + example: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + description: >- + The ID of the project that the load balancer is associated with. If + no ID is provided at creation, the load balancer associates with the + user's default project. If an invalid project ID is provided, the + load balancer will not be created. + ip: + type: string + pattern: >- + ^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ + readOnly: true + example: 104.131.186.241 + description: >- + An attribute containing the public-facing IP address of the load + balancer. + ipv6: + type: string + readOnly: true + example: 2604:a880:800:14::85f5:c000 + description: >- + An attribute containing the public-facing IPv6 address of the load + balancer. + size_unit: + type: integer + default: 1 + minimum: 1 + maximum: 100 + example: 3 + description: >- + How many nodes the load balancer contains. Each additional node + increases the load balancer's ability to manage more connections. + Load balancers can be scaled up or down, and you can change the + number of nodes after creation up to once per hour. This field is + currently not available in the AMS2, NYC2, or SFO1 regions. Use the + `size` field to scale load balancers that reside in these regions. + size: + type: string + enum: + - lb-small + - lb-medium + - lb-large + deprecated: true + default: lb-small + example: lb-small + description: >- + This field has been replaced by the `size_unit` field for all + regions except in AMS2, NYC2, and SFO1. Each available load balancer + size now equates to the load balancer having a set number of nodes. + + * `lb-small` = 1 node + + * `lb-medium` = 3 nodes + + * `lb-large` = 6 nodes + + + You can resize load balancers after creation up to once per hour. + You cannot resize a load balancer within the first hour of its + creation. + algorithm: + type: string + example: round_robin + enum: + - round_robin + - least_connections + deprecated: true + default: round_robin + description: >- + This field has been deprecated. You can no longer specify an + algorithm for load balancers. + status: + type: string + example: new + enum: + - new + - active + - errored + readOnly: true + description: >- + A status string indicating the current state of the load balancer. + This can be `new`, `active`, or `errored`. + created_at: + type: string + format: date-time + readOnly: true + example: '2017-02-01T22:22:58Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the load balancer was created. + forwarding_rules: + type: array + minItems: 1 + items: + $ref: '#/components/schemas/forwarding_rule' + description: >- + An array of objects specifying the forwarding rules for a load + balancer. + health_check: + $ref: '#/components/schemas/health_check' + sticky_sessions: + $ref: '#/components/schemas/sticky_sessions' + redirect_http_to_https: + type: boolean + example: true + default: false + description: >- + A boolean value indicating whether HTTP requests to the load + balancer on port 80 will be redirected to HTTPS on port 443. + enable_proxy_protocol: + type: boolean + example: true + default: false + description: A boolean value indicating whether PROXY Protocol is in use. + enable_backend_keepalive: + type: boolean + example: true + default: false + description: >- + A boolean value indicating whether HTTP keepalive connections are + maintained to target Droplets. + http_idle_timeout_seconds: + type: integer + example: 90 + default: 60 + minimum: 30 + maximum: 600 + description: >- + An integer value which configures the idle timeout for HTTP requests + to the target droplets. + vpc_uuid: + type: string + format: uuid + example: c33931f2-a26a-4e61-b85c-4e95a2ec431b + description: >- + A string specifying the UUID of the VPC to which the load balancer + is assigned. + disable_lets_encrypt_dns_records: + type: boolean + example: true + default: false + description: >- + A boolean value indicating whether to disable automatic DNS record + creation for Let's Encrypt certificates that are added to the load + balancer. + firewall: + $ref: '#/components/schemas/lb_firewall' + network: + type: string + example: EXTERNAL + enum: + - EXTERNAL + - INTERNAL + default: EXTERNAL + description: >- + A string indicating whether the load balancer should be external or + internal. Internal load balancers have no public IPs and are only + accessible to resources on the same VPC network. This property + cannot be updated after creating the load balancer. + network_stack: + type: string + example: IPV4 + enum: + - IPV4 + - DUALSTACK + default: IPV4 + description: >- + A string indicating whether the load balancer will support IPv4 or + both IPv4 and IPv6 networking. This property cannot be updated after + creating the load balancer. + type: + type: string + example: REGIONAL + enum: + - REGIONAL + - REGIONAL_NETWORK + - GLOBAL + default: REGIONAL + description: >- + A string indicating whether the load balancer should be a standard + regional HTTP load balancer, a regional network load balancer that + routes traffic at the TCP/UDP transport layer, or a global load + balancer. + domains: + type: array + items: + $ref: '#/components/schemas/domains' + description: >- + An array of objects specifying the domain configurations for a + Global load balancer. + glb_settings: + $ref: '#/components/schemas/glb_settings' + target_load_balancer_ids: + type: array + items: + type: string + example: + - 7dbf91fe-cbdb-48dc-8290-c3a181554905 + - 996fa239-fac3-42a2-b9a1-9fa822268b7a + description: >- + An array containing the UUIDs of the Regional load balancers to be + used as target backends for a Global load balancer. + tls_cipher_policy: + type: string + example: STRONG + enum: + - DEFAULT + - STRONG + default: DEFAULT + description: >- + A string indicating the policy for the TLS cipher suites used by the + load balancer. The possible values are `DEFAULT` or `STRONG`. The + default value is `DEFAULT`. + required: + - forwarding_rules + load_balancer: + allOf: + - $ref: '#/components/schemas/load_balancer_base' + - type: object + properties: + region: + type: object + allOf: + - description: >- + The region where the load balancer instance is located. When + setting a region, the value should be the slug identifier + for the region. When you query a load balancer, an entire + region object will be returned. + - $ref: '#/components/schemas/region' + - type: object + properties: + droplet_ids: + type: array + items: + type: integer + example: + - 3164444 + - 3164445 + description: >- + An array containing the IDs of the Droplets assigned to the load + balancer. + - type: object + properties: + tag: + type: string + example: prod:web + description: >- + The name of a Droplet tag corresponding to Droplets assigned to + the load balancer. + load_balancer_create: + oneOf: + - title: Assign Droplets by ID + allOf: + - type: object + properties: + droplet_ids: + type: array + items: + type: integer + example: + - 3164444 + - 3164445 + description: >- + An array containing the IDs of the Droplets assigned to the + load balancer. + - type: object + properties: + region: + $ref: '#/components/schemas/region_slug' + - $ref: '#/components/schemas/load_balancer_base' + required: + - droplet_ids + - region + - title: Assign Droplets by Tag + allOf: + - type: object + properties: + tag: + type: string + example: prod:web + description: >- + The name of a Droplet tag corresponding to Droplets assigned + to the load balancer. + - type: object + properties: + region: + $ref: '#/components/schemas/region_slug' + - $ref: '#/components/schemas/load_balancer_base' + required: + - tag + - region + slack_details: + type: object + required: + - url + - channel + properties: + channel: + type: string + example: Production Alerts + description: Slack channel to notify of an alert trigger. + url: + type: string + description: Slack Webhook URL. + example: https://example.invalid/redacted-slack-webhook + alerts: + type: object + required: + - slack + - email + properties: + email: + description: An email to notify on an alert trigger. + example: + - bob@exmaple.com + type: array + items: + type: string + slack: + type: array + description: Slack integration details. + items: + $ref: '#/components/schemas/slack_details' + alert_policy: + type: object + required: + - uuid + - type + - description + - compare + - value + - window + - entities + - tags + - alerts + - enabled + properties: + alerts: + $ref: '#/components/schemas/alerts' + compare: + type: string + example: GreaterThan + enum: + - GreaterThan + - LessThan + description: + type: string + example: CPU Alert + enabled: + type: boolean + example: true + entities: + type: array + items: + type: string + example: + - '192018292' + tags: + type: array + items: + type: string + example: + - droplet_tag + type: + type: string + enum: + - v1/insights/droplet/load_1 + - v1/insights/droplet/load_5 + - v1/insights/droplet/load_15 + - v1/insights/droplet/memory_utilization_percent + - v1/insights/droplet/disk_utilization_percent + - v1/insights/droplet/cpu + - v1/insights/droplet/disk_read + - v1/insights/droplet/disk_write + - v1/insights/droplet/public_outbound_bandwidth + - v1/insights/droplet/public_inbound_bandwidth + - v1/insights/droplet/private_outbound_bandwidth + - v1/insights/droplet/private_inbound_bandwidth + - v1/insights/lbaas/avg_cpu_utilization_percent + - v1/insights/lbaas/connection_utilization_percent + - v1/insights/lbaas/droplet_health + - v1/insights/lbaas/tls_connections_per_second_utilization_percent + - v1/insights/lbaas/increase_in_http_error_rate_percentage_5xx + - v1/insights/lbaas/increase_in_http_error_rate_percentage_4xx + - v1/insights/lbaas/increase_in_http_error_rate_count_5xx + - v1/insights/lbaas/increase_in_http_error_rate_count_4xx + - v1/insights/lbaas/high_http_request_response_time + - v1/insights/lbaas/high_http_request_response_time_50p + - v1/insights/lbaas/high_http_request_response_time_95p + - v1/insights/lbaas/high_http_request_response_time_99p + - v1/dbaas/alerts/load_15_alerts + - v1/dbaas/alerts/memory_utilization_alerts + - v1/dbaas/alerts/disk_utilization_alerts + - v1/dbaas/alerts/cpu_alerts + - v1/droplet/autoscale_alerts/current_instances + - v1/droplet/autoscale_alerts/target_instances + - v1/droplet/autoscale_alerts/current_cpu_utilization + - v1/droplet/autoscale_alerts/target_cpu_utilization + - v1/droplet/autoscale_alerts/current_memory_utilization + - v1/droplet/autoscale_alerts/target_memory_utilization + - v1/droplet/autoscale_alerts/scale_up + - v1/droplet/autoscale_alerts/scale_down + example: v1/insights/droplet/cpu + uuid: + type: string + example: 78b3da62-27e5-49ba-ac70-5db0b5935c64 + value: + type: number + format: float + example: 80 + window: + type: string + enum: + - 5m + - 10m + - 30m + - 1h + example: 5m + list_alert_policy: + type: object + required: + - policies + properties: + policies: + type: array + items: + $ref: '#/components/schemas/alert_policy' + alert_policy_request: + type: object + required: + - type + - description + - compare + - value + - window + - entities + - tags + - alerts + - enabled + properties: + alerts: + $ref: '#/components/schemas/alerts' + compare: + type: string + example: GreaterThan + enum: + - GreaterThan + - LessThan + description: + type: string + example: CPU Alert + enabled: + type: boolean + example: true + entities: + type: array + items: + type: string + example: + - '192018292' + tags: + type: array + items: + type: string + example: + - droplet_tag + type: + type: string + enum: + - v1/insights/droplet/load_1 + - v1/insights/droplet/load_5 + - v1/insights/droplet/load_15 + - v1/insights/droplet/memory_utilization_percent + - v1/insights/droplet/disk_utilization_percent + - v1/insights/droplet/cpu + - v1/insights/droplet/disk_read + - v1/insights/droplet/disk_write + - v1/insights/droplet/public_outbound_bandwidth + - v1/insights/droplet/public_inbound_bandwidth + - v1/insights/droplet/private_outbound_bandwidth + - v1/insights/droplet/private_inbound_bandwidth + - v1/insights/lbaas/avg_cpu_utilization_percent + - v1/insights/lbaas/connection_utilization_percent + - v1/insights/lbaas/droplet_health + - v1/insights/lbaas/tls_connections_per_second_utilization_percent + - v1/insights/lbaas/increase_in_http_error_rate_percentage_5xx + - v1/insights/lbaas/increase_in_http_error_rate_percentage_4xx + - v1/insights/lbaas/increase_in_http_error_rate_count_5xx + - v1/insights/lbaas/increase_in_http_error_rate_count_4xx + - v1/insights/lbaas/high_http_request_response_time + - v1/insights/lbaas/high_http_request_response_time_50p + - v1/insights/lbaas/high_http_request_response_time_95p + - v1/insights/lbaas/high_http_request_response_time_99p + - v1/dbaas/alerts/load_15_alerts + - v1/dbaas/alerts/memory_utilization_alerts + - v1/dbaas/alerts/disk_utilization_alerts + - v1/dbaas/alerts/cpu_alerts + - v1/droplet/autoscale_alerts/current_instances + - v1/droplet/autoscale_alerts/target_instances + - v1/droplet/autoscale_alerts/current_cpu_utilization + - v1/droplet/autoscale_alerts/target_cpu_utilization + - v1/droplet/autoscale_alerts/current_memory_utilization + - v1/droplet/autoscale_alerts/target_memory_utilization + - v1/droplet/autoscale_alerts/scale_up + - v1/droplet/autoscale_alerts/scale_down + example: v1/insights/droplet/cpu + value: + type: number + format: float + example: 80 + window: + type: string + example: 5m + enum: + - 5m + - 10m + - 30m + - 1h + metrics_result: + type: object + required: + - metric + - values + properties: + metric: + type: object + description: >- + An object containing the metric's labels. These labels are key/value + pairs that vary depending on the metric being queried. For example, + load balancer metrics contain a `lb_id` label, while Droplet metrics + contain a `host_id` label, and App Platform metrics contain a + `app_component` label. + additionalProperties: + type: string + example: + host_id: '19201920' + values: + type: array + description: An array of values for the metric. + example: + - - 1435781430 + - '1' + - - 1435781445 + - '1' + items: + type: array + items: + oneOf: + - type: integer + - type: string + metrics_data: + type: object + required: + - resultType + - result + properties: + result: + type: array + description: Result of query. + items: + $ref: '#/components/schemas/metrics_result' + resultType: + type: string + enum: + - matrix + example: matrix + metrics: + type: object + required: + - status + - data + properties: + data: + $ref: '#/components/schemas/metrics_data' + status: + type: string + example: success + enum: + - success + - error + opensearch_config_omit_credentials: + type: object + description: OpenSearch destination configuration with `credentials` omitted. + properties: + id: + type: string + description: A unique identifier for a configuration. + example: 41078d41-165c-4cff-9f0a-19536e3e3d49 + endpoint: + type: string + example: example.com + description: host of the OpenSearch cluster + cluster_uuid: + type: string + example: 85148069-7e35-4999-80bd-6fa1637ca385 + description: A unique identifier for a managed OpenSearch cluster. + cluster_name: + type: string + example: managed_dbaas_cluster + description: Name of a managed OpenSearch cluster. + index_name: + type: string + description: OpenSearch index to send logs to. + example: logs + retention_days: + type: integer + description: Number of days to retain logs in OpenSearch. + example: 14 + default: 14 + destination_omit_credentials: + type: object + properties: + id: + type: string + description: A unique identifier for a destination. + example: 01f30bfa-319a-4769-ba95-9d43971fb514 + name: + type: string + description: destination name + example: managed_opensearch_cluster + type: + type: string + enum: + - opensearch_dbaas + - opensearch_ext + description: > + The destination type. `opensearch_dbaas` for a DigitalOcean managed + OpenSearch + + cluster or `opensearch_ext` for an externally managed one. + example: opensearch_dbaas + config: + $ref: '#/components/schemas/opensearch_config_omit_credentials' + opensearch_config_request: + type: object + required: + - endpoint + properties: + credentials: + type: object + description: >- + Credentials for an OpenSearch cluster user. Optional if + `cluster_uuid` is passed. + properties: + username: + type: string + example: username + password: + type: string + example: password + endpoint: + type: string + example: example.com + description: host of the OpenSearch cluster + cluster_uuid: + type: string + example: 85148069-7e35-4999-80bd-6fa1637ca385 + description: A unique identifier for a managed OpenSearch cluster. + cluster_name: + type: string + example: managed_dbaas_cluster + description: Name of a managed OpenSearch cluster. + index_name: + type: string + description: OpenSearch index to send logs to. + example: logs + retention_days: + type: integer + description: Number of days to retain logs in an OpenSearch cluster. + example: 14 + default: 14 + destination_request: + type: object + required: + - config + - type + properties: + name: + type: string + description: destination name + example: managed_opensearch_cluster + type: + type: string + enum: + - opensearch_dbaas + - opensearch_ext + description: > + The destination type. `opensearch_dbaas` for a DigitalOcean managed + OpenSearch + + cluster or `opensearch_ext` for an externally managed one. + config: + $ref: '#/components/schemas/opensearch_config_request' + urn: + type: string + pattern: >- + ^do:(dbaas|domain|droplet|floatingip|loadbalancer|space|volume|kubernetes|vpc):.* + example: do:droplet:13457723 + description: >- + The uniform resource name (URN) for the resource in the format + do:resource_type:resource_id. + opensearch_config: + type: object + required: + - endpoint + properties: + id: + type: string + description: A unique identifier for a configuration. + example: 41078d41-165c-4cff-9f0a-19536e3e3d49 + credentials: + type: object + description: >- + Credentials for an OpenSearch cluster user. Optional if + `cluster_uuid` is passed. + properties: + username: + type: string + example: username + password: + type: string + example: password + endpoint: + type: string + example: example.com + description: host of the OpenSearch cluster + cluster_uuid: + type: string + example: 85148069-7e35-4999-80bd-6fa1637ca385 + description: A unique identifier for a managed OpenSearch cluster. + cluster_name: + type: string + example: managed_dbaas_cluster + description: Name of a managed OpenSearch cluster. + index_name: + type: string + description: OpenSearch index to send logs to. + example: logs + retention_days: + type: integer + description: 'Number of days to retain logs in OpenSearch (default: 14)' + example: 14 + destination: + type: object + required: + - config + properties: + id: + type: string + description: A unique identifier for a destination. + example: 01f30bfa-319a-4769-ba95-9d43971fb514 + name: + type: string + description: destination name + example: managed_opensearch_cluster + type: + type: string + enum: + - opensearch_dbaas + - opensearch_ext + description: > + The destination type. `opensearch_dbaas` for a DigitalOcean managed + OpenSearch + + cluster or `opensearch_ext` for an externally managed one. + example: opensearch_dbaas + config: + $ref: '#/components/schemas/opensearch_config' + sink_resource: + type: object + required: + - urn + properties: + urn: + type: string + pattern: ^do:kubernetes:.* + example: do:kubernetes:f453aa14-646e-4cf8-8c62-75a19fb24ec2 + description: >- + The uniform resource name (URN) for the resource in the format + do:resource_type:resource_id. + name: + type: string + description: resource name + example: managed_kubernetes_cluster + sinks_response: + type: object + required: + - urn + properties: + destination: + $ref: '#/components/schemas/destination' + resources: + type: array + description: List of resources identified by their URNs. + items: + $ref: '#/components/schemas/sink_resource' + nfs_response: + type: object + properties: + id: + type: string + description: The unique identifier of the NFS share. + readOnly: true + example: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + name: + type: string + description: The human-readable name of the share. + example: sammy-share-drive + size_gib: + type: integer + description: >- + The desired/provisioned size of the share in GiB (Gibibytes). Must + be >= 50. + example: 1024 + region: + type: string + description: >- + The DigitalOcean region slug (e.g., nyc2, atl1) where the NFS share + resides. + example: atl1 + status: + type: string + enum: + - CREATING + - ACTIVE + - FAILED + - DELETED + description: The current status of the share. + readOnly: true + example: ACTIVE + created_at: + type: string + format: date-time + description: Timestamp for when the NFS share was created. + readOnly: true + example: '2023-01-01T00:00:00Z' + vpc_ids: + type: array + items: + type: string + description: List of VPC IDs that should be able to access the share. + example: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + mount_path: + type: string + description: >- + Path at which the share will be available, to be mounted at a target + of the user's choice within the client + example: /123456/your-nfs-share-uuid + host: + type: string + description: >- + The host IP of the NFS server that will be accessible from the + associated VPC + example: 10.128.32.2 + required: + - id + - name + - size_gib + - region + - status + - created_at + nfs_list_response: + type: object + properties: + shares: + type: array + items: + $ref: '#/components/schemas/nfs_response' + nfs_request: + type: object + properties: + name: + type: string + description: The human-readable name of the share. + example: my-nfs-share + size_gib: + type: integer + description: >- + The desired/provisioned size of the share in GiB (Gibibytes). Must + be >= 50. + example: 50 + region: + type: string + description: >- + The DigitalOcean region slug (e.g., nyc2, atl1) where the NFS share + resides. + example: atl1 + vpc_ids: + type: array + items: + type: string + description: List of VPC IDs that should be able to access the share. + example: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + performance_tier: + type: string + description: The performance tier of the share. + example: standard + required: + - name + - size_gib + - region + - vpc_ids + nfs_create_response: + type: object + properties: + share: + $ref: '#/components/schemas/nfs_response' + nfs_get_response: + type: object + properties: + share: + $ref: '#/components/schemas/nfs_response' + nfs_action: + required: + - type + type: object + description: Specifies the action that will be taken on the NFS share. + properties: + type: + type: string + enum: + - resize + - snapshot + - attach + - detach + - reassign + - switch_performance_tier + example: resize + description: >- + The type of action to initiate for the NFS share (such as resize or + snapshot). + region: + type: string + description: >- + The DigitalOcean region slug (e.g. atl1, nyc2) where the NFS + snapshot resides. + example: atl1 + nfs_action_resize: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + size_gib: + type: integer + example: 2048 + description: The new size for the NFS share. + required: + - size_gib + nfs_action_snapshot: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + name: + type: string + example: daily-backup + description: Snapshot name of the NFS share + required: + - name + nfs_action_attach: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + vpc_id: + type: string + example: vpc-id-123 + description: The ID of the VPC to which the NFS share will be attached + required: + - vpc_id + nfs_action_detach: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + vpc_id: + type: string + example: vpc-id-123 + description: The ID of the VPC from which the NFS share will be detached + required: + - vpc_id + nfs_action_reassign: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + old_vpc_id: + type: string + example: vpc-id-123 + description: >- + The ID of the VPC from which the NFS share will be + reassigned + new_vpc_id: + type: string + example: vpc-id-456 + description: The ID of the VPC to which the NFS share will be reassigned + required: + - old_vpc_id + - new_vpc_id + nfs_action_switch_performance_tier: + allOf: + - $ref: '#/components/schemas/nfs_action' + - type: object + properties: + params: + type: object + properties: + performance_tier: + type: string + example: standard + description: >- + The performance tier to which the NFS share will be switched + (e.g., standard, high). + required: + - performance_tier + nfs_actions_response: + type: object + description: Action response of an NFS share. + properties: + action: + type: object + description: The action that was submitted. + properties: + region_slug: + type: string + description: The DigitalOcean region slug where the resource is located. + example: atl1 + resource_id: + type: string + format: uuid + description: >- + The unique identifier of the resource on which the action is + being performed. + example: b5eb9e60-6750-4f3f-90b6-8296966eaf35 + resource_type: + type: string + enum: + - network_file_share + - network_file_share_snapshot + description: The type of resource on which the action is being performed. + example: network_file_share + started_at: + type: string + format: date-time + description: The timestamp when the action was started. + example: '2025-10-14T11:55:31.615157397Z' + status: + type: string + enum: + - in-progress + - completed + - errored + description: The current status of the action. + example: in-progress + type: + type: string + description: The type of action being performed. + example: resize + required: + - region_slug + - resource_id + - resource_type + - started_at + - status + - type + required: + - action + nfs_snapshot_response: + type: object + description: Represents an NFS snapshot. + properties: + id: + type: string + description: The unique identifier of the snapshot. + example: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + name: + type: string + description: The human-readable name of the snapshot. + example: daily-backup + size_gib: + type: integer + format: uint64 + description: The size of the snapshot in GiB. + example: 1024 + region: + type: string + description: The DigitalOcean region slug where the snapshot is located. + example: atl1 + status: + type: string + enum: + - UNKNOWN + - CREATING + - ACTIVE + - FAILED + - DELETED + description: The current status of the snapshot. + example: CREATING + created_at: + type: string + format: date-time + description: The timestamp when the snapshot was created. + example: '2023-11-14T16:29:21Z' + share_id: + type: string + format: uuid + description: >- + The unique identifier of the share from which this snapshot was + created. + example: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d + required: + - id + - name + - region + - size_gib + - status + - created_at + - share_id + nfs_snapshot_list_response: + type: object + properties: + snapshots: + type: array + items: + $ref: '#/components/schemas/nfs_snapshot_response' + nfs_snapshot_get_response: + type: object + properties: + snapshot: + $ref: '#/components/schemas/nfs_snapshot_response' + partner_attachment: + type: object + properties: + id: + type: string + format: string + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: >- + A unique ID that can be used to identify and reference the partner + attachment. + x-order: 1 + name: + type: string + pattern: ^[a-zA-Z0-9\-\.]+$ + example: env.prod-partner-network-connect + description: >- + The name of the partner attachment. Must be unique and may only + contain alphanumeric characters, dashes, and periods. + x-order: 2 + state: + type: string + readOnly: true + example: active + description: The current operational state of the attachment. + x-order: 4 + connection_bandwidth_in_mbps: + type: integer + example: 1000 + description: The bandwidth (in Mbps) of the connection. + x-order: 5 + region: + type: string + example: nyc + description: The region where the partner attachment is located. + x-order: 6 + naas_provider: + type: string + example: megaport + description: The Network as a Service (NaaS) provider for the partner attachment. + x-order: 7 + vpc_ids: + type: array + items: + type: string + format: string + minItems: 1 + example: + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + - 994a2735-dc84-11e8-80bc-3cfdfea9fba1 + description: An array of VPC network IDs. + x-order: 8 + bgp: + type: object + properties: + local_asn: + type: integer + example: 64532 + description: ASN of the local router. + peer_asn: + type: integer + example: 64532 + description: ASN of the peer router + local_router_ip: + type: string + example: 169.254.0.1/29 + description: IP of the DigitalOcean router + peer_router_ip: + type: string + example: 169.254.0.1/29 + description: IP of the peer router + description: The BGP configuration for the partner attachment. + x-order: 9 + created_at: + type: string + format: date-time + readOnly: true + example: '2020-03-13T19:20:47.442049222Z' + description: A time value given in ISO8601 combined date and time format. + x-order: 10 + parent_uuid: + type: string + readOnly: true + example: 34259a41-0ca6-4a6b-97dd-a22bcab900dd + description: Associated partner attachment UUID + x-order: 11 + children: + type: array + readOnly: true + items: + type: string + format: string + minItems: 1 + example: + - ee1ad867-7026-44a5-bfcc-2587b52e1291 + description: An array of associated partner attachment UUIDs. + x-order: 12 + partner_attachment_writable: + type: object + required: + - name + - connection_bandwidth_in_mbps + - region + - naas_provider + - vpc_ids + properties: + name: + type: string + pattern: ^[a-zA-Z0-9\-\.]+$ + example: env.prod-partner-network-connect + description: >- + The name of the partner attachment. Must be unique and may only + contain alphanumeric characters, dashes, and periods. + connection_bandwidth_in_mbps: + type: integer + description: Bandwidth (in Mbps) of the connection. + enum: + - 1000 + - 2000 + - 5000 + - 10000 + example: 1000 + region: + description: The region to create the partner attachment. + enum: + - nyc + - sfo + - fra + - ams + - sgp + type: string + example: nyc + naas_provider: + type: string + example: megaport + vpc_ids: + type: array + items: + type: string + format: string + minItems: 1 + example: + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + - 994a2735-dc84-11e8-80bc-3cfdfea9fba1 + description: An array of VPCs IDs. + parent_uuid: + type: string + description: Optional associated partner attachment UUID + example: d594cf8d-8c79-4bc5-aec1-6f9b211506b3 + bgp: + type: object + description: Optional BGP configurations + required: + - local_router_ip + - peer_router_ip + - peer_router_asn + - auth_key + properties: + local_router_ip: + type: string + example: 169.254.0.1/29 + description: IP of the DO router + peer_router_ip: + type: string + example: 169.254.0.6/29 + description: IP of the Naas Provider router + peer_router_asn: + type: integer + example: 64532 + description: ASN of the peer router + auth_key: + type: string + example: 0xsNnb1pwQlowdoMySEfWwk4I + description: BGP Auth Key + redundancy_zone: + type: string + description: Optional redundancy zone for the partner attachment. + enum: + - MEGAPORT_BLUE + - MEGAPORT_RED + example: MEGAPORT_BLUE + partner_attachment_updatable: + anyOf: + - title: Name + required: + - name + type: object + properties: + name: + type: string + pattern: ^[a-zA-Z0-9\-\.]+$ + example: env.prod-partner-network-connect + description: >- + The name of the partner attachment. Must be unique and may only + contain alphanumeric characters, dashes, and periods. + - title: VPC IDs + type: object + required: + - vpc_ids + properties: + vpc_ids: + type: array + items: + type: string + format: string + minItems: 1 + example: + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + - 994a2735-dc84-11e8-80bc-3cfdfea9fba1 + description: An array of VPCs IDs. + - title: BGP + type: object + properties: + bgp: + type: object + description: BGP configurations + required: + - local_router_ip + - peer_router_ip + - peer_router_asn + - auth_key + properties: + local_router_ip: + type: string + example: 169.254.0.1/29 + description: IP of the DO router + peer_router_ip: + type: string + example: 169.254.0.6/29 + description: IP of the NaaS provider router + peer_router_asn: + type: integer + example: 64532 + description: ASN of the peer router + auth_key: + type: string + example: 0xsNnb1pwQlowdoMySEfWwk4I + description: BGP Auth Key + partner_attachment_service_key: + type: object + properties: + value: + type: string + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + x-order: 1 + created_at: + type: string + format: date-time + readOnly: true + example: '2020-03-13T19:20:47.442049222Z' + description: A time value given in the ISO 8601 combined date and time format. + x-order: 2 + state: + type: string + readOnly: true + example: CREATED + x-order: 3 + partner_attachment_remote_route: + type: object + properties: + cidr: + type: string + readOnly: true + example: 10.10.10.0/24 + description: A CIDR block representing a remote route. + project_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679 + description: The unique universal identifier of this project. + owner_uuid: + type: string + readOnly: true + example: 99525febec065ca37b2ffe4f852fd2b2581895e7 + description: The unique universal identifier of the project owner. + owner_id: + type: integer + readOnly: true + example: 258992 + description: The integer id of the project owner. + name: + type: string + maxLength: 175 + example: my-web-api + description: >- + The human-readable name for the project. The maximum length is 175 + characters and the name must be unique. + description: + type: string + maxLength: 255 + example: My website API + description: >- + The description of the project. The maximum length is 255 + characters. + purpose: + type: string + maxLength: 255 + example: Service or API + description: > + The purpose of the project. The maximum length is 255 characters. It + can + + have one of the following values: + + + - Just trying out DigitalOcean + + - Class project / Educational purposes + + - Website or blog + + - Web Application + + - Service or API + + - Mobile Application + + - Machine learning / AI / Data processing + + - IoT + + - Operational / Developer tooling + + + If another value for purpose is specified, for example, "your custom + purpose", + + your purpose will be stored as `Other: your custom purpose`. + environment: + type: string + enum: + - Development + - Staging + - Production + example: Production + description: The environment of the project's resources. + created_at: + type: string + format: date-time + readOnly: true + example: '2018-09-27T20:10:35Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the project was created. + updated_at: + type: string + format: date-time + readOnly: true + example: '2018-09-27T20:10:35Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the project was updated. + project: + allOf: + - $ref: '#/components/schemas/project_base' + - type: object + properties: + is_default: + type: boolean + example: false + description: >- + If true, all resources will be added to this project if no + project is specified. + resource: + type: object + properties: + urn: + $ref: '#/components/schemas/urn' + assigned_at: + type: string + format: date-time + example: '2018-09-28T19:26:37Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the project was created. + links: + type: object + description: >- + The links object contains the `self` object, which contains the + resource relationship. + properties: + self: + type: string + format: uri + example: https://api.digitalocean.com/v2/droplets/13457723 + description: A URI that can be used to retrieve the resource. + status: + type: string + enum: + - ok + - not_found + - assigned + - already_assigned + - service_down + example: ok + description: The status of assigning and fetching the resources. + project_assignment: + type: object + properties: + resources: + type: array + items: + $ref: '#/components/schemas/urn' + example: + - do:droplet:13457723 + description: >- + A list of uniform resource names (URNs) to be added to a project. + Only resources that you are authorized to see will be returned. + registry_base: + type: object + properties: + name: + type: string + maxLength: 63 + pattern: ^[a-z0-9-]{1,63}$ + example: example + description: >- + A globally unique name for the container registry. Must be lowercase + and be composed only of numbers, letters and `-`, up to a limit of + 63 characters. + created_at: + type: string + format: date-time + readOnly: true + example: '2020-03-21T16:02:37Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the registry was created. + region: + type: string + example: fra1 + description: Slug of the region where registry data is stored + storage_usage_bytes: + type: integer + readOnly: true + example: 29393920 + description: The amount of storage used in the registry in bytes. + storage_usage_bytes_updated_at: + type: string + format: date-time + readOnly: true + example: '2020-11-04T21:39:49.530562231Z' + description: >- + The time at which the storage usage was updated. Storage usage is + calculated asynchronously, and may not immediately reflect pushes to + the registry. + subscription_tier_base: + type: object + properties: + name: + type: string + example: Basic + description: The name of the subscription tier. + slug: + type: string + example: basic + description: The slug identifier of the subscription tier. + included_repositories: + type: integer + example: 5 + description: >- + The number of repositories included in the subscription tier. `0` + indicates that the subscription tier includes unlimited + repositories. + included_storage_bytes: + type: integer + example: 5368709120 + description: The amount of storage included in the subscription tier in bytes. + allow_storage_overage: + type: boolean + example: true + description: >- + A boolean indicating whether the subscription tier supports + additional storage above what is included in the base plan at an + additional cost per GiB used. + included_bandwidth_bytes: + type: integer + example: 5368709120 + description: >- + The amount of outbound data transfer included in the subscription + tier in bytes. + monthly_price_in_cents: + type: integer + example: 500 + description: The monthly cost of the subscription tier in cents. + storage_overage_price_in_cents: + type: integer + example: 2 + description: >- + The price paid in cents per GiB for additional storage beyond what + is included in the subscription plan. + subscription: + type: object + properties: + tier: + $ref: '#/components/schemas/subscription_tier_base' + created_at: + type: string + format: date-time + readOnly: true + example: '2020-01-23T21:19:12Z' + description: The time at which the subscription was created. + updated_at: + type: string + format: date-time + readOnly: true + example: '2020-11-05T15:53:24Z' + description: The time at which the subscription was last updated. + registry: + type: object + allOf: + - $ref: '#/components/schemas/registry_base' + - type: object + properties: + subscription: + allOf: + - readOnly: true + - $ref: '#/components/schemas/subscription' + multiregistry_create: + type: object + properties: + name: + type: string + maxLength: 63 + pattern: ^[a-z0-9-]{1,63}$ + example: example + description: >- + A globally unique name for the container registry. Must be lowercase + and be composed only of numbers, letters and `-`, up to a limit of + 63 characters. + subscription_tier_slug: + type: string + enum: + - starter + - basic + - professional + example: basic + description: >- + The slug of the subscription tier to sign up for. Valid values can + be retrieved using the options endpoint. + region: + type: string + enum: + - nyc3 + - sfo3 + - sfo2 + - ams3 + - sgp1 + - fra1 + - blr1 + - syd1 + example: fra1 + description: >- + Slug of the region where registry data is stored. When not provided, + a region will be selected. + required: + - name + multiregistry: + type: object + allOf: + - $ref: '#/components/schemas/registry_base' + docker_credentials: + type: object + properties: + auths: + type: object + properties: + registry.digitalocean.com: + type: object + properties: + auth: + type: string + example: >- + YjdkMDNhNjk0N2IyMTdlZmI2ZjNlYzNiZDM1MDQ1ODI6YjdkMDNhNjk0N2IyMTdlZmI2ZjNlYzNiZDM1MDQ1ODIK + description: >- + A base64 encoded string containing credentials for the + container registry. + subscription_tier_extended: + type: object + properties: + eligible: + type: boolean + example: true + description: >- + A boolean indicating whether your account it eligible to use a + certain subscription tier. + eligibility_reasons: + type: array + items: + type: string + enum: + - OverRepositoryLimit + - OverStorageLimit + example: + - OverRepositoryLimit + description: >- + If your account is not eligible to use a certain subscription tier, + this will include a list of reasons that prevent you from using the + tier. + garbage_collection: + type: object + properties: + uuid: + type: string + example: eff0feee-49c7-4e8f-ba5c-a320c109c8a8 + description: A string specifying the UUID of the garbage collection. + registry_name: + type: string + example: example + description: The name of the container registry. + status: + type: string + enum: + - requested + - waiting for write JWTs to expire + - scanning manifests + - deleting unreferenced blobs + - cancelling + - failed + - succeeded + - cancelled + example: requested + description: The current status of this garbage collection. + created_at: + type: string + format: date-time + example: '2020-10-30T21:03:24Z' + description: The time the garbage collection was created. + updated_at: + type: string + format: date-time + example: '2020-10-30T21:03:44Z' + description: The time the garbage collection was last updated. + blobs_deleted: + type: integer + example: 42 + description: The number of blobs deleted as a result of this garbage collection. + freed_bytes: + type: integer + example: 667 + description: The number of bytes freed as a result of this garbage collection. + update_registry: + type: object + properties: + cancel: + type: boolean + example: true + description: >- + A boolean value indicating that the garbage collection should be + cancelled. + repository_blob: + type: object + properties: + digest: + type: string + example: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + description: The digest of the blob + compressed_size_bytes: + type: integer + example: 2803255 + description: The compressed size of the blob in bytes. + repository_manifest: + type: object + properties: + registry_name: + type: string + example: example + description: The name of the container registry. + repository: + type: string + example: repo-1 + description: The name of the repository. + digest: + type: string + example: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + description: The manifest digest + compressed_size_bytes: + type: integer + example: 2803255 + description: The compressed size of the manifest in bytes. + size_bytes: + type: integer + example: 5861888 + description: >- + The uncompressed size of the manifest in bytes (this size is + calculated asynchronously so it may not be immediately available). + updated_at: + type: string + format: date-time + example: '2020-04-09T23:54:25Z' + description: The time the manifest was last updated. + tags: + type: array + items: + type: string + example: + - latest + - v1 + - v2 + description: All tags associated with this manifest + blobs: + type: array + items: + $ref: '#/components/schemas/repository_blob' + description: All blobs associated with this manifest + repository_v2: + type: object + properties: + registry_name: + type: string + example: example + description: The name of the container registry. + name: + type: string + example: repo-1 + description: The name of the repository. + latest_manifest: + $ref: '#/components/schemas/repository_manifest' + tag_count: + type: integer + example: 1 + description: The number of tags in the repository. + manifest_count: + type: integer + example: 1 + description: The number of manifests in the repository. + repository_tag: + type: object + properties: + registry_name: + type: string + example: example + description: The name of the container registry. + repository: + type: string + example: repo-1 + description: The name of the repository. + tag: + type: string + example: latest + description: The name of the tag. + manifest_digest: + type: string + example: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + description: The digest of the manifest associated with the tag. + compressed_size_bytes: + type: integer + example: 2803255 + description: The compressed size of the tag in bytes. + size_bytes: + type: integer + example: 5861888 + description: >- + The uncompressed size of the tag in bytes (this size is calculated + asynchronously so it may not be immediately available). + updated_at: + type: string + format: date-time + example: '2020-04-09T23:54:25Z' + description: The time the tag was last updated. + validate_registry: + type: object + properties: + name: + type: string + maxLength: 63 + pattern: ^[a-z0-9-]{1,63}$ + example: example + description: >- + A globally unique name for the container registry. Must be lowercase + and be composed only of numbers, letters and `-`, up to a limit of + 63 characters. + required: + - name + registry_create: + type: object + properties: + name: + type: string + maxLength: 63 + pattern: ^[a-z0-9-]{1,63}$ + example: example + description: >- + A globally unique name for the container registry. Must be lowercase + and be composed only of numbers, letters and `-`, up to a limit of + 63 characters. + subscription_tier_slug: + type: string + enum: + - starter + - basic + - professional + example: basic + description: >- + The slug of the subscription tier to sign up for. Valid values can + be retrieved using the options endpoint. + region: + type: string + enum: + - nyc3 + - sfo3 + - ams3 + - sgp1 + - fra1 + example: fra1 + description: >- + Slug of the region where registry data is stored. When not provided, + a region will be selected. + required: + - name + - subscription_tier_slug + repository: + type: object + properties: + registry_name: + type: string + example: example + description: The name of the container registry. + name: + type: string + example: repo-1 + description: The name of the repository. + latest_tag: + $ref: '#/components/schemas/repository_tag' + tag_count: + type: integer + example: 1 + description: The number of tags in the repository. + registry_run_gc: + type: object + properties: + type: + type: string + enum: + - untagged manifests only + - unreferenced blobs only + - untagged manifests and unreferenced blobs + example: unreferenced blobs only + description: Type of the garbage collection to run against this registry + neighbor_ids: + type: object + properties: + neighbor_ids: + type: array + items: + type: array + items: + type: integer + description: >- + An array of arrays. Each array will contain a set of Droplet IDs for + Droplets that share a physical server. + example: + - - 168671828 + - 168663509 + - 168671815 + - - 168671883 + - 168671750 + reserved_ip: + type: object + properties: + ip: + type: string + format: ipv4 + example: 45.55.96.47 + description: >- + The public IP address of the reserved IP. It also serves as its + identifier. + region: + allOf: + - $ref: '#/components/schemas/region' + - type: object + description: >- + The region that the reserved IP is reserved to. When you query a + reserved IP, the entire region object will be returned. + droplet: + description: >- + The Droplet that the reserved IP has been assigned to. When you + query a reserved IP, if it is assigned to a Droplet, the entire + Droplet object will be returned. If it is not assigned, the value + will be null.

Requires `droplet:read` scope. + anyOf: + - title: 'null' + type: object + nullable: true + description: >- + If the reserved IP is not assigned to a Droplet, the value will + be null. + - $ref: '#/components/schemas/droplet' + example: null + locked: + type: boolean + example: true + description: >- + A boolean value indicating whether or not the reserved IP has + pending actions preventing new ones from being submitted. + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the reserved IP currently + belongs.

Requires `project:read` scope. + reserved_ip_create: + oneOf: + - title: Assign to Droplet + type: object + properties: + droplet_id: + type: integer + example: 2457247 + description: The ID of the Droplet that the reserved IP will be assigned to. + required: + - droplet_id + - title: Reserve to Region + type: object + properties: + region: + type: string + example: nyc3 + description: >- + The slug identifier for the region the reserved IP will be + reserved to. + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the reserved IP will be + assigned. + required: + - region + reserved_ip_action_type: + type: object + required: + - type + properties: + type: + type: string + enum: + - assign + - unassign + description: The type of action to initiate for the reserved IP. + discriminator: + propertyName: type + mapping: + assign: '#/components/schemas/reserved_ip_action_assign' + unassign: '#/components/schemas/reserved_ip_action_unassign' + reserved_ip_action_assign: + allOf: + - $ref: '#/components/schemas/reserved_ip_action_type' + - type: object + required: + - type + - droplet_id + properties: + droplet_id: + type: integer + example: 758604968 + description: The ID of the Droplet that the reserved IP will be assigned to. + reserved_ip_action_unassign: + allOf: + - $ref: '#/components/schemas/reserved_ip_action_type' + - type: object + required: + - type + reserved_ipv6_list: + type: object + properties: + reserved_ipv6s: + type: array + items: + properties: + ip: + type: string + format: ipv6 + example: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + description: >- + The public IP address of the reserved IPv6. It also serves as + its identifier. + region_slug: + type: string + description: >- + The region that the reserved IPv6 is reserved to. When you + query a reserved IPv6,the region_slug will be returned. + example: nyc3 + reserved_at: + type: string + format: date-time + example: '2020-01-01T00:00:00Z' + droplet: + description: Requires `droplet:read` scope. + anyOf: + - title: 'null' + type: object + nullable: true + description: >- + If the reserved IP is not assigned to a Droplet, the value + will be null.

Requires `droplet:read` scope. + - $ref: '#/components/schemas/droplet' + example: null + reserved_ipv6_create: + title: Reserve to Region + type: object + properties: + region_slug: + type: string + example: nyc3 + description: >- + The slug identifier for the region the reserved IPv6 will be + reserved to. + required: + - region_slug + reserved_ipv6: + type: object + properties: + ip: + type: string + format: ipv6 + example: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + description: >- + The public IP address of the reserved IPv6. It also serves as its + identifier. + reserved_at: + type: string + format: date-time + example: '2024-11-20T11:08:30Z' + description: The date and time when the reserved IPv6 was reserved. + region_slug: + type: string + description: >- + The region that the reserved IPv6 is reserved to. When you query a + reserved IPv6,the region_slug will be returned. + example: nyc3 + droplet: + anyOf: + - title: 'null' + type: object + nullable: true + description: >- + If the reserved IP is not assigned to a Droplet, the value will + be null.

Requires `droplet:read` scope. + - $ref: '#/components/schemas/droplet' + example: null + reserved_ipv6_action_type: + type: object + required: + - type + properties: + type: + type: string + enum: + - assign + - unassign + description: The type of action to initiate for the reserved IPv6. + discriminator: + propertyName: type + mapping: + assign: '#/components/schemas/reserved_ipv6_action_assign' + unassign: '#/components/schemas/reserved_ipv6_action_unassign' + reserved_ipv6_action_assign: + allOf: + - $ref: '#/components/schemas/reserved_ipv6_action_type' + - type: object + required: + - type + - droplet_id + properties: + droplet_id: + type: integer + example: 758604968 + description: >- + The ID of the Droplet that the reserved IPv6 will be assigned + to. + reserved_ipv6_action_unassign: + allOf: + - $ref: '#/components/schemas/reserved_ipv6_action_type' + - type: object + required: + - type + byoip_prefix: + type: object + properties: + uuid: + type: string + description: Unique identifier for the BYOIP prefix + example: f47ac10b-58cc-4372-a567-0e02b2c3d479 + name: + type: string + description: Name of the BYOIP prefix + example: '' + prefix: + type: string + description: The IP prefix in CIDR notation + example: 203.0.113.0/24 + status: + type: string + description: Status of the BYOIP prefix + example: active + region: + type: string + description: Region where the BYOIP prefix is located + example: nyc3 + validations: + type: array + description: List of validation statuses for the BYOIP prefix + items: + type: object + properties: + name: + type: string + description: Name of the validation + example: SIGNATURE HASH + status: + type: string + description: Status of the validation + example: FAILED + note: + type: string + description: Additional notes or details about the validation + example: '' + failure_reason: + type: string + description: Reason for failure, if applicable + example: '' + locked: + type: boolean + description: Whether the BYOIP prefix is locked + example: false + advertised: + type: boolean + description: Whether the BYOIP prefix is being advertised + example: true + project_id: + type: string + description: The ID of the project associated with the BYOIP prefix + example: 12345678-1234-1234-1234-123456789012 + byoip_prefix_create: + type: object + properties: + prefix: + type: string + description: The IP prefix in CIDR notation to bring + example: 203.11.13.0/24 + region: + type: string + description: The region where the prefix will be created + example: nyc3 + signature: + type: string + description: The signature hash for the prefix creation request + example: + required: + - prefix + - region + - signature + byoip_prefix_update: + type: object + properties: + advertise: + type: boolean + description: Whether the BYOIP prefix should be advertised + example: true + byoip_prefix_resource: + type: object + properties: + id: + type: integer + format: int64 + description: Unique identifier for the allocation + example: 10001 + byoip: + type: string + description: The BYOIP prefix UUID + example: f47ac10b-58cc-4372-a567-0e02b2c3d479 + region: + type: string + description: Region where the allocation is made + example: nyc3 + resource: + type: string + description: The resource associated with the allocation + example: do:droplet:fa3c10b-58cc-4372-a567-0e02b2c3d479 + assigned_at: + type: string + format: date-time + description: Time when the allocation was assigned + example: '2025-06-25T12:00:00Z' + scan: + type: object + properties: + id: + title: id + type: string + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: The unique identifier for the scan. + status: + title: status + type: string + enum: + - IN_PROGRESS + - COMPLETED + - FAILED + - CSPM_NOT_ENABLED + - SCAN_NOT_RUN + example: COMPLETED + description: The status of the scan. + created_at: + title: created_at + type: string + format: date-time + example: '2025-12-04T00:00:00Z' + description: When scan was created. + findings: + title: findings + type: array + items: + type: object + description: The results of the scan. + properties: + rule_uuid: + title: rule_uuid + type: string + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: The unique identifier for the rule that triggered the finding. + name: + title: name + type: string + example: All Firewall Ports Exposed to a Source + description: The name of the rule that triggered the finding. + details: + title: details + type: string + example: >- + The Cloud Firewall protecting this Droplet includes a rule + that allows traffic on all + + ports for one or more protocols. Even if sources are + restricted, this overly + + permissive configuration can expose sensitive internal or + administrative services. + description: A description of the risk associated with the finding. + found_at: + title: found_at + type: string + format: date-time + example: '2025-12-04T00:00:00Z' + description: When the finding was discovered. + severity: + title: severity + type: string + enum: + - CRITICAL + - HIGH + - MEDIUM + - LOW + example: CRITICAL + description: The severity of the finding. + business_impact: + title: business_impact + type: string + example: >- + Without at least one completed backup, any critical event such + as hardware failure, + + ransomware, or accidental deletion could result in permanent + data loss. This can lead + + to downtime, expensive recovery efforts, and loss of customer + trust. Until a backup + + successfully completes, your environment remains unprotected. + description: A description of the business impact of the finding. + technical_details: + title: technical_details + type: string + example: >- + DigitalOcean's backup service automatically runs on a weekly + schedule. This condition + + can occur for two main reasons:\n- The Droplet is newly + created and its first scheduled + + backup window hasn't run yet, or\n- A previous backup attempt + failed. In both cases, + + no backup image currently exists in your account, leaving the + Droplet without a + + restorable recovery point managed by the platform. + description: A description of the technical details related to the finding. + mitigation_steps: + title: mitigation_steps + type: array + items: + type: object + properties: + step: + title: step + type: integer + example: 1 + title: + title: title + type: string + example: Enable backups + description: + title: description + type: string + example: Turn on automated backups for this Droplet. + description: The mitigation steps to resolve the finding. + affected_resources_count: + title: affected_resources_count + type: integer + example: 12 + description: The number of affected resources for the finding. + affected_resource: + type: object + properties: + urn: + title: urn + type: string + example: do:droplet:760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: The URN for the affected resource. + name: + title: name + type: string + example: Test Droplet + description: The name of the affected resource. + type: + title: type + type: string + example: Droplet + description: The type of the affected resource. + suppressed_resource: + type: object + properties: + id: + title: id + type: string + example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + description: Unique identifier for the suppressed resource. + rule_uuid: + title: rule_uuid + type: string + example: 460e09ef-dc84-11e8-981e-3cfdfeaae000 + description: Unique identifier for the suppressed rule. + rule_name: + title: rule_name + type: string + example: Droplet Backups Not Enabled + description: Human-readable rule name for the suppressed rule. + resource_id: + title: resource_id + type: string + example: '123' + description: Unique identifier for the resource suppressed. + resource_type: + title: resource_type + type: string + example: Droplet + description: Resource type for the resource suppressed. + suppressed_resource_root: + type: object + properties: + resources: + type: array + items: + $ref: '#/components/schemas/suppressed_resource' + meta: + type: object + properties: + page: + type: integer + example: 1 + pages: + type: integer + example: 3 + total: + type: integer + example: 25 + links: + type: object + properties: + pages: + type: object + properties: + first: + type: string + example: >- + https://api.digitalocean.com/v2/security/settings/suppressions?page=1 + prev: + type: string + example: >- + https://api.digitalocean.com/v2/security/settings/suppressions?page=1 + next: + type: string + example: >- + https://api.digitalocean.com/v2/security/settings/suppressions?page=2 + last: + type: string + example: >- + https://api.digitalocean.com/v2/security/settings/suppressions?page=3 + plan_downgrades: + type: object + description: Resources moving to a tier at a given effective time. + properties: + resources: + type: array + items: + type: string + description: URNs of resources that will be downgraded. + example: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + effective_at: + type: string + format: date-time + description: When the coverage downgrade takes effect. + example: '2025-12-01T00:00:00Z' + settings: + type: object + properties: + settings: + type: object + properties: + suppressions: + $ref: '#/components/schemas/suppressed_resource_root' + tier_coverage: + type: object + additionalProperties: + type: object + properties: + resources: + type: array + items: + type: string + example: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + tags: + type: array + items: + type: string + example: + - production + plan_downgrades: + type: object + additionalProperties: + $ref: '#/components/schemas/plan_downgrades' + snapshots: + allOf: + - type: object + properties: + id: + type: string + example: '6372321' + description: The unique identifier for the snapshot. + required: + - id + - $ref: '#/components/schemas/snapshots_base' + - type: object + properties: + resource_id: + type: string + example: '200776916' + description: >- + The unique identifier for the resource that the snapshot + originated from. + resource_type: + type: string + enum: + - droplet + - volume + example: droplet + description: The type of resource that the snapshot originated from. + tags: + description: >- + An array of Tags the snapshot has been tagged + with.

Requires `tag:read` scope. + type: array + items: + type: string + nullable: true + example: + - web + - env:prod + required: + - resource_id + - resource_type + - tags + grant: + type: object + properties: + bucket: + type: string + description: The name of the bucket. + example: my-bucket + permission: + type: string + description: >- + The permission to grant to the user. Possible values are `read`, + `readwrite`, `fullaccess`, or an empty string. + example: read + required: + - bucket + - permission + key: + type: object + properties: + name: + type: string + description: The access key's name. + example: my-access-key + grants: + type: array + description: The list of permissions for the access key. + items: + $ref: '#/components/schemas/grant' + default: [] + access_key: + type: string + description: The Access Key ID used to access a bucket. + example: DOACCESSKEYEXAMPLE + readOnly: true + created_at: + type: string + format: date-time + description: The date and time the key was created. + example: '2018-07-19T15:04:16Z' + readOnly: true + key_create_response: + allOf: + - type: object + properties: + secret_key: + type: string + description: >- + The secret key used to access the bucket. We return secret keys + only once upon creation. Make sure to copy the key and securely + store it. + example: DOSECRETKEYEXAMPLE + readOnly: true + - $ref: '#/components/schemas/key' + tags_metadata: + type: object + description: >- + Tagged Resource Statistics include metadata regarding the resource type + that has been tagged. + properties: + count: + type: integer + description: The number of tagged objects for this type of resource. + example: 5 + minimum: 0 + last_tagged_uri: + type: string + description: The URI for the last tagged object for this type of resource. + example: https://api.digitalocean.com/v2/images/7555620 + tags: + type: object + description: >- + A tag is a label that can be applied to a resource (currently Droplets, + Images, Volumes, Volume Snapshots, and Database clusters) in order to + better organize or facilitate the lookups and actions on it. + + Tags have two attributes: a user defined `name` attribute and an + embedded `resources` attribute with information about resources that + have been tagged. + properties: + name: + type: string + description: > + The name of the tag. Tags may contain letters, numbers, colons, + dashes, and underscores. + + There is a limit of 255 characters per tag. + + + **Note:** Tag names are case stable, which means the capitalization + you use when you first create a tag is canonical. + + + When working with tags in the API, you must use the tag's canonical + capitalization. For example, if you create a tag named "PROD", the + URL to add that tag to a resource would be + `https://api.digitalocean.com/v2/tags/PROD/resources` (not + `/v2/tags/prod/resources`). + + + Tagged resources in the control panel will always display the + canonical capitalization. For example, if you create a tag named + "PROD", you can tag resources in the control panel by entering + "prod". The tag will still display with its canonical + capitalization, "PROD". + pattern: ^[a-zA-Z0-9_\-\:]+$ + maxLength: 255 + example: extra-awesome + resources: + type: object + description: > + An embedded object containing key value pairs of resource type and + resource statistics. + + It also includes a count of the total number of resources tagged + with the current tag as well as a `last_tagged_uri` attribute set to + the last resource tagged with the current tag. + + + This will only include resources that you are authorized to see. For + example, to see tagged Droplets, include the `droplet:read` scope. + readOnly: true + allOf: + - $ref: '#/components/schemas/tags_metadata' + - properties: + droplets: + allOf: + - description: >- + Droplets that are tagged with the specified + tag.
Requires `droplet:read` scope. + - $ref: '#/components/schemas/tags_metadata' + imgages: + allOf: + - description: >- + Images that are tagged with the specified + tag.
Requires `image:read` scope. + - $ref: '#/components/schemas/tags_metadata' + volumes: + allOf: + - description: >- + Volumes that are tagged with the specified + tag.
Requires `block_storage:read` scope. + - $ref: '#/components/schemas/tags_metadata' + volume_snapshots: + allOf: + - description: >- + Volume Snapshots that are tagged with the specified + tag.
Requires `block_storage_snapshot:read` scope. + - $ref: '#/components/schemas/tags_metadata' + databases: + allOf: + - description: >- + Databases that are tagged with the specified + tag.
Requires `database:read` scope. + - $ref: '#/components/schemas/tags_metadata' + example: + count: 5 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + droplets: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/droplets/3164444 + images: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + volumes: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/volumes/3d80cb72-342b-4aaa-b92e-4e4abb24a933 + volume_snapshots: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/snapshots/1f6f46e8-6b60-11e9-be4e-0a58ac144519 + databases: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/databases/b92438f6-ba03-416c-b642-e9236db91976 + error_with_root_causes: + type: object + properties: + error: + description: A message providing information about the error. + type: string + example: not_found + messages: + description: A list of error messages. + type: array + items: + type: string + nullable: true + example: null + root_causes: + description: >- + A list of underlying causes for the error, including details to + help resolve it when possible. + type: array + items: + type: string + example: [] + required: + - error + - root_causes + tags_resource: + type: object + properties: + resources: + description: > + An array of objects containing resource_id and resource_type + + attributes. + + + This response will only include resources that you are authorized to + see. + + For example, to see Droplets, include the `droplet:read` scope. + type: array + items: + properties: + resource_id: + type: string + description: The identifier of a resource. + example: 3d80cb72-342b-4aaa-b92e-4e4abb24a933 + resource_type: + type: string + description: The type of the resource. + example: volume + enum: + - droplet + - image + - volume + - volume_snapshot + example: + - resource_id: '9569411' + resource_type: droplet + - resource_id: '7555620' + resource_type: image + - resource_id: 3d80cb72-342b-4aaa-b92e-4e4abb24a933 + resource_type: volume + required: + - resources + tags_array_read: + type: array + items: + type: string + nullable: true + description: >- + A flat array of tag names as strings applied to the resource. +

Requires `tag:read` scope. + example: + - base-image + - prod + volume_base_read: + type: object + properties: + id: + type: string + description: The unique identifier for the block storage volume. + example: 506f78a4-e098-11e5-ad9f-000f53306ae1 + readOnly: true + droplet_ids: + type: array + items: + type: integer + nullable: true + description: >- + An array containing the IDs of the Droplets the volume is attached + to. Note that at this time, a volume can only be attached to a + single Droplet. + example: [] + readOnly: true + name: + type: string + description: >- + A human-readable name for the block storage volume. Must be + lowercase and be composed only of numbers, letters and "-", up to a + limit of 64 characters. The name must begin with a letter. + example: example + description: + type: string + description: An optional free-form text field to describe a block storage volume. + example: Block store for examples + size_gigabytes: + type: integer + description: >- + The size of the block storage volume in GiB (1024^3). This field + does not apply when creating a volume from a snapshot. + example: 10 + created_at: + type: string + description: >- + A time value given in ISO8601 combined date and time format that + represents when the block storage volume was created. + example: '2020-03-02T17:00:49Z' + readOnly: true + tags: + $ref: '#/components/schemas/tags_array_read' + volume_full: + type: object + allOf: + - $ref: '#/components/schemas/volume_base_read' + - properties: + region: + allOf: + - description: >- + The region that the block storage volume is located in. When + setting a region, the value should be the slug identifier + for the region. When you query a block storage volume, the + entire region object will be returned. + - $ref: '#/components/schemas/region' + example: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + readOnly: true + filesystem_type: + type: string + description: The type of filesystem currently in-use on the volume. + example: ext4 + filesystem_label: + type: string + description: The label currently applied to the filesystem. + example: example + volume_base: + type: object + properties: + id: + type: string + description: The unique identifier for the block storage volume. + example: 506f78a4-e098-11e5-ad9f-000f53306ae1 + readOnly: true + droplet_ids: + type: array + items: + type: integer + nullable: true + description: >- + An array containing the IDs of the Droplets the volume is attached + to. Note that at this time, a volume can only be attached to a + single Droplet. + example: [] + readOnly: true + name: + type: string + description: >- + A human-readable name for the block storage volume. Must be + lowercase and be composed only of numbers, letters and "-", up to a + limit of 64 characters. The name must begin with a letter. + example: example + description: + type: string + description: An optional free-form text field to describe a block storage volume. + example: Block store for examples + size_gigabytes: + type: integer + description: >- + The size of the block storage volume in GiB (1024^3). This field + does not apply when creating a volume from a snapshot. + example: 10 + created_at: + type: string + description: >- + A time value given in ISO8601 combined date and time format that + represents when the block storage volume was created. + example: '2020-03-02T17:00:49Z' + readOnly: true + tags: + $ref: '#/components/schemas/tags_array' + volume_snapshot_id: + properties: + snapshot_id: + type: string + description: >- + The unique identifier for the volume snapshot from which to create + the volume. + example: b0798135-fb76-11eb-946a-0a58ac146f33 + volume_write_file_system_type: + type: object + properties: + filesystem_type: + type: string + description: >- + The name of the filesystem type to be used on the volume. When + provided, the volume will automatically be formatted to the + specified filesystem type. Currently, the available options are + `ext4` and `xfs`. 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 other Droplets is not recommended. + example: ext4 + volume_write_file_system_label: + type: string + description: >- + The label applied to the filesystem. Labels for ext4 type filesystems + may contain 16 characters while labels for xfs type filesystems are + limited to 12 characters. May only be used in conjunction with + filesystem_type. + example: example + volumes_ext4: + type: object + allOf: + - $ref: '#/components/schemas/volume_base' + - $ref: '#/components/schemas/volume_snapshot_id' + - $ref: '#/components/schemas/volume_write_file_system_type' + - properties: + region: + $ref: '#/components/schemas/region_slug' + filesystem_label: + allOf: + - $ref: '#/components/schemas/volume_write_file_system_label' + - maxLength: 16 + required: + - name + - size_gigabytes + - region + volumes_xfs: + type: object + allOf: + - $ref: '#/components/schemas/volume_base' + - $ref: '#/components/schemas/volume_snapshot_id' + - $ref: '#/components/schemas/volume_write_file_system_type' + - properties: + region: + $ref: '#/components/schemas/region_slug' + filesystem_label: + allOf: + - $ref: '#/components/schemas/volume_write_file_system_label' + - maxLength: 12 + required: + - name + - size_gigabytes + - region + volume_action_post_base: + type: object + properties: + type: + type: string + description: The volume action to initiate. + enum: + - attach + - detach + - resize + example: attach + region: + $ref: '#/components/schemas/region_slug' + required: + - type + volume_action_droplet_id: + type: integer + description: >- + The unique identifier for the Droplet the volume will be attached or + detached from. + example: 11612190 + volume_action_post_attach: + type: object + allOf: + - $ref: '#/components/schemas/volume_action_post_base' + - properties: + droplet_id: + $ref: '#/components/schemas/volume_action_droplet_id' + tags: + $ref: '#/components/schemas/tags_array' + required: + - droplet_id + volume_action_post_detach: + type: object + allOf: + - $ref: '#/components/schemas/volume_action_post_base' + - properties: + droplet_id: + $ref: '#/components/schemas/volume_action_droplet_id' + required: + - droplet_id + volumeAction: + type: object + allOf: + - properties: + type: + type: string + description: >- + This is the type of action that the object represents. For + example, this could be "attach_volume" to represent the state of + a volume attach action. + example: attach_volume + resource_id: + type: integer + nullable: true + example: null + - $ref: '#/components/schemas/action' + volume_action_post_resize: + type: object + allOf: + - $ref: '#/components/schemas/volume_action_post_base' + - properties: + size_gigabytes: + type: integer + description: The new size of the block storage volume in GiB (1024^3). + maximum: 16384 + required: + - size_gigabytes + vpc_updatable: + type: object + properties: + name: + type: string + pattern: ^[a-zA-Z0-9\-\.]+$ + example: env.prod-vpc + description: >- + The name of the VPC. Must be unique and may only contain + alphanumeric characters, dashes, and periods. + description: + type: string + maxLength: 255 + example: VPC for production environment + description: >- + A free-form text field for describing the VPC's purpose. It may be a + maximum of 255 characters. + vpc_create: + type: object + properties: + region: + type: string + example: nyc1 + description: The slug identifier for the region where the VPC will be created. + ip_range: + type: string + example: 10.10.10.0/24 + description: >- + The range of IP addresses in the VPC in CIDR notation. Network + ranges cannot overlap with other networks in the same account and + must be in range of private addresses as defined in RFC1918. It may + not be smaller than `/28` nor larger than `/16`. If no IP range is + specified, a `/20` network range is generated that won't conflict + with other VPC networks in your account. + vpc_default: + type: object + properties: + default: + type: boolean + example: true + description: >- + A boolean value indicating whether or not the VPC is the default + network for the region. All applicable resources are placed into the + default VPC network unless otherwise specified during their + creation. The `default` field cannot be unset from `true`. If you + want to set a new default VPC network, update the `default` field of + another VPC network in the same region. The previous network's + `default` field will be set to `false` when a new default VPC has + been defined. + urn-2: + type: string + pattern: >- + ^do:(dbaas|domain|droplet|floatingip|loadbalancer|space|volume|kubernetes|vpc):.* + example: do:vpc:5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: >- + The uniform resource name (URN) for the resource in the format + do:resource_type:resource_id. + vpc_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: A unique ID that can be used to identify and reference the VPC. + urn: + $ref: '#/components/schemas/urn-2' + created_at: + type: string + format: date-time + readOnly: true + example: '2020-03-13T19:20:47.442049222Z' + description: A time value given in ISO8601 combined date and time format. + vpc: + type: object + allOf: + - $ref: '#/components/schemas/vpc_updatable' + - $ref: '#/components/schemas/vpc_create' + - $ref: '#/components/schemas/vpc_default' + - $ref: '#/components/schemas/vpc_base' + vpc_member: + type: object + properties: + name: + type: string + example: nyc1-load-balancer-01 + description: The name of the resource. + urn: + $ref: '#/components/schemas/urn' + created_at: + type: string + example: '2020-03-13T19:30:48Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the resource was created. + vpc_peering_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: >- + A unique ID that can be used to identify and reference the VPC + peering. + created_at: + type: string + format: date-time + readOnly: true + example: '2020-03-13T19:20:47.442049222Z' + description: A time value given in ISO8601 combined date and time format. + status: + type: string + enum: + - PROVISIONING + - ACTIVE + - DELETING + readOnly: true + example: ACTIVE + description: The current status of the VPC peering. + vpc_peering_create: + type: object + properties: + vpc_ids: + type: array + items: + type: string + format: uuid + minItems: 2 + maxItems: 2 + example: + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + - 994a2735-dc84-11e8-80bc-3cfdfea9fba1 + description: An array of the two peered VPCs IDs. + vpc_peering_updatable: + type: object + properties: + name: + type: string + pattern: ^[a-zA-Z0-9\-]+$ + example: nyc1-blr1-peering + description: >- + The name of the VPC peering. Must be unique within the team and may + only contain alphanumeric characters and dashes. + vpc_peering: + type: object + allOf: + - $ref: '#/components/schemas/vpc_peering_base' + - $ref: '#/components/schemas/vpc_peering_create' + - $ref: '#/components/schemas/vpc_peering_updatable' + vpc_nat_gateway_get: + type: object + properties: + id: + type: string + example: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + description: >- + The unique identifier for the VPC NAT gateway. This is automatically + generated upon creation. + name: + type: string + example: my-vpc-nat-gateway + description: The human-readable name of the VPC NAT gateway. + type: + type: string + enum: + - PUBLIC + example: PUBLIC + description: The type of the VPC NAT gateway. + state: + type: string + enum: + - NEW + - PROVISIONING + - ACTIVE + - DELETING + - ERROR + - INVALID + description: The current state of the VPC NAT gateway. + example: ACTIVE + region: + type: string + enum: + - nyc1 + - nyc2 + - nyc3 + - ams2 + - ams3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - lon1 + - fra1 + - tor1 + - blr1 + - syd1 + - atl1 + example: tor1 + description: The region in which the VPC NAT gateway is created. + size: + type: integer + example: 1 + description: The size of the VPC NAT gateway. + vpcs: + type: array + items: + type: object + properties: + vpc_uuid: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + description: >- + The unique identifier of the VPC to which the NAT gateway is + attached. + gateway_ip: + type: string + example: 10.118.0.35 + description: The gateway IP address of the VPC NAT gateway. + description: An array of VPCs associated with the VPC NAT gateway. + egresses: + type: object + properties: + public_gateways: + type: array + description: An array of public gateway IP addresses for the VPC NAT gateway. + items: + type: object + properties: + ipv4: + type: string + example: 174.138.113.197 + description: IPv4 address of the public gateway. + description: An object containing egress information for the VPC NAT gateway. + udp_timeout_seconds: + type: integer + example: 30 + description: The UDP timeout in seconds for the VPC NAT gateway. + icmp_timeout_seconds: + type: integer + example: 30 + description: The ICMP timeout in seconds for the VPC NAT gateway. + tcp_timeout_seconds: + type: integer + example: 30 + description: The TCP timeout in seconds for the VPC NAT gateway. + created_at: + format: date-time + title: The creation time of the VPC NAT gateway. + type: string + example: '2020-07-28T18:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the VPC NAT gateway was created. + updated_at: + format: date-time + title: The last update time of the VPC NAT gateway. + type: string + example: '2020-07-28T18:00:00Z' + description: >- + A time value given in ISO8601 combined date and time format that + represents when the VPC NAT gateway was last updated. + vpc_nat_gateway_create: + type: object + properties: + name: + type: string + example: my-vpc-nat-gateway + description: The human-readable name of the VPC NAT gateway. + type: + type: string + enum: + - PUBLIC + example: PUBLIC + description: The type of the VPC NAT gateway. + region: + type: string + enum: + - nyc1 + - nyc2 + - nyc3 + - ams2 + - ams3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - lon1 + - fra1 + - tor1 + - blr1 + - syd1 + - atl1 + example: tor1 + description: The region in which the VPC NAT gateway is created. + size: + type: integer + example: 1 + description: The size of the VPC NAT gateway. + vpcs: + type: array + items: + type: object + properties: + vpc_uuid: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + description: >- + The unique identifier of the VPC to which the NAT gateway is + attached. + default_gateway: + type: boolean + example: true + description: >- + The classification of the NAT gateway as the default egress + route for the VPC traffic. + required: + - vpc_uuid + description: An array of VPCs associated with the VPC NAT gateway. + udp_timeout_seconds: + type: integer + example: 30 + description: The UDP timeout in seconds for the VPC NAT gateway. + icmp_timeout_seconds: + type: integer + example: 30 + description: The ICMP timeout in seconds for the VPC NAT gateway. + tcp_timeout_seconds: + type: integer + example: 30 + description: The TCP timeout in seconds for the VPC NAT gateway. + required: + - name + - type + - region + - size + - vpcs + vpc_nat_gateway_update: + type: object + properties: + name: + type: string + example: my-vpc-nat-gateway + description: The human-readable name of the VPC NAT gateway. + size: + type: integer + example: 1 + description: The size of the VPC NAT gateway. + vpcs: + type: array + items: + type: object + properties: + vpc_uuid: + type: string + example: 0d3db13e-a604-4944-9827-7ec2642d32ac + description: >- + The unique identifier of the VPC to which the NAT gateway is + attached. + default_gateway: + type: boolean + example: false + description: >- + The classification of the NAT gateway as the default egress + route for the VPC traffic. + description: An array of VPCs associated with the VPC NAT gateway. + udp_timeout_seconds: + type: integer + example: 30 + description: The UDP timeout in seconds for the VPC NAT gateway. + icmp_timeout_seconds: + type: integer + example: 30 + description: The ICMP timeout in seconds for the VPC NAT gateway. + tcp_timeout_seconds: + type: integer + example: 30 + description: The TCP timeout in seconds for the VPC NAT gateway. + required: + - name + - size + check_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: A unique ID that can be used to identify and reference the check. + check_updatable: + type: object + properties: + name: + type: string + example: Landing page check + description: A human-friendly display name. + type: + type: string + example: https + enum: + - ping + - http + - https + description: The type of health check to perform. + target: + type: string + format: url + example: https://www.landingpage.com + description: The endpoint to perform healthchecks on. + regions: + type: array + items: + type: string + enum: + - us_east + - us_west + - eu_west + - se_asia + example: + - us_east + - eu_west + description: >- + An array containing the selected regions to perform healthchecks + from. + enabled: + type: boolean + example: true + default: true + description: A boolean value indicating whether the check is enabled/disabled. + check: + type: object + allOf: + - $ref: '#/components/schemas/check_base' + - $ref: '#/components/schemas/check_updatable' + region_state: + type: object + properties: + status: + type: string + example: UP + enum: + - DOWN + - UP + - CHECKING + status_changed_at: + type: string + example: '2022-03-17T22:28:51Z' + thirty_day_uptime_percentage: + type: number + example: 97.99 + regional_state: + type: object + description: A map of region to regional state + properties: + us_east: + $ref: '#/components/schemas/region_state' + eu_west: + $ref: '#/components/schemas/region_state' + previous_outage: + type: object + properties: + region: + type: string + example: us_east + started_at: + type: string + example: '2022-03-17T18:04:55Z' + ended_at: + type: string + example: '2022-03-17T18:06:55Z' + duration_seconds: + type: integer + example: 120 + state: + type: object + properties: + regions: + $ref: '#/components/schemas/regional_state' + previous_outage: + $ref: '#/components/schemas/previous_outage' + alert_base: + type: object + properties: + id: + type: string + format: uuid + readOnly: true + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + description: A unique ID that can be used to identify and reference the alert. + notification: + type: object + description: The notification settings for a trigger alert. + required: + - slack + - email + properties: + email: + description: >- + An email to notify on an alert trigger. The Email has to be one that + is verified on that DigitalOcean account. + example: + - bob@example.com + type: array + items: + type: string + slack: + type: array + description: Slack integration details. + items: + type: object + required: + - url + - channel + properties: + channel: + type: string + format: string + example: Production Alerts + description: Slack channel to notify of an alert trigger. + url: + type: string + format: string + description: Slack Webhook URL. + example: https://example.invalid/redacted-slack-webhook + alert_updatable: + type: object + properties: + name: + type: string + example: Landing page degraded performance + description: A human-friendly display name. + type: + type: string + example: latency + enum: + - latency + - down + - down_global + - ssl_expiry + description: The type of alert. + threshold: + type: integer + example: 300 + description: >- + The threshold at which the alert will enter a trigger state. The + specific threshold is dependent on the alert type. + comparison: + type: string + example: greater_than + description: The comparison operator used against the alert's threshold. + enum: + - greater_than + - less_than + notifications: + $ref: '#/components/schemas/notification' + period: + type: string + example: 2m + description: Period of time the threshold must be exceeded to trigger the alert. + enum: + - 2m + - 3m + - 5m + - 10m + - 15m + - 30m + - 1h + alert: + type: object + allOf: + - $ref: '#/components/schemas/alert_base' + - $ref: '#/components/schemas/alert_updatable' + apiChatbot: + description: A Chatbot + properties: + allowed_domains: + example: + - example string + items: + example: example string + type: string + type: array + button_background_color: + example: example string + type: string + logo: + example: example string + type: string + name: + description: Name of chatbot + example: example name + type: string + primary_color: + example: example string + type: string + secondary_color: + example: example string + type: string + starting_message: + example: example string + type: string + type: object + apiAgentChatbotIdentifier: + description: Agent Chatbot Identifier + properties: + agent_chatbot_identifier: + description: Agent chatbot identifier + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiDeploymentStatus: + default: STATUS_UNKNOWN + enum: + - STATUS_UNKNOWN + - STATUS_WAITING_FOR_DEPLOYMENT + - STATUS_DEPLOYING + - STATUS_RUNNING + - STATUS_FAILED + - STATUS_WAITING_FOR_UNDEPLOYMENT + - STATUS_UNDEPLOYING + - STATUS_UNDEPLOYMENT_FAILED + - STATUS_DELETED + - STATUS_BUILDING + example: STATUS_UNKNOWN + type: string + apiDeploymentVisibility: + default: VISIBILITY_UNKNOWN + description: |- + - VISIBILITY_UNKNOWN: The status of the deployment is unknown + - VISIBILITY_DISABLED: The deployment is disabled and will no longer service requests + - VISIBILITY_PLAYGROUND: Deprecated: No longer a valid state + - VISIBILITY_PUBLIC: The deployment is public and will service requests from the public internet + - VISIBILITY_PRIVATE: The deployment is private and will only service requests from other agents, or through API keys + enum: + - VISIBILITY_UNKNOWN + - VISIBILITY_DISABLED + - VISIBILITY_PLAYGROUND + - VISIBILITY_PUBLIC + - VISIBILITY_PRIVATE + example: VISIBILITY_UNKNOWN + type: string + apiDeployment: + description: Description of deployment + properties: + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + name: + description: Name + example: example name + type: string + status: + $ref: '#/components/schemas/apiDeploymentStatus' + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + url: + description: Access your deployed agent here + example: example string + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + visibility: + $ref: '#/components/schemas/apiDeploymentVisibility' + type: object + apiMcpServer: + description: McpServer defines a remote MCP server configuration for an agent. + properties: + allowed_tools: + description: Optional list of allowed tool names to expose from this server + example: + - example string + items: + example: example string + type: string + type: array + authorization: + description: Optional authorization header value for the MCP server + example: example string + type: string + headers: + additionalProperties: + example: example string + type: string + description: Optional additional headers to send to the MCP server + type: object + server_label: + description: A label identifying this MCP server + example: example string + type: string + server_url: + description: The URL of the MCP server + example: example string + type: string + type: object + apiAgreement: + description: Agreement Description + properties: + description: + example: example string + type: string + name: + example: example name + type: string + url: + example: example string + type: string + uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiModelEndpoint: + description: An available endpoint for a model and its capabilities + properties: + capabilities: + description: >- + Capabilities supported by this endpoint (e.g. input_text, + output_text, input_image) + example: + - example string + items: + example: example string + type: string + type: array + endpoint: + description: The endpoint path (e.g. /chat/responses) + example: /chat/responses + type: string + type: object + apiModelModalities: + description: Input/output modalities + properties: + input: + example: + - example string + items: + example: example string + type: string + type: array + output: + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiModelProvider: + default: MODEL_PROVIDER_DIGITALOCEAN + enum: + - MODEL_PROVIDER_DIGITALOCEAN + - MODEL_PROVIDER_ANTHROPIC + - MODEL_PROVIDER_OPENAI + example: MODEL_PROVIDER_DIGITALOCEAN + type: string + apiModelSetting: + description: A configurable setting for a model in the playground + properties: + default_string: + description: String default value (for type="dropdown", e.g. "medium") + example: example string + type: string + default_value: + description: Numeric default value (for type="number") + example: 0.7 + format: double + type: number + max: + description: Maximum allowed value (for type="number") + example: 1 + format: double + type: number + min: + description: Minimum allowed value (for type="number") + example: 0 + format: double + type: number + name: + description: Setting key name (e.g. "max_tokens", "temperature", "resolution") + example: temperature + type: string + options: + description: Allowed values for dropdown selections (for type="dropdown") + example: + - example string + items: + example: example string + type: string + type: array + step: + description: Step increment for numeric settings (for type="number") + example: 123 + format: double + type: number + type: + description: 'Setting value type: "number" or "dropdown"' + example: number + type: string + type: object + apiModelUsecase: + default: MODEL_USECASE_UNKNOWN + description: |- + - MODEL_USECASE_UNKNOWN: The use case of the model is unknown + - MODEL_USECASE_AGENT: The model maybe used in an agent + - MODEL_USECASE_FINETUNED: The model maybe used for fine tuning + - MODEL_USECASE_KNOWLEDGEBASE: The model maybe used for knowledge bases (embedding models) + - MODEL_USECASE_GUARDRAIL: The model maybe used for guardrails + - MODEL_USECASE_REASONING: The model usecase for reasoning + - MODEL_USECASE_SERVERLESS: The model usecase for serverless inference + - MODEL_USECASE_EVALUATION_JUDGE: The model usecase for evaluation judge + - MODEL_USECASE_CODING: The model usecase for coding-optimized models + - MODEL_USECASE_AUDIO: The model usecase for audio models + - MODEL_USECASE_RERANKING: The model usecase for knowledge base reranking (cross-encoder) models + - MODEL_USECASE_TEXT: The model usecase for text modality (non image, non audio, non embedding, non reranking) serverless chat models + enum: + - MODEL_USECASE_UNKNOWN + - MODEL_USECASE_AGENT + - MODEL_USECASE_FINETUNED + - MODEL_USECASE_KNOWLEDGEBASE + - MODEL_USECASE_GUARDRAIL + - MODEL_USECASE_REASONING + - MODEL_USECASE_SERVERLESS + - MODEL_USECASE_EVALUATION_JUDGE + - MODEL_USECASE_CODING + - MODEL_USECASE_AUDIO + - MODEL_USECASE_RERANKING + - MODEL_USECASE_TEXT + example: MODEL_USECASE_UNKNOWN + type: string + apiModelVersion: + description: Version Information about a Model + properties: + major: + description: Major version number + example: 123 + format: int64 + type: integer + minor: + description: Minor version number + example: 123 + format: int64 + type: integer + patch: + description: Patch version number + example: 123 + format: int64 + type: integer + type: object + apiModel: + description: Description of a Model + properties: + agreement: + $ref: '#/components/schemas/apiAgreement' + benchmark_score: + description: Benchmark scores for this model, stored as arbitrary JSON + type: object + capabilities: + description: High-level capabilities (e.g. tool_calling, vision, streaming) + example: + - example string + items: + example: example string + type: string + type: array + context_window: + description: Context window size in tokens + example: '12345' + format: int64 + type: string + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + endpoints: + description: Available endpoints and their capabilities + items: + $ref: '#/components/schemas/apiModelEndpoint' + type: array + inference_name: + description: Internally used name + example: example name + type: string + inference_version: + description: Internally used version + example: example string + type: string + is_foundational: + description: True if it is a foundational model provided by do + example: true + type: boolean + kb_default_chunk_size: + description: Default chunking size limit to show in UI + example: 123 + format: int64 + type: integer + kb_max_chunk_size: + description: Maximum chunk size limit of model + example: 123 + format: int64 + type: integer + kb_min_chunk_size: + description: >- + Minimum chunking size token limits if model supports KNOWLEDGEBASE + usecase + example: 123 + format: int64 + type: integer + lifecycle_status: + description: >- + Lifecycle status of the model (internal, public-preview, active, + deprecated, end_of_life) + example: example string + type: string + metadata: + description: Additional meta data + type: object + modalities: + $ref: '#/components/schemas/apiModelModalities' + name: + description: Name of the model + example: example name + type: string + parameter_count: + description: Parameter count in billions + example: 123 + format: float + type: number + parent_uuid: + description: Unique id of the model, this model is based on + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + provider: + $ref: '#/components/schemas/apiModelProvider' + reasoning_efforts: + description: Available reasoning efforts for this model + example: + - example string + items: + example: example string + type: string + type: array + settings: + description: Playground settings derived from model metadata + items: + $ref: '#/components/schemas/apiModelSetting' + type: array + thinking: + description: Whether this model supports extended thinking (Anthropic models) + example: true + type: boolean + type: + description: Model type (chat, embedding, image, reasoning, coding) + example: example string + type: string + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + upload_complete: + description: Model has been fully uploaded + example: true + type: boolean + url: + description: Download url + example: example string + type: string + usecases: + description: Usecases of the model + example: + - MODEL_USECASE_AGENT + - MODEL_USECASE_GUARDRAIL + items: + $ref: '#/components/schemas/apiModelUsecase' + type: array + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + version: + $ref: '#/components/schemas/apiModelVersion' + type: object + apiModelRouterTaskDetails: + description: Task definition embedded in a model router config. + properties: + description: + description: Short task description + example: '"Summarize long-form text"' + type: string + name: + description: Task name + example: '"Custom Summarization"' + type: string + type: object + apiModelRouterSelectionPolicy: + description: Selection policy preference for choosing among assigned models. + properties: + prefer: + description: 'One of: none, cheapest, fastest' + example: '"cheapest"' + type: string + type: object + apiModelRouterTaskPolicy: + description: Model router policy + properties: + custom_task: + $ref: '#/components/schemas/apiModelRouterTaskDetails' + models: + description: Models assigned to the task + example: + - example string + items: + example: example string + type: string + type: array + selection_policy: + $ref: '#/components/schemas/apiModelRouterSelectionPolicy' + task_slug: + description: Task slug + example: '"summarization"' + type: string + type: object + apiModelRouterConfig: + properties: + fallback_models: + description: Router-level fallback models + example: + - example string + items: + example: example string + type: string + type: array + policies: + description: Task routing policies + items: + $ref: '#/components/schemas/apiModelRouterTaskPolicy' + type: array + type: object + apiModelRouter: + description: Model router + properties: + config: + $ref: '#/components/schemas/apiModelRouterConfig' + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + description: + description: Description + example: example string + type: string + name: + description: Name of the model router + example: example name + type: string + regions: + description: Target regions for the router + example: + - example string + items: + example: example string + type: string + type: array + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiRetrievalMethod: + default: RETRIEVAL_METHOD_UNKNOWN + description: |- + - RETRIEVAL_METHOD_UNKNOWN: The retrieval method is unknown + - RETRIEVAL_METHOD_REWRITE: The retrieval method is rewrite + - RETRIEVAL_METHOD_STEP_BACK: The retrieval method is step back + - RETRIEVAL_METHOD_SUB_QUERIES: The retrieval method is sub queries + - RETRIEVAL_METHOD_NONE: The retrieval method is none + enum: + - RETRIEVAL_METHOD_UNKNOWN + - RETRIEVAL_METHOD_REWRITE + - RETRIEVAL_METHOD_STEP_BACK + - RETRIEVAL_METHOD_SUB_QUERIES + - RETRIEVAL_METHOD_NONE + example: RETRIEVAL_METHOD_UNKNOWN + type: string + apiAgentTemplateGuardrail: + properties: + priority: + description: Priority of the guardrail + example: 123 + format: int32 + type: integer + uuid: + description: Uuid of the guardrail + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiIndexedDataSourceStatus: + default: DATA_SOURCE_STATUS_UNKNOWN + enum: + - DATA_SOURCE_STATUS_UNKNOWN + - DATA_SOURCE_STATUS_IN_PROGRESS + - DATA_SOURCE_STATUS_UPDATED + - DATA_SOURCE_STATUS_PARTIALLY_UPDATED + - DATA_SOURCE_STATUS_NOT_UPDATED + - DATA_SOURCE_STATUS_FAILED + - DATA_SOURCE_STATUS_CANCELLED + example: DATA_SOURCE_STATUS_UNKNOWN + type: string + apiIndexedDataSource: + properties: + completed_at: + description: Timestamp when data source completed indexing + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + data_source_uuid: + description: Uuid of the indexed data source + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + error_details: + description: A detailed error description + example: example string + type: string + error_msg: + description: >- + A string code provinding a hint which part of the system experienced + an error + example: example string + type: string + failed_item_count: + description: Total count of files that have failed + example: '12345' + format: uint64 + type: string + indexed_file_count: + description: Total count of files that have been indexed + example: '12345' + format: uint64 + type: string + indexed_item_count: + description: Total count of files that have been indexed + example: '12345' + format: uint64 + type: string + removed_item_count: + description: Total count of files that have been removed + example: '12345' + format: uint64 + type: string + skipped_item_count: + description: Total count of files that have been skipped + example: '12345' + format: uint64 + type: string + started_at: + description: Timestamp when data source started indexing + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + status: + $ref: '#/components/schemas/apiIndexedDataSourceStatus' + total_bytes: + description: Total size of files in data source in bytes + example: '12345' + format: uint64 + type: string + total_bytes_indexed: + description: Total size of files in data source in bytes that have been indexed + example: '12345' + format: uint64 + type: string + total_file_count: + description: Total file count in the data source + example: '12345' + format: uint64 + type: string + type: object + apiBatchJobPhase: + default: BATCH_JOB_PHASE_UNKNOWN + enum: + - BATCH_JOB_PHASE_UNKNOWN + - BATCH_JOB_PHASE_PENDING + - BATCH_JOB_PHASE_RUNNING + - BATCH_JOB_PHASE_SUCCEEDED + - BATCH_JOB_PHASE_FAILED + - BATCH_JOB_PHASE_ERROR + - BATCH_JOB_PHASE_CANCELLED + example: BATCH_JOB_PHASE_UNKNOWN + type: string + apiIndexJobStatus: + default: INDEX_JOB_STATUS_UNKNOWN + enum: + - INDEX_JOB_STATUS_UNKNOWN + - INDEX_JOB_STATUS_PARTIAL + - INDEX_JOB_STATUS_IN_PROGRESS + - INDEX_JOB_STATUS_COMPLETED + - INDEX_JOB_STATUS_FAILED + - INDEX_JOB_STATUS_NO_CHANGES + - INDEX_JOB_STATUS_PENDING + - INDEX_JOB_STATUS_CANCELLED + example: INDEX_JOB_STATUS_UNKNOWN + type: string + apiIndexingJob: + description: IndexingJob description + properties: + completed_datasources: + description: Number of datasources indexed completed + example: 123 + format: int64 + type: integer + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + data_source_jobs: + description: Details on Data Sources included in the Indexing Job + items: + $ref: '#/components/schemas/apiIndexedDataSource' + type: array + data_source_uuids: + example: + - example string + items: + example: example string + type: string + type: array + finished_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + is_report_available: + description: Boolean value to determine if the indexing job details are available + example: true + type: boolean + knowledge_base_uuid: + description: Knowledge base id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + phase: + $ref: '#/components/schemas/apiBatchJobPhase' + started_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + status: + $ref: '#/components/schemas/apiIndexJobStatus' + tokens: + description: Number of tokens [This field is deprecated] + example: 123 + format: int64 + type: integer + total_datasources: + description: Number of datasources being indexed + example: 123 + format: int64 + type: integer + total_tokens: + description: Total Tokens Consumed By the Indexing Job + example: '12345' + format: uint64 + type: string + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiRerankingConfiguration: + description: Configuration for cross-encoder reranking during retrieval. + properties: + enabled: + description: Whether reranking is enabled for retrieval + example: true + type: boolean + model: + description: Reranker model internal name + example: '"bge-reranker-v2-m3"' + type: string + type: object + apiKnowledgeBase: + description: Knowledgebase Description + properties: + added_to_agent_at: + description: Time when the knowledge base was added to the agent + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + database_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + embedding_model_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + is_public: + description: Whether the knowledge base is public or not + example: true + type: boolean + last_indexing_job: + $ref: '#/components/schemas/apiIndexingJob' + name: + description: Name of knowledge base + example: example name + type: string + project_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + region: + description: Region code + example: example string + type: string + reranking_config: + $ref: '#/components/schemas/apiRerankingConfiguration' + tags: + description: Tags to organize related resources + example: + - example string + items: + example: example string + type: string + type: array + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + user_id: + description: Id of user that created the knowledge base + example: '12345' + format: int64 + type: string + uuid: + description: Unique id for knowledge base + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentTemplateType: + default: AGENT_TEMPLATE_TYPE_STANDARD + description: |- + - AGENT_TEMPLATE_TYPE_STANDARD: The standard agent template + - AGENT_TEMPLATE_TYPE_ONE_CLICK: The one click agent template + enum: + - AGENT_TEMPLATE_TYPE_STANDARD + - AGENT_TEMPLATE_TYPE_ONE_CLICK + example: AGENT_TEMPLATE_TYPE_STANDARD + type: string + apiAgentTemplate: + description: Represents an AgentTemplate entity + properties: + created_at: + description: The agent template's creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + description: + description: Deprecated - Use summary instead + example: example string + type: string + guardrails: + description: List of guardrails associated with the agent template + items: + $ref: '#/components/schemas/apiAgentTemplateGuardrail' + type: array + instruction: + description: Instructions for the agent template + example: example string + type: string + k: + description: The 'k' value for the agent template + example: 123 + format: int64 + type: integer + knowledge_bases: + description: List of knowledge bases associated with the agent template + items: + $ref: '#/components/schemas/apiKnowledgeBase' + type: array + long_description: + description: The long description of the agent template + example: >- + "Enhance your customer service with an AI agent designed to provide + consistent, helpful, and accurate support across multiple channels. + This template creates an agent that can answer product questions, + troubleshoot common issues, process simple requests, and maintain a + friendly, on-brand voice throughout customer interactions. Reduce + response times, handle routine inquiries efficiently, and ensure + your customers feel heard and helped." + type: string + max_tokens: + description: The max_tokens setting for the agent template + example: 123 + format: int64 + type: integer + model: + $ref: '#/components/schemas/apiModel' + name: + description: Name of the agent template + example: example name + type: string + short_description: + description: The short description of the agent template + example: >- + "This template has been designed with question-answer and + conversational use cases in mind. It comes with validated agent + instructions, fine-tuned model settings, and preconfigured + guardrails defined for customer support-related use cases." + type: string + summary: + description: The summary of the agent template + example: example string + type: string + tags: + description: List of tags associated with the agent template + example: + - example string + items: + example: example string + type: string + type: array + temperature: + description: The temperature setting for the agent template + example: 123 + format: float + type: number + template_type: + $ref: '#/components/schemas/apiAgentTemplateType' + top_p: + description: The top_p setting for the agent template + example: 123 + format: float + type: number + updated_at: + description: The agent template's last updated date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentPublic: + description: A GenAI Agent's configuration + properties: + chatbot: + $ref: '#/components/schemas/apiChatbot' + chatbot_identifiers: + description: Chatbot identifiers + items: + $ref: '#/components/schemas/apiAgentChatbotIdentifier' + type: array + created_at: + description: Creation date / time + example: '2021-01-01T00:00:00Z' + format: date-time + type: string + deployment: + $ref: '#/components/schemas/apiDeployment' + description: + description: Description of agent + example: This is a chatbot that can help you with your questions. + type: string + if_case: + description: Instructions to the agent on how to use the route + example: if talking about the weather use this route + type: string + instruction: + description: >- + Agent instruction. Instructions help your agent to perform its job + effectively. See [Write Effective Agent + Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) + for best practices. + example: Hello, how can I help you? + type: string + k: + description: >- + How many results should be considered from an attached knowledge + base + example: 5 + format: int64 + type: integer + max_tokens: + description: >- + Specifies the maximum number of tokens the model can process in a + single input or output, set as a number between 1 and 512. This + determines the length of each response. + example: 100 + format: int64 + type: integer + mcp_servers: + description: MCP (Model Context Protocol) servers attached to this agent + items: + $ref: '#/components/schemas/apiMcpServer' + type: array + model: + $ref: '#/components/schemas/apiModel' + model_router: + $ref: '#/components/schemas/apiModelRouter' + name: + description: Agent name + example: My Agent + type: string + project_id: + description: The DigitalOcean project ID associated with the agent + example: 12345678-1234-1234-1234-123456789012 + type: string + provide_citations: + description: Whether the agent should provide in-response citations + example: true + type: boolean + reasoning_effort: + description: The reasoning effort for the agent + example: '"low"' + type: string + region: + description: Region code + example: '"tor1"' + type: string + retrieval_method: + $ref: '#/components/schemas/apiRetrievalMethod' + route_created_at: + description: Creation of route date / time + example: '2021-01-01T00:00:00Z' + format: date-time + type: string + route_created_by: + description: Id of user that created the route + example: '12345678' + format: uint64 + type: string + route_name: + description: Route name + example: Route Name + type: string + route_uuid: + description: Route uuid + example: '"12345678-1234-1234-1234-123456789012"' + type: string + tags: + description: A set of abitrary tags to organize your agent + example: + - example string + items: + example: example string + type: string + type: array + temperature: + description: >- + Controls the model’s creativity, specified as a number between 0 and + 1. Lower values produce more predictable and conservative responses, + while higher values encourage creativity and variation. + example: 0.5 + format: float + type: number + template: + $ref: '#/components/schemas/apiAgentTemplate' + thinking_token_budget: + description: >- + The thinking token budget for Anthropic extended thinking (0 = + disabled) + example: 1000 + format: int64 + type: integer + top_p: + description: >- + Defines the cumulative probability threshold for word selection, + specified as a number between 0 and 1. Higher values allow for more + diverse outputs, while lower values ensure focused and coherent + responses. + example: 0.9 + format: float + type: number + updated_at: + description: Last modified + example: '2021-01-01T00:00:00Z' + format: date-time + type: string + url: + description: Access your agent under this url + example: https://example.com/agent + type: string + user_id: + description: Id of user that created the agent + example: '12345678' + format: uint64 + type: string + uuid: + description: Unique agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + version_hash: + description: The latest version of the agent + example: example string + type: string + type: object + apiPages: + description: Information about how to reach other pages + properties: + first: + description: First page + example: example string + type: string + last: + description: Last page + example: example string + type: string + next: + description: Next page + example: example string + type: string + previous: + description: Previous page + example: example string + type: string + type: object + apiLinks: + description: Links to other pages + properties: + pages: + $ref: '#/components/schemas/apiPages' + type: object + apiMeta: + description: Meta information about the data set + properties: + page: + description: The current page + example: 123 + format: int64 + type: integer + pages: + description: Total number of pages + example: 123 + format: int64 + type: integer + total: + description: Total amount of items over all pages + example: 123 + format: int64 + type: integer + type: object + apiListAgentsOutputPublic: + description: List of Agents + properties: + agents: + description: Agents + items: + $ref: '#/components/schemas/apiAgentPublic' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateAgentInputPublic: + description: Parameters for Agent Creation + properties: + anthropic_key_uuid: + description: Optional Anthropic API key ID to use with Anthropic models + example: '"12345678-1234-1234-1234-123456789012"' + type: string + description: + description: A text description of the agent, not used in inference + example: '"My Agent Description"' + type: string + instruction: + description: >- + Agent instruction. Instructions help your agent to perform its job + effectively. See [Write Effective Agent + Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) + for best practices. + example: '"You are an agent who thinks deeply about the world"' + type: string + knowledge_base_uuid: + description: Ids of the knowledge base(s) to attach to the agent + example: + - example string + items: + example: example string + type: string + type: array + mcp_servers: + description: MCP (Model Context Protocol) servers to attach to the agent + items: + $ref: '#/components/schemas/apiMcpServer' + type: array + model_provider_key_uuid: + example: '"12345678-1234-1234-1234-123456789012"' + type: string + model_router_uuid: + example: '"12345678-1234-1234-1234-123456789012"' + type: string + model_uuid: + description: Identifier for the foundation model. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Agent name + example: '"My Agent"' + type: string + open_ai_key_uuid: + description: Optional OpenAI API key ID to use with OpenAI models + example: '"12345678-1234-1234-1234-123456789012"' + type: string + project_id: + description: The id of the DigitalOcean project this agent will belong to + example: '"12345678-1234-1234-1234-123456789012"' + type: string + reasoning_effort: + example: '"low"' + type: string + region: + description: The DigitalOcean region to deploy your agent in + example: '"tor1"' + type: string + router_preset_slug: + example: '"general"' + type: string + tags: + description: Agent tag to organize related resources + example: + - example string + items: + example: example string + type: string + type: array + thinking_token_budget: + example: 123 + format: int64 + type: integer + workspace_uuid: + description: Identifier for the workspace + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAnthropicAPIKeyInfo: + description: Anthropic API Key Info + properties: + created_at: + description: Key creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by user id from DO + example: '12345' + format: uint64 + type: string + deleted_at: + description: Key deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + name: + description: Name + example: example name + type: string + updated_at: + description: Key last updated date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentAPIKeyInfo: + description: Agent API Key Info + properties: + created_at: + description: Creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by + example: '12345' + format: uint64 + type: string + deleted_at: + description: Deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + name: + description: Name + example: example name + type: string + secret_key: + example: example string + type: string + uuid: + description: Uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentAPIKey: + description: Agent API Key + properties: + api_key: + description: Api key + example: example string + type: string + type: object + apiAgent: + description: An Agent + properties: + anthropic_api_key: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + api_key_infos: + description: Api key infos + items: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: array + api_keys: + description: Api keys + items: + $ref: '#/components/schemas/apiAgentAPIKey' + type: array + chatbot: + $ref: '#/components/schemas/apiChatbot' + chatbot_identifiers: + description: Chatbot identifiers + items: + $ref: '#/components/schemas/apiAgentChatbotIdentifier' + type: array + child_agents: + description: Child agents + items: + $ref: '#/components/schemas/apiAgent' + type: array + conversation_logs_enabled: + description: Whether conversation logs are enabled for the agent + example: true + type: boolean + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + deployment: + $ref: '#/components/schemas/apiDeployment' + description: + description: Description of agent + example: example string + type: string + functions: + items: + $ref: '#/components/schemas/apiAgentFunction' + type: array + guardrails: + description: The guardrails the agent is attached to + items: + $ref: '#/components/schemas/apiAgentGuardrail' + type: array + if_case: + example: example string + type: string + instruction: + description: >- + Agent instruction. Instructions help your agent to perform its job + effectively. See [Write Effective Agent + Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) + for best practices. + example: example string + type: string + k: + example: 123 + format: int64 + type: integer + knowledge_bases: + description: Knowledge bases + items: + $ref: '#/components/schemas/apiKnowledgeBase' + type: array + logging_config: + $ref: '#/components/schemas/apiAgentLoggingConfig' + max_tokens: + example: 123 + format: int64 + type: integer + mcp_servers: + description: MCP (Model Context Protocol) servers attached to this agent + items: + $ref: '#/components/schemas/apiMcpServer' + type: array + model: + $ref: '#/components/schemas/apiModel' + model_provider_key: + $ref: '#/components/schemas/apiModelProviderKeyInfo' + model_router: + $ref: '#/components/schemas/apiModelRouter' + name: + description: Agent name + example: example name + type: string + openai_api_key: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + parent_agents: + description: Parent agents + items: + $ref: '#/components/schemas/apiAgent' + type: array + project_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + provide_citations: + description: Whether the agent should provide in-response citations + example: true + type: boolean + reasoning_effort: + description: The reasoning effort for the agent + example: example string + type: string + region: + description: Region code + example: example string + type: string + retrieval_method: + $ref: '#/components/schemas/apiRetrievalMethod' + route_created_at: + description: Creation of route date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + route_created_by: + example: '12345' + format: uint64 + type: string + route_name: + description: Route name + example: example name + type: string + route_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + tags: + description: Agent tag to organize related resources + example: + - example string + items: + example: example string + type: string + type: array + temperature: + example: 123 + format: float + type: number + template: + $ref: '#/components/schemas/apiAgentTemplate' + thinking_token_budget: + description: >- + The thinking token budget for Anthropic extended thinking (0 = + disabled) + example: 123 + format: int64 + type: integer + top_p: + example: 123 + format: float + type: number + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + url: + description: Access your agent under this url + example: example string + type: string + user_id: + description: Id of user that created the agent + example: '12345' + format: uint64 + type: string + uuid: + description: Unique agent id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + version_hash: + description: The latest version of the agent + example: example string + type: string + vpc_egress_ips: + description: VPC Egress IPs + example: + - example string + items: + example: example string + type: string + type: array + vpc_uuid: + example: '"12345678-1234-1234-1234-123456789012"' + type: string + workspace: + $ref: '#/components/schemas/apiWorkspace' + type: object + apiAgentFunction: + description: Description missing + properties: + api_key: + description: Api key + example: example string + type: string + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by user id from DO + example: '12345' + format: uint64 + type: string + description: + description: Agent description + example: example string + type: string + faas_name: + example: example name + type: string + faas_namespace: + example: example name + type: string + input_schema: + type: object + name: + description: Name + example: example name + type: string + output_schema: + type: object + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + url: + description: Download your agent here + example: example string + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiGuardrailType: + default: GUARDRAIL_TYPE_UNKNOWN + enum: + - GUARDRAIL_TYPE_UNKNOWN + - GUARDRAIL_TYPE_JAILBREAK + - GUARDRAIL_TYPE_SENSITIVE_DATA + - GUARDRAIL_TYPE_CONTENT_MODERATION + example: GUARDRAIL_TYPE_UNKNOWN + type: string + apiAgentGuardrail: + description: A Agent Guardrail + properties: + agent_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + created_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + default_response: + example: example string + type: string + description: + example: example string + type: string + guardrail_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + is_attached: + example: true + type: boolean + is_default: + example: true + type: boolean + metadata: + type: object + name: + example: example name + type: string + priority: + example: 123 + format: int32 + type: integer + type: + $ref: '#/components/schemas/apiGuardrailType' + updated_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentLoggingConfig: + properties: + galileo_project_id: + description: Galileo project identifier + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + galileo_project_name: + description: Name of the Galileo project + example: example name + type: string + insights_enabled: + description: Whether insights are enabled + example: true + type: boolean + insights_enabled_at: + description: Timestamp when insights were enabled + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + log_stream_id: + description: Identifier for the log stream + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + log_stream_name: + description: Name of the log stream + example: example name + type: string + type: object + apiModelProviderKeyInfo: + properties: + api_key_uuid: + description: API key ID + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + created_at: + description: Key creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by user id from DO + example: '12345' + format: uint64 + type: string + deleted_at: + description: Key deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + models: + description: Models supported by the openAI api key + items: + $ref: '#/components/schemas/apiModel' + type: array + name: + description: Name of the key + example: example name + type: string + provider: + $ref: '#/components/schemas/apiModelProvider' + updated_at: + description: Key last updated date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + type: object + apiOpenAIAPIKeyInfo: + description: OpenAI API Key Info + properties: + created_at: + description: Key creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by user id from DO + example: '12345' + format: uint64 + type: string + deleted_at: + description: Key deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + models: + description: Models supported by the openAI api key + items: + $ref: '#/components/schemas/apiModel' + type: array + name: + description: Name + example: example name + type: string + updated_at: + description: Key last updated date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiEvaluationDatasetType: + default: EVALUATION_DATASET_TYPE_UNKNOWN + enum: + - EVALUATION_DATASET_TYPE_UNKNOWN + - EVALUATION_DATASET_TYPE_ADK + - EVALUATION_DATASET_TYPE_NON_ADK + - EVALUATION_DATASET_TYPE_MODEL + example: EVALUATION_DATASET_TYPE_UNKNOWN + type: string + apiEvaluationDataset: + properties: + created_at: + description: Time created at. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + dataset_name: + description: Name of the dataset. + example: example name + type: string + dataset_type: + $ref: '#/components/schemas/apiEvaluationDatasetType' + dataset_uuid: + description: UUID of the dataset. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + file_size: + description: The size of the dataset uploaded file in bytes. + example: '12345' + format: uint64 + type: string + has_ground_truth: + description: Does the dataset have a ground truth column? + example: true + type: boolean + row_count: + description: Number of rows in the dataset. + example: 123 + format: int64 + type: integer + type: object + apiEvaluationMetricCategory: + default: METRIC_CATEGORY_UNSPECIFIED + enum: + - METRIC_CATEGORY_UNSPECIFIED + - METRIC_CATEGORY_CORRECTNESS + - METRIC_CATEGORY_USER_OUTCOMES + - METRIC_CATEGORY_SAFETY_AND_SECURITY + - METRIC_CATEGORY_CONTEXT_QUALITY + - METRIC_CATEGORY_MODEL_FIT + example: METRIC_CATEGORY_UNSPECIFIED + type: string + apiEvaluationScope: + default: EVALUATION_SCOPE_UNSPECIFIED + description: >- + Scope that determines whether a metric belongs to agent evaluation or + model evaluation. + + For backwards compatibility, UNSPECIFIED defaults to agent metrics only + in list operations. + enum: + - EVALUATION_SCOPE_UNSPECIFIED + - EVALUATION_SCOPE_AGENT + - EVALUATION_SCOPE_MODEL + example: EVALUATION_SCOPE_UNSPECIFIED + type: string + apiEvaluationMetricType: + default: METRIC_TYPE_UNSPECIFIED + enum: + - METRIC_TYPE_UNSPECIFIED + - METRIC_TYPE_GENERAL_QUALITY + - METRIC_TYPE_RAG_AND_TOOL + - METRIC_TYPE_MODEL_QUALITY + - METRIC_TYPE_MODEL_SAFETY + example: METRIC_TYPE_UNSPECIFIED + type: string + apiEvaluationMetricValueType: + default: METRIC_VALUE_TYPE_UNSPECIFIED + enum: + - METRIC_VALUE_TYPE_UNSPECIFIED + - METRIC_VALUE_TYPE_NUMBER + - METRIC_VALUE_TYPE_STRING + - METRIC_VALUE_TYPE_PERCENTAGE + example: METRIC_VALUE_TYPE_UNSPECIFIED + type: string + apiEvaluationMetric: + properties: + category: + $ref: '#/components/schemas/apiEvaluationMetricCategory' + description: + example: example string + type: string + evaluation_scope: + $ref: '#/components/schemas/apiEvaluationScope' + inverted: + description: >- + If true, the metric is inverted, meaning that a lower value is + better. + example: true + type: boolean + is_metric_goal: + example: true + type: boolean + metric_name: + example: example name + type: string + metric_rank: + example: 123 + format: int64 + type: integer + metric_type: + $ref: '#/components/schemas/apiEvaluationMetricType' + metric_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + metric_value_type: + $ref: '#/components/schemas/apiEvaluationMetricValueType' + range_max: + description: The maximum value for the metric. + example: 123 + format: float + type: number + range_min: + description: The minimum value for the metric. + example: 123 + format: float + type: number + type: object + apiStarMetric: + properties: + metric_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + name: + example: example name + type: string + success_threshold: + description: >- + The success threshold for the star metric. + + This is a value that the metric must reach to be considered + successful. + example: 123 + format: float + type: number + success_threshold_pct: + description: |- + The success threshold for the star metric. + This is a percentage value between 0 and 100. + example: 123 + format: int32 + type: integer + type: object + apiEvaluationTestCase: + properties: + archived_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by_user_email: + example: example@example.com + type: string + created_by_user_id: + example: '12345' + format: uint64 + type: string + dataset: + $ref: '#/components/schemas/apiEvaluationDataset' + dataset_name: + example: example name + type: string + dataset_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + description: + example: example string + type: string + latest_version_number_of_runs: + example: 123 + format: int32 + type: integer + metrics: + items: + $ref: '#/components/schemas/apiEvaluationMetric' + type: array + name: + example: example name + type: string + star_metric: + $ref: '#/components/schemas/apiStarMetric' + test_case_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + total_runs: + example: 123 + format: int32 + type: integer + updated_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + updated_by_user_email: + example: example@example.com + type: string + updated_by_user_id: + example: '12345' + format: uint64 + type: string + version: + example: 123 + format: int64 + type: integer + type: object + apiWorkspace: + properties: + agents: + description: Agents + items: + $ref: '#/components/schemas/apiAgent' + type: array + created_at: + description: Creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: The id of user who created this workspace + example: '12345' + format: uint64 + type: string + created_by_email: + description: The email of the user who created this workspace + example: example@example.com + type: string + deleted_at: + description: Deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + description: + description: Description of the workspace + example: example string + type: string + evaluation_test_cases: + description: Evaluations + items: + $ref: '#/components/schemas/apiEvaluationTestCase' + type: array + name: + description: Name of the workspace + example: example name + type: string + updated_at: + description: Update date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiCreateAgentOutput: + description: Information about a newly created Agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiListAgentAPIKeysOutput: + properties: + api_key_infos: + description: Api key infos + items: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateAgentAPIKeyInputPublic: + properties: + agent_uuid: + description: Agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: A human friendly name to identify the key + example: Production Key + type: string + type: object + apiCreateAgentAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: object + apiUpdateAgentAPIKeyInputPublic: + properties: + agent_uuid: + description: Agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + api_key_uuid: + description: API key ID + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Name + example: '"Production Key"' + type: string + type: object + apiUpdateAgentAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: object + apiDeleteAgentAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: object + apiRegenerateAgentAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiAgentAPIKeyInfo' + type: object + apiLinkAgentFunctionInputPublic: + description: Information for a agent function link + properties: + agent_uuid: + description: Agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + description: + description: Function description + example: '"My Function Description"' + type: string + faas_name: + description: The name of the function in the DigitalOcean functions platform + example: '"my-function"' + type: string + faas_namespace: + description: The namespace of the function in the DigitalOcean functions platform + example: '"default"' + type: string + function_name: + description: Function name + example: '"My Function"' + type: string + input_schema: + description: Describe the input schema for the function so the agent may call it + type: object + output_schema: + description: >- + Describe the output schema for the function so the agent handle its + response + type: object + type: object + apiLinkAgentFunctionOutput: + description: Information about a newly function linked agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUpdateAgentFunctionInputPublic: + description: Information about updating an agent function + properties: + agent_uuid: + description: Agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + description: + description: Funciton description + example: '"My Function Description"' + type: string + faas_name: + description: The name of the function in the DigitalOcean functions platform + example: '"my-function"' + type: string + faas_namespace: + description: The namespace of the function in the DigitalOcean functions platform + example: '"default"' + type: string + function_name: + description: Function name + example: '"My Function"' + type: string + function_uuid: + description: Function id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + input_schema: + description: Describe the input schema for the function so the agent may call it + type: object + output_schema: + description: >- + Describe the output schema for the function so the agent handle its + response + type: object + type: object + apiUpdateAgentFunctionOutput: + description: The updated agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUnlinkAgentFunctionOutput: + description: Information about a newly unlinked agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiAgentGuardrailInput: + properties: + guardrail_uuid: + description: Guardrail uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + priority: + description: Priority of the guardrail + example: 123 + format: int64 + type: integer + type: object + apiLinkAgentGuardrailsInputPublic: + description: Information about linking an agent to a guardrail + properties: + agent_uuid: + description: The UUID of the agent. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + guardrails: + description: The list of guardrails to attach. + items: + $ref: '#/components/schemas/apiAgentGuardrailInput' + type: array + type: object + apiLinkAgentGuardrailOutput: + description: Information about an updated agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUnlinkAgentGuardrailOutput: + description: UnlinkAgentGuardrailOutput description + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiLinkKnowledgeBaseOutput: + description: Information about a linked knowledge base + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUnlinkKnowledgeBaseOutput: + description: Informatinon about a unlinked knowledge base + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUpdateLinkedAgentInputPublic: + description: Information about updating the linkage of an agent + properties: + child_agent_uuid: + description: Routed agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + if_case: + description: Describes the case in which the child agent should be used + example: '"use this to get weather information"' + type: string + parent_agent_uuid: + description: A unique identifier for the parent agent. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + route_name: + description: Route name + example: '"weather_route"' + type: string + uuid: + description: Unique id of linkage + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiUpdateLinkedAgentOutput: + description: Information about an updated linkage + properties: + child_agent_uuid: + description: Routed agent id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + parent_agent_uuid: + description: A unique identifier for the parent agent. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + rollback: + example: true + type: boolean + uuid: + description: Unique id of linkage + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiLinkAgentInputPublic: + description: Information for linking an agent + properties: + child_agent_uuid: + description: Routed agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + if_case: + example: '"use this to get weather information"' + type: string + parent_agent_uuid: + description: A unique identifier for the parent agent. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + route_name: + description: Name of route + example: '"weather_route"' + type: string + type: object + apiLinkAgentOutput: + description: Information about a newly linked agent + properties: + child_agent_uuid: + description: Routed agent id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + parent_agent_uuid: + description: A unique identifier for the parent agent. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiUnlinkAgentOutput: + description: Information about a removed linkage + properties: + child_agent_uuid: + description: Routed agent id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + parent_agent_uuid: + description: Pagent agent id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiGetAgentOutput: + description: One Agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUpdateAgentInputPublic: + description: Data to modify an existing Agent + properties: + agent_log_insights_enabled: + example: true + type: boolean + allowed_domains: + description: >- + Optional list of allowed domains for the chatbot - Must use fully + qualified domain name (FQDN) such as https://example.com + example: + - example string + items: + example: example string + type: string + type: array + anthropic_key_uuid: + description: Optional anthropic key uuid for use with anthropic models + example: '"12345678-1234-1234-1234-123456789012"' + type: string + clear_mcp_servers: + description: >- + When true, removes all MCP servers from the agent. Use this instead + of sending an empty mcp_servers array. + example: true + type: boolean + conversation_logs_enabled: + description: Optional update of conversation logs enabled + example: true + type: boolean + description: + description: Agent description + example: '"My Agent Description"' + type: string + instruction: + description: >- + Agent instruction. Instructions help your agent to perform its job + effectively. See [Write Effective Agent + Instructions](https://docs.digitalocean.com/products/genai-platform/concepts/best-practices/#agent-instructions) + for best practices. + example: '"You are an agent who thinks deeply about the world"' + type: string + k: + description: >- + How many results should be considered from an attached knowledge + base + example: 5 + format: int64 + type: integer + max_tokens: + description: >- + Specifies the maximum number of tokens the model can process in a + single input or output, set as a number between 1 and 512. This + determines the length of each response. + example: 100 + format: int64 + type: integer + mcp_servers: + description: MCP (Model Context Protocol) servers to attach to the agent + items: + $ref: '#/components/schemas/apiMcpServer' + type: array + model_provider_key_uuid: + description: Optional Model Provider uuid for use with provider models + example: '"12345678-1234-1234-1234-123456789012"' + type: string + model_router_uuid: + example: '"12345678-1234-1234-1234-123456789012"' + type: string + model_uuid: + description: Identifier for the foundation model. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Agent name + example: '"My New Agent Name"' + type: string + open_ai_key_uuid: + description: Optional OpenAI key uuid for use with OpenAI models + example: '"12345678-1234-1234-1234-123456789012"' + type: string + project_id: + description: The id of the DigitalOcean project this agent will belong to + example: '"12345678-1234-1234-1234-123456789012"' + type: string + provide_citations: + example: true + type: boolean + reasoning_effort: + example: '"low"' + type: string + retrieval_method: + $ref: '#/components/schemas/apiRetrievalMethod' + router_preset_slug: + example: '"general"' + type: string + tags: + description: A set of abitrary tags to organize your agent + example: + - example string + items: + example: example string + type: string + type: array + temperature: + description: >- + Controls the model’s creativity, specified as a number between 0 and + 1. Lower values produce more predictable and conservative responses, + while higher values encourage creativity and variation. + example: 0.7 + format: float + type: number + thinking_token_budget: + example: 123 + format: int64 + type: integer + top_p: + description: >- + Defines the cumulative probability threshold for word selection, + specified as a number between 0 and 1. Higher values allow for more + diverse outputs, while lower values ensure focused and coherent + responses. + example: 0.9 + format: float + type: number + uuid: + description: Unique agent id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiUpdateAgentOutput: + description: Information about an updated agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiDeleteAgentOutput: + description: Info about a deleted agent + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiGetChildrenOutput: + description: Child list for an agent + properties: + children: + description: Child agents + items: + $ref: '#/components/schemas/apiAgent' + type: array + type: object + apiUpdateAgentDeploymentVisibilityInputPublic: + description: UpdateAgentDeploymentVisibilityInputPublic description + properties: + uuid: + description: Unique id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + visibility: + $ref: '#/components/schemas/apiDeploymentVisibility' + type: object + apiUpdateAgentDeploymentVisbilityOutput: + description: UpdateAgentDeploymentVisbilityOutput description + properties: + agent: + $ref: '#/components/schemas/apiAgent' + type: object + apiUsageMeasurement: + description: Usage Measurement Description + properties: + tokens: + example: 123 + format: int64 + type: integer + usage_type: + example: example string + type: string + type: object + apiResourceUsage: + description: Resource Usage Description + properties: + measurements: + items: + $ref: '#/components/schemas/apiUsageMeasurement' + type: array + resource_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + start: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + stop: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + type: object + apiGetAgentUsageOutput: + description: Agent usage + properties: + log_insights_usage: + $ref: '#/components/schemas/apiResourceUsage' + usage: + $ref: '#/components/schemas/apiResourceUsage' + type: object + apiAgentChildRelationshipVerion: + properties: + agent_name: + description: Name of the child agent + example: example name + type: string + child_agent_uuid: + description: Child agent unique identifier + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + if_case: + description: If case + example: example string + type: string + is_deleted: + description: Child agent is deleted + example: true + type: boolean + route_name: + description: Route name + example: example name + type: string + type: object + apiAgentFunctionVersion: + description: Function represents a function configuration for an agent + properties: + description: + description: Description of the function + example: example string + type: string + faas_name: + description: FaaS name of the function + example: example name + type: string + faas_namespace: + description: FaaS namespace of the function + example: example name + type: string + is_deleted: + description: Whether the function is deleted + example: true + type: boolean + name: + description: Name of the function + example: example name + type: string + type: object + apiAgentGuardrailVersion: + description: Agent Guardrail version + properties: + is_deleted: + description: Whether the guardrail is deleted + example: true + type: boolean + name: + description: Guardrail Name + example: example name + type: string + priority: + description: Guardrail Priority + example: 123 + format: int64 + type: integer + uuid: + description: Guardrail UUID + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentKnowledgeBaseVersion: + properties: + is_deleted: + description: Deletet at date / time + example: true + type: boolean + name: + description: Name of the knowledge base + example: example name + type: string + uuid: + description: Unique id of the knowledge base + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiAgentVersion: + description: Represents an AgentVersion entity + properties: + agent_uuid: + description: Uuid of the agent this version belongs to + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + attached_child_agents: + description: List of child agent relationships + items: + $ref: '#/components/schemas/apiAgentChildRelationshipVerion' + type: array + attached_functions: + description: List of function versions + items: + $ref: '#/components/schemas/apiAgentFunctionVersion' + type: array + attached_guardrails: + description: List of guardrail version + items: + $ref: '#/components/schemas/apiAgentGuardrailVersion' + type: array + attached_knowledgebases: + description: List of knowledge base agent versions + items: + $ref: '#/components/schemas/apiAgentKnowledgeBaseVersion' + type: array + can_rollback: + description: Whether the version is able to be rolled back to + example: true + type: boolean + created_at: + description: Creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by_email: + description: User who created this version + example: example@example.com + type: string + currently_applied: + description: Whether this is the currently applied configuration + example: true + type: boolean + description: + description: Description of the agent + example: example string + type: string + id: + description: Unique identifier + example: '12345' + format: uint64 + type: string + instruction: + description: Instruction for the agent + example: example string + type: string + k: + description: K value for the agent's configuration + example: 123 + format: int64 + type: integer + max_tokens: + description: Max tokens setting for the agent + example: 123 + format: int64 + type: integer + model_name: + description: Name of model associated to the agent version + example: example name + type: string + name: + description: Name of the agent + example: example name + type: string + provide_citations: + description: Whether the agent should provide in-response citations + example: true + type: boolean + retrieval_method: + $ref: '#/components/schemas/apiRetrievalMethod' + tags: + description: Tags associated with the agent + example: + - example string + items: + example: example string + type: string + type: array + temperature: + description: Temperature setting for the agent + example: 123 + format: float + type: number + top_p: + description: Top_p setting for the agent + example: 123 + format: float + type: number + trigger_action: + description: Action triggering the configuration update + example: example string + type: string + version_hash: + description: Version hash + example: example string + type: string + type: object + apiListAgentVersionsOutput: + description: List of agent versions + properties: + agent_versions: + description: Agents + items: + $ref: '#/components/schemas/apiAgentVersion' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiRollbackToAgentVersionInputPublic: + properties: + uuid: + description: Agent unique identifier + example: '"12345678-1234-1234-1234-123456789012"' + type: string + version_hash: + description: Unique identifier + example: c3658d8b5c05494cd03ce042926ef08157889ed54b1b74b5ee0b3d66dcee4b73 + type: string + type: object + apiAuditHeader: + description: An alternative way to provide auth information. for internal use only. + properties: + actor_id: + example: '12345' + format: uint64 + type: string + actor_ip: + example: example string + type: string + actor_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + context_urn: + example: example string + type: string + origin_application: + example: example string + type: string + user_id: + example: '12345' + format: uint64 + type: string + user_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiRollbackToAgentVersionOutput: + properties: + audit_header: + $ref: '#/components/schemas/apiAuditHeader' + version_hash: + description: Unique identifier + example: example string + type: string + type: object + apiListAnthropicAPIKeysOutput: + description: >- + ListAnthropicAPIKeysOutput is used to return the list of Anthropic API + keys for a specific agent. + properties: + api_key_infos: + description: Api key infos + items: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateAnthropicAPIKeyInputPublic: + description: >- + CreateAnthropicAPIKeyInputPublic is used to create a new Anthropic API + key for a specific agent. + properties: + api_key: + description: Anthropic API key + example: '"sk-ant-12345678901234567890123456789012"' + type: string + name: + description: Name of the key + example: '"Production Key"' + type: string + type: object + apiCreateAnthropicAPIKeyOutput: + description: >- + CreateAnthropicAPIKeyOutput is used to return the newly created + Anthropic API key. + properties: + api_key_info: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + type: object + apiGetAnthropicAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + type: object + apiUpdateAnthropicAPIKeyInputPublic: + description: >- + UpdateAnthropicAPIKeyInputPublic is used to update an existing Anthropic + API key for a specific agent. + properties: + api_key: + description: Anthropic API key + example: '"sk-ant-12345678901234567890123456789012"' + type: string + api_key_uuid: + description: API key ID + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Name of the key + example: '"Production Key"' + type: string + type: object + apiUpdateAnthropicAPIKeyOutput: + description: >- + UpdateAnthropicAPIKeyOutput is used to return the updated Anthropic API + key. + properties: + api_key_info: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + type: object + apiDeleteAnthropicAPIKeyOutput: + description: >- + DeleteAnthropicAPIKeyOutput is used to return the deleted Anthropic API + key. + properties: + api_key_info: + $ref: '#/components/schemas/apiAnthropicAPIKeyInfo' + type: object + apiListAgentsByAnthropicKeyOutput: + description: List of Agents that linked to a specific Anthropic Key + properties: + agents: + items: + $ref: '#/components/schemas/apiAgent' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + CustomModelActiveDeploymentEndpoints: + description: >- + Endpoint URLs for a dedicated inference deployment associated with a + custom model. + properties: + private_endpoint_fqdn: + description: Private FQDN for the deployment + example: example string + type: string + public_endpoint_fqdn: + description: Public FQDN for the deployment + example: example string + type: string + type: object + CustomModelActiveDeployment: + description: An active dedicated inference deployment using this custom model. + properties: + created_at: + description: >- + RFC 3339 timestamp indicating when the dedicated inference + deployment was created + example: example string + type: string + endpoints: + $ref: '#/components/schemas/CustomModelActiveDeploymentEndpoints' + id: + description: Unique identifier (UUID) of the dedicated inference deployment + example: example string + type: string + name: + description: Human-readable name of the dedicated inference deployment + example: example name + type: string + region_slug: + description: >- + Slug of the region where the dedicated inference deployment is + running (e.g. "atl1") + example: example string + type: string + state: + description: >- + Current lifecycle state of the dedicated inference deployment (e.g. + "ACTIVE", "PROVISIONING") + example: example string + type: string + updated_at: + description: >- + RFC 3339 timestamp indicating when the dedicated inference + deployment was last updated + example: '2023-01-01' + type: string + type: object + SourceRefAccessType: + default: ACCESS_TYPE_UNSPECIFIED + description: Access level required for the model repository + enum: + - ACCESS_TYPE_UNSPECIFIED + - ACCESS_TYPE_PUBLIC + - ACCESS_TYPE_PRIVATE + - ACCESS_TYPE_GATED + example: ACCESS_TYPE_UNSPECIFIED + type: string + CustomModelSourceRef: + description: Reference to the original source of the model + properties: + access_type: + $ref: '#/components/schemas/SourceRefAccessType' + bucket: + description: Spaces bucket name + example: example string + type: string + commit_sha: + description: Git commit SHA of the model version + example: example string + type: string + hf_token: + description: >- + User-provided HuggingFace token for gated/private models (not + persisted in source_ref) + example: example string + type: string + prefix: + description: Object prefix path in the bucket + example: example string + type: string + region: + description: Spaces bucket region + example: example string + type: string + repo_id: + description: Huggingface repository identifier + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + CustomModelSourceType: + default: SOURCE_TYPE_UNSPECIFIED + description: Source from which the model was imported + enum: + - SOURCE_TYPE_UNSPECIFIED + - SOURCE_TYPE_HUGGINGFACE + - SOURCE_TYPE_SPACES_BUCKET + - SOURCE_TYPE_SDK_UPLOAD + - SOURCE_TYPE_FINE_TUNING + example: SOURCE_TYPE_UNSPECIFIED + type: string + apiCustomModelStatus: + default: STATUS_UNSPECIFIED + description: Import and deployment status of the custom model + enum: + - STATUS_UNSPECIFIED + - STATUS_IMPORTING + - STATUS_READY + - STATUS_FAILED + - STATUS_DELETED + example: STATUS_UNSPECIFIED + type: string + CustomModelTags: + description: User-defined tags for organizing models + properties: + tags: + description: List of tag strings + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiCustomModel: + description: Custom model - user-imported model from HuggingFace, Spaces, etc. + properties: + active_deployments: + description: List of active deployments using this model + items: + $ref: '#/components/schemas/CustomModelActiveDeployment' + type: array + architecture: + description: Model architecture type (free-form string from config.json) + example: example string + type: string + config_json: + description: Raw config.json contents from the model repository + type: object + context_length: + description: Maximum context length supported by the model + example: 123 + format: int64 + type: integer + cost_estimate_per_month: + description: Estimated monthly cost in dollars for hosting + example: 123 + format: int64 + type: integer + created_at: + description: Timestamp when the model was created + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + description: + description: Description of the custom model + example: example string + type: string + file_count: + description: Number of files in the model + example: 123 + format: int64 + type: integer + input_modalities: + description: Input modalities supported (e.g., text, image) + example: + - example string + items: + example: example string + type: string + type: array + license: + description: License under which the model is distributed + example: example string + type: string + name: + description: Name of the custom model + example: example name + type: string + output_modalities: + description: Output modalities supported (e.g., text, image) + example: + - example string + items: + example: example string + type: string + type: array + parameters: + description: Number of parameters in the model + example: '12345' + format: uint64 + type: string + source_ref: + $ref: '#/components/schemas/CustomModelSourceRef' + source_type: + $ref: '#/components/schemas/CustomModelSourceType' + status: + $ref: '#/components/schemas/apiCustomModelStatus' + storage_region: + description: Region of the Spaces bucket where model files are stored + example: example string + type: string + tags: + $ref: '#/components/schemas/CustomModelTags' + team_id: + description: Team that owns the model + example: '12345' + format: uint64 + type: string + total_size_bytes: + description: Total size of model files in bytes + example: '12345' + format: uint64 + type: string + updated_at: + description: Timestamp when the model was last updated + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique identifier for the custom model + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiListCustomModelsOutputPublic: + description: Response containing a list of custom models (public) + properties: + links: + $ref: '#/components/schemas/apiLinks' + max_threshold: + description: Maximum number of custom models allowed for this team's tier + example: 123 + format: int64 + type: integer + meta: + $ref: '#/components/schemas/apiMeta' + models: + description: List of custom models + items: + $ref: '#/components/schemas/apiCustomModel' + type: array + type: object + apiImportCustomModelInputPublic: + description: Request to import a custom model (public) + properties: + accept_terms_and_conditions: + description: >- + Whether the caller accepts the terms and conditions for importing + this model + example: true + type: boolean + description: + description: Description of the model + example: Production model for customer support + type: string + name: + description: Name for the imported model + example: my-mistral-7b + type: string + preferred_gpu_region: + description: Preferred GPU region for deployment + example: nyc3 + type: string + source_ref: + $ref: '#/components/schemas/CustomModelSourceRef' + source_type: + $ref: '#/components/schemas/CustomModelSourceType' + tags: + $ref: '#/components/schemas/CustomModelTags' + type: object + apiCustomModelImportJob: + description: Import job tracking for a custom model + properties: + bytes_done: + description: Bytes imported so far + example: '12345' + format: uint64 + type: string + bytes_total: + description: Total bytes to import + example: '12345' + format: uint64 + type: string + completed_at: + description: Timestamp when the import completed + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_at: + description: Timestamp when the job was created + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + error_message: + description: Error message if import failed + example: example string + type: string + error_step: + description: Step at which the error occurred + example: example string + type: string + files_done: + description: Number of files imported so far + example: 123 + format: int64 + type: integer + files_total: + description: Total number of files to import + example: 123 + format: int64 + type: integer + started_at: + description: Timestamp when the import started + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + status: + description: Current status of the import job + example: example string + type: string + uuid: + description: Unique identifier for the import job + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiImportValidationStep: + description: Validation step result during model import + properties: + error: + description: Error message if validation failed + example: example string + type: string + name: + description: Name of the validation step + example: example name + type: string + passed: + description: Whether the validation step passed + example: true + type: boolean + type: object + apiImportCustomModelOutputPublic: + description: Response containing imported model details (public) + properties: + error: + example: example string + type: string + import_job: + $ref: '#/components/schemas/apiCustomModelImportJob' + model: + $ref: '#/components/schemas/apiCustomModel' + validation_steps: + description: Validation steps performed during import + items: + $ref: '#/components/schemas/apiImportValidationStep' + type: array + type: object + apiGetCustomModelOutputPublic: + description: Response containing a single custom model (public) + properties: + model: + $ref: '#/components/schemas/apiCustomModel' + type: object + apiDeleteCustomModelStatus: + default: DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED + description: Status of delete operation + enum: + - DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED + - DELETE_CUSTOM_MODEL_STATUS_SUCCESS + - DELETE_CUSTOM_MODEL_STATUS_FAIL + example: DELETE_CUSTOM_MODEL_STATUS_UNSPECIFIED + type: string + apiDeleteCustomModelOutputPublic: + description: Response containing delete operation status (public) + properties: + error: + description: Error message if deletion failed + example: example string + type: string + status: + $ref: '#/components/schemas/apiDeleteCustomModelStatus' + type: object + apiUpdateCustomModelMetadataInputPublic: + description: Request to update custom model metadata (public) + properties: + description: + example: example string + type: string + name: + example: example name + type: string + tags: + $ref: '#/components/schemas/CustomModelTags' + uuid: + description: UUID of the custom model to update + example: a1b2c3d4-... + type: string + type: object + apiUpdateCustomModelMetadataOutputPublic: + description: Response containing the updated custom model (public) + properties: + model: + $ref: '#/components/schemas/apiCustomModel' + type: object + apiFileUploadDataSource: + description: File to upload as data source for knowledge base. + properties: + original_file_name: + description: The original file name + example: example name + type: string + size_in_bytes: + description: The size of the file in bytes + example: '12345' + format: uint64 + type: string + stored_object_key: + description: The object key the file was stored as + example: example string + type: string + type: object + apiCreateEvaluationDatasetInputPublic: + description: Creates an evaluation dataset for an agent + properties: + dataset_type: + $ref: '#/components/schemas/apiEvaluationDatasetType' + file_upload_dataset: + $ref: '#/components/schemas/apiFileUploadDataSource' + name: + description: The name of the agent evaluation dataset. + example: example name + type: string + type: object + apiCreateEvaluationDatasetOutput: + description: Output for creating an agent evaluation dataset + properties: + evaluation_dataset_uuid: + description: Evaluation dataset uuid. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiPresignedUrlFile: + description: A single file’s metadata in the request. + properties: + file_name: + description: Local filename + example: example name + type: string + file_size: + description: The size of the file in bytes. + example: '12345' + format: int64 + type: string + type: object + apiCreateDataSourceFileUploadPresignedUrlsInputPublic: + description: Request for pre-signed URL's to upload files for KB Data Sources + properties: + files: + description: A list of files to generate presigned URLs for. + items: + $ref: '#/components/schemas/apiPresignedUrlFile' + type: array + type: object + apiFilePresignedUrlResponse: + description: Detailed info about each presigned URL returned to the client. + properties: + expires_at: + description: The time the url expires at. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + object_key: + description: The unique object key to store the file as. + example: example string + type: string + original_file_name: + description: The original file name. + example: example name + type: string + presigned_url: + description: >- + The actual presigned URL the client can use to upload the file + directly. + example: example string + type: string + type: object + apiCreateDataSourceFileUploadPresignedUrlsOutput: + description: Response with pre-signed urls to upload files. + properties: + request_id: + description: The ID generated for the request for Presigned URLs. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + uploads: + description: A list of generated presigned URLs and object keys, one per file. + items: + $ref: '#/components/schemas/apiFilePresignedUrlResponse' + type: array + type: object + apiGetEvaluationDatasetDownloadURLOutput: + description: Response containing a presigned download URL for an evaluation dataset. + properties: + download_url: + description: The presigned URL to download the dataset file. + example: example string + type: string + expires_at: + description: The time the URL expires at. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + type: object + apiListEvaluationMetricsOutput: + properties: + metrics: + items: + $ref: '#/components/schemas/apiEvaluationMetric' + type: array + type: object + apiRunEvaluationTestCaseInputPublic: + description: Run an evaluation test case. + properties: + agent_deployment_names: + description: >- + Agent deployment names to run the test case against (ADK agent + workspaces). + example: + - example string + items: + example: example string + type: string + type: array + agent_uuids: + description: Agent UUIDs to run the test case against (legacy agents). + example: + - example string + items: + example: example string + type: string + type: array + run_name: + description: The name of the run. + example: Evaluation Run Name + type: string + test_case_uuid: + description: Test-case UUID to run + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiRunEvaluationTestCaseOutput: + properties: + evaluation_run_uuids: + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiEvaluationMetricResult: + properties: + error_description: + description: Error description if the metric could not be calculated. + example: example string + type: string + metric_name: + description: Metric name + example: example name + type: string + metric_value_type: + $ref: '#/components/schemas/apiEvaluationMetricValueType' + number_value: + description: The value of the metric as a number. + example: 123 + format: double + type: number + reasoning: + description: Reasoning of the metric result. + example: example string + type: string + string_value: + description: The value of the metric as a string. + example: example string + type: string + type: object + apiEvaluationRunStatus: + default: EVALUATION_RUN_STATUS_UNSPECIFIED + description: Evaluation Run Statuses + enum: + - EVALUATION_RUN_STATUS_UNSPECIFIED + - EVALUATION_RUN_QUEUED + - EVALUATION_RUN_RUNNING_DATASET + - EVALUATION_RUN_EVALUATING_RESULTS + - EVALUATION_RUN_CANCELLING + - EVALUATION_RUN_CANCELLED + - EVALUATION_RUN_SUCCESSFUL + - EVALUATION_RUN_PARTIALLY_SUCCESSFUL + - EVALUATION_RUN_FAILED + example: EVALUATION_RUN_STATUS_UNSPECIFIED + type: string + apiEvaluationRun: + properties: + agent_deleted: + description: Whether agent is deleted + example: true + type: boolean + agent_deployment_name: + description: The agent deployment name + example: example name + type: string + agent_name: + description: Agent name + example: example name + type: string + agent_uuid: + description: Agent UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + agent_version_hash: + description: Version hash + example: example string + type: string + agent_workspace_uuid: + description: Agent workspace uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + created_by_user_email: + example: example@example.com + type: string + created_by_user_id: + example: '12345' + format: uint64 + type: string + error_description: + description: The error description + example: example string + type: string + evaluation_run_uuid: + description: Evaluation run UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + evaluation_test_case_workspace_uuid: + description: Evaluation test case workspace uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + finished_at: + description: Run end time. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + pass_status: + description: The pass status of the evaluation run based on the star metric. + example: true + type: boolean + queued_at: + description: Run queued time. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + run_level_metric_results: + items: + $ref: '#/components/schemas/apiEvaluationMetricResult' + type: array + run_name: + description: Run name. + example: example name + type: string + star_metric_result: + $ref: '#/components/schemas/apiEvaluationMetricResult' + started_at: + description: Run start time. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + status: + $ref: '#/components/schemas/apiEvaluationRunStatus' + test_case_description: + description: Test case description. + example: example string + type: string + test_case_name: + description: Test case name. + example: example name + type: string + test_case_uuid: + description: Test-case UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + test_case_version: + description: Test-case-version. + example: 123 + format: int64 + type: integer + type: object + apiGetEvaluationRunOutput: + properties: + evaluation_run: + $ref: '#/components/schemas/apiEvaluationRun' + type: object + apiPromptChunk: + properties: + chunk_usage_pct: + description: The usage percentage of the chunk. + example: 123 + format: double + type: number + chunk_used: + description: Indicates if the chunk was used in the prompt. + example: true + type: boolean + index_uuid: + description: The index uuid (Knowledge Base) of the chunk. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + source_name: + description: >- + The source name for the chunk, e.g., the file name or document + title. + example: example name + type: string + text: + description: Text content of the chunk. + example: example string + type: string + type: object + apiAgentType: + default: AGENT_TYPE_UNSPECIFIED + description: Agent span + enum: + - AGENT_TYPE_UNSPECIFIED + - AGENT_TYPE_DEFAULT + - AGENT_TYPE_PLANNER + - AGENT_TYPE_REACT + - AGENT_TYPE_REFLECTION + - AGENT_TYPE_ROUTER + - AGENT_TYPE_CLASSIFIER + - AGENT_TYPE_SUPERVISOR + - AGENT_TYPE_JUDGE + example: AGENT_TYPE_UNSPECIFIED + type: string + apiSpanCommon: + description: Common optional fields shared by all span types + properties: + created_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + duration_ns: + example: '12345' + format: int64 + type: string + metadata: + additionalProperties: + example: example string + type: string + description: Arbitrary structured metadata + type: object + status_code: + example: 123 + format: int32 + type: integer + tags: + description: Free-form tags for filtering/grouping + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiTraceSpan: + description: Represents a span within a trace (e.g., LLM call, tool call, etc.) + properties: + agent: + $ref: '#/components/schemas/apiAgentSpan' + created_at: + description: When the span was created + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + input: + description: >- + Input data for the span (flexible structure - can be messages array, + string, etc.) + type: object + llm: + $ref: '#/components/schemas/apiLLMSpan' + name: + description: Name/identifier for the span + example: example name + type: string + output: + description: >- + Output data from the span (flexible structure - can be message, + string, etc.) + type: object + retriever: + $ref: '#/components/schemas/apiRetrieverSpan' + tool: + $ref: '#/components/schemas/apiToolSpan' + type: + $ref: '#/components/schemas/apiTraceSpanType' + workflow: + $ref: '#/components/schemas/apiWorkflowSpan' + type: object + apiAgentSpan: + properties: + agent_type: + $ref: '#/components/schemas/apiAgentType' + common: + $ref: '#/components/schemas/apiSpanCommon' + redacted_input: + example: example string + type: string + redacted_output: + example: example string + type: string + spans: + description: |- + Child spans - must contain between 1 and 999 spans + Allowed types: llm, tool, retriever + items: + $ref: '#/components/schemas/apiTraceSpan' + type: array + type: object + apiLLMSpan: + description: LLM span + properties: + common: + $ref: '#/components/schemas/apiSpanCommon' + model: + example: example string + type: string + num_input_tokens: + example: 123 + format: int32 + type: integer + num_output_tokens: + example: 123 + format: int32 + type: integer + temperature: + example: 123 + format: float + type: number + time_to_first_token_ns: + example: '12345' + format: int64 + type: string + tools: + description: Tool definitions passed to the model + items: + type: object + type: array + total_tokens: + example: 123 + format: int32 + type: integer + type: object + apiRetrieverSpan: + description: Retriever span + properties: + common: + $ref: '#/components/schemas/apiSpanCommon' + type: object + apiToolSpan: + description: Tool span + properties: + common: + $ref: '#/components/schemas/apiSpanCommon' + tool_call_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiTraceSpanType: + default: TRACE_SPAN_TYPE_UNKNOWN + description: Types of spans in a trace + enum: + - TRACE_SPAN_TYPE_UNKNOWN + - TRACE_SPAN_TYPE_LLM + - TRACE_SPAN_TYPE_RETRIEVER + - TRACE_SPAN_TYPE_TOOL + - TRACE_SPAN_TYPE_AGENT + - TRACE_SPAN_TYPE_WORKFLOW + example: TRACE_SPAN_TYPE_UNKNOWN + type: string + apiWorkflowSpan: + description: Workflow span - can contain child spans (agent, llm, tool, retriever) + properties: + common: + $ref: '#/components/schemas/apiSpanCommon' + spans: + description: |- + Child spans - must contain between 1 and 999 spans + Allowed types: agent, llm, tool, retriever (not workflow) + items: + $ref: '#/components/schemas/apiTraceSpan' + type: array + type: object + apiEvaluationTraceSpan: + description: >- + Represents a span within an evaluatioin trace (e.g., LLM call, tool + call, etc.) + properties: + created_at: + description: When the span was created + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + input: + description: >- + Input data for the span (flexible structure - can be messages array, + string, etc.) + type: object + name: + description: Name/identifier for the span + example: example name + type: string + output: + description: >- + Output data from the span (flexible structure - can be message, + string, etc.) + type: object + retriever_chunks: + description: Any retriever span chunks that were included as part of the span. + items: + $ref: '#/components/schemas/apiPromptChunk' + type: array + span_level_metric_results: + description: The span-level metric results. + items: + $ref: '#/components/schemas/apiEvaluationMetricResult' + type: array + spans: + description: |- + Child spans - must contain between 1 and 999 spans + Allowed types: agent, llm, tool, retriever (not workflow) + items: + $ref: '#/components/schemas/apiTraceSpan' + type: array + type: + $ref: '#/components/schemas/apiTraceSpanType' + type: object + apiPrompt: + properties: + evaluation_trace_spans: + description: The evaluated trace spans. + items: + $ref: '#/components/schemas/apiEvaluationTraceSpan' + type: array + ground_truth: + description: The ground truth for the prompt. + example: example string + type: string + input: + example: example string + type: string + input_tokens: + description: The number of input tokens used in the prompt. + example: '12345' + format: uint64 + type: string + output: + example: example string + type: string + output_tokens: + description: The number of output tokens used in the prompt. + example: '12345' + format: uint64 + type: string + prompt_chunks: + description: The list of prompt chunks. + items: + $ref: '#/components/schemas/apiPromptChunk' + type: array + prompt_id: + description: Prompt ID + example: 123 + format: int64 + type: integer + prompt_level_metric_results: + description: The metric results for the prompt. + items: + $ref: '#/components/schemas/apiEvaluationMetricResult' + type: array + trace_id: + description: The trace id for the prompt. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiGetEvaluationRunResultsOutput: + description: Gets the full results of an evaluation run with all prompts. + properties: + evaluation_run: + $ref: '#/components/schemas/apiEvaluationRun' + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + prompts: + description: The prompt level results. + items: + $ref: '#/components/schemas/apiPrompt' + type: array + type: object + apiGetEvaluationRunPromptResultsOutput: + properties: + prompt: + $ref: '#/components/schemas/apiPrompt' + type: object + apiListEvaluationTestCasesOutput: + properties: + evaluation_test_cases: + description: >- + Alternative way of authentication for internal usage only - should + not be exposed to public api + items: + $ref: '#/components/schemas/apiEvaluationTestCase' + type: array + type: object + apiCreateEvaluationTestCaseInputPublic: + properties: + agent_workspace_name: + example: example name + type: string + dataset_uuid: + description: Dataset against which the test‑case is executed. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + description: + description: Description of the test case. + example: example string + type: string + metrics: + description: Full metric list to use for evaluation test case. + example: + - example string + items: + example: example string + type: string + type: array + name: + description: Name of the test case. + example: example name + type: string + star_metric: + $ref: '#/components/schemas/apiStarMetric' + workspace_uuid: + description: The workspace uuid. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiCreateEvaluationTestCaseOutput: + properties: + test_case_uuid: + description: Test‑case UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiListEvaluationRunsByTestCaseOutput: + properties: + evaluation_runs: + description: List of evaluation runs. + items: + $ref: '#/components/schemas/apiEvaluationRun' + type: array + type: object + apiGetEvaluationTestCaseOutput: + properties: + evaluation_test_case: + $ref: '#/components/schemas/apiEvaluationTestCase' + type: object + apiEvaluationTestCaseMetricList: + properties: + metric_uuids: + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiUpdateEvaluationTestCaseInputPublic: + properties: + dataset_uuid: + description: Dataset against which the test‑case is executed. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + description: + description: Description of the test case. + example: example string + type: string + metrics: + $ref: '#/components/schemas/apiEvaluationTestCaseMetricList' + name: + description: Name of the test case. + example: example name + type: string + star_metric: + $ref: '#/components/schemas/apiStarMetric' + test_case_uuid: + description: Test-case UUID to update + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiUpdateEvaluationTestCaseOutput: + properties: + test_case_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + version: + description: The new verson of the test case. + example: 123 + format: int32 + type: integer + type: object + apiListKnowledgeBaseIndexingJobsOutput: + description: Indexing jobs + properties: + jobs: + description: The indexing jobs + items: + $ref: '#/components/schemas/apiIndexingJob' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiStartKnowledgeBaseIndexingJobInputPublic: + description: StartKnowledgeBaseIndexingJobInputPublic description + properties: + data_source_uuids: + description: >- + List of data source ids to index, if none are provided, all data + sources will be indexed + example: + - example string + items: + example: example string + type: string + type: array + knowledge_base_uuid: + description: Knowledge base id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiStartKnowledgeBaseIndexingJobOutput: + description: StartKnowledgeBaseIndexingJobOutput description + properties: + job: + $ref: '#/components/schemas/apiIndexingJob' + type: object + apiListIndexingJobDataSourcesOutput: + properties: + indexed_data_sources: + items: + $ref: '#/components/schemas/apiIndexedDataSource' + type: array + type: object + apiGetIndexingJobDetailsSignedURLOutput: + properties: + signed_url: + description: The signed url for downloading the indexing job details + example: example string + type: string + type: object + apiGetKnowledgeBaseIndexingJobOutput: + description: GetKnowledgeBaseIndexingJobOutput description + properties: + job: + $ref: '#/components/schemas/apiIndexingJob' + type: object + apiCancelKnowledgeBaseIndexingJobInputPublic: + description: CancelKnowledgeBaseIndexingJobInputPublic description + properties: + uuid: + description: A unique identifier for an indexing job. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiCancelKnowledgeBaseIndexingJobOutput: + description: CancelKnowledgeBaseIndexingJobOutput description + properties: + job: + $ref: '#/components/schemas/apiIndexingJob' + type: object + apiListKnowledgeBasesOutput: + description: List of knowledge bases + properties: + knowledge_bases: + description: The knowledge bases + items: + $ref: '#/components/schemas/apiKnowledgeBase' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiAWSDataSource: + description: AWS S3 Data Source + properties: + bucket_name: + description: Spaces bucket name + example: example name + type: string + item_path: + example: example string + type: string + key_id: + description: The AWS Key ID + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + region: + description: Region of bucket + example: example string + type: string + secret_key: + description: The AWS Secret Key + example: example string + type: string + type: object + apiChunkingAlgorithm: + default: CHUNKING_ALGORITHM_UNKNOWN + enum: + - CHUNKING_ALGORITHM_UNKNOWN + - CHUNKING_ALGORITHM_SECTION_BASED + - CHUNKING_ALGORITHM_HIERARCHICAL + - CHUNKING_ALGORITHM_SEMANTIC + - CHUNKING_ALGORITHM_FIXED_LENGTH + example: CHUNKING_ALGORITHM_UNKNOWN + type: string + apiChunkingOptions: + properties: + child_chunk_size: + example: 350 + format: int64 + type: integer + max_chunk_size: + description: Common options + example: 750 + format: int64 + type: integer + parent_chunk_size: + description: Hierarchical options + example: 1000 + format: int64 + type: integer + semantic_threshold: + description: Semantic options + example: 0.5 + format: float + type: number + type: object + apiDropboxDataSource: + description: Dropbox Data Source + properties: + folder: + example: example string + type: string + refresh_token: + description: >- + Refresh token. you can obrain a refresh token by following the + oauth2 flow. see /v2/gen-ai/oauth2/dropbox/tokens for reference. + example: example string + type: string + type: object + apiGoogleDriveDataSource: + description: Google Drive Data Source + properties: + folder_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + refresh_token: + description: >- + Refresh token. you can obrain a refresh token by following the + oauth2 flow. see /v2/gen-ai/oauth2/google/tokens for reference. + example: example string + type: string + type: object + apiSpacesDataSource: + description: Spaces Bucket Data Source + properties: + bucket_name: + description: Spaces bucket name + example: example name + type: string + item_path: + example: example string + type: string + region: + description: Region of bucket + example: example string + type: string + type: object + apiCrawlingOption: + default: UNKNOWN + description: |- + Options for specifying how URLs found on pages should be handled. + + - UNKNOWN: Default unknown value + - SCOPED: Only include the base URL. + - PATH: Crawl the base URL and linked pages within the URL path. + - DOMAIN: Crawl the base URL and linked pages within the same domain. + - SUBDOMAINS: Crawl the base URL and linked pages for any subdomain. + - SITEMAP: Crawl URLs discovered in the sitemap. + enum: + - UNKNOWN + - SCOPED + - PATH + - DOMAIN + - SUBDOMAINS + - SITEMAP + example: UNKNOWN + type: string + apiWebCrawlerDataSource: + description: WebCrawlerDataSource + properties: + base_url: + description: The base url to crawl. + example: example string + type: string + crawling_option: + $ref: '#/components/schemas/apiCrawlingOption' + embed_media: + description: Whether to ingest and index media (images, etc.) on web pages. + example: true + type: boolean + exclude_tags: + description: Declaring which tags to exclude in web pages while webcrawling + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiKBDataSource: + properties: + aws_data_source: + $ref: '#/components/schemas/apiAWSDataSource' + bucket_name: + description: Deprecated, moved to data_source_details + example: example name + type: string + bucket_region: + description: Deprecated, moved to data_source_details + example: example string + type: string + chunking_algorithm: + $ref: '#/components/schemas/apiChunkingAlgorithm' + chunking_options: + $ref: '#/components/schemas/apiChunkingOptions' + dropbox_data_source: + $ref: '#/components/schemas/apiDropboxDataSource' + file_upload_data_source: + $ref: '#/components/schemas/apiFileUploadDataSource' + google_drive_data_source: + $ref: '#/components/schemas/apiGoogleDriveDataSource' + item_path: + example: example string + type: string + spaces_data_source: + $ref: '#/components/schemas/apiSpacesDataSource' + web_crawler_data_source: + $ref: '#/components/schemas/apiWebCrawlerDataSource' + type: object + apiOpenSearchPlanSize: + default: OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED + enum: + - OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED + - OPEN_SEARCH_PLAN_SIZE_SMALL + - OPEN_SEARCH_PLAN_SIZE_MEDIUM + - OPEN_SEARCH_PLAN_SIZE_LARGE + - OPEN_SEARCH_PLAN_SIZE_EXTRA_LARGE + example: OPEN_SEARCH_PLAN_SIZE_UNSPECIFIED + type: string + apiCreateKnowledgeBaseInputPublic: + description: Data to create a new knowledge base. + properties: + database_id: + description: >- + Identifier of the DigitalOcean OpenSearch database this knowledge + base will use, optional. + + If not provided, we create a new database for the knowledge base in + + the same region as the knowledge base. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + datasources: + description: >- + Optional data sources to attach at creation. Omit or use an empty + list to create the knowledge base without sources, then add sources + (with chunking strategy and sizes) using [Add a Data Source to a + Knowledge Base](#operation/create_knowledge_base_data_source). When + provided, see [Organize Data + Sources](https://docs.digitalocean.com/products/gradient-ai-platform/how-to/create-manage-agent-knowledge-bases/#add-data-sources) + for best practices. + items: + $ref: '#/components/schemas/apiKBDataSource' + type: array + embedding_model_uuid: + description: >- + Identifier for the [embedding + model](https://docs.digitalocean.com/products/genai-platform/details/models/#embedding-models). + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Name of the knowledge base. + example: '"My Knowledge Base"' + type: string + project_id: + description: >- + Identifier of the DigitalOcean project this knowledge base will + belong to. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + region: + description: The datacenter region to deploy the knowledge base in. + example: '"tor1"' + type: string + reranking_config: + $ref: '#/components/schemas/apiRerankingConfiguration' + size: + $ref: '#/components/schemas/apiOpenSearchPlanSize' + tags: + description: Tags to organize your knowledge base. + example: + - example string + items: + example: example string + type: string + type: array + vpc_uuid: + description: The VPC to deploy the knowledge base database in + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiCreateKnowledgeBaseOutput: + description: Information about a newly created knowledge base + properties: + knowledge_base: + $ref: '#/components/schemas/apiKnowledgeBase' + type: object + apiAWSDataSourceDisplay: + description: AWS S3 Data Source for Display + properties: + bucket_name: + description: Spaces bucket name + example: example name + type: string + item_path: + example: example string + type: string + region: + description: Region of bucket + example: example string + type: string + type: object + apiDropboxDataSourceDisplay: + description: Dropbox Data Source for Display + properties: + folder: + example: example string + type: string + type: object + apiGoogleDriveDataSourceDisplay: + description: Google Drive Data Source for Display + properties: + folder_id: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + folder_name: + description: Name of the selected folder if available + example: example name + type: string + type: object + apiKnowledgeBaseDataSource: + description: Data Source configuration for Knowledge Bases + properties: + aws_data_source: + $ref: '#/components/schemas/apiAWSDataSourceDisplay' + bucket_name: + description: Name of storage bucket - Deprecated, moved to data_source_details + example: example name + type: string + chunking_algorithm: + $ref: '#/components/schemas/apiChunkingAlgorithm' + chunking_options: + $ref: '#/components/schemas/apiChunkingOptions' + created_at: + description: Creation date / time + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + dropbox_data_source: + $ref: '#/components/schemas/apiDropboxDataSourceDisplay' + file_upload_data_source: + $ref: '#/components/schemas/apiFileUploadDataSource' + google_drive_data_source: + $ref: '#/components/schemas/apiGoogleDriveDataSourceDisplay' + item_path: + description: >- + Path of folder or object in bucket - Deprecated, moved to + data_source_details + example: example string + type: string + last_datasource_indexing_job: + $ref: '#/components/schemas/apiIndexedDataSource' + region: + description: Region code - Deprecated, moved to data_source_details + example: example string + type: string + spaces_data_source: + $ref: '#/components/schemas/apiSpacesDataSource' + updated_at: + description: Last modified + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique id of knowledge base + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + web_crawler_data_source: + $ref: '#/components/schemas/apiWebCrawlerDataSource' + type: object + apiListKnowledgeBaseDataSourcesOutput: + description: A list of knowledge base data sources + properties: + knowledge_base_data_sources: + description: The data sources + items: + $ref: '#/components/schemas/apiKnowledgeBaseDataSource' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateKnowledgeBaseDataSourceInputPublic: + description: Data to create a knowledge base data source + properties: + aws_data_source: + $ref: '#/components/schemas/apiAWSDataSource' + chunking_algorithm: + $ref: '#/components/schemas/apiChunkingAlgorithm' + chunking_options: + $ref: '#/components/schemas/apiChunkingOptions' + knowledge_base_uuid: + description: Knowledge base id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + spaces_data_source: + $ref: '#/components/schemas/apiSpacesDataSource' + web_crawler_data_source: + $ref: '#/components/schemas/apiWebCrawlerDataSource' + type: object + apiCreateKnowledgeBaseDataSourceOutput: + description: Information about a newly created knowldege base data source + properties: + knowledge_base_data_source: + $ref: '#/components/schemas/apiKnowledgeBaseDataSource' + type: object + apiUpdateKnowledgeBaseDataSourceInputPublic: + description: >- + Update a data source of a knowledge base with change in chunking + algorithm/options + properties: + chunking_algorithm: + $ref: '#/components/schemas/apiChunkingAlgorithm' + chunking_options: + $ref: '#/components/schemas/apiChunkingOptions' + data_source_uuid: + description: Data Source ID (Path Parameter) + example: '"98765432-1234-1234-1234-123456789012"' + type: string + knowledge_base_uuid: + description: Knowledge Base ID (Path Parameter) + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiUpdateKnowledgeBaseDataSourceOutput: + description: >- + Update a data source of a knowledge base with change in chunking + algorithm/options + properties: + knowledge_base_data_source: + $ref: '#/components/schemas/apiKnowledgeBaseDataSource' + type: object + apiDeleteKnowledgeBaseDataSourceOutput: + description: Information about a newly deleted knowledge base data source + properties: + data_source_uuid: + description: Data source id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + knowledge_base_uuid: + description: Knowledge base id + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + dbaasClusterStatus: + default: CREATING + enum: + - CREATING + - ONLINE + - POWEROFF + - REBUILDING + - REBALANCING + - DECOMMISSIONED + - FORKING + - MIGRATING + - RESIZING + - RESTORING + - POWERING_ON + - UNHEALTHY + - UPGRADING + example: CREATING + type: string + apiGetKnowledgeBaseOutput: + description: The knowledge base + properties: + database_status: + $ref: '#/components/schemas/dbaasClusterStatus' + knowledge_base: + $ref: '#/components/schemas/apiKnowledgeBase' + type: object + apiUpdateKnowledgeBaseInputPublic: + description: Information about updating a knowledge base + properties: + database_id: + description: >- + The id of the DigitalOcean database this knowledge base will use, + optional. + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Knowledge base name + example: '"My Knowledge Base"' + type: string + project_id: + description: >- + The id of the DigitalOcean project this knowledge base will belong + to + example: '"12345678-1234-1234-1234-123456789012"' + type: string + reranking_config: + $ref: '#/components/schemas/apiRerankingConfiguration' + tags: + description: Tags to organize your knowledge base. + example: + - example string + items: + example: example string + type: string + type: array + uuid: + description: Knowledge base id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiUpdateKnowledgeBaseOutput: + description: Information about an updated knowledge base + properties: + knowledge_base: + $ref: '#/components/schemas/apiKnowledgeBase' + type: object + apiDeleteKnowledgeBaseOutput: + description: Information about a deleted knowledge base + properties: + uuid: + description: The id of the deleted knowledge base + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiCreateModelEvalDatasetUploadPresignedUrlsInputPublic: + description: >- + Public request for presigned upload URLs for model evaluation dataset + files. + properties: + files: + description: A list of files to generate presigned URLs for. + items: + $ref: '#/components/schemas/apiPresignedUrlFile' + type: array + type: object + apiListModelEvaluationMetricsOutput: + properties: + metrics: + description: List of model evaluation metrics + items: + $ref: '#/components/schemas/apiEvaluationMetric' + type: array + type: object + apiCandidateModelSource: + default: CANDIDATE_MODEL_SOURCE_SERVERLESS + description: >- + Whether inference runs against the serverless platform, a dedicated + deployment, or a model router. + enum: + - CANDIDATE_MODEL_SOURCE_SERVERLESS + - CANDIDATE_MODEL_SOURCE_DEDICATED + - CANDIDATE_MODEL_SOURCE_ROUTER + example: CANDIDATE_MODEL_SOURCE_SERVERLESS + type: string + apiModelEvaluationRunStatus: + default: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + description: Model Evaluation Run Statuses + enum: + - MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + - MODEL_EVALUATION_RUN_QUEUED + - MODEL_EVALUATION_RUN_RUNNING_DATASET + - MODEL_EVALUATION_RUN_EVALUATING_RESULTS + - MODEL_EVALUATION_RUN_CANCELLING + - MODEL_EVALUATION_RUN_CANCELLED + - MODEL_EVALUATION_RUN_SUCCESSFUL + - MODEL_EVALUATION_RUN_PARTIALLY_SUCCESSFUL + - MODEL_EVALUATION_RUN_FAILED + example: MODEL_EVALUATION_RUN_STATUS_UNSPECIFIED + type: string + apiModelEvaluationRunSummary: + description: >- + Model Evaluation Run Summary - lightweight view used in run history + list. + properties: + candidate_model_name: + description: Name of the candidate model being evaluated. + example: example name + type: string + candidate_model_source: + $ref: '#/components/schemas/apiCandidateModelSource' + candidate_model_uuid: + description: UUID of the candidate model being evaluated. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + created_at: + description: Timestamp when the run was created. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + dataset_name: + description: Name of the dataset used for evaluation. + example: example name + type: string + dataset_uuid: + description: UUID of the dataset used for evaluation. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + eval_run_uuid: + description: UUID of the evaluation run. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + judge_model_name: + example: example name + type: string + judge_model_uuid: + description: Judge model used to score responses. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + name: + description: Name of the evaluation run. + example: example name + type: string + status: + $ref: '#/components/schemas/apiModelEvaluationRunStatus' + type: object + apiListModelEvaluationRunsOutput: + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + runs: + description: Summary view of evaluation runs for the run history list. + items: + $ref: '#/components/schemas/apiModelEvaluationRunSummary' + type: array + type: object + apiCandidateInferenceConfig: + description: Inference configuration for the candidate model during evaluation. + properties: + max_tokens: + example: 123 + format: int64 + type: integer + stop_token: + example: example string + type: string + system_prompt: + example: example string + type: string + temperature: + example: 123 + format: float + type: number + type: object + apiCreateModelEvaluationRunInputPublic: + properties: + candidate_inference_config: + $ref: '#/components/schemas/apiCandidateInferenceConfig' + candidate_model_name: + description: |- + Model slug used to call the candidate model API. + For dedicated inference, this is the model slug from the deployment. + For serverless, this should match the model's internal name. + example: example name + type: string + candidate_model_source: + $ref: '#/components/schemas/apiCandidateModelSource' + candidate_model_uuid: + description: UUID of the candidate model to evaluate. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + dataset_uuid: + description: UUID of the dataset to use for evaluation. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + eval_preset_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + judge_model_uuid: + description: UUID of the judge model used to score responses. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + metric_uuids: + description: >- + UUIDs of metrics to evaluate (selected from + ListModelEvaluationMetrics). + example: + - example string + items: + example: example string + type: string + type: array + name: + example: example name + type: string + preset_name: + example: example name + type: string + save_as_preset: + description: |- + If true, saves the inline config as a reusable preset + Ignored when eval_preset_uuid is provided. + example: true + type: boolean + source: + description: Source of the run creation (api, sdk, cli). + example: example string + type: string + star_metric: + $ref: '#/components/schemas/apiStarMetric' + type: object + apiCreateModelEvaluationRunOutput: + properties: + eval_run_uuid: + description: UUID of the created evaluation run. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiModelEvaluationResult: + description: Result for a single prompt in a model evaluation run. + properties: + candidate_model_name: + example: example name + type: string + candidate_model_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + ground_truth: + example: example string + type: string + input: + description: The input query sent to the candidate model. + example: example string + type: string + metric_results: + description: Per-metric scores and judge reasoning for this prompt. + items: + $ref: '#/components/schemas/apiEvaluationMetricResult' + type: array + output: + description: The response from the candidate model. + example: example string + type: string + type: object + apiMetricResultSummary: + description: Per-metric aggregated pass/fail statistics across all prompts. + properties: + description: + example: example string + type: string + fail_percent: + example: 123 + format: double + type: number + metric_name: + example: example name + type: string + metric_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + pass_percent: + example: 123 + format: double + type: number + type: object + apiLatencyMetrics: + description: Latency metrics for candidate model invocations (in milliseconds). + properties: + avg_e2e_latency_ms: + description: Average end-to-end latency across all invocations. + example: 123 + format: double + type: number + max_e2e_latency_ms: + description: Maximum end-to-end latency observed. + example: 123 + format: double + type: number + min_e2e_latency_ms: + description: Minimum end-to-end latency observed. + example: 123 + format: double + type: number + p50_latency_ms: + description: P50 (median) latency. + example: 123 + format: double + type: number + p90_latency_ms: + description: P90 latency. + example: 123 + format: double + type: number + p95_latency_ms: + description: P95 latency. + example: 123 + format: double + type: number + type: object + apiTokenUsage: + properties: + total_candidate_input_tokens: + example: '12345' + format: uint64 + type: string + total_candidate_output_tokens: + example: '12345' + format: uint64 + type: string + total_candidate_tokens: + example: '12345' + format: uint64 + type: string + total_judge_input_tokens: + example: '12345' + format: uint64 + type: string + total_judge_output_tokens: + example: '12345' + format: uint64 + type: string + total_judge_tokens: + example: '12345' + format: uint64 + type: string + type: object + apiPerformanceMetrics: + description: >- + All performance metrics are for the candidate model unless noted + otherwise. + properties: + candidate_latency: + $ref: '#/components/schemas/apiLatencyMetrics' + token_usage: + $ref: '#/components/schemas/apiTokenUsage' + type: object + apiPerModelResultSummary: + description: Per-model breakdown of evaluation results for router evaluations. + properties: + metric_summaries: + description: Per-metric pass/fail for only this model's prompts. + items: + $ref: '#/components/schemas/apiMetricResultSummary' + type: array + model_name: + description: Name/slug of the model (matches routed_model from results). + example: example name + type: string + performance_metrics: + $ref: '#/components/schemas/apiPerformanceMetrics' + prompt_count: + description: Number of prompts routed to this model. + example: 123 + format: int64 + type: integer + type: object + apiPerModelResultSummaries: + description: >- + Wrapper for per-model summaries, used inside a oneof on + ModelEvaluationRunResultSummary. + properties: + summaries: + items: + $ref: '#/components/schemas/apiPerModelResultSummary' + type: array + type: object + apiTokenPricing: + description: Token pricing breakdown for a single model. + properties: + input_cost: + description: Cost of input tokens. + example: 123 + format: double + type: number + output_cost: + description: Cost of output tokens. + example: 123 + format: double + type: number + total_cost: + description: Total cost (input + output). + example: 123 + format: double + type: number + type: object + apiModelPricingEntry: + description: Pricing entry for a specific model. + properties: + model_name: + description: Model name (for display purposes). + example: example name + type: string + model_uuid: + description: Model UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + pricing: + $ref: '#/components/schemas/apiTokenPricing' + prompt_count: + description: Number of prompts/rows routed to this model. + example: 123 + format: int64 + type: integer + type: object + apiEvaluationPricing: + description: Pricing breakdown for an evaluation run. + properties: + currency: + description: Currency code (e.g., "USD"). + example: example string + type: string + judge_model_pricing: + $ref: '#/components/schemas/apiTokenPricing' + per_candidate_model_pricing: + description: Pricing per candidate model. + items: + $ref: '#/components/schemas/apiModelPricingEntry' + type: array + total_cost: + description: Total cost of the evaluation run (all candidates + judge). + example: 123 + format: double + type: number + type: object + apiStarMetricSummary: + description: Star metric summary with identifying details and threshold. + properties: + metric_name: + example: example name + type: string + metric_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + threshold: + example: 123 + format: float + type: number + type: object + apiModelEvaluationRunResultSummary: + description: Aggregated result summary for a completed model evaluation run. + properties: + end_time: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + metric_summaries: + description: Per-metric aggregated pass/fail statistics. + items: + $ref: '#/components/schemas/apiMetricResultSummary' + type: array + overall_score_percent: + example: 123 + format: double + type: number + per_model_summaries: + $ref: '#/components/schemas/apiPerModelResultSummaries' + performance_metrics: + $ref: '#/components/schemas/apiPerformanceMetrics' + pricing: + $ref: '#/components/schemas/apiEvaluationPricing' + star_metric_summary: + $ref: '#/components/schemas/apiStarMetricSummary' + start_time: + description: Run timing. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + total_duration_seconds: + description: Total wall-clock duration in seconds. + example: 123 + format: int64 + type: integer + type: object + apiModelEvaluationRunDetail: + description: >- + Model Evaluation Run Detail - full view returned when fetching a + specific run. + properties: + candidate_inference_config: + $ref: '#/components/schemas/apiCandidateInferenceConfig' + candidate_model_name: + example: example name + type: string + candidate_model_source: + $ref: '#/components/schemas/apiCandidateModelSource' + candidate_model_uuid: + description: Candidate model being evaluated. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + completed_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + dataset_name: + example: example name + type: string + dataset_uuid: + description: Dataset used for the evaluation. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + error_description: + description: Error description if the run failed or partially succeeded. + example: example string + type: string + eval_preset_name: + example: example name + type: string + eval_preset_uuid: + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + eval_run_uuid: + description: UUID of the evaluation run. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + judge_model_name: + example: example name + type: string + judge_model_uuid: + description: Judge model used to score responses. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + metrics: + description: Metrics selected for this evaluation. + items: + $ref: '#/components/schemas/apiEvaluationMetric' + type: array + name: + description: Name of the evaluation run. + example: example name + type: string + result_summary: + $ref: '#/components/schemas/apiModelEvaluationRunResultSummary' + star_metric: + $ref: '#/components/schemas/apiStarMetric' + started_at: + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + status: + $ref: '#/components/schemas/apiModelEvaluationRunStatus' + type: object + apiGetModelEvaluationRunOutput: + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + results: + description: Paginated per-prompt evaluation results. + items: + $ref: '#/components/schemas/apiModelEvaluationResult' + type: array + run: + $ref: '#/components/schemas/apiModelEvaluationRunDetail' + type: object + apiGetModelEvaluationRunResultsDownloadURLOutput: + description: >- + Response containing a presigned download URL for model evaluation run + results. + properties: + download_url: + description: >- + The presigned URL to download the gzip-compressed JSON results file + (.json.gz). + example: example string + type: string + expires_at: + description: The time the URL expires at. + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + type: object + apiModelPricing: + description: Pricing per million tokens (aligns with existing ModelPrice pattern) + properties: + input_price_per_million: + example: 0.6 + format: double + type: number + output_price_per_million: + example: 0.9 + format: double + type: number + price_per_audio: + example: 0.002 + format: double + type: number + price_per_image: + description: >- + Unit-based pricing for non-token models (e.g., Fal AI + image/video/audio + + generation, speech models). At most one of these is typically + populated + + per model. Token-based models (chat, embeddings) leave all of these + at 0 + + and populate input_price_per_million / output_price_per_million + instead. + example: 0.003 + format: double + type: number + price_per_megapixel: + example: 0.00003 + format: double + type: number + price_per_second: + example: 0.0001 + format: double + type: number + price_per_thousand_characters: + example: 0.015 + format: double + type: number + price_per_video: + example: 0.05 + format: double + type: number + type: object + apiModelPublic: + description: A machine learning model stored on the GenAI platform + properties: + agreement: + $ref: '#/components/schemas/apiAgreement' + benchmark_score: + description: Benchmark scores for this model, stored as arbitrary JSON + type: object + capabilities: + description: Model capabilities (inference, reasoning, vectorization, etc.) + example: + - example string + items: + example: example string + type: string + type: array + context_window: + description: Context window (maximum tokens) + example: '12345' + format: int64 + type: string + created_at: + description: Creation date / time + example: '2021-01-01T00:00:00Z' + format: date-time + type: string + description: + description: Model description + example: example string + type: string + endpoints: + description: Available endpoints and their capabilities + items: + $ref: '#/components/schemas/apiModelEndpoint' + type: array + id: + description: Human-readable model identifier + example: llama3.3-70b-instruct + type: string + is_foundational: + description: True if it is a foundational model provided by do + example: true + type: boolean + kb_default_chunk_size: + description: Default chunking size limit to show in UI + example: 123 + format: int64 + type: integer + kb_max_chunk_size: + description: Maximum chunk size limit of model + example: 123 + format: int64 + type: integer + kb_min_chunk_size: + description: >- + Minimum chunking size token limits if model supports KNOWLEDGEBASE + usecase + example: 123 + format: int64 + type: integer + lifecycle_status: + description: >- + Lifecycle status of the model (internal, public-preview, active, + deprecated, end_of_life) + example: active + type: string + modalities: + $ref: '#/components/schemas/apiModelModalities' + model_availability: + description: Model availability (serverless, dedicated, etc.) + example: example string + type: string + name: + description: Display name of the model + example: Llama 3.3 Instruct (70B) + type: string + parameter_count: + description: Parameter count in billions + example: 123 + format: float + type: number + parent_uuid: + description: Unique id of the model, this model is based on + example: '"12345678-1234-1234-1234-123456789012"' + type: string + pricing: + $ref: '#/components/schemas/apiModelPricing' + provider: + $ref: '#/components/schemas/apiModelProvider' + reasoning_efforts: + description: Available reasoning efforts for this model + example: + - example string + items: + example: example string + type: string + type: array + settings: + description: Playground settings derived from model metadata + items: + $ref: '#/components/schemas/apiModelSetting' + type: array + thinking: + description: Whether this model supports extended thinking (Anthropic models) + example: true + type: boolean + type: + description: Model type (chat, embedding, image, reasoning, coding) + example: example string + type: string + updated_at: + description: Last modified + example: '2021-01-01T00:00:00Z' + format: date-time + type: string + upload_complete: + description: Model has been fully uploaded + example: true + type: boolean + url: + description: Download url + example: https://example.com/model.zip + type: string + uuid: + description: Unique id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + version: + $ref: '#/components/schemas/apiModelVersion' + type: object + apiListModelsOutputPublic: + description: A list of models + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + models: + description: The models + items: + $ref: '#/components/schemas/apiModelPublic' + type: array + type: object + apiModelAPIKeyInfo: + description: Model API Key Info + properties: + created_at: + description: Creation date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + created_by: + description: Created by + example: '12345' + format: uint64 + type: string + deleted_at: + description: Deleted date + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + name: + description: Name + example: example name + type: string + secret_key: + example: example string + type: string + uuid: + description: Uuid + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiListModelAPIKeysOutput: + properties: + api_key_infos: + description: Api key infos + items: + $ref: '#/components/schemas/apiModelAPIKeyInfo' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateModelAPIKeyInputPublic: + properties: + name: + description: A human friendly name to identify the key + example: Production Key + type: string + type: object + apiCreateModelAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiModelAPIKeyInfo' + type: object + apiUpdateModelAPIKeyInputPublic: + properties: + api_key_uuid: + description: API key ID + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Name + example: '"Production Key"' + type: string + type: object + apiUpdateModelAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiModelAPIKeyInfo' + type: object + apiDeleteModelAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiModelAPIKeyInfo' + type: object + apiRegenerateModelAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiModelAPIKeyInfo' + type: object + apiModelCatalogEntry: + description: List item for ListModelCatalog + properties: + availability: + example: + - example string + items: + example: example string + type: string + type: array + benchmark_score: + description: Benchmark scores for this model, stored as arbitrary JSON + type: object + capabilities: + example: + - example string + items: + example: example string + type: string + type: array + context_window: + description: Specs (flat) + example: '128000' + format: int64 + type: string + creator: + description: Model creator/developer (e.g., "Meta", "Anthropic", "OpenAI") + example: '"Meta"' + type: string + id: + description: Identity + example: '"506a3371-88d0-4047-9212-e2079497ac68"' + type: string + model_id: + description: Model identifier used for API calls (e.g., "llama3.1-70b-instruct") + example: '"llama3.1-70b-instruct"' + type: string + name: + example: '"Llama 3.1 70B"' + type: string + parameter_count: + example: 70 + format: float + type: number + pricing: + $ref: '#/components/schemas/apiModelPricing' + provider: + $ref: '#/components/schemas/apiModelProvider' + short_description: + example: '"Fast, efficient model for general tasks"' + type: string + type: + example: '"text-to-text"' + type: string + type: object + apiListModelCatalogOutput: + properties: + data: + items: + $ref: '#/components/schemas/apiModelCatalogEntry' + type: array + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCodeSnippets: + description: Code examples for using the model + properties: + curl: + example: example string + type: string + javascript: + example: example string + type: string + python: + example: example string + type: string + sdk: + example: example string + type: string + type: object + apiModelCatalogCard: + description: Detail view for GetModelCatalogCard + properties: + availability: + example: + - example string + items: + example: example string + type: string + type: array + benchmark_score: + description: Benchmark scores for this model, stored as arbitrary JSON + type: object + capabilities: + example: + - example string + items: + example: example string + type: string + type: array + code_snippets: + $ref: '#/components/schemas/apiCodeSnippets' + context_window: + description: Specs (same as Entry) + example: '128000' + format: int64 + type: string + creator: + description: Model creator/developer (e.g., "Meta", "Anthropic", "OpenAI") + example: '"Meta"' + type: string + description: + description: Card-specific + example: '"Claude Sonnet 4 is Anthropic''s most capable model..."' + type: string + id: + description: Identity (same as Entry) + example: '"506a3371-88d0-4047-9212-e2079497ac68"' + type: string + modalities: + $ref: '#/components/schemas/apiModelModalities' + model_id: + description: Model identifier used for API calls (e.g., "llama3.1-70b-instruct") + example: '"llama3.1-70b-instruct"' + type: string + name: + example: '"Llama 3.1 70B"' + type: string + parameter_count: + example: 70 + format: float + type: number + pricing: + $ref: '#/components/schemas/apiModelPricing' + provider: + $ref: '#/components/schemas/apiModelProvider' + short_description: + example: '"Fast, efficient model for general tasks"' + type: string + type: + example: '"text-to-text"' + type: string + type: object + apiGetModelCatalogCardOutput: + properties: + data: + $ref: '#/components/schemas/apiModelCatalogCard' + type: object + apiListModelRoutersOutput: + description: List of model routers + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + model_routers: + description: The model routers + items: + $ref: '#/components/schemas/apiModelRouter' + type: array + type: object + apiCreateModelRouterInputPublic: + description: Create a model router + properties: + description: + description: Model router description + example: '"My Model Router Description"' + type: string + fallback_models: + description: Fallback models + example: + - example string + items: + example: example string + type: string + type: array + name: + description: Model router name + example: '"My Model Router"' + type: string + policies: + description: Router policies + items: + $ref: '#/components/schemas/apiModelRouterTaskPolicy' + type: array + regions: + description: Target regions for the router + example: + - example string + items: + example: example string + type: string + type: array + type: object + apiCreateModelRouterOutput: + description: Information about a newly created model router + properties: + model_router: + $ref: '#/components/schemas/apiModelRouter' + type: object + apiModelRouterPreset: + description: Model router preset used to prefill new router configurations. + properties: + config: + $ref: '#/components/schemas/apiModelRouterConfig' + display_name: + description: Display name for UI surfaces + example: example name + type: string + long_description: + description: Long description for details views + example: example string + type: string + short_description: + description: Short description for list views + example: example string + type: string + slug: + description: Stable slug for routing usage + example: example string + type: string + type: object + apiListModelRouterPresetsOutput: + description: List of model router presets + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + presets: + description: The model router presets + items: + $ref: '#/components/schemas/apiModelRouterPreset' + type: array + type: object + apiModelRouterTaskPreset: + description: Task preset that can be referenced by slug in model router policies. + properties: + category: + description: Higher-level grouping used by the UI + example: example string + type: string + description: + description: Task description + example: example string + type: string + models: + description: Default models assigned to this task + example: + - example string + items: + example: example string + type: string + type: array + name: + description: Display name + example: example name + type: string + selection_policy: + $ref: '#/components/schemas/apiModelRouterSelectionPolicy' + tags: + description: Lightweight labels for filtering + example: + - example string + items: + example: example string + type: string + type: array + task_slug: + description: Task slug + example: example string + type: string + type: object + apiListModelRouterTaskPresetsOutput: + description: List of model router task presets + properties: + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + tasks: + description: The task presets + items: + $ref: '#/components/schemas/apiModelRouterTaskPreset' + type: array + type: object + apiGetModelRouterOutput: + description: The model router + properties: + model_router: + $ref: '#/components/schemas/apiModelRouter' + type: object + apiUpdateModelRouterInputPublic: + description: Information about updating a model router + properties: + description: + description: Model router description + example: '"My Model Router Description"' + type: string + fallback_models: + items: + type: object + type: array + name: + description: Model router name + example: '"My Model Router"' + type: string + policies: + description: Router policies + items: + $ref: '#/components/schemas/apiModelRouterTaskPolicy' + type: array + regions: + description: Target regions for the router + example: + - example string + items: + example: example string + type: string + type: array + uuid: + description: Model router id + example: '"12345678-1234-1234-1234-123456789012"' + type: string + type: object + apiUpdateModelRouterOutput: + description: Information about an updated model router + properties: + model_router: + $ref: '#/components/schemas/apiModelRouter' + type: object + apiDeleteModelRouterOutput: + description: Information about a deleted model router + properties: + uuid: + description: The id of the deleted model router + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiDropboxOauth2GetTokensInput: + description: The oauth2 code from google + properties: + code: + description: The oauth2 code from google + example: example string + type: string + redirect_url: + description: Redirect url + example: example string + type: string + type: object + apiDropboxOauth2GetTokensOutput: + description: The dropbox oauth2 token and refresh token + properties: + refresh_token: + description: The refresh token + example: example string + type: string + token: + description: The access token + example: example string + type: string + type: object + apiGenerateOauth2URLOutput: + description: The url for the oauth2 flow + properties: + url: + description: The oauth2 url + example: example string + type: string + type: object + apiListOpenAIAPIKeysOutput: + description: >- + ListOpenAIAPIKeysOutput is used to return the list of OpenAI API keys + for a specific agent. + properties: + api_key_infos: + description: Api key infos + items: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiCreateOpenAIAPIKeyInputPublic: + description: >- + CreateOpenAIAPIKeyInputPublic is used to create a new OpenAI API key for + a specific agent. + properties: + api_key: + description: OpenAI API key + example: '"sk-proj--123456789098765432123456789"' + type: string + name: + description: Name of the key + example: '"Production Key"' + type: string + type: object + apiCreateOpenAIAPIKeyOutput: + description: >- + CreateOpenAIAPIKeyOutput is used to return the newly created OpenAI API + key. + properties: + api_key_info: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + type: object + apiGetOpenAIAPIKeyOutput: + properties: + api_key_info: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + type: object + apiUpdateOpenAIAPIKeyInputPublic: + description: >- + UpdateOpenAIAPIKeyInputPublic is used to update an existing OpenAI API + key for a specific agent. + properties: + api_key: + description: OpenAI API key + example: '"sk-ant-12345678901234567890123456789012"' + type: string + api_key_uuid: + description: API key ID + example: '"12345678-1234-1234-1234-123456789012"' + type: string + name: + description: Name of the key + example: '"Production Key"' + type: string + type: object + apiUpdateOpenAIAPIKeyOutput: + description: UpdateOpenAIAPIKeyOutput is used to return the updated OpenAI API key. + properties: + api_key_info: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + type: object + apiDeleteOpenAIAPIKeyOutput: + description: DeleteOpenAIAPIKeyOutput is used to return the deleted OpenAI API key. + properties: + api_key_info: + $ref: '#/components/schemas/apiOpenAIAPIKeyInfo' + type: object + apiListAgentsByOpenAIKeyOutput: + description: List of Agents that are linked to a specific OpenAI Key + properties: + agents: + items: + $ref: '#/components/schemas/apiAgent' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + genaiapiRegion: + description: Description for a specific Region + properties: + inference_url: + description: Url for inference server + example: example string + type: string + region: + description: Region code + example: example string + type: string + serves_batch: + description: This datacenter is capable of running batch jobs + example: true + type: boolean + serves_inference: + description: This datacenter is capable of serving inference + example: true + type: boolean + stream_inference_url: + description: The url for the inference streaming server + example: example string + type: string + type: object + apiListRegionsOutput: + description: Region Codes + properties: + regions: + description: Region code + items: + $ref: '#/components/schemas/genaiapiRegion' + type: array + type: object + apiCreateScheduledIndexingInputPublic: + properties: + days: + description: >- + Days for execution (day is represented same as in a cron expression, + e.g. Monday begins with 1 ) + items: + example: 123 + format: int32 + type: integer + type: array + knowledge_base_uuid: + description: Knowledge base uuid for which the schedule is created + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + time: + description: Time of execution (HH:MM) UTC + example: example string + type: string + type: object + apiScheduledIndexingInfo: + description: Metadata for scheduled indexing entries + properties: + created_at: + description: Created at timestamp + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + days: + description: >- + Days for execution (day is represented same as in a cron expression, + e.g. Monday begins with 1 ) + items: + example: 123 + format: int32 + type: integer + type: array + deleted_at: + description: Deleted at timestamp (if soft deleted) + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + is_active: + description: Whether the schedule is currently active + example: true + type: boolean + knowledge_base_uuid: + description: Knowledge base uuid associated with this schedule + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + last_ran_at: + description: Last time the schedule was executed + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + next_run_at: + description: Next scheduled run + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + time: + description: Scheduled time of execution (HH:MM:SS format) + example: example string + type: string + updated_at: + description: Updated at timestamp + example: '2023-01-01T00:00:00Z' + format: date-time + type: string + uuid: + description: Unique identifier for the scheduled indexing entry + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiCreateScheduledIndexingOutput: + properties: + indexing_info: + $ref: '#/components/schemas/apiScheduledIndexingInfo' + type: object + apiGetScheduledIndexingOutput: + properties: + indexing_info: + $ref: '#/components/schemas/apiScheduledIndexingInfo' + type: object + apiDeleteScheduledIndexingOutput: + properties: + indexing_info: + $ref: '#/components/schemas/apiScheduledIndexingInfo' + type: object + apiListWorkspacesOutput: + properties: + workspaces: + description: Workspaces + items: + $ref: '#/components/schemas/apiWorkspace' + type: array + type: object + apiCreateWorkspaceInputPublic: + description: Parameters for Workspace Creation + properties: + agent_uuids: + description: Ids of the agents(s) to attach to the workspace + example: + - example string + items: + example: example string + type: string + type: array + description: + description: Description of the workspace + example: example string + type: string + name: + description: Name of the workspace + example: example name + type: string + type: object + apiCreateWorkspaceOutput: + properties: + workspace: + $ref: '#/components/schemas/apiWorkspace' + type: object + apiGetWorkspaceOutput: + properties: + workspace: + $ref: '#/components/schemas/apiWorkspace' + type: object + apiUpdateWorkspaceInputPublic: + description: Parameters for Update Workspace + properties: + description: + description: The new description of the workspace + example: example string + type: string + name: + description: The new name of the workspace + example: example name + type: string + workspace_uuid: + description: Workspace UUID. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiUpdateWorkspaceOutput: + properties: + workspace: + $ref: '#/components/schemas/apiWorkspace' + type: object + apiDeleteWorkspaceOutput: + properties: + workspace_uuid: + description: Workspace + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiListAgentsByWorkspaceOutput: + properties: + agents: + items: + $ref: '#/components/schemas/apiAgent' + type: array + links: + $ref: '#/components/schemas/apiLinks' + meta: + $ref: '#/components/schemas/apiMeta' + type: object + apiMoveAgentsToWorkspaceInputPublic: + description: Parameters for Moving agents to a Workspace + properties: + agent_uuids: + description: Agent uuids + example: + - example string + items: + example: example string + type: string + type: array + workspace_uuid: + description: Workspace uuid to move agents to + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + type: object + apiMoveAgentsToWorkspaceOutput: + properties: + workspace: + $ref: '#/components/schemas/apiWorkspace' + type: object + apiListEvaluationTestCasesByWorkspaceOutput: + properties: + evaluation_test_cases: + items: + $ref: '#/components/schemas/apiEvaluationTestCase' + type: array + type: object + chat_completion_tool_call: + type: object + required: + - id + - type + - function + properties: + id: + type: string + description: The ID of the tool call. + example: call_abc123 + type: + type: string + enum: + - function + description: The type of the tool. Currently, only function is supported. + example: function + function: + type: object + required: + - name + - arguments + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + arguments: + type: string + description: >- + The arguments to call the function with, as generated by the + model in JSON format. + example: '{"location": "Boston"}' + chat_message: + type: object + description: A message in the chat conversation. + required: + - role + properties: + role: + type: string + description: The role of the message author. + enum: + - system + - developer + - user + - assistant + - tool + example: user + content: + type: string + nullable: true + description: The contents of the message. + example: Hello, how are you? + refusal: + type: string + nullable: true + description: >- + The refusal message generated by the model (assistant messages + only). + example: null + tool_calls: + type: array + description: The tool calls generated by the model (assistant messages only). + items: + $ref: '#/components/schemas/chat_completion_tool_call' + tool_call_id: + type: string + description: Tool call that this message is responding to (tool messages only). + example: call_abc123 + reasoning_content: + type: string + nullable: true + description: >- + The reasoning content generated by the model (assistant messages + only). + example: null + function_object: + type: object + required: + - name + properties: + name: + type: string + description: >- + The name of the function to be called. Must be a-z, A-Z, 0-9, or + contain underscores and dashes, with a maximum length of 64. + example: get_weather + description: + type: string + description: >- + A description of what the function does, used by the model to choose + when and how to call the function. + example: Get the current weather for a location. + parameters: + type: object + description: >- + The parameters the function accepts, described as a JSON Schema + object. + additionalProperties: true + chat_completion_tool: + type: object + required: + - type + - function + properties: + type: + type: string + enum: + - function + description: The type of the tool. Currently, only function is supported. + example: function + function: + $ref: '#/components/schemas/function_object' + chat_completion_request: + type: object + required: + - model + - messages + properties: + messages: + description: A list of messages comprising the conversation so far. + type: array + minItems: 1 + items: + $ref: '#/components/schemas/chat_message' + model: + description: Model ID used to generate the response. + type: string + example: llama3-8b-instruct + max_tokens: + type: integer + minimum: 0 + nullable: true + description: > + The maximum number of tokens that can be generated in the + completion. The token count of your prompt plus max_tokens cannot + exceed the model's context length. + max_completion_tokens: + type: integer + nullable: true + minimum: 256 + description: > + The maximum number of completion tokens that may be used over the + course of the run. The run will make a best effort to use only the + number of completion tokens specified, across multiple turns of the + run. + frequency_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on their existing frequency in the text so far, decreasing the + model's likelihood to repeat the same line verbatim. + presence_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on whether they appear in the text so far, increasing the + model's likelihood to talk about new topics. + top_logprobs: + type: integer + minimum: 0 + maximum: 20 + nullable: true + description: > + An integer between 0 and 20 specifying the number of most likely + tokens to return at each token position, each with an associated log + probability. logprobs must be set to true if this parameter is used. + tools: + type: array + description: >- + A list of tools the model may call. Currently, only functions are + supported as a tool. + items: + $ref: '#/components/schemas/chat_completion_tool' + tool_choice: + description: > + Controls which (if any) tool is called by the model. none means the + model will not call any tool and instead generates a message. auto + means the model can pick between generating a message or calling one + or more tools. required means the model must call one or more tools. + Specifying a particular tool via {"type": "function", "function": + {"name": "my_function"}} forces the model to call that tool. none is + the default when no tools are present. auto is the default if tools + are present. + oneOf: + - type: string + enum: + - none + - auto + - required + - type: object + description: Force a specific tool to be called. + required: + - type + - function + properties: + type: + type: string + enum: + - function + example: function + function: + type: object + required: + - name + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + stream: + type: boolean + nullable: true + default: false + description: > + If set to true, the model response data will be streamed to the + client as it is generated using server-sent events. + stop: + description: > + Up to 4 sequences where the API will stop generating further tokens. + The returned text will not contain the stop sequence. + default: null + oneOf: + - type: string + - type: array + minItems: 1 + maxItems: 4 + items: + type: string + logit_bias: + type: object + default: null + nullable: true + additionalProperties: + type: integer + description: > + Modify the likelihood of specified tokens appearing in the + completion. Accepts a JSON object that maps tokens (specified by + their token ID in the tokenizer) to an associated bias value from + -100 to 100. Mathematically, the bias is added to the logits + generated by the model prior to sampling. The exact effect will vary + per model, but values between -1 and 1 should decrease or increase + likelihood of selection; values like -100 or 100 should result in a + ban or exclusive selection of the relevant token. + logprobs: + type: boolean + default: false + nullable: true + description: > + Whether to return log probabilities of the output tokens or not. If + true, returns the log probabilities of each output token returned in + the content of message. + 'n': + type: integer + minimum: 1 + maximum: 128 + default: 1 + example: 1 + nullable: true + description: >- + How many chat completion choices to generate for each input message. + Note that you will be charged based on the number of generated + tokens across all of the choices. Keep n as 1 to minimize costs. + stream_options: + description: >- + Options for streaming response. Only set this when you set stream to + true. + type: object + nullable: true + default: null + properties: + include_usage: + type: boolean + description: >- + If set, an additional chunk will be streamed before the data + [DONE] message. The usage field on this chunk shows the token + usage statistics for the entire request, and the choices field + will always be an empty array. + reasoning_effort: + type: string + nullable: true + description: > + Constrains effort on reasoning for reasoning models. Reducing + reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. + enum: + - none + - minimal + - low + - medium + - high + - xhigh + seed: + type: integer + nullable: true + description: > + If specified, the system will make a best effort to sample + deterministically, such that repeated requests with the same seed + and parameters should return the same result. Determinism is not + guaranteed. + metadata: + type: object + nullable: true + description: >- + Set of 16 key-value pairs that can be attached to an object. This + can be useful for storing additional information about the object in + a structured format. Keys are strings with a maximum length of 64 + characters. Values are strings with a maximum length of 512 + characters. + additionalProperties: + type: string + temperature: + type: number + minimum: 0 + maximum: 2 + example: 1 + nullable: true + description: > + What sampling temperature to use, between 0 and 2. Higher values + like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. We generally + recommend altering this or top_p but not both. + top_p: + type: number + minimum: 0 + maximum: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. So 0.1 means only the tokens comprising the + top 10% probability mass are considered. We generally recommend + altering this or temperature but not both. + user: + type: string + example: user-1234 + description: >- + A unique identifier representing your end-user, which can help + DigitalOcean to monitor and detect abuse. + chat_completion_top_logprob_item: + type: object + required: + - token + - logprob + - bytes + properties: + token: + type: string + description: The token. + example: Hello + logprob: + type: number + description: The log probability of this token. + example: -1.2345 + bytes: + type: array + nullable: true + items: + type: integer + chat_completion_token_logprob: + type: object + required: + - token + - logprob + - bytes + - top_logprobs + properties: + token: + type: string + description: The token. + example: Hello + logprob: + type: number + description: >- + The log probability of this token, if it is within the top 20 most + likely tokens. Otherwise, the value -9999.0 is used to signify that + the token is very unlikely. + example: -1.2345 + bytes: + type: array + nullable: true + description: >- + A list of integers representing the UTF-8 bytes representation of + the token. Can be null if there is no bytes representation for the + token. + items: + type: integer + top_logprobs: + type: array + description: >- + List of the most likely tokens and their log probability, at this + token position. + items: + $ref: '#/components/schemas/chat_completion_top_logprob_item' + completion_usage: + type: object + description: Usage statistics for the completion request. + required: + - prompt_tokens + - completion_tokens + - total_tokens + - cache_created_input_tokens + - cache_read_input_tokens + - cache_creation + properties: + completion_tokens: + type: integer + default: 0 + description: Number of tokens in the generated completion. + example: 20 + prompt_tokens: + type: integer + default: 0 + description: Number of tokens in the prompt. + example: 10 + cache_created_input_tokens: + type: integer + default: 0 + description: Number of prompt tokens written to cache. + example: 0 + cache_creation: + type: object + description: Breakdown of prompt tokens written to cache. + required: + - ephemeral_5m_input_tokens + - ephemeral_1h_input_tokens + properties: + ephemeral_5m_input_tokens: + type: integer + default: 0 + description: Number of prompt tokens written to 5m cache. + example: 0 + ephemeral_1h_input_tokens: + type: integer + default: 0 + description: Number of prompt tokens written to 1h cache. + example: 0 + cache_read_input_tokens: + type: integer + default: 0 + description: Number of prompt tokens read from cache. + example: 0 + total_tokens: + type: integer + default: 0 + description: Total number of tokens used in the request (prompt + completion). + example: 30 + chat_completion_response: + type: object + description: >- + Represents a chat completion response returned by model, based on the + provided input. + required: + - choices + - created + - id + - model + - object + properties: + id: + type: string + description: A unique identifier for the chat completion. + example: chatcmpl-abc123 + choices: + type: array + description: >- + A list of chat completion choices. Can be more than one if n is + greater than 1. + items: + type: object + required: + - finish_reason + - index + - message + - logprobs + properties: + finish_reason: + type: string + description: > + The reason the model stopped generating tokens. stop if the + model hit a natural stop point or a provided stop sequence, + length if the maximum number of tokens specified in the + request was reached, tool_calls if the model called a tool. + enum: + - stop + - length + - tool_calls + - content_filter + example: stop + index: + type: integer + description: The index of the choice in the list of choices. + example: 0 + message: + type: object + description: A chat completion message generated by the model. + required: + - role + - content + - refusal + - reasoning_content + properties: + content: + type: string + nullable: true + description: The contents of the message. + example: Hello! How can I help you today? + refusal: + type: string + nullable: true + description: The refusal message generated by the model. + example: '' + tool_calls: + type: array + description: >- + The tool calls generated by the model, such as function + calls. + items: + type: object + required: + - id + - type + - function + properties: + id: + type: string + description: The ID of the tool call. + example: call_abc123 + type: + type: string + enum: + - function + description: The type of the tool. + example: function + function: + type: object + required: + - name + - arguments + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + arguments: + type: string + description: The arguments to call the function with. + example: '{"location": "Boston"}' + reasoning_content: + type: string + nullable: true + description: The reasoning content generated by the model. + example: '' + role: + type: string + enum: + - assistant + description: The role of the author of this message. + example: assistant + logprobs: + type: object + nullable: true + description: Log probability information for the choice. + properties: + content: + type: array + nullable: true + description: >- + A list of message content tokens with log probability + information. + items: + $ref: '#/components/schemas/chat_completion_token_logprob' + refusal: + type: array + nullable: true + description: >- + A list of message refusal tokens with log probability + information. + items: + $ref: '#/components/schemas/chat_completion_token_logprob' + required: + - content + - refusal + created: + type: integer + description: >- + The Unix timestamp (in seconds) of when the chat completion was + created. + example: 1677649420 + model: + type: string + description: The model used for the chat completion. + example: llama3-8b-instruct + object: + type: string + description: The object type, which is always chat.completion. + enum: + - chat.completion + example: chat.completion + usage: + $ref: '#/components/schemas/completion_usage' + chat_completion_tool_call_chunk: + type: object + properties: + index: + type: integer + example: 0 + id: + type: string + description: The ID of the tool call. + example: call_abc123 + type: + type: string + enum: + - function + example: function + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + arguments: + type: string + description: The arguments to call the function with. + example: '{"location":' + chat_completion_stream_response_delta: + type: object + description: A chat completion delta generated by streamed model responses. + properties: + content: + type: string + nullable: true + description: The contents of the chunk message. + example: Hello + tool_calls: + type: array + items: + $ref: '#/components/schemas/chat_completion_tool_call_chunk' + reasoning_content: + type: string + nullable: true + description: The reasoning content generated by the model. + example: null + role: + type: string + enum: + - developer + - user + - assistant + description: The role of the author of this message. + example: assistant + refusal: + type: string + nullable: true + description: The refusal message generated by the model. + example: null + chat_completion_chunk: + type: object + description: >- + Represents a streamed chunk of a chat completion response returned by + the model, based on the provided input. + required: + - choices + - created + - id + - model + - object + properties: + id: + type: string + description: >- + A unique identifier for the chat completion. Each chunk has the same + ID. + example: chatcmpl-abc123 + choices: + type: array + description: > + A list of chat completion choices. Can contain more than one element + if n is greater than 1. Can also be empty for the last chunk if you + set stream_options include_usage to true. + items: + type: object + required: + - delta + - finish_reason + - index + properties: + delta: + $ref: '#/components/schemas/chat_completion_stream_response_delta' + logprobs: + type: object + nullable: true + description: Log probability information for the choice. + properties: + content: + type: array + nullable: true + description: >- + A list of message content tokens with log probability + information. + items: + $ref: '#/components/schemas/chat_completion_token_logprob' + refusal: + type: array + nullable: true + description: >- + A list of message refusal tokens with log probability + information. + items: + $ref: '#/components/schemas/chat_completion_token_logprob' + required: + - content + - refusal + finish_reason: + type: string + nullable: true + description: > + The reason the model stopped generating tokens. stop if the + model hit a natural stop point or a provided stop sequence, + length if the maximum number of tokens specified in the + request was reached, tool_calls if the model called a tool. + enum: + - stop + - length + - tool_calls + - content_filter + example: stop + index: + type: integer + description: The index of the choice in the list of choices. + example: 0 + created: + type: integer + description: >- + The Unix timestamp (in seconds) of when the chat completion was + created. Each chunk has the same timestamp. + example: 1677649420 + model: + type: string + description: The model to generate the completion. + example: llama3-8b-instruct + object: + type: string + description: The object type, which is always chat.completion.chunk. + enum: + - chat.completion.chunk + example: chat.completion.chunk + usage: + nullable: true + description: > + An optional field that will only be present when you set + stream_options include_usage to true in your request. When present, + it contains a null value except for the last chunk which contains + the token usage statistics for the entire request. + allOf: + - $ref: '#/components/schemas/completion_usage' + messages_request_text_block_param: + type: object + description: A text content block in a request message. + required: + - type + - text + properties: + type: + type: string + enum: + - text + description: Block type identifier. + example: text + text: + type: string + description: Plain text for this block. + example: Hello, Claude + messages_image_source_param: + type: object + description: Image payload (for example base64-encoded bytes). + required: + - type + - media_type + - data + properties: + type: + type: string + description: Source kind (for example `base64`). + example: base64 + media_type: + type: string + description: MIME type of the image (for example `image/jpeg`). + example: image/jpeg + data: + type: string + description: Encoded image data. + example: /9j/4AAQSkZJRg== + messages_image_block_param: + type: object + description: Image content block in a request message. + required: + - type + - source + properties: + type: + type: string + enum: + - image + example: image + source: + $ref: '#/components/schemas/messages_image_source_param' + messages_tool_use_block_param: + type: object + description: >- + Tool invocation block in a request message (from the model or a prior + turn). + required: + - type + - id + - name + - input + properties: + type: + type: string + enum: + - tool_use + example: tool_use + id: + type: string + example: toolu_01ABCdefGhIjKlMnOpQrStUv + name: + type: string + example: get_weather + input: + type: object + description: JSON object matching the tool's `input_schema`. + additionalProperties: true + messages_tool_result_block_param: + type: object + description: Result for a prior `tool_use` block, returned to the model. + required: + - type + - tool_use_id + - content + properties: + type: + type: string + enum: + - tool_result + example: tool_result + tool_use_id: + type: string + example: toolu_01ABCdefGhIjKlMnOpQrStUv + content: + description: Tool output as plain text or structured objects. + example: 72°F and sunny + oneOf: + - type: string + - type: array + items: + type: object + additionalProperties: true + messages_request_content_block_param: + description: > + Structured message content. Block `type` is one of `text`, `image`, + `tool_use`, or `tool_result`. Some tool definitions may be rejected by + server policy even when valid here. + oneOf: + - $ref: '#/components/schemas/messages_request_text_block_param' + - $ref: '#/components/schemas/messages_image_block_param' + - $ref: '#/components/schemas/messages_tool_use_block_param' + - $ref: '#/components/schemas/messages_tool_result_block_param' + messages_api_message_param: + type: object + description: > + One turn in the conversation. Roles are `user` or `assistant` (no + `system` role; use the top-level `system` field). Content may be a + string (equivalent to a single text block) or an array of content + blocks. + required: + - role + - content + properties: + role: + type: string + description: Speaker role for this message. + enum: + - user + - assistant + example: user + content: + description: Message body as plain text or structured blocks. + example: What is the capital of Portugal? + oneOf: + - type: string + - type: array + items: + $ref: '#/components/schemas/messages_request_content_block_param' + messages_tool_definition_param: + type: object + description: Tool definition the model may call (`name`, JSON Schema for `input`). + required: + - name + - input_schema + properties: + name: + type: string + description: Tool name referenced in `tool_use` blocks. + example: get_weather + description: + type: string + description: Human-readable description of what the tool does. + example: Get the current weather for a location. + input_schema: + type: object + description: JSON Schema (draft 2020-12 style) describing the tool input object. + additionalProperties: true + messages_tool_choice_param: + description: > + Controls how the model uses tools: automatic selection, require any + tool, force a specific tool, or a string form accepted by the service. + oneOf: + - type: string + example: auto + - type: object + required: + - type + properties: + type: + type: string + enum: + - auto + - any + - tool + description: Tool selection mode. + example: tool + name: + type: string + description: When `type` is `tool`, the tool name to use. + example: get_weather + messages_thinking_config_param: + type: object + nullable: true + description: > + Extended thinking configuration. Executors that do not support thinking + may ignore this field. + required: + - type + properties: + type: + type: string + description: Thinking mode discriminator (for example enabled or disabled). + example: enabled + messages_create_request: + type: object + description: > + Request body for `POST /v1/messages`. Required fields are `model`, + `messages`, and `max_tokens`. + required: + - model + - max_tokens + - messages + properties: + model: + type: string + description: Model ID (for example `claude-opus-4-6` or a serverless model id). + example: claude-opus-4-6 + max_tokens: + type: integer + minimum: 1 + description: Maximum tokens to generate before stopping. + messages: + type: array + description: > + Conversation turns. Each item has `role` `user` or `assistant` and + `content` as a string or an array of content blocks. + minItems: 1 + items: + $ref: '#/components/schemas/messages_api_message_param' + system: + description: System prompt as plain text or as an array of text blocks. + oneOf: + - type: string + - type: array + items: + $ref: '#/components/schemas/messages_request_text_block_param' + stop_sequences: + type: array + description: Custom strings that stop generation when produced. + items: + type: string + stream: + type: boolean + default: false + description: When true, the response is streamed using server-sent events (SSE). + temperature: + type: number + minimum: 0 + maximum: 1 + nullable: true + description: Sampling temperature between 0.0 and 1.0. + top_p: + type: number + nullable: true + description: Nucleus sampling; use either `temperature` or `top_p`, not both. + top_k: + type: integer + minimum: 0 + nullable: true + description: Top-K sampling cutoff. + tools: + type: array + description: Tool definitions the model may invoke. + items: + $ref: '#/components/schemas/messages_tool_definition_param' + tool_choice: + $ref: '#/components/schemas/messages_tool_choice_param' + metadata: + type: object + description: Optional request metadata. + properties: + user_id: + type: string + description: > + Opaque identifier for the end user (for example a UUID or hash). + Do not include PII. + example: 550e8400-e29b-41d4-a716-446655440000 + reasoning_effort: + type: string + nullable: true + description: > + DigitalOcean extension for reasoning-capable models. Ignored by + executors that do not support it. + enum: + - none + - minimal + - low + - medium + - high + - xhigh + speed: + type: string + nullable: true + description: > + DigitalOcean extension for preferred inference speed. Ignored when + not supported. + enum: + - standard + - fast + thinking: + $ref: '#/components/schemas/messages_thinking_config_param' + messages_response_text_block: + type: object + description: A text block in an assistant message in the response. + required: + - type + - text + properties: + type: + type: string + enum: + - text + example: text + text: + type: string + description: Generated text for this block. + example: Hi! How can I help? + messages_response_tool_use_block: + type: object + description: Tool call emitted by the assistant in the response. + required: + - type + - id + - name + - input + properties: + type: + type: string + enum: + - tool_use + example: tool_use + id: + type: string + example: toolu_01ABCdefGhIjKlMnOpQrStUv + name: + type: string + example: get_weather + input: + type: object + additionalProperties: true + description: Arguments for the tool invocation. + messages_response_content_block: + description: Assistant output block (text and tool calls). + oneOf: + - $ref: '#/components/schemas/messages_response_text_block' + - $ref: '#/components/schemas/messages_response_tool_use_block' + messages_usage: + type: object + description: Token usage for a non-streaming `POST /v1/messages` response. + required: + - input_tokens + - output_tokens + properties: + input_tokens: + type: integer + description: Number of input tokens billed for this request. + example: 42 + output_tokens: + type: integer + description: Number of output tokens generated. + example: 128 + cache_creation_input_tokens: + type: integer + description: Input tokens used to create a prompt cache entry, if applicable. + example: 0 + cache_read_input_tokens: + type: integer + description: Input tokens read from a prompt cache, if applicable. + example: 0 + speed: + type: string + nullable: true + description: Inference speed tier reflected in billing or routing. + enum: + - standard + - fast + example: standard + messages_create_response: + type: object + description: > + Non-streaming assistant message from `POST /v1/messages`. `type` is + always `message` and `role` is always `assistant`. + required: + - id + - type + - role + - content + - model + - stop_reason + - usage + properties: + id: + type: string + description: Unique identifier for this message object. + example: msg_01AbCdEfGhIjKlMnOpQrStUv + type: + type: string + description: Object type discriminator. + enum: + - message + example: message + role: + type: string + description: Always `assistant` for this response. + enum: + - assistant + example: assistant + content: + type: array + description: Assistant output blocks (`text` and/or `tool_use`). + items: + $ref: '#/components/schemas/messages_response_content_block' + model: + type: string + description: Model that produced the message. + example: claude-opus-4-6 + stop_reason: + type: string + nullable: true + description: Why generation stopped. + enum: + - end_turn + - max_tokens + - stop_sequence + - tool_use + stop_sequence: + type: string + nullable: true + description: When `stop_reason` is `stop_sequence`, the sequence that matched. + usage: + $ref: '#/components/schemas/messages_usage' + messages_stream_event: + type: object + description: > + One server-sent event (SSE) JSON payload when `stream` is true. Each + event line contains a JSON object after the `data:` prefix. + required: + - type + properties: + type: + type: string + description: SSE event type. + enum: + - message_start + - content_block_start + - content_block_delta + - content_block_stop + - message_delta + - message_stop + - ping + message: + type: object + description: Present on `message_start`; initial message metadata. + additionalProperties: true + index: + type: integer + description: Index of the content block this event refers to. + content_block: + type: object + description: Present on `content_block_start`. + additionalProperties: true + delta: + type: object + description: Present on `content_block_delta` and `message_delta`. + additionalProperties: true + usage: + type: object + description: Streamed usage (for example on `message_delta`). + properties: + output_tokens: + type: integer + example: 64 + speed: + type: string + nullable: true + enum: + - standard + - fast + example: fast + messages_create_error_response: + type: object + description: Error envelope for some failures from this endpoint. + required: + - type + - error + properties: + type: + type: string + enum: + - error + error: + type: object + required: + - type + - message + properties: + type: + type: string + description: Machine-readable error code. + example: invalid_request_error + message: + type: string + description: Human-readable error message. + example: max_tokens must be positive + embeddings_request: + type: object + description: >- + Request body for `POST /v1/embeddings` (OpenAI-compatible). Extra fields + are rejected. + required: + - model + - input + additionalProperties: false + properties: + model: + type: string + description: >- + Model id to use for embeddings. Must match a model your account can + access. + example: qwen3-embedding-0.6b + input: + description: >- + A single string or 1–2048 strings; each string produces one row in + `data`, in order. + example: hello world + oneOf: + - type: string + example: hello world + - type: array + minItems: 1 + maxItems: 2048 + items: + type: string + example: + - hello world + - goodbye world + user: + type: string + description: Optional end-user identifier to help with abuse monitoring. + example: user-1234 + encoding_format: + type: string + description: How embedding values are returned in each `data[].embedding` field. + enum: + - float + - base64 + default: float + example: float + embedding_data_item: + type: object + description: >- + One row in the embeddings `data` array, aligned with a single `input` + item. + required: + - index + - object + - embedding + properties: + index: + type: integer + description: >- + Zero-based index of the corresponding `input` item (0 when `input` + is a string). + example: 0 + object: + type: string + description: The object type, which is always `embedding`. + enum: + - embedding + example: embedding + embedding: + description: >- + The embedding vector, or a base64-encoded string when the request + set encoding_format to base64. + example: + - 0.0123 + - -0.0456 + - 0.0001 + oneOf: + - type: array + description: Float vector when encoding_format is float or omitted. + items: + type: number + example: + - 0.0123 + - -0.0456 + - 0.0001 + - type: string + description: Base64 payload when encoding_format is base64. + example: AGZ...encoded... + embeddings_usage: + type: object + description: Token usage for the embeddings request. + required: + - prompt_tokens + - total_tokens + properties: + prompt_tokens: + type: integer + description: Number of input tokens used for the embedding. + example: 6 + total_tokens: + type: integer + description: Total billable tokens for the request. + example: 6 + embeddings_response: + type: object + description: OpenAI-style embeddings response. + required: + - object + - model + - data + - usage + properties: + object: + type: string + description: The object type, which is always the string `list`. + enum: + - list + example: list + model: + type: string + description: The embedding model that produced the vectors. + example: qwen3-embedding-0.6b + data: + type: array + description: One entry for each `input` string, in the same order. + items: + $ref: '#/components/schemas/embedding_data_item' + usage: + $ref: '#/components/schemas/embeddings_usage' + create_image_request: + type: object + description: Request body for image generation. + required: + - prompt + - model + - 'n' + properties: + prompt: + type: string + minLength: 1 + description: > + A text description of the desired image(s). Supports up to 32,000 + characters and provides automatic prompt optimization for best + results. + example: A cute baby sea otter floating on its back in calm blue water + model: + type: string + description: | + The model to use for image generation. + example: openai-gpt-image-1 + moderation: + type: string + nullable: true + description: > + The moderation setting for the image generation. Supported values: + low, auto. + example: auto + background: + type: string + nullable: true + description: > + The background setting for the image generation. Supported values: + transparent, opaque, auto. + example: auto + output_format: + type: string + nullable: true + description: > + The output format for the image generation. Supported values: png, + webp, jpeg. + example: png + output_compression: + type: integer + minimum: 0 + nullable: true + description: | + The output compression level for the image generation (0-100). + example: 100 + 'n': + type: integer + minimum: 1 + maximum: 10 + description: | + The number of images to generate. Must be between 1 and 10. + example: 1 + quality: + type: string + nullable: true + description: > + The quality of the image that will be generated. Supported values: + auto, high, medium, low. + example: auto + size: + type: string + description: > + The size of the generated images. GPT-IMAGE-1 supports: auto + (automatically select best size), 1536x1024 (landscape), 1024x1536 + (portrait). + enum: + - auto + - 1536x1024 + - 1024x1536 + example: auto + stream: + type: boolean + default: false + nullable: true + description: > + If set to true, partial image data will be streamed as the image is + being generated. The response will be sent as server-sent events + with partial image chunks. When stream is true, partial_images must + be greater than 0. + example: false + partial_images: + type: integer + minimum: 0 + nullable: true + description: > + The number of partial image chunks to return during streaming + generation. Defaults to 0. When stream=true, this must be greater + than 0 to receive progressive updates of the image as it is being + generated. + example: 1 + user: + type: string + maxLength: 256 + nullable: true + description: > + A unique identifier representing your end-user, which can help + DigitalOcean to monitor and detect abuse. + example: user-1234 + generated_image: + type: object + description: Represents the content of a generated image. + required: + - b64_json + properties: + b64_json: + type: string + description: | + The base64-encoded JSON of the generated image. + example: iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEX... + revised_prompt: + type: string + description: | + The optimized prompt that was used to generate the image. + example: >- + A cute baby sea otter floating on its back in calm blue water, + captured with professional photography lighting and composition + images_usage: + type: object + description: Token usage information for the image generation. + required: + - total_tokens + - input_tokens + - output_tokens + - input_tokens_details + properties: + total_tokens: + type: integer + description: >- + The total number of tokens (images and text) used for the image + generation. + example: 4172 + input_tokens: + type: integer + description: The number of tokens (images and text) in the input prompt. + example: 12 + output_tokens: + type: integer + description: The number of image tokens in the output image. + example: 4160 + input_tokens_details: + type: object + description: Detailed breakdown of input tokens. + required: + - text_tokens + - image_tokens + properties: + text_tokens: + type: integer + description: The number of text tokens in the input prompt. + example: 12 + image_tokens: + type: integer + description: The number of image tokens in the input prompt. + example: 0 + images_response: + type: object + description: The response from the image generation endpoint. + required: + - created + - data + properties: + created: + type: integer + description: The Unix timestamp (in seconds) of when the images were created. + example: 1677649456 + data: + type: array + description: The list of generated images. + minItems: 1 + maxItems: 10 + items: + $ref: '#/components/schemas/generated_image' + background: + type: string + description: The background setting used for the image generation. + example: opaque + nullable: true + output_format: + type: string + description: The output format of the generated image. + example: png + nullable: true + quality: + type: string + description: The quality setting used for the image generation. + example: high + nullable: true + size: + type: string + description: The size of the generated image. + example: 1024x1024 + nullable: true + usage: + nullable: true + description: Usage statistics for the image generation request. + allOf: + - $ref: '#/components/schemas/images_usage' + image_gen_partial_image_event: + type: object + description: >- + Emitted when a partial image is available during image generation + streaming. + required: + - type + - b64_json + - created_at + - size + - quality + - background + - output_format + - partial_image_index + properties: + type: + type: string + description: The type of the event. Always `image_generation.partial_image`. + enum: + - image_generation.partial_image + example: image_generation.partial_image + b64_json: + type: string + description: >- + Base64-encoded partial image data, suitable for rendering as an + image. + example: iVBORw0KGgoAAAANSUhEUgAAAQ... + created_at: + type: integer + description: The Unix timestamp when the event was created. + example: 1677649456 + size: + type: string + description: The size of the requested image. + enum: + - 1024x1024 + - 1024x1536 + - 1536x1024 + - auto + example: 1024x1024 + quality: + type: string + description: The quality setting for the requested image. + enum: + - low + - medium + - high + - auto + example: auto + background: + type: string + description: The background setting for the requested image. + enum: + - transparent + - opaque + - auto + example: auto + output_format: + type: string + description: The output format for the requested image. + enum: + - png + - webp + - jpeg + example: png + partial_image_index: + type: integer + description: 0-based index for the partial image (streaming). + example: 0 + model: + type: object + description: Describes a model offering that can be used with the API. + required: + - id + - object + - created + - owned_by + properties: + id: + type: string + description: The model identifier, which can be referenced in the API endpoints. + example: meta-llama/Meta-Llama-3.1-8B-Instruct + created: + type: integer + description: The Unix timestamp (in seconds) when the model was created. + example: 1686935002 + object: + type: string + description: The object type, which is always "model". + enum: + - model + example: model + owned_by: + type: string + description: The organization that owns the model. + example: digitalocean + list_models_response: + type: object + description: Response listing available models. + required: + - object + - data + properties: + object: + type: string + description: The object type, which is always "list". + enum: + - list + example: list + data: + type: array + description: The list of available models. + items: + $ref: '#/components/schemas/model' + create_response_request: + type: object + description: Request body for sending a prompt to a model using the Responses API. + required: + - model + - input + properties: + model: + type: string + description: > + The model ID of the model you want to use. Get the model ID using + `/v1/models` or on the available models page. + example: openai-gpt-oss-20b + input: + description: > + The prompt or input content you want the model to respond to. Can be + a simple text string or an array of message objects for conversation + context. + oneOf: + - type: string + description: Simple text input prompt. + example: What is the capital of France? + - type: array + description: Array of message objects for conversation context. + minItems: 1 + items: + type: object + properties: + role: + type: string + enum: + - user + - assistant + - system + - tool + - developer + description: The role of the message author. + example: user + content: + type: string + description: The content of the message. + example: What is the capital of France? + required: + - content + max_output_tokens: + type: integer + minimum: 1 + nullable: true + description: | + The maximum number of tokens to generate in the response. + example: 50 + temperature: + type: number + minimum: 0 + maximum: 2 + nullable: true + description: > + A value between 0.0 and 2.0 to control randomness and creativity. + Lower values like 0.2 make the output more focused and + deterministic, while higher values like 0.8 make it more random. + example: 0.7 + stream: + type: boolean + nullable: true + default: false + description: | + Set to true to stream partial responses as Server-Sent Events. + example: false + instructions: + type: string + nullable: true + description: > + System-level instructions for the model. This sets the behavior and + context for the response generation. + example: You are a helpful assistant. + top_p: + type: number + minimum: 0 + maximum: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, where the model considers the results of the tokens with + top_p probability mass. + example: 1 + stream_options: + type: object + nullable: true + default: null + description: >- + Options for streaming response. Only set this when you set stream to + true. + properties: + include_usage: + type: boolean + description: > + If set, an additional chunk will be streamed before the data: + [DONE] message with token usage statistics for the entire + request. + example: true + tools: + type: array + nullable: true + description: | + A list of tools the model may call. + items: + type: object + required: + - type + properties: + type: + type: string + enum: + - function + description: The type of the tool. + example: function + name: + type: string + description: The name of the function to be called. + example: get_weather + description: + type: string + description: A description of what the function does. + example: Get the current weather in a given location. + parameters: + type: object + description: >- + The parameters the function accepts, described as a JSON + Schema object. + additionalProperties: true + tool_choice: + description: | + Controls which (if any) tool is called by the model. + oneOf: + - type: string + enum: + - none + - auto + - required + example: auto + - type: object + properties: + type: + type: string + enum: + - function + example: function + function: + type: object + required: + - name + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + required: + - type + - function + stop: + description: | + Up to 4 sequences where the API will stop generating further tokens. + nullable: true + default: null + oneOf: + - type: string + example: |+ + + - type: array + minItems: 1 + maxItems: 4 + items: + type: string + metadata: + type: object + nullable: true + description: | + Set of key-value pairs that can be attached to the request. + additionalProperties: + type: string + example: + session_id: abc123 + user: + type: string + nullable: true + description: | + A unique identifier representing your end-user. + example: user-1234 + response_usage: + type: object + description: > + Detailed usage statistics for the Responses API request, including + input/output token counts and detailed breakdowns. + required: + - input_tokens + - output_tokens + - total_tokens + - input_tokens_details + - output_tokens_details + properties: + input_tokens: + type: integer + description: The number of input tokens. + example: 133 + input_tokens_details: + type: object + description: A detailed breakdown of the input tokens. + required: + - cached_tokens + properties: + cached_tokens: + type: integer + description: The number of tokens that were retrieved from the cache. + example: 128 + output_tokens: + type: integer + description: The number of output tokens. + example: 41 + output_tokens_details: + type: object + description: A detailed breakdown of the output tokens. + required: + - reasoning_tokens + - tool_output_tokens + properties: + reasoning_tokens: + type: integer + description: The number of reasoning tokens. + example: 24 + tool_output_tokens: + type: integer + description: The number of tool output tokens. + example: 0 + total_tokens: + type: integer + description: The total number of tokens used. + example: 174 + create_response_response: + type: object + description: | + The response includes structured output and token usage details. + required: + - id + - object + - created + - model + - output + - usage + properties: + id: + type: string + description: A unique identifier for the response. + example: response-abc123def456 + object: + type: string + description: The object type, which is always `response`. + enum: + - response + example: response + created: + type: integer + description: The Unix timestamp (in seconds) of when the response was created. + example: 1721596428 + model: + type: string + description: The model used to generate the response. + example: openai-gpt-oss-20b + output: + type: array + description: > + An array of content items generated by the model. Each item has a + type and a content array. Types include reasoning and output text. + items: + type: object + required: + - type + - content + properties: + type: + type: string + description: > + The type of output item. One of `reasoning`, `message`, or + `function_call`. + enum: + - reasoning + - message + - function_call + example: message + id: + type: string + description: The unique ID of the output item. + example: item_abc123 + status: + type: string + nullable: true + description: Status of the item. + example: completed + role: + type: string + nullable: true + description: >- + The role associated with this output item (typically + `assistant`). + example: assistant + content: + type: array + description: > + Array of content parts for this output item. Each part has a + type and text. Content types include `reasoning_text` for + reasoning items and `output_text` for final output. + items: + type: object + required: + - type + - text + properties: + type: + type: string + description: > + The type of content part. `reasoning_text` for reasoning + content, `output_text` for final output text. + enum: + - reasoning_text + - output_text + example: output_text + text: + type: string + description: The text content. + example: The capital of France is **Paris**. + call_id: + type: string + nullable: true + description: >- + The unique ID of the function tool call (present when type is + `function_call`). + example: call_abc123 + name: + type: string + nullable: true + description: >- + The name of the function to call (present when type is + `function_call`). + example: get_weather + arguments: + type: string + nullable: true + description: >- + JSON string of function arguments (present when type is + `function_call`). + example: '{"location": "San Francisco"}' + usage: + $ref: '#/components/schemas/response_usage' + parallel_tool_calls: + type: boolean + nullable: true + description: Whether parallel tool calls are enabled. + example: false + temperature: + type: number + nullable: true + description: Temperature setting used for the response. + example: 0.7 + tool_choice: + type: string + nullable: true + description: Tool choice setting used for the response. + example: auto + tools: + type: array + nullable: true + description: Tools available for the response. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool. + example: function + name: + type: string + description: The name of the function. + example: get_weather + description: + type: string + description: A description of what the function does. + example: Get the current weather in a given location. + parameters: + type: object + description: The parameters the function accepts. + additionalProperties: true + required: + - type + top_p: + type: number + nullable: true + description: Top-p setting used for the response. + example: 1 + max_output_tokens: + type: integer + nullable: true + description: Maximum output tokens setting. + example: 50 + status: + type: string + nullable: true + description: Status of the response. + example: completed + user: + type: string + nullable: true + description: User identifier. + example: user-1234 + create_response_stream_response: + type: object + description: > + Represents a streamed chunk of a text-to-text response returned by the + model, based on the provided input. + required: + - id + - object + - created + - model + - choices + properties: + id: + type: string + description: A unique identifier for the response. Each chunk has the same ID. + example: response-abc123def456 + object: + type: string + description: The object type, which is always `response.chunk`. + enum: + - response.chunk + example: response.chunk + created: + type: integer + description: > + The Unix timestamp (in seconds) of when the response was created. + Each chunk has the same timestamp. + example: 1721596428 + model: + type: string + description: The model used to generate the response. + example: llama3-8b-instruct + choices: + type: array + description: > + A list of response choice chunks. Can contain more than one element + if `n` is greater than 1. Can also be empty for the last chunk if + you set `stream_options: {"include_usage": true}`. + items: + type: object + required: + - index + - delta + properties: + index: + type: integer + description: The index of the choice in the list of choices. + example: 0 + delta: + type: object + description: A chunk of the response message generated by the model. + properties: + role: + type: string + enum: + - assistant + nullable: true + description: >- + The role of the message author. Only present in the first + chunk. + example: assistant + content: + type: string + nullable: true + description: > + The contents of the chunk message. Can be null for chunks + with tool calls or other non-text content. + example: Once upon a time + reasoning_content: + type: string + nullable: true + description: > + The reasoning content generated by the model. Only present + when the model generates reasoning text. + example: Let me think about this... + tool_calls: + type: array + nullable: true + description: > + The tool calls generated by the model, such as function + calls. Only present when the model decides to call a tool. + items: + type: object + properties: + id: + type: string + description: The ID of the tool call. + example: call_abc123 + type: + type: string + enum: + - function + description: The type of the tool call. + example: function + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + example: get_weather + arguments: + type: string + description: >- + The arguments to call the function with, as a + JSON string. + example: '{"location": "San Francisco"}' + required: + - name + - arguments + required: + - id + - type + - function + finish_reason: + type: string + nullable: true + description: > + The reason the model stopped generating tokens. Only present + in the final chunk. + enum: + - stop + - length + - tool_calls + - content_filter + example: stop + logprobs: + type: object + nullable: true + description: Log probability information for the choice. + properties: + content: + type: array + nullable: true + description: >- + A list of message content tokens with log probability + information. + items: + $ref: '#/components/schemas/chat_completion_token_logprob' + required: + - content + usage: + nullable: true + description: > + An optional field that will only be present when you set + `stream_options: {"include_usage": true}` in your request. When + present, it contains a null value except for the last chunk which + contains the token usage statistics for the entire request. + allOf: + - $ref: '#/components/schemas/response_usage' + async_invoke_request: + type: object + description: > + Request body for asynchronously invoking a model. Supports image + generation, audio generation, and text-to-speech models. The `input` + object fields vary depending on the model type. + required: + - model_id + - input + properties: + model_id: + type: string + description: | + The ID of the model to invoke asynchronously. + example: fal-ai/flux/schnell + input: + type: object + description: > + The input parameters for the model invocation. Fields vary by model + type. + + + For **image generation** models (e.g., `fal-ai/flux/schnell`, + `fal-ai/fast-sdxl`), use `prompt` along with optional image + parameters like `output_format`, `num_inference_steps`, + `guidance_scale`, `num_images`, and `enable_safety_checker`. + + + For **audio generation** models (e.g., + `fal-ai/stable-audio-25/text-to-audio`), use `prompt` along with + `seconds_total` to control the duration. + + + For **text-to-speech** models (e.g., + `fal-ai/elevenlabs/tts/multilingual-v2`), use `text` with the + content you want converted to speech. + properties: + prompt: + type: string + description: > + The text prompt describing the desired output. Used for image + generation and audio generation models. + example: A futuristic city at sunset + text: + type: string + description: > + The text content to convert to speech. Used for text-to-speech + models. + example: >- + This text-to-speech example uses DigitalOcean multilingual + voice. + output_format: + type: string + nullable: true + description: | + The desired output format or aspect ratio for image generation. + example: landscape_4_3 + num_inference_steps: + type: integer + minimum: 1 + nullable: true + description: > + The number of inference steps to use during image generation. + More steps generally produce higher quality output but take + longer. + example: 4 + guidance_scale: + type: number + nullable: true + description: > + Controls how closely the image generation model follows the + prompt. Higher values produce output more closely matching the + prompt. + example: 3.5 + num_images: + type: integer + minimum: 1 + nullable: true + description: The number of images to generate. + example: 1 + enable_safety_checker: + type: boolean + nullable: true + description: Whether to enable the safety checker for generated content. + example: true + seconds_total: + type: integer + minimum: 1 + nullable: true + description: > + The total duration in seconds for generated audio. Used for + audio generation models. + example: 60 + additionalProperties: true + tags: + type: array + nullable: true + description: > + An optional list of key-value tags to attach to the invocation + request for tracking or categorization. + items: + type: object + required: + - key + - value + properties: + key: + type: string + description: The tag key. + example: type + value: + type: string + description: The tag value. + example: test + async_invoke_response: + type: object + description: > + Response returned when an asynchronous invocation request is accepted. + The job status is QUEUED initially. Use the request_id to poll for the + result. + required: + - request_id + - status + - model_id + - created_at + properties: + request_id: + type: string + description: > + A unique identifier for the async invocation request. Use this ID to + check the status and retrieve the result. + example: 6590784a-ce47-4556-9ff4-53baff2693fb + status: + type: string + description: The current status of the async invocation. + enum: + - QUEUED + - IN_PROGRESS + - COMPLETED + - FAILED + example: QUEUED + model_id: + type: string + description: The model ID that was invoked. + example: fal-ai/fast-sdxl + created_at: + type: string + format: date-time + description: The timestamp when the request was created. + example: '2026-01-22T19:19:19.112403432Z' + started_at: + type: string + format: date-time + nullable: true + description: The timestamp when the job started processing. Null while queued. + example: null + completed_at: + type: string + format: date-time + nullable: true + description: The timestamp when the job completed. Null until finished. + example: null + output: + type: object + nullable: true + description: > + The output of the invocation. Null while the job is queued or in + progress. Contains the result once completed. + additionalProperties: true + example: null + error: + type: string + nullable: true + description: Error message if the job failed. Null on success. + example: null + batch_file_create_request: + type: object + title: BatchFileCreateRequest + description: Request body for creating a batch input file intent. + required: + - file_name + properties: + file_name: + type: string + description: > + The file you plan to upload. Must end with `.jsonl` + (case-insensitive) and contain one request per line in the schema + expected by the target `provider`. + minLength: 7 + pattern: .+\.[Jj][Ss][Oo][Nn][Ll]$ + example: batch_requests.jsonl + batch_file_create_response: + type: object + description: Presigned upload URL and `file_id` for a new batch input file. + required: + - file_id + - upload_url + properties: + file_id: + type: string + format: uuid + description: Pass this value as `file_id` when creating a batch job. + example: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + upload_url: + type: string + format: uri + description: > + Short-lived presigned `PUT` URL (typically valid for ~15 minutes). + If it expires before upload, create a new file intent. + example: >- + https://batch-inference.nyc3.digitaloceanspaces.com/uploads/a1b2c3d4-e5f6-4789-90ab-cdef12345678.jsonl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=... + expires_at: + type: string + format: date-time + nullable: true + description: When `upload_url` expires. + example: '2026-04-24T19:34:19Z' + batch: + type: object + description: A Batch Inference job. + required: + - batch_id + - status + - provider + - completion_window + - input_file_id + - created_at + properties: + batch_id: + type: string + format: uuid + description: Unique identifier for the batch job. + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + status: + type: string + description: > + Lifecycle status. Terminal states: `completed`, `failed`, `expired`, + `cancelled`. + enum: + - validating + - in_progress + - finalizing + - completed + - failed + - expired + - cancelling + - cancelled + example: in_progress + provider: + type: string + enum: + - openai + - anthropic + example: openai + endpoint: + type: string + description: Inference endpoint each request is dispatched to. + example: /v1/chat/completions + completion_window: + type: string + enum: + - 24h + example: 24h + input_file_id: + type: string + format: uuid + description: The uploaded JSONL input file. + example: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + output_file_id: + type: string + format: uuid + nullable: true + description: Output JSONL file. Populated once the job completes. + example: null + error_file_id: + type: string + format: uuid + nullable: true + description: Error sidecar file. Null when no errors were produced. + example: null + request_counts: + type: object + description: Aggregate request counts. + properties: + total: + type: integer + example: 10000 + completed: + type: integer + example: 0 + failed: + type: integer + example: 0 + request_id: + type: string + description: The idempotency key supplied at creation. + example: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11 + metadata: + type: object + nullable: true + description: Metadata attached at creation. + additionalProperties: + type: string + example: null + errors: + type: array + nullable: true + description: Top-level errors that prevented the batch from completing. + items: + type: object + properties: + code: + type: string + example: invalid_input_file + message: + type: string + example: 'Line 42: missing required field ''custom_id''.' + line: + type: integer + nullable: true + description: 1-based JSONL line number, if applicable. + example: 42 + created_at: + type: string + format: date-time + example: '2026-04-24T19:19:19Z' + in_progress_at: + type: string + format: date-time + nullable: true + example: '2026-04-24T19:20:05Z' + finalizing_at: + type: string + format: date-time + nullable: true + example: '2026-04-24T20:10:42Z' + completed_at: + type: string + format: date-time + nullable: true + example: '2026-04-24T20:15:30Z' + expires_at: + type: string + format: date-time + nullable: true + description: Derived from `created_at` plus `completion_window`. + example: '2026-04-25T19:19:19Z' + cancelled_at: + type: string + format: date-time + nullable: true + example: '2026-04-24T19:45:11Z' + failed_at: + type: string + format: date-time + nullable: true + example: '2026-04-24T19:50:00Z' + batch_list_response: + type: object + title: BatchListResponse + description: Cursor-paginated list of batch inference jobs. + required: + - object + - data + - has_more + properties: + object: + type: string + description: The object type, always `list`. + enum: + - list + example: list + data: + type: array + description: Batch jobs on this page, ordered newest first. + items: + $ref: '#/components/schemas/batch' + first_id: + type: string + format: uuid + nullable: true + description: ID of the first batch on this page. Null when the page is empty. + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + last_id: + type: string + format: uuid + nullable: true + description: > + ID of the last batch on this page. Pass as `after` to fetch the next + page. + example: 7b2e9c1a-6f4d-4d9b-a0f1-5c4b7e2f8a12 + has_more: + type: boolean + description: Whether additional batches exist beyond this page. + example: false + batch_create_request: + type: object + description: > + Request body for creating a batch inference job. + + + When `provider` is `openai`, `endpoint` is required and must be one of + `/v1/responses` or `/v1/chat/completions`. When `provider` is + `anthropic`, `endpoint` must be omitted — the Anthropic Message Batches + API does not need a per-job endpoint. + required: + - file_id + - provider + - completion_window + - request_id + properties: + file_id: + type: string + format: uuid + description: The `file_id` returned by `POST /v1/batches/files`. + example: a1b2c3d4-e5f6-4789-90ab-cdef12345678 + provider: + type: string + description: > + The inference provider whose JSONL schema the input file conforms + to. `openai` follows the OpenAI Batch API input schema (`custom_id`, + `method`, `url`, `body`); `anthropic` follows the Anthropic Message + Batches JSONL conventions. + enum: + - openai + - anthropic + example: openai + endpoint: + type: string + description: > + Inference endpoint each request is dispatched to. **Required when + `provider` is `openai` and must match the `url` on every JSONL line. + Must be omitted when `provider` is `anthropic`.** + enum: + - /v1/responses + - /v1/chat/completions + example: /v1/chat/completions + completion_window: + type: string + description: > + Time window in which the job must complete. Jobs that do not finish + in time transition to `expired`. + enum: + - 24h + default: 24h + example: 24h + request_id: + type: string + description: > + Client-supplied idempotency key. Retries with the same value return + the existing job instead of creating a duplicate. + example: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11 + metadata: + type: object + nullable: true + description: Optional string-valued metadata to attach to the job. + additionalProperties: + type: string + example: + team: ml-eval + dataset: prompts_v1 + batch_results_response: + type: object + title: BatchResultsResponse + description: > + Presigned download URLs for a batch job. URLs are short-lived — download + the artifacts soon after fetching them. + required: + - batch_id + - result_available + properties: + batch_id: + type: string + format: uuid + example: 0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21 + result_available: + type: boolean + description: | + When `false`, keep polling batch status and retry later. + example: true + output_file_url: + type: string + format: uri + nullable: true + description: Presigned URL for the main results JSONL. + example: >- + https://batch-inference.nyc3.digitaloceanspaces.com/outputs/0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21.jsonl?X-Amz-Signature=... + error_file_url: + type: string + format: uri + nullable: true + description: Presigned URL for the error sidecar JSONL, if any. + example: null + expires_at: + type: string + format: date-time + nullable: true + description: When the presigned URLs expire. + example: '2026-04-24T20:19:19Z' + responses: + unexpected_error: + description: There was an unexpected error. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: example_error + message: some error message + oneClicks_all: + description: A JSON object with a key of `1_clicks`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + 1_clicks: + type: array + items: + $ref: '#/components/schemas/oneClicks' + examples: + All 1-Click Applications: + value: + 1_clicks: + - slug: monitoring + type: kubernetes + - slug: wordpress-18-04 + type: droplet + unauthorized: + description: Authentication failed due to invalid credentials. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: unauthorized + message: Unable to authenticate you. + too_many_requests: + description: The API rate limit has been exceeded. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: too_many_requests + message: API rate limit exceeded. + server_error: + description: There was a server error. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: server_error + message: Unexpected server-side error + oneClicks_create: + description: > + The response will verify that a job has been successfully created to + install a 1-Click. The + + post-installation lifecycle of a 1-Click application can not be managed + via the DigitalOcean + + API. For additional details specific to the 1-Click, find and view its + + [DigitalOcean Marketplace](https://marketplace.digitalocean.com) page. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A message about the result of the request. + example: Successfully kicked off addon job. + examples: + Install a 1-Click Application: + value: + message: Successfully kicked off addon job. + account: + description: >- + A JSON object keyed on account with an excerpt of the current user + account data. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + account: + $ref: '#/components/schemas/account' + sshKeys_all: + description: >- + A JSON object with the key set to `ssh_keys`. The value is an array of + `ssh_key` objects, each of which contains the standard `ssh_key` + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - properties: + ssh_keys: + type: array + items: + $ref: '#/components/schemas/sshKeys' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + ssh_keys: + - id: 289794 + fingerprint: 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + public_key: >- + ssh-rsa + ANOTHEREXAMPLEaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V + anotherexample + name: Other Public Key + links: {} + meta: + total: 1 + sshKeys_new: + description: The response body will be a JSON object with a key set to `ssh_key`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + ssh_key: + $ref: '#/components/schemas/sshKeys' + links: + sshKeys_get_by_id: + $ref: '#/components/links/sshKeys_get_by_id' + sshKeys_get_by_fingerprint: + $ref: '#/components/links/sshKeys_get_by_fingerprint' + sshKeys_delete_by_id: + $ref: '#/components/links/sshKeys_delete_by_id' + sshKeys_delete_by_fingerprint: + $ref: '#/components/links/sshKeys_delete_by_fingerprint' + sshKeys_existing: + description: >- + A JSON object with the key set to `ssh_key`. The value is an `ssh_key` + object containing the standard `ssh_key` attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + ssh_key: + $ref: '#/components/schemas/sshKeys' + links: + sshKeys_get_by_id: + $ref: '#/components/links/sshKeys_get_by_id' + sshKeys_get_by_fingerprint: + $ref: '#/components/links/sshKeys_get_by_fingerprint' + sshKeys_delete_by_id: + $ref: '#/components/links/sshKeys_delete_by_id' + sshKeys_delete_by_fingerprint: + $ref: '#/components/links/sshKeys_delete_by_fingerprint' + not_found: + description: The resource was not found. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: not_found + message: The resource you requested could not be found. + no_content: + description: The action was successful and the response body is empty. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + actions: + description: >- + 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 + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + action: + description: >- + The result will be a JSON object with an action key. This will be set + to an action object containing the standard action attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + $ref: '#/components/schemas/action' + addons_get_app: + description: >- + The response will be a JSON object with a key called `apps`. `apps` will + be an array of objects. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + apps: + type: array + items: + $ref: '#/components/schemas/addons_app_info' + addons_get_app_metadata: + description: >- + The response will be a JSON object with a key called `metadata`. + `metadata` will be an array of objects, each representing a metadata + item for the app. Each object will contain details such as `id`, `name`, + `display_name`, `description`, `type`, and `options`. For additional + details specific to the app, find and view its [DigitalOcean + Marketplace](https://marketplace.digitalocean.com) page. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + metadata: + type: array + items: + $ref: '#/components/schemas/addons_app_metadata' + addons_list: + description: >- + The response will be an array of JSON objects with a key called + `resources`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + resources: + type: array + items: + $ref: '#/components/schemas/addons_resource' + addons_create: + description: >- + The response will be a JSON object with a key called `resource`. The + value of this will be the resource created with the given. For + additional details specific to the app, find and view its [DigitalOcean + Marketplace](https://marketplace.digitalocean.com) page. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + resource: + $ref: '#/components/schemas/addons_resource' + addons_get: + description: The response will be a JSON object with a key called `resource`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + resource: + $ref: '#/components/schemas/addons_resource' + addons_update: + description: >- + The response will be a JSON object with a key called `resource`, + representing the updated resource. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + resource: + $ref: '#/components/schemas/addons_resource' + list_apps: + description: A JSON object with a `apps` key. This is list of object `apps`. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_response' + examples: + apps: + $ref: '#/components/examples/apps' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + new_app: + description: A JSON or YAML of a `spec` object. + content: + application/json: + schema: + $ref: '#/components/schemas/app_response' + examples: + app: + $ref: '#/components/examples/app' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + apps_get: + description: A JSON with key `app` + content: + application/json: + schema: + $ref: '#/components/schemas/app_response' + examples: + app: + $ref: '#/components/examples/app' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + update_app: + description: A JSON object of the updated `app` + content: + application/json: + schema: + $ref: '#/components/schemas/app_response' + examples: + app: + $ref: '#/components/examples/app' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + delete_app: + description: the ID of the app deleted. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_delete_app_response' + example: + id: b7d64052-3706-4cb7-b21a-c5a2f44e63b3 + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + new_app_deployment: + description: A JSON object with a `deployment` key. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_deployment_response' + examples: + deployment: + $ref: '#/components/examples/deployment' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_logs: + description: A JSON object with urls that point to archived logs + content: + application/json: + schema: + $ref: '#/components/schemas/apps_get_logs_response' + examples: + logs: + $ref: '#/components/examples/logs' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + get_exec: + description: >- + A JSON object with a websocket URL that allows sending/receiving console + input and output. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_get_exec_response' + examples: + exec: + $ref: '#/components/examples/exec' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + apps_instances: + description: A JSON with key `instances` + content: + application/json: + schema: + $ref: '#/components/schemas/app_instances' + examples: + app_instances: + $ref: '#/components/examples/app_instances' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + existing_deployments: + description: >- + A JSON object with a `deployments` key. This will be a list of all app + deployments + content: + application/json: + schema: + $ref: '#/components/schemas/apps_deployments_response' + examples: + deployments: + $ref: '#/components/examples/deployments' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_deployment: + description: A JSON of the requested deployment + content: + application/json: + schema: + $ref: '#/components/schemas/apps_deployment_response' + examples: + deployment: + $ref: '#/components/examples/deployment' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + cancel_deployment: + description: A JSON the `deployment` that was just cancelled. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_deployment_response' + examples: + deployment: + $ref: '#/components/examples/deployment' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_job_invocations: + description: A JSON with key `job_invocations` + content: + application/json: + schema: + $ref: '#/components/schemas/app_job_invocations' + examples: + job_invocations: + $ref: '#/components/examples/job_invocations' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + get_job_invocation: + description: A JSON with key `job_invocation` + content: + application/json: + schema: + $ref: '#/components/schemas/app_job_invocation' + examples: + job_invocation: + $ref: '#/components/examples/job_invocation' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + cancel_job_invocation: + description: A JSON with key `job_invocation` + content: + application/json: + schema: + $ref: '#/components/schemas/app_job_invocation' + examples: + job_invocation: + $ref: '#/components/examples/job_invocation' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + apps_get_logs: + description: A JSON object with urls that point to Job Invocation logs + content: + application/json: + schema: + $ref: '#/components/schemas/apps_get_logs_response' + examples: + logs: + $ref: '#/components/examples/logs' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_events: + description: A JSON with key `events` + content: + application/json: + schema: + $ref: '#/components/schemas/app_events' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + get_event: + description: A JSON with key `event` + content: + application/json: + schema: + type: object + properties: + event: + $ref: '#/components/schemas/app_event' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + cancel_event: + description: A JSON with key `event` + content: + application/json: + schema: + type: object + properties: + event: + $ref: '#/components/schemas/app_event' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_instance: + description: A JSON with key `instance_sizes` + content: + application/json: + schema: + $ref: '#/components/schemas/apps_list_instance_sizes_response' + examples: + instance_sizes: + $ref: '#/components/examples/instance_sizes' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + get_instance: + description: A JSON with key `instance_size` + content: + application/json: + schema: + $ref: '#/components/schemas/apps_get_instance_size_response' + examples: + instance_size: + $ref: '#/components/examples/instance_size' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_regions: + description: A JSON object with key `regions` + content: + application/json: + schema: + $ref: '#/components/schemas/apps_list_regions_response' + examples: + regions: + $ref: '#/components/examples/regions' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + propose_app: + description: A JSON object. + content: + application/json: + schema: + $ref: '#/components/schemas/app_propose_response' + examples: + propose: + $ref: '#/components/examples/propose' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_alerts: + description: A JSON object with a `alerts` key. This is list of object `alerts`. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_list_alerts_response' + examples: + apps: + $ref: '#/components/examples/alerts' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + assign_alert_destinations: + description: A JSON object with an `alert` key. This is an object of type `alert`. + content: + application/json: + schema: + $ref: '#/components/schemas/apps_alert_response' + examples: + apps: + $ref: '#/components/examples/alert' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + apps_validate_rollback: + description: A JSON object with the validation results. + content: + application/json: + schema: + type: object + properties: + valid: + type: boolean + description: >- + Indicates whether the app can be rolled back to the specified + deployment. + error: + allOf: + - description: >- + Contains the failing condition that is causing the + rollback to be invalid. + - $ref: '#/components/schemas/app_rollback_validation_condition' + warnings: + type: array + description: >- + Contains a list of warnings that may cause the rollback to run + under unideal circumstances. + items: + $ref: '#/components/schemas/app_rollback_validation_condition' + examples: + Valid rollback: + value: + valid: true + Valid rollback with warnings: + value: + valid: true + warnings: + - code: image_source_missing_digest + components: + - docker-worker + message: >- + one or more components are missing an image digest and are + not guaranteed rollback to the old version + Invalid rollback: + value: + valid: false + error: + code: incompatible_result + message: deployment result "failed" is unsuitable for rollback + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + get_metrics_bandwidth_usage: + description: A JSON object with a `app_bandwidth_usage` key + content: + application/json: + schema: + $ref: '#/components/schemas/app_metrics_bandwidth_usage' + examples: + app_bandwidth_usage: + $ref: '#/components/examples/app_bandwidth_usage' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + list_metrics_bandwidth_usage: + description: A JSON object with a `app_bandwidth_usage` key + content: + application/json: + schema: + $ref: '#/components/schemas/app_metrics_bandwidth_usage' + examples: + app_bandwidth_usage: + $ref: '#/components/examples/app_bandwidth_usage_multiple' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + apps_health: + description: A JSON with key `app_health` + content: + application/json: + schema: + $ref: '#/components/schemas/app_health_response' + examples: + app_health: + $ref: '#/components/examples/app_health' + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + all_cdn_endpoints: + description: >- + The result will be a JSON object with an `endpoints` key. This will be + set to an array of endpoint objects, each of which will contain the + standard CDN endpoint attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + endpoints: + type: array + items: + $ref: '#/components/schemas/cdn_endpoint' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + endpoints: + - id: 19f06b6a-3ace-4315-b086-499a0e521b76 + origin: static-images.nyc3.digitaloceanspaces.com + endpoint: static-images.nyc3.cdn.digitaloceanspaces.com + created_at: '2018-07-19T15:04:16Z' + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + custom_domain: static.example.com + ttl: 3600 + links: {} + meta: + total: 1 + existing_endpoint: + description: >- + The response will be a JSON object with an `endpoint` key. This will be + set to an object containing the standard CDN endpoint attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + endpoint: + $ref: '#/components/schemas/cdn_endpoint' + examples: + CDN Endpoint: + value: + endpoint: + id: 19f06b6a-3ace-4315-b086-499a0e521b76 + origin: static-images.nyc3.digitaloceanspaces.com + endpoint: static-images.nyc3.cdn.digitaloceanspaces.com + created_at: '2018-07-19T15:04:16Z' + ttl: 3600 + CDN Endpoint With Custom Domain: + value: + endpoint: + id: 19f06b6a-3ace-4315-b086-499a0e521b76 + origin: static-images.nyc3.digitaloceanspaces.com + endpoint: static-images.nyc3.cdn.digitaloceanspaces.com + created_at: '2018-07-19T15:04:16Z' + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + custom_domain: static.example.com + ttl: 3600 + all_certificates: + description: >- + The result will be a JSON object with a `certificates` key. This will be + set to an array of certificate objects, each of which will contain the + standard certificate attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + certificates: + type: array + items: + $ref: '#/components/schemas/certificate' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + AllCertificates: + $ref: '#/components/examples/certificates_all' + new_certificate: + description: >- + The response will be a JSON object with a key called `certificate`. The + value of this will be an object that contains the standard attributes + associated with a certificate. + + When using Let's Encrypt, the initial value of the certificate's `state` + attribute will be `pending`. When the certificate has been successfully + issued by Let's Encrypt, this will transition to `verified` and be ready + for use. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + certificate: + $ref: '#/components/schemas/certificate' + examples: + Custom Certificate: + $ref: '#/components/examples/certificates_custom' + Let's Encrypt Certificate: + $ref: '#/components/examples/certificates_lets_encrypt_pending' + existing_certificate: + description: >- + The response will be a JSON object with a `certificate` key. This will + be set to an object containing the standard certificate attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + certificate: + $ref: '#/components/schemas/certificate' + examples: + Custom Certificate: + $ref: '#/components/examples/certificates_custom' + Let's Encrypt Certificate: + $ref: '#/components/examples/certificates_lets_encrypt' + balance: + description: >- + The response will be a JSON object that contains the following + attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/balance' + example: + month_to_date_balance: '23.44' + account_balance: '12.23' + month_to_date_usage: '11.21' + generated_at: '2019-07-09T15:01:12Z' + billing_history: + description: >- + The response will be a JSON object that contains the following + attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + billing_history: + type: array + items: + $ref: '#/components/schemas/billing_history' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta_optional_total' + example: + billing_history: + - description: Invoice for May 2018 + amount: '12.34' + invoice_id: '123' + invoice_uuid: example-uuid + date: '2018-06-01T08:44:38Z' + type: Invoice + - description: Payment (MC 2018) + amount: '-12.34' + date: '2018-06-02T08:44:38Z' + type: Payment + links: + pages: + next: >- + https://api.digitalocean.com/v2/customers/my/billing_history?page=2&per_page=2 + last: >- + https://api.digitalocean.com/v2/customers/my/billing_history?page=3&per_page=2 + meta: + total: 5 + invoices: + description: >- + The response will be a JSON object contains that contains a list of + invoices under the `invoices` key, and the invoice preview under the + `invoice_preview` key. + + Each element contains the invoice summary attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + invoices: + type: array + items: + $ref: '#/components/schemas/invoice_preview' + invoice_preview: + $ref: '#/components/schemas/invoice_preview' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + invoices: + - invoice_uuid: 22737513-0ea7-4206-8ceb-98a575af7681 + invoice_id: '12345678' + amount: '12.34' + invoice_period: 2019-12 + - invoice_uuid: fdabb512-6faf-443c-ba2e-665452332a9e + invoice_id: '23456789' + amount: '23.45' + invoice_period: 2019-11 + invoice_preview: + invoice_uuid: 1afe95e6-0958-4eb0-8d9a-9c5060d3ef03 + invoice_id: '34567890' + amount: '34.56' + invoice_period: 2020-02 + updated_at: '2020-02-23T06:31:50Z' + links: + pages: + next: >- + https://api.digitalocean.com/v2/customers/my/invoices?page=2&per_page=2 + last: >- + https://api.digitalocean.com/v2/customers/my/invoices?page=35&per_page=2 + meta: + total: 70 + invoice: + description: >- + The response will be a JSON object with a key called `invoice_items`. + This will be set to an array of invoice item objects. All resources will + be shown on invoices, regardless of permissions. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + invoice_items: + type: array + items: + $ref: '#/components/schemas/invoice_item' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + invoice_items: + - product: Kubernetes Clusters + resource_uuid: 711157cb-37c8-4817-b371-44fa3504a39c + group_description: my-doks-cluster + description: a56e086a317d8410c8b4cfd1f4dc9f82 + amount: '12.34' + duration: '744' + duration_unit: Hours + start_time: '2020-01-01T00:00:00Z' + end_time: '2020-02-01T00:00:00Z' + - product: Spaces Subscription + description: Spaces ($5/mo 250GB storage & 1TB bandwidth) + amount: '34.45' + duration: '744' + duration_unit: Hours + start_time: '2020-01-01T00:00:00Z' + end_time: '2020-02-01T00:00:00Z' + links: + pages: + next: >- + https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681?page=2&per_page=2 + last: >- + https://api.digitalocean.com/v2/customers/my/invoices/22737513-0ea7-4206-8ceb-98a575af7681?page=3&per_page=2 + meta: + total: 6 + invoice_csv: + description: The response will be a CSV file. + headers: + content-disposition: + $ref: '#/components/headers/content-disposition' + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + text/csv: + schema: + type: string + example: > + product,group_description,description,hours,start,end,USD,project_name,category + + Floating IPs,,Unused Floating IP - 1.1.1.1,100,2020-07-01 00:00:00 + +0000,2020-07-22 18:14:39 +0000,$3.11,,iaas + + Taxes,,STATE SALES TAX (6.25%),,2020-07-01 00:00:00 +0000,2020-07-31 + 23:59:59 +0000,$0.16,,iaas + invoice_pdf: + description: The response will be a PDF file. + headers: + content-disposition: + $ref: '#/components/headers/content-disposition' + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/pdf: + schema: + type: string + format: binary + invoice_summary: + description: >- + To retrieve a summary for an invoice, send a GET request to + `/v2/customers/my/invoices/$INVOICE_UUID/summary`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/invoice_summary' + example: + invoice_uuid: 22737513-0ea7-4206-8ceb-98a575af7681 + invoice_id: '123456789' + billing_period: 2020-01 + amount: '27.13' + user_name: Sammy Shark + user_billing_address: + address_line1: 101 Shark Row + city: Atlantis + region: OC + postal_code: '12345' + country_iso2_code: US + created_at: '2019-09-03T16:34:46.000+00:00' + updated_at: '2019-09-03T16:34:46.000+00:00' + user_company: DigitalOcean + user_email: sammy@digitalocean.com + product_charges: + name: Product usage charges + amount: '12.34' + items: + - amount: '10.00' + name: Spaces Subscription + count: '1' + - amount: '2.34' + name: Database Clusters + count: '1' + overages: + name: Overages + amount: '3.45' + taxes: + name: Taxes + amount: '4.56' + credits_and_adjustments: + name: Credits & adjustments + amount: '6.78' + billing_insights: + description: >- + The response will be a JSON object that contains a list of billing data + points under the `data_points` key, along with pagination metadata + including `total_items`, `total_pages`, and `current_page`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + data_points: + type: array + description: >- + Array of billing data points, which are day-over-day changes + in billing resource usage based on nightly invoice item + estimates, for the requested period + items: + $ref: '#/components/schemas/billing_data_point' + total_items: + type: integer + description: Total number of items available across all pages + example: 250 + total_pages: + type: integer + description: Total number of pages available + example: 3 + current_page: + type: integer + description: Current page number + example: 1 + required: + - data_points + - total_items + - total_pages + - current_page + example: + data_points: + - usage_team_urn: do:team:12345678-1234-1234-1234-123456789012 + start_date: '2025-01-01' + total_amount: '0.86' + region: nyc3 + sku: 1-DO-DROP-0109 + description: droplet name (c-2-4GiB) + group_description: '' + - usage_team_urn: do:team:12345678-1234-1234-1234-123456789012 + start_date: '2025-01-01' + total_amount: '2.57' + region: nyc3 + sku: 1-KS-K8SWN-00109 + description: 3 nodes - 4 GB / 2 vCPU / 80 GB SSD + group_description: kubernetes cluster name + total_items: 2 + total_pages: 1 + current_page: 1 + options: + description: A JSON string with a key of `options`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/options' + example: + options: + kafka: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '3.8' + layouts: + - num_nodes: 3 + sizes: + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - db-s-2vcpu-4gb + - db-s-2vcpu-2gb + - num_nodes: 6 + sizes: + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - num_nodes: 9 + sizes: + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - num_nodes: 15 + sizes: + - gd-2vcpu-8gb + - gd-4vcpu-16gb + default_version: '3.8' + mongodb: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '6.0' + - '7.0' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - num_nodes: 3 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + default_version: '7.0' + mysql: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '8' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-1gb + - db-amd-1vcpu-1gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-amd-2vcpu-8gb + - db-intel-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-amd-4vcpu-16gb + - db-intel-4vcpu-16gb + - db-intel-8vcpu-32gb + - db-amd-8vcpu-32gb + - db-intel-16vcpu-64gb + - db-amd-16vcpu-64gb + - num_nodes: 2 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-intel-2vcpu-8gb + - db-amd-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-intel-4vcpu-16gb + - db-amd-4vcpu-16gb + - db-amd-8vcpu-32gb + - db-intel-8vcpu-32gb + - db-amd-16vcpu-64gb + - db-intel-16vcpu-64gb + - num_nodes: 3 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-intel-2vcpu-8gb + - db-amd-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-intel-4vcpu-16gb + - db-amd-4vcpu-16gb + - db-amd-8vcpu-32gb + - db-intel-8vcpu-32gb + - db-amd-16vcpu-64gb + - db-intel-16vcpu-64gb + default_version: '8' + advanced_mysql: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - 8.4.8 + layouts: + - num_nodes: 1 + sizes: + - gd-2vcpu-8gb-intel + - so1_5-2vcpu-16gb-intel + - so1_5-2vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb-intel + - so1_5-4vcpu-32gb-intel + - so1_5-4vcpu-32gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - so1_5-8vcpu-64gb + - gd-8vcpu-32gb-intel + - so1_5-8vcpu-64gb-intel + - gd-16vcpu-64gb + - so1_5-16vcpu-128gb + - gd-16vcpu-64gb-intel + - so1_5-16vcpu-128gb-intel + - so1_5-24vcpu-192gb + - so1_5-24vcpu-192gb-intel + - so1_5-32vcpu-256gb-intel + - gd-32vcpu-128gb + - gd-32vcpu-128gb-intel + - so1_5-32vcpu-256gb + - gd-40vcpu-160gb + - so1_5-48vcpu-384gb-intel + - gd-48vcpu-192gb-intel + - so1_5-48vcpu-256gb + - c-96-intel + - num_nodes: 3 + sizes: + - gd-2vcpu-8gb-intel + - so1_5-2vcpu-16gb-intel + - so1_5-2vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb-intel + - so1_5-4vcpu-32gb-intel + - so1_5-4vcpu-32gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - so1_5-8vcpu-64gb + - gd-8vcpu-32gb-intel + - so1_5-8vcpu-64gb-intel + - gd-16vcpu-64gb + - so1_5-16vcpu-128gb + - gd-16vcpu-64gb-intel + - so1_5-16vcpu-128gb-intel + - so1_5-24vcpu-192gb + - so1_5-24vcpu-192gb-intel + - so1_5-32vcpu-256gb-intel + - gd-32vcpu-128gb + - gd-32vcpu-128gb-intel + - so1_5-32vcpu-256gb + - gd-40vcpu-160gb + - so1_5-48vcpu-384gb-intel + - gd-48vcpu-192gb-intel + - so1_5-48vcpu-256gb + - c-96-intel + default_version: 8.4.8 + opensearch: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '1' + - '2' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - gd-2vcpu-8gb + - m3-2vcpu-16gb + - db-s-4vcpu-8gb + - gd-4vcpu-16gb + - m3-4vcpu-32gb + - m3-8vcpu-64gb + - num_nodes: 3 + sizes: + - db-s-2vcpu-4gb + - gd-2vcpu-8gb + - m3-2vcpu-16gb + - db-s-4vcpu-8gb + - gd-4vcpu-16gb + - m3-4vcpu-32gb + - m3-8vcpu-64gb + - num_nodes: 6 + sizes: + - gd-2vcpu-8gb + - m3-2vcpu-16gb + - gd-4vcpu-16gb + - m3-4vcpu-32gb + - m3-8vcpu-64gb + - num_nodes: 9 + sizes: + - gd-2vcpu-8gb + - m3-2vcpu-16gb + - gd-4vcpu-16gb + - m3-4vcpu-32gb + - m3-8vcpu-64gb + - num_nodes: 15 + sizes: + - gd-2vcpu-8gb + - m3-2vcpu-16gb + - gd-4vcpu-16gb + - m3-4vcpu-32gb + - m3-8vcpu-64gb + default_version: '2' + pg: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '13' + - '14' + - '15' + - '16' + - '17' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-1gb + - db-amd-1vcpu-1gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-amd-2vcpu-8gb + - db-intel-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-amd-4vcpu-16gb + - db-intel-4vcpu-16gb + - db-intel-8vcpu-32gb + - db-amd-8vcpu-32gb + - db-intel-16vcpu-64gb + - db-amd-16vcpu-64gb + - num_nodes: 2 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-intel-2vcpu-8gb + - db-amd-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-intel-4vcpu-16gb + - db-amd-4vcpu-16gb + - db-amd-8vcpu-32gb + - db-intel-8vcpu-32gb + - db-amd-16vcpu-64gb + - db-intel-16vcpu-64gb + - num_nodes: 3 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - gd-16vcpu-64gb + - gd-32vcpu-128gb + - gd-40vcpu-160gb + - so1_5-2vcpu-16gb + - so1_5-4vcpu-32gb + - so1_5-8vcpu-64gb + - so1_5-16vcpu-128gb + - so1_5-24vcpu-192gb + - so1_5-32vcpu-256gb + - db-intel-1vcpu-2gb + - db-amd-1vcpu-2gb + - db-amd-2vcpu-4gb + - db-intel-2vcpu-4gb + - db-intel-2vcpu-8gb + - db-amd-2vcpu-8gb + - db-intel-4vcpu-8gb + - db-amd-4vcpu-8gb + - db-intel-4vcpu-16gb + - db-amd-4vcpu-16gb + - db-amd-8vcpu-32gb + - db-intel-8vcpu-32gb + - db-amd-16vcpu-64gb + - db-intel-16vcpu-64gb + default_version: '17' + advanced_pg: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '16' + - '17' + - '18' + layouts: + - num_nodes: 1 + sizes: + - gd-2vcpu-8gb-intel + - so1_5-2vcpu-16gb-intel + - so1_5-2vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb-intel + - so1_5-4vcpu-32gb-intel + - so1_5-4vcpu-32gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - so1_5-8vcpu-64gb + - gd-8vcpu-32gb-intel + - so1_5-8vcpu-64gb-intel + - gd-16vcpu-64gb + - so1_5-16vcpu-128gb + - gd-16vcpu-64gb-intel + - so1_5-16vcpu-128gb-intel + - so1_5-24vcpu-192gb + - so1_5-24vcpu-192gb-intel + - so1_5-32vcpu-256gb-intel + - gd-32vcpu-128gb + - gd-32vcpu-128gb-intel + - so1_5-32vcpu-256gb + - gd-40vcpu-160gb + - so1_5-48vcpu-384gb-intel + - gd-48vcpu-192gb-intel + - so1_5-48vcpu-256gb + - c-96-intel + - num_nodes: 2 + sizes: + - gd-2vcpu-8gb-intel + - so1_5-2vcpu-16gb-intel + - so1_5-2vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb-intel + - so1_5-4vcpu-32gb-intel + - so1_5-4vcpu-32gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - so1_5-8vcpu-64gb + - gd-8vcpu-32gb-intel + - so1_5-8vcpu-64gb-intel + - gd-16vcpu-64gb + - so1_5-16vcpu-128gb + - gd-16vcpu-64gb-intel + - so1_5-16vcpu-128gb-intel + - so1_5-24vcpu-192gb + - so1_5-24vcpu-192gb-intel + - so1_5-32vcpu-256gb-intel + - gd-32vcpu-128gb + - gd-32vcpu-128gb-intel + - so1_5-32vcpu-256gb + - gd-40vcpu-160gb + - so1_5-48vcpu-384gb-intel + - gd-48vcpu-192gb-intel + - so1_5-48vcpu-256gb + - c-96-intel + - num_nodes: 3 + sizes: + - gd-2vcpu-8gb-intel + - so1_5-2vcpu-16gb-intel + - so1_5-2vcpu-16gb + - gd-2vcpu-8gb + - gd-4vcpu-16gb-intel + - so1_5-4vcpu-32gb-intel + - so1_5-4vcpu-32gb + - gd-4vcpu-16gb + - gd-8vcpu-32gb + - so1_5-8vcpu-64gb + - gd-8vcpu-32gb-intel + - so1_5-8vcpu-64gb-intel + - gd-16vcpu-64gb + - so1_5-16vcpu-128gb + - gd-16vcpu-64gb-intel + - so1_5-16vcpu-128gb-intel + - so1_5-24vcpu-192gb + - so1_5-24vcpu-192gb-intel + - so1_5-32vcpu-256gb-intel + - gd-32vcpu-128gb + - gd-32vcpu-128gb-intel + - so1_5-32vcpu-256gb + - gd-40vcpu-160gb + - so1_5-48vcpu-384gb-intel + - gd-48vcpu-192gb-intel + - so1_5-48vcpu-256gb + - c-96-intel + default_version: '18' + redis: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '7' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + - num_nodes: 2 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + - num_nodes: 3 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + valkey: + regions: + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc3 + - sfo2 + - sfo3 + - sgp1 + - syd1 + - tor1 + - ric1 + - atl1 + versions: + - '8' + layouts: + - num_nodes: 1 + sizes: + - db-s-1vcpu-1gb + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + - num_nodes: 2 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + - num_nodes: 3 + sizes: + - db-s-1vcpu-2gb + - db-s-2vcpu-4gb + - db-s-4vcpu-8gb + - db-s-6vcpu-16gb + - db-s-8vcpu-32gb + - db-s-16vcpu-64gb + - m-2vcpu-16gb + - m-4vcpu-32gb + - m-8vcpu-64gb + - m-16vcpu-128gb + - m-24vcpu-192gb + - m-32vcpu-256gb + default_version: '8' + version_availability: + kafka: + - end_of_life: null + end_of_availability: '2025-06-03T00:00:00Z' + version: '3.8' + default: true + mongodb: + - end_of_life: '2025-07-01T07:00:00Z' + end_of_availability: null + version: '6.0' + default: false + - end_of_life: '2026-08-01T07:00:00Z' + end_of_availability: null + version: '7.0' + default: true + mysql: + - end_of_life: null + end_of_availability: null + version: '8' + default: true + opensearch: + - end_of_life: null + end_of_availability: null + version: '1' + default: false + - end_of_life: null + end_of_availability: null + version: '2' + default: true + pg: + - end_of_life: '2025-11-13T00:00:00Z' + end_of_availability: '2025-05-13T00:00:00Z' + version: '13' + default: false + - end_of_life: '2026-11-12T00:00:00Z' + end_of_availability: '2026-05-12T00:00:00Z' + version: '14' + default: false + - end_of_life: '2027-11-11T00:00:00Z' + end_of_availability: '2027-05-12T00:00:00Z' + version: '15' + default: false + - end_of_life: '2028-11-09T00:00:00Z' + end_of_availability: '2028-05-09T00:00:00Z' + version: '16' + default: false + - end_of_life: '2029-11-08T00:00:00Z' + end_of_availability: '2029-05-08T00:00:00Z' + version: '17' + default: true + redis: + - end_of_life: '2025-06-30T00:00:00Z' + end_of_availability: '2025-04-30T00:00:00Z' + version: '7' + default: true + valkey: + - end_of_life: null + end_of_availability: null + version: '8' + default: true + advanced_pg: + - end_of_life: '2028-11-09T00:00:00Z' + end_of_availability: '2028-05-09T00:00:00Z' + version: '16' + default: false + - end_of_life: '2029-11-08T00:00:00Z' + end_of_availability: '2029-05-08T00:00:00Z' + version: '17' + default: false + - end_of_life: '2030-11-13T00:00:00Z' + end_of_availability: '2030-05-13T00:00:00Z' + version: '18' + default: true + advanced_mysql: + - end_of_life: null + end_of_availability: null + version: 8.4.8 + default: true + database_clusters: + description: A JSON object with a key of `databases`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + databases: + type: array + items: + $ref: '#/components/schemas/database_cluster_read' + example: + databases: + - id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + name: backend + engine: pg + version: '10' + connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + private_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: private-backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + users: + - name: doadmin + role: primary + password: wv78n3zpz42xezdk + db_names: + - defaultdb + num_nodes: 1 + region: nyc3 + status: online + created_at: '2019-01-11T18:37:36Z' + maintenance_window: + day: saturday + hour: '08:45:12' + pending: true + description: + - Update TimescaleDB to version 1.2.1 + - Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases + size: db-s-2vcpu-4gb + tags: + - production + private_network_uuid: d455e75d-4858-4eec-8c95-da2f0a5f93a7 + version_end_of_life: '2023-11-09T00:00:00Z' + version_end_of_availability: '2023-05-09T00:00:00Z' + storage_size_mib: 61440 + database_cluster: + description: A JSON object with a key of `database`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + database: + $ref: '#/components/schemas/database_cluster_read' + required: + - database + example: + database: + id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + name: backend + engine: pg + version: '14' + semantic_version: '14.5' + connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + private_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: private-backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + standby_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@replica-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: replica-backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + standby_private_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@private-replica-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: >- + private-replica-backend-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + users: + - name: doadmin + role: primary + password: wv78n3zpz42xezdk + db_names: + - defaultdb + num_nodes: 2 + region: nyc3 + status: creating + created_at: '2019-01-11T18:37:36Z' + maintenance_window: + day: saturday + hour: '08:45:12' + pending: true + description: + - Update TimescaleDB to version 1.2.1 + - Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases + size: db-s-2vcpu-4gb + tags: + - production + private_network_uuid: d455e75d-4858-4eec-8c95-da2f0a5f93a7 + version_end_of_life: '2023-11-09T00:00:00Z' + version_end_of_availability: '2023-05-09T00:00:00Z' + storage_size_mib: 61440 + do_settings: + service_cnames: + - db.example.com + - database.myapp.io + database_config: + description: A JSON object with a key of `config`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + config: + anyOf: + - $ref: '#/components/schemas/mysql_advanced_config' + - $ref: '#/components/schemas/postgres_advanced_config' + - $ref: '#/components/schemas/redis_advanced_config' + - $ref: '#/components/schemas/valkey_advanced_config' + - $ref: '#/components/schemas/kafka_advanced_config' + - $ref: '#/components/schemas/opensearch_advanced_config' + - $ref: '#/components/schemas/mongo_advanced_config' + required: + - config + example: + config: + sql_mode: >- + ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES + sql_require_primary_key: true + ca: + description: A JSON object with a key of `ca`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + ca: + $ref: '#/components/schemas/ca' + required: + - ca + example: + ca: + certificate: >- + LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVRVENDQXFtZ0F3SUJBZ0lVRUZZWTdBWFZQS0Raam9jb1lpMk00Y0dvcU0wd0RRWUpLb1pJaHZjTkFRRU0KQlFBd09qRTRNRFlHQTFVRUF3d3ZOek0zT1RaaE1XRXRaamhrTUMwME9HSmpMV0V4Wm1NdFpqbGhNVFZsWXprdwpORGhsSUZCeWIycGxZM1FnUTBFd0hoY05NakF3TnpFM01UVTFNREEyV2hjTk16QXdOekUxTVRVMU1EQTJXakE2Ck1UZ3dOZ1lEVlFRRERDODNNemM1Tm1FeFlTMW1PR1F3TFRRNFltTXRZVEZtWXkxbU9XRXhOV1ZqT1RBME9HVWcKVUhKdmFtVmpkQ0JEUVRDQ0FhSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnR1BBRENDQVlvQ2dnR0JBTVdScXhycwpMZnpNdHZyUmxKVEw4MldYMVBLZkhKbitvYjNYcmVBY3FZd1dBUUp2Q3IycmhxSXZieVZzMGlaU0NzOHI4c3RGClljQ0R1bkxJNmUwTy9laERZYTBIT2RrMkFFRzE1ckVOVmNha2NSczcyQWlHVHNrdkNXS2VkUjFTUWswVWt0WCsKQUg4S1ExS3F5bzNtZ2Y2cVV1WUpzc3JNTXFselk3YTN1RVpEb2ZqTjN5Q3MvM21pTVJKcVcyNm1JV0IrUUlEbAo5YzdLRVF5MTZvdCtjeHVnd0lLMm9oZHMzaFY1bjBKMFVBM0I3QWRBdXY5aUl5L3JHaHlTNm5CNTdaWm9JZnAyCnFybXdOY0UrVjlIdXhQSGtRVjFOQjUwOFFudWZ4Z0E5VCtqU2VrdGVUbWFORkxqNjFXL3BtcndrTytOaWFXUTIKaGgzVXBKOEozY1BoNkErbHRnUmpSV2NEb2lsYVNwRVVpU09WemNNYVFvalZKYVJlNk9NbnZYc29NaSs3ZzdneApWcittQ0lUcGcvck9DaXpBWWQ2UFAxLzdYTjk1ZXNmU2tBQnM5c3hJakpjTUFqbDBYTEFzRmtGZVdyeHNIajlVCmJnaDNWYXdtcnpUeXhZT0RQcXV1cS9JcGlwc0RRT3Fpb2ZsUStkWEJJL3NUT0NNbVp6K0pNcG5HYXdJREFRQUIKb3o4d1BUQWRCZ05WSFE0RUZnUVVSekdDRlE3WEtUdHRDN3JzNS8ydFlQcExTZGN3RHdZRFZSMFRCQWd3QmdFQgovd0lCQURBTEJnTlZIUThFQkFNQ0FRWXdEUVlKS29aSWh2Y05BUUVNQlFBRGdnR0JBSWFKQ0dSVVNxUExtcmcvCmk3MW10b0NHUDdzeG1BVXVCek1oOEdrU25uaVdaZnZGMTRwSUtqTlkwbzVkWmpHKzZqK1VjalZtK0RIdGE1RjYKOWJPeEk5S0NFeEI1blBjRXpMWjNZYitNOTcrellxbm9zUm85S21DVFJBb2JrNTZ0WU1FS1h1aVJja2tkMm1yUQo4cGw2N2xxdThjM1V4c0dHZEZVT01wMkk3ZTNpdUdWVm5UR0ZWM3JQZUdaQ0J3WGVyUUQyY0F4UjkzS3BnWVZ2ClhUUzk5dnpSbm1HOHhhUm9EVy9FbEdXZ2xWd0Q5a1JrbXhUUkdoYTdDWVZCcjFQVWY2dVVFVjhmVFIxc1hFZnIKLytMR1JoSVVsSUhWT3l2Yzk3YnZYQURPbWF1MWZDVE5lWGtRdTNyZnZFSlBmaFlLeVIwT0V3eWVvdlhRNzl0LwpTV2ZGTjBreU1Pc1UrNVNIdHJKSEh1eWNWcU0yQlVVK083VjM1UnNwOU9MZGRZMFFVbTZldFpEVEhhSUhYYzRRCnl1Rm1OL1NhSFZtNE0wL3BTVlJQdVd6TmpxMnZyRllvSDRtbGhIZk95TUNJMjc2elE2aWhGNkdDSHlkOUJqajcKUm1UWGEyNHM3NWhmSi9YTDV2bnJSdEtpVHJlVHF6V21EOVhnUmNMQ0gyS1hJaVRtSWc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg== + online_migration: + description: A JSON object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/online_migration' + example: + id: 77b28fc8-19ff-11eb-8c9c-c68e24557488 + status: running + created_at: '2020-10-29T15:57:38Z' + accepted: + description: >- + This does not indicate the success or failure of any operation, just + that the request has been accepted for processing. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + firewall_rules: + description: A JSON object with a key of `rules`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + rules: + type: array + items: + $ref: '#/components/schemas/firewall_rule' + example: + rules: + - uuid: 79f26d28-ea8a-41f2-8ad8-8cfcdd020095 + cluster_uuid: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + type: k8s + value: ff2a6c52-5a44-4b63-b99c-0e98e7a63d61 + created_at: '2019-11-14T20:30:28Z' + - uuid: adfe81a8-0fa1-4e2d-973f-06aa5af19b44 + cluster_uuid: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + type: ip_addr + description: a development IP address + value: 192.168.1.1 + created_at: '2019-11-14T20:30:28Z' + - uuid: b9b42276-8295-4313-b40f-74173a7f46e6 + cluster_uuid: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + type: droplet + value: '163973392' + created_at: '2019-11-14T20:30:28Z' + - uuid: 718d23e0-13d7-4129-8a00-47fb72ee0deb + cluster_uuid: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + type: tag + value: backend + created_at: '2019-11-14T20:30:28Z' + database_backups: + description: A JSON object with a key of `database_backups`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + backups: + type: array + items: + $ref: '#/components/schemas/backup' + scheduled_backup_time: + type: object + properties: + backup_hour: + type: integer + example: 20 + description: The hour of the day when the backup is scheduled (in UTC). + backup_minute: + type: integer + example: 40 + description: The minute of the hour when the backup is scheduled. + backup_interval_hours: + type: integer + example: 24 + description: The frequency, in hours, at which backups are taken. + backup_progress: + type: string + example: '36' + description: >- + If a backup is currently in progress, this attribute shows the + percentage of completion. If no backup is in progress, this + attribute will be hidden. + required: + - backups + example: + backups: + - created_at: '2019-01-11T18:42:27Z' + size_gigabytes: 0.03357696 + incremental: false + - created_at: '2019-01-12T18:42:29Z' + size_gigabytes: 0.03364864 + incremental: true + scheduled_backup_time: + backup_hour: 20 + backup_minute: 40 + backup_interval_hours: 24 + backup_progress: '36' + database_replicas: + description: A JSON object with a key of `replicas`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + replicas: + type: array + items: + $ref: '#/components/schemas/database_replica_read' + example: + replicas: + - name: read-nyc3-01 + connection: + uri: '' + database: defaultdb + host: read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + private_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: >- + private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + region: nyc3 + status: online + created_at: '2019-01-11T18:37:36Z' + database_replica: + description: A JSON object with a key of `replica`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + replica: + $ref: '#/components/schemas/database_replica_read' + example: + replica: + name: read-nyc3-01 + connection: + uri: '' + database: defaultdb + host: read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + private_connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require + database: '' + host: private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com + port: 25060 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + region: nyc3 + status: online + created_at: '2019-01-11T18:37:36Z' + do_settings: + service_cnames: + - replica-db.example.com + - read-replica.myapp.io + events_logs: + description: A JSON object with a key of `events`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + events: + type: array + items: + $ref: '#/components/schemas/events_logs' + example: + events: + - id: pe8u2huh + cluster_name: customer-events + event_type: cluster_create + create_time: '2020-10-29T15:57:38Z' + - id: pe8ufefuh + cluster_name: customer-events + event_type: cluster_update + create_time: '2023-10-30T15:57:38Z' + users: + description: A JSON object with a key of `users`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + users: + type: array + items: + $ref: '#/components/schemas/database_user' + example: + users: + - name: app-01 + role: normal + password: jge5lfxtzhx42iff + - name: doadmin + role: primary + password: wv78n3zpz42xezd + user: + description: A JSON object with a key of `user`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + user: + $ref: '#/components/schemas/database_user' + required: + - user + examples: + New User: + value: + user: + name: app-01 + role: normal + password: jge5lfxtzhx42iff + New User with MySQL Auth Plugin: + value: + user: + name: app-02 + role: normal + password: wv78n3zpz42xezdk + mysql_settings: + auth_plugin: mysql_native_password + New User for Postgres with replication rights: + value: + user: + name: app-02 + role: normal + password: wv78n3zpz42xezdk + settings: + pg_allow_replication: true + Kafka User: + value: + user: + name: app-03 + role: normal + password: qv78n3zes42xezdk + access_cert: >- + -----BEGIN CERTIFICATE----- + + MIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA + + MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD + + ExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x + + NzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j + + b20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+ + + CYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb + + 8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4 + + oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz + + Z03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna + + k/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb + + QwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB + + BQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1 + + MbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG + + CCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl + + dHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s + + ZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu + + Zy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW + + MCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB + + BQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1 + + cG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp + + dGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl + + bmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM + + PKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e + + iXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD + + D3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7 + + q9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/ + + WyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu + + UlF1zblDmg2Iaw== + + -----END CERTIFICATE----- + access_key: >- + -----BEGIN PRIVATE KEY----- + + MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52 + + SVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1 + + DwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X + + wrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w + + Z2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F + + ZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX + + fqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l + + 9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm + + cVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt + + eRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF + + 0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6x + + gtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRh + + GGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+ + + P8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj + + IntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49 + + W1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ + + 3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt + + Nfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx + + pxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG + + RKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0 + + o4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E + + sAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW + + JUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo + + QbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/ + + AangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg + + eTuK2xNR0PIM8OI7pRpgyj1I + + -----END PRIVATE KEY----- + settings: + acl: + - id: acl128aaaa99239 + permission: produceconsume + topic: customer-events + - id: acl293098flskdf + permission: produce + topic: customer-events.* + - id: acl128ajei20123 + permission: consume + topic: customer-events + databases: + description: A JSON object with a key of `databases`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + dbs: + type: array + items: + $ref: '#/components/schemas/database' + example: + dbs: + - name: alpha + - name: defaultdb + database: + description: A JSON object with a key of `db`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + db: + $ref: '#/components/schemas/database' + required: + - db + example: + db: + name: alpha + connection_pools: + description: A JSON object with a key of `pools`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/connection_pools' + example: + pools: + - user: doadmin + name: reporting-pool + size: 10 + db: defaultdb + mode: session + connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/foo?sslmode=require + database: foo + host: backend-do-user-19081923-0.db.ondigitalocean.com + port: 25061 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + - user: doadmin + name: backend-pool + size: 10 + db: defaultdb + mode: transaction + connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require + database: backend-pool + host: backend-do-user-19081923-0.db.ondigitalocean.com + port: 25061 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + connection_pool: + description: A JSON object with a key of `pool`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + pool: + $ref: '#/components/schemas/connection_pool' + required: + - pool + example: + pool: + user: doadmin + name: backend-pool + size: 10 + db: defaultdb + mode: transaction + connection: + uri: >- + postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require + database: backend-pool + host: backend-do-user-19081923-0.db.ondigitalocean.com + port: 25061 + user: doadmin + password: wv78n3zpz42xezdk + ssl: true + eviction_policy_response: + description: A JSON string with a key of `eviction_policy`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + required: + - eviction_policy + properties: + eviction_policy: + $ref: '#/components/schemas/eviction_policy_model' + sql_mode: + description: A JSON string with a key of `sql_mode`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/sql_mode' + example: + sql_mode: >- + ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES + autoscale: + description: A JSON object with autoscale configuration details. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + autoscale: + $ref: '#/components/schemas/database_autoscale_params' + example: + autoscale: + storage: + enabled: true + threshold_percent: 80 + increment_gib: 10 + unprocessable_entity: + description: Unprocessable Entity + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: unprocessable_entity + message: request payload validation failed + request_id: 4851a473-1621-42ea-b2f9-5071c0ea8414 + kafka_topics: + description: A JSON object with a key of `topics`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + topics: + type: array + items: + $ref: '#/components/schemas/kafka_topic' + example: + topics: + - name: customer-events + state: active + replication_factor: 2 + partition_count: 3 + - name: engineering-events + state: configuring + replication_factor: 2 + partition_count: 10 + kafka_topic: + description: A JSON object with a key of `topic`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + topic: + $ref: '#/components/schemas/kafka_topic_verbose' + example: + topic: + name: customer-events + partitions: + - size: 4096 + id: 0 + in_sync_replicas: 3 + earliest_offset: 0 + consumer_groups: + - name: consumer-group-1 + offset: 0 + - name: consumer-group-2 + offset: 1 + - size: 4096 + id: 1 + in_sync_replicas: 3 + earliest_offset: 0 + consumer_groups: null + replication_factor: 3 + state: active + config: + cleanup_policy: delete + compression_type: producer + delete_retention_ms: 86400000 + file_delete_delay_ms: 60000 + flush_messages: 9223372036854776000 + flush_ms: 9223372036854776000 + index_interval_bytes: 4096 + max_compaction_lag_ms: 9223372036854776000 + max_message_bytes: 1048588 + message_down_conversion_enable: true + message_format_version: 3.0-IV1 + message_timestamp_difference_max_ms: 9223372036854776000 + message_timestamp_type: create_time + min_cleanable_dirty_ratio: 0.5 + min_compaction_lag_ms: 0 + min_insync_replicas: 1 + preallocate: false + retention_bytes: -1 + retention_ms: 604800000 + segment_bytes: 209715200 + segment_index_bytes: 10485760 + segment_jitter_ms: 0 + segment_ms: 604800000 + logsinks: + description: A JSON object with a key of `sinks`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + sinks: + type: array + items: + $ref: '#/components/schemas/logsink_schema' + example: + sinks: + - sink_id: 799990b6-d551-454b-9ffe-b8618e9d6272 + sink_name: logs-sink-1 + sink_type: rsyslog + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc5424 + - sink_id: d6e95157-5f58-48d0-9023-8cfb409d102a + sink_name: logs-sink-2 + sink_type: rsyslog + config: + server: 192.168.10.1 + port: 514 + tls: false + format: rfc3164 + logsink: + description: A JSON object with a key of `sink`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + sink: + $ref: '#/components/schemas/logsink_schema' + examples: + Create an opensearch logsink: + value: + sink: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: opensearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: opensearch-logs + index_days_max: 5 + Create an elasticsearch logsink: + value: + sink: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: elasticsearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: elasticsearch-logs + index_days_max: 5 + Create a rsyslog logsink: + value: + sink: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: rsyslog + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc5424 + Create a datadog logsink: + value: + sink: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: rsyslog + config: + site: http-intake.logs.datadoghq.com + datadog_api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + logsink_data: + description: A JSON object with logsink properties. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/logsink_schema' + examples: + Get an opensearch logsink: + value: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: opensearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: opensearch-logs + index_days_max: 5 + Get an elasticsearch logsink: + value: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: elasticsearch + config: + url: https://user:passwd@192.168.0.1:25060 + index_prefix: elasticsearch-logs + index_days_max: 5 + Get a rsyslog logsink: + value: + sink_id: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + sink_name: logs-sink + sink_type: rsyslog + config: + server: 192.168.0.1 + port: 514 + tls: false + format: rfc5424 + kafka_schemas: + description: A JSON object with a key of `subjects`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + subjects: + type: array + items: + $ref: '#/components/schemas/kafka_schema_verbose' + kafka_schema: + description: A JSON object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/kafka_schema_verbose' + required: + - schema_id + - subject_name + - schema_type + - schema + kafka_schema_version: + description: A JSON object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/kafka_schema_version_verbose' + required: + - schema_id + - subject_name + - schema_type + - schema + - version + database_schema_registry_config: + description: A JSON object with a key of `compatibility_level`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + compatibility_level: + type: string + enum: + - NONE + - BACKWARD + - BACKWARD_TRANSITIVE + - FORWARD + - FORWARD_TRANSITIVE + - FULL + - FULL_TRANSITIVE + description: The compatibility level of the schema registry. + required: + - compatibility_level + example: + compatibility_level: BACKWARD + database_schema_registry_subject_config: + description: A JSON object with a key of `compatibility_level`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + subject_name: + type: string + description: The name of the schema subject. + compatibility_level: + type: string + enum: + - NONE + - BACKWARD + - BACKWARD_TRANSITIVE + - FORWARD + - FORWARD_TRANSITIVE + - FULL + - FULL_TRANSITIVE + description: The compatibility level of the schema registry. + required: + - subject_name + - compatibility_level + example: + subject_name: my-schema-subject + compatibility_level: BACKWARD + database_metrics_auth: + description: A JSON object with a key of `credentials`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + credentials: + $ref: '#/components/schemas/database_metrics_credentials' + example: + credentials: + basic_auth_username: username + basic_auth_password: password + opensearch_indexes: + description: A JSON object with a key of `indexes`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + indexes: + type: array + items: + $ref: '#/components/schemas/opensearch_index' + example: + indexes: + - index_name: sample-data + number_of_shards: 2 + number_of_replicas: 3 + size: 208 + created_time: '2021-01-01T00:00:00Z' + status: open + health: green + - index_name: logs-* + number_of_shards: 2 + number_of_replicas: 3 + size: 208 + created_time: '2021-01-01T00:00:00Z' + status: open + health: green + dedicated_inference: + description: Response containing a single Dedicated Inference instance. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + dedicated_inference: + $ref: '#/components/schemas/dedicated_inference' + example: + dedicated_inference: + id: 6b5c619c-359c-44ca-87e2-47e98170c01d + status: active + region: atl1 + vpc_uuid: 997615ce-132d-4bae-9270-9ee21b395e5d + endpoints: + public_endpoint_fqdn: >- + https://b4bfug4jc41kts2ro54if91eo-public-dedicated-inference.do-infra.ai + private_endpoint_fqdn: >- + https://b4bfug4jc41kts2ro54if91eo-private-dedicated-inference.do-infra.ai + created_at: '2024-01-09T20:44:32Z' + updated_at: '2024-01-09T20:44:32Z' + dedicated_inference_update_accepted: + description: >- + Dedicated Inference update accepted for processing (202). Response + contains only the dedicated_inference; no token is returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + dedicated_inference: + $ref: '#/components/schemas/dedicated_inference' + all_dedicated_inferences: + description: >- + The response will be a JSON object with a key called + `dedicated_inferences`. This will be set to an array of objects, each of + which will contain the standard attributes associated with a Dedicated + Inference. Pagination uses the same `links` and `meta` structure as + other list endpoints. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + required: + - dedicated_inferences + - links + - meta + properties: + dedicated_inferences: + type: array + items: + $ref: '#/components/schemas/dedicated_inference' + description: Array of Dedicated Inference instances. + links: + type: object + properties: + pages: + type: object + description: Pagination links (first, prev, next, last). + additionalProperties: + type: string + format: uri + meta: + type: object + required: + - total + properties: + total: + type: integer + example: 1 + description: Total number of results. + example: + dedicated_inferences: + - id: 6b5c619c-359c-44ca-87e2-47e98170c01d + status: active + region: atl1 + vpc_uuid: 997615ce-132d-4bae-9270-9ee21b395e5d + endpoints: + public_endpoint_fqdn: >- + https://b4bfug4jc41kts2ro54if91eo-public-dedicated-inference.do-infra.ai + private_endpoint_fqdn: >- + https://b4bfug4jc41kts2ro54if91eo-private-dedicated-inference.do-infra.ai + created_at: '2024-01-09T20:44:32Z' + updated_at: '2024-01-09T20:44:32Z' + links: + pages: + first: >- + https://api.digitalocean.com/v2/dedicated-inferences?page=1&per_page=20 + last: >- + https://api.digitalocean.com/v2/dedicated-inferences?page=1&per_page=20 + meta: + total: 1 + dedicated_inference_provisioning: + description: >- + Dedicated Inference create/update accepted for processing (202). Success + or failure is not indicated by the response code. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + dedicated_inference: + $ref: '#/components/schemas/dedicated_inference' + token: + $ref: '#/components/schemas/dedicated_inference_access_token' + accelerators_list: + description: >- + The response will be a JSON object with a key called `accelerators`. + This will be set to an array of accelerator objects. Pagination uses the + same `links` and `meta` structure as other list endpoints. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + accelerators: + type: array + items: + $ref: '#/components/schemas/dedicated_inference_accelerator' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + accelerators: + - id: 5b5c619c-359c-44ca-87e2-47e98170c02f + name: mi300x1-ghfpsf + slug: gpu-mi300x1-192gb + role: prefill_and_decode + status: active + created_at: '2024-01-09T20:44:32Z' + links: + pages: + first: >- + https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/accelerators?page=1&per_page=20 + last: >- + https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/accelerators?page=1&per_page=20 + meta: + total: 1 + ca_certificate: + description: >- + CA certificate for the Dedicated Inference (base64-encoded). Required + for private endpoint connectivity. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + required: + - cert + properties: + cert: + type: string + description: Base64-encoded CA certificate. + example: + cert: LS0tLS1CRUdJTi... + tokens_list: + description: >- + The response will be a JSON object with a key called `tokens`. This will + be set to an array of objects (id, name, created_at, is_managed; value + is not returned). Pagination uses the same `links` and `meta` structure + as other list endpoints (e.g. VPC peerings). + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + tokens: + type: array + items: + $ref: '#/components/schemas/dedicated_inference_access_token' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + tokens: [] + links: + pages: + first: >- + https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/tokens?page=1&per_page=20 + last: >- + https://api.digitalocean.com/v2/dedicated-inferences/6b5c619c-359c-44ca-87e2-47e98170c01d/tokens?page=1&per_page=20 + meta: + total: 0 + token_created: + description: Token created; value is returned only once. Store securely. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + token: + $ref: '#/components/schemas/dedicated_inference_access_token' + all_domains_response: + description: >- + The response will be a JSON object with a key called `domains`. The + value of this will be an array of Domain objects, each of which contain + the standard domain attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + domains: + type: array + items: + $ref: '#/components/schemas/domain' + description: Array of volumes. + required: + - domains + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + domains: + - name: example.com + ttl: 1800 + zone_file: > + $ORIGIN example.com. + + $TTL 1800 + + example.com. IN SOA ns1.digitalocean.com. + hostmaster.example.com. 1415982609 10800 3600 604800 1800 + + example.com. 1800 IN NS ns1.digitalocean.com. + + example.com. 1800 IN NS ns2.digitalocean.com. + + example.com. 1800 IN NS ns3.digitalocean.com. + + example.com. 1800 IN A 1.2.3.4 + links: {} + meta: + total: 1 + create_domain_response: + description: >- + The response will be a JSON object with a key called `domain`. The value + of this will be an object that contains the standard attributes + associated with a domain. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + domain: + $ref: '#/components/schemas/domain' + example: + domain: + name: example.com + ttl: 1800 + zone_file: null + existing_domain: + description: >- + The response will be a JSON object with a key called `domain`. The value + of this will be an object that contains the standard attributes defined + for a domain. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + domain: + $ref: '#/components/schemas/domain' + example: + domain: + name: example.com + ttl: 1800 + zone_file: > + $ORIGIN example.com. + + $TTL 1800 + + example.com. IN SOA ns1.digitalocean.com. + hostmaster.example.com. 1415982611 10800 3600 604800 1800 + + example.com. 1800 IN NS ns1.digitalocean.com. + + example.com. 1800 IN NS ns2.digitalocean.com. + + example.com. 1800 IN NS ns3.digitalocean.com. + + example.com. 1800 IN A 1.2.3.4 + all_domain_records_response: + description: >- + The response will be a JSON object with a key called `domain_records`. + The value of this will be an array of domain record objects, each of + which contains the standard domain record attributes. For attributes + that are not used by a specific record type, a value of `null` will be + returned. For instance, all records other than SRV will have `null` for + the `weight` and `port` attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + domain_records: + type: array + items: + $ref: '#/components/schemas/domain_record' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Domain Records: + $ref: '#/components/examples/domain_records_all' + created_domain_record: + description: >- + The response body will be a JSON object with a key called + `domain_record`. The value of this will be an object representing the + new record. Attributes that are not applicable for the record type will + be set to `null`. An `id` attribute is generated for each record as part + of the object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + domain_record: + $ref: '#/components/schemas/domain_record' + example: + domain_record: + id: 28448433 + type: A + name: www + data: 162.10.66.0 + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + domain_record: + description: >- + The response will be a JSON object with a key called `domain_record`. + The value of this will be a domain record object which contains the + standard domain record attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + domain_record: + $ref: '#/components/schemas/domain_record' + example: + domain_record: + id: 3352896 + type: A + name: blog + data: 162.10.66.0 + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + all_droplets: + description: A JSON object with a key of `droplets`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/droplet' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Droplets: + $ref: '#/components/examples/droplets_all' + Droplets Filtered By Tag: + $ref: '#/components/examples/droplets_tagged' + GPU Droplets: + $ref: '#/components/examples/gpu_droplets' + droplet_create: + description: Accepted + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + oneOf: + - title: Single Droplet Response + properties: + droplet: + $ref: '#/components/schemas/droplet' + links: + type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action_link' + required: + - droplet + - links + - title: Multiple Droplet Response + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/droplet' + links: + type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action_link' + required: + - droplets + - links + examples: + Single Droplet Create Response: + $ref: '#/components/examples/droplet_create_response' + Multiple Droplet Create Response: + $ref: '#/components/examples/droplet_multi_create_response' + no_content_with_content_type: + description: >- + The action was successful and the response body is empty. This response + has content-type set. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content-type: + $ref: '#/components/headers/content-type' + existing_droplet: + description: > + The response will be a JSON object with a key called `droplet`. This + will be + + set to a JSON object that contains the standard Droplet attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + droplet: + $ref: '#/components/schemas/droplet' + examples: + Single Droplet: + $ref: '#/components/examples/droplet_single' + all_droplet_backups: + description: A JSON object with an `backups` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + backups: + type: array + items: + $ref: '#/components/schemas/droplet_snapshot' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + backups: + - id: 67539192 + name: web-01- 2020-07-29 + distribution: Ubuntu + slug: null + public: false + regions: + - nyc3 + created_at: '2020-07-29T01:44:35Z' + min_disk_size: 50 + size_gigabytes: 2.34 + type: backup + links: {} + meta: + total: 1 + droplet_backup_policy: + description: > + The response will be a JSON object with a key called `policy`. This will + be + + set to a JSON object that contains the standard Droplet backup policy + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + policy: + $ref: '#/components/schemas/droplet_backup_policy_record' + example: + policy: + droplet_id: 444909706 + backup_enabled: true + backup_policy: + plan: weekly + weekday: SUN + hour: 20 + window_length_hours: 4 + retention_period_days: 28 + next_backup_window: + start: '2024-09-15T20:00:00Z' + end: '2024-09-16T00:00:00Z' + all_droplet_backup_policies: + description: >- + A JSON object with a `policies` key set to a map. The keys are Droplet + IDs and the values are objects containing the backup policy information + for each Droplet. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + policies: + type: object + description: > + A map where the keys are the Droplet IDs and the values + are + + objects containing the backup policy information for each + Droplet. + additionalProperties: + $ref: '#/components/schemas/droplet_backup_policy_record' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + policies: + '436444618': + droplet_id: 436444618 + backup_enabled: false + '444909314': + droplet_id: 444909314 + backup_enabled: true + backup_policy: + plan: daily + hour: 20 + window_length_hours: 4 + retention_period_days: 7 + next_backup_window: + start: '2024-09-13T20:00:00Z' + end: '2024-09-14T00:00:00Z' + '444909706': + droplet_id: 444909706 + backup_enabled: true + backup_policy: + plan: weekly + weekday: SUN + hour: 20 + window_length_hours: 4 + retention_period_days: 28 + next_backup_window: + start: '2024-09-15T20:00:00Z' + end: '2024-09-16T00:00:00Z' + links: {} + meta: + total: 3 + droplets_supported_backup_policies: + description: >- + A JSON object with an `supported_policies` key set to an array of + objects describing each supported backup policy. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + supported_policies: + type: array + items: + $ref: '#/components/schemas/supported_droplet_backup_policy' + example: + supported_policies: + - name: weekly + possible_window_starts: + - 0 + - 4 + - 8 + - 12 + - 16 + - 20 + window_length_hours: 4 + retention_period_days: 28 + possible_days: + - SUN + - MON + - TUE + - WED + - THU + - FRI + - SAT + - name: daily + possible_window_starts: + - 0 + - 4 + - 8 + - 12 + - 16 + - 20 + window_length_hours: 4 + retention_period_days: 7 + possible_days: [] + all_droplet_snapshots: + description: A JSON object with an `snapshots` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + snapshots: + type: array + items: + $ref: '#/components/schemas/droplet_snapshot' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + snapshots: + - id: 6372321 + name: web-01-1595954862243 + created_at: '2020-07-28T16:47:44Z' + regions: + - nyc3 + - sfo3 + min_disk_size: 25 + size_gigabytes: 2.34 + type: snapshot + links: {} + meta: + total: 1 + all_droplet_actions: + description: A JSON object with an `actions` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + actions: + - id: 982864273 + status: completed + type: create + started_at: '2020-07-20T19:37:30Z' + completed_at: '2020-07-20T19:37:45Z' + resource_id: 3164444 + resource_type: droplet + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - m-1vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + region_slug: nyc3 + links: {} + meta: + total: 1 + droplet_action: + description: The response will be a JSON object with a key called `action`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + $ref: '#/components/schemas/action' + droplet_actions_response: + description: The response will be a JSON object with a key called `actions`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + all_kernels: + description: A JSON object that has a key called `kernels`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + kernels: + type: array + items: + $ref: '#/components/schemas/kernel' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + kernels: + - id: 7515 + name: DigitalOcean GrubLoader v0.2 (20160714) + version: 2016.07.13-DigitalOcean_loader_Ubuntu + links: + pages: + next: >- + https://api.digitalocean.com/v2/droplets/3164444/kernels?page=2&per_page=1 + last: >- + https://api.digitalocean.com/v2/droplets/3164444/kernels?page=171&per_page=1 + meta: + total: 171 + all_firewalls: + description: A JSON object that has a key called `firewalls`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + firewalls: + type: array + items: + $ref: '#/components/schemas/firewall' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + firewalls: + - id: bb4b2611-3d72-467b-8602-280330ecd65c + status: succeeded + created_at: '2020-05-23T21:24:00Z' + pending_changes: + - droplet_id: 8043964 + removing: true + status: waiting + name: firewall + droplet_ids: + - 89989 + - 33322 + tags: + - base-image + - prod + inbound_rules: + - protocol: udp + ports: 8000-9000 + sources: + addresses: + - 1.2.3.4 + - 18.0.0.0/8 + droplet_ids: + - 8282823 + - 3930392 + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + tags: + - base-image + - dev + outbound_rules: + - protocol: tcp + ports: 7000-9000 + destinations: + addresses: + - 1.2.3.4 + - 18.0.0.0/8 + droplet_ids: + - 3827493 + - 213213 + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + tags: + - base-image + - prod + links: + pages: {} + meta: + total: 1 + neighbor_droplets: + description: A JSON object with an `droplets` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/droplet' + associated_resources_list: + description: >- + A JSON object containing `snapshots`, `volumes`, and `volume_snapshots` + keys. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + reserved_ips: + type: array + description: >- + Reserved IPs that are associated with this + Droplet.
Requires `reserved_ip:read` scope. + items: + $ref: '#/components/schemas/associated_resource' + floating_ips: + type: array + description: >- + Floating IPs that are associated with this + Droplet.
Requires `reserved_ip:read` scope. + items: + $ref: '#/components/schemas/associated_resource' + snapshots: + type: array + description: >- + Snapshots that are associated with this + Droplet.
Requires `image:read` scope. + items: + $ref: '#/components/schemas/associated_resource' + volumes: + type: array + description: >- + Volumes that are associated with this Droplet.
Requires + `block_storage:read` scope. + items: + $ref: '#/components/schemas/associated_resource' + volume_snapshots: + type: array + description: >- + Volume Snapshots that are associated with this + Droplet.
Requires `block_storage_snapshot:read` scope. + items: + $ref: '#/components/schemas/associated_resource' + example: + reserved_ips: + - id: '6186916' + name: 45.55.96.47 + cost: '4.00' + floating_ips: + - id: '6186916' + name: 45.55.96.47 + cost: '4.00' + snapshots: + - id: '61486916' + name: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 + cost: '0.05' + volumes: + - id: ba49449a-7435-11ea-b89e-0a58ac14480f + name: volume-nyc1-01 + cost: '10.00' + volume_snapshots: + - id: edb0478d-7436-11ea-86e6-0a58ac144b91 + name: volume-nyc1-01-1585758983629 + cost: '0.04' + associated_resources_status: + description: >- + A JSON object containing containing the status of a request to destroy a + Droplet and its associated resources. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/associated_resource_status' + example: + droplet: + id: '187000742' + name: ubuntu-s-1vcpu-1gb-nyc1-01 + destroyed_at: '2020-04-01T18:11:49Z' + resources: + reserved_ips: + - id: '6186916' + name: 45.55.96.47 + destroyed_at: '2020-04-01T18:11:44Z' + floating_ips: + - id: '6186916' + name: 45.55.96.47 + destroyed_at: '2020-04-01T18:11:44Z' + snapshots: + - id: '61486916' + name: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 + destroyed_at: '2020-04-01T18:11:44Z' + volumes: [] + volume_snapshots: + - id: edb0478d-7436-11ea-86e6-0a58ac144b91 + name: volume-nyc1-01-1585758983629 + destroyed_at: '2020-04-01T18:11:44Z' + completed_at: '2020-04-01T18:11:49Z' + failures: 0 + conflict: + description: The request could not be completed due to a conflict. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: conflict + message: The request could not be completed due to a conflict. + all_autoscale_pools: + description: A JSON object with a key of `autoscale_pools`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + autoscale_pools: + type: array + items: + $ref: '#/components/schemas/autoscale_pool' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Autoscale Pools: + $ref: '#/components/examples/autoscale_pools_all' + autoscale_pool_create: + description: Accepted + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + autoscale_pool: + $ref: '#/components/schemas/autoscale_pool' + examples: + Autoscale Create Response Dynamic Config: + $ref: '#/components/examples/autoscale_create_response_dynamic' + Autoscale Create Response Static Config: + $ref: '#/components/examples/autoscale_create_response_static' + existing_autoscale_pool: + description: > + The response will be a JSON object with a key called `autoscale_pool`. + This will be + + set to a JSON object that contains the standard autoscale pool + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + autoscale_pool: + $ref: '#/components/schemas/autoscale_pool' + examples: + Single Autoscale Pool: + $ref: '#/components/examples/autoscale_pool_single' + all_members: + description: A JSON object with a key of `droplets`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/member' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All members: + $ref: '#/components/examples/members_all' + history_events: + description: A JSON object with a key of `history`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + history: + type: array + items: + $ref: '#/components/schemas/history' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All History Events: + $ref: '#/components/examples/history_all' + list_firewalls_response: + description: >- + To list all of the firewalls available on your account, send a GET + request to `/v2/firewalls`.

Firewalls responses will include only + the resources that you are granted to see. Ensure that your API token + includes all necessary `:read` permissions for requested + firewall. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + firewalls: + type: array + items: + $ref: '#/components/schemas/firewall' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + firewalls: + - id: fb6045f1-cf1d-4ca3-bfac-18832663025b + name: firewall + status: succeeded + inbound_rules: + - protocol: tcp + ports: '80' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '80' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + created_at: '2017-05-23T21:23:59Z' + droplet_ids: + - 8043964 + tags: [] + pending_changes: [] + links: {} + meta: + total: 1 + create_firewall_response: + description: >- + The response will be a JSON object with a firewall key. This will be set + to an object containing the standard firewall attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + firewall: + $ref: '#/components/schemas/firewall' + example: + firewall: + id: bb4b2611-3d72-467b-8602-280330ecd65c + name: firewall + status: waiting + inbound_rules: + - protocol: tcp + ports: '80' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '80' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + created_at: '2017-05-23T21:24:00Z' + droplet_ids: + - 8043964 + tags: [] + pending_changes: + - droplet_id: 8043964 + removing: false + status: waiting + bad_request: + description: There was an error parsing the request body. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: error parsing request body + request_id: 4851a473-1621-42ea-b2f9-5071c0ea8414 + get_firewall_response: + description: >- + The response will be a JSON object with a firewall key. This will be set + to an object containing the standard firewall + attributes.

Firewalls responses will include only the resources + that you are granted to see. Ensure that your API token includes all + necessary `:read` permissions for requested firewall. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + firewall: + $ref: '#/components/schemas/firewall' + example: + firewall: + id: bb4b2611-3d72-467b-8602-280330ecd65c + name: firewall + status: succeeded + inbound_rules: + - protocol: tcp + ports: '80' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '80' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + created_at: '2017-05-23T21:24:00Z' + droplet_ids: + - 8043964 + tags: [] + pending_changes: [] + put_firewall_response: + description: >- + The response will be a JSON object with a `firewall` key. This will be + set to an object containing the standard firewall attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + firewall: + $ref: '#/components/schemas/firewall' + example: + firewall: + id: bb4b2611-3d72-467b-8602-280330ecd65c + name: frontend-firewall + inbound_rules: + - protocol: tcp + ports: '80' + sources: + load_balancer_uids: + - 4de7ac8b-495b-4884-9a69-1050c6793cd6 + - protocol: tcp + ports: '22' + sources: + tags: + - gateway + addresses: + - 18.0.0.0/8 + outbound_rules: + - protocol: tcp + ports: '80' + destinations: + addresses: + - 0.0.0.0/0 + - '::/0' + created_at: '2020-05-23T21:24:00Z' + droplet_ids: + - 8043964 + tags: + - frontend + status: waiting + pending_changes: + - droplet_id: 8043964 + removing: false + status: waiting + floating_ip_list: + description: >- + The response will be a JSON object with a key called `floating_ips`. + This will be set to an array of floating IP objects, each of which will + contain the standard floating IP attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + floating_ips: + type: array + items: + $ref: '#/components/schemas/floating_ip' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + floating_ips: + - ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: {} + meta: + total: 1 + floating_ip_created: + description: >- + The response will be a JSON object with a key called `floating_ip`. The + value of this will be an object that contains the standard attributes + associated with a floating IP. + + When assigning a floating IP to a Droplet at same time as it created, + the response's `links` object will contain links to both the Droplet and + the assignment action. The latter can be used to check the status of the + action. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + floating_ip: + $ref: '#/components/schemas/floating_ip' + links: + type: object + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/action_link' + actions: + type: array + items: + $ref: '#/components/schemas/action_link' + examples: + floating_ip_assigning: + $ref: '#/components/examples/floating_ip_assigning' + floating_ip_reserving: + $ref: '#/components/examples/floating_ip_reserving' + floating_ip: + description: >- + The response will be a JSON object with a key called `floating_ip`. The + value of this will be an object that contains the standard attributes + associated with a floating IP. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + floating_ip: + $ref: '#/components/schemas/floating_ip' + examples: + floating_ip_assigned: + $ref: '#/components/examples/floating_ip_assigned' + floating_ip_reserved: + $ref: '#/components/examples/floating_ip_reserved' + floating_ip_actions: + description: >- + 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 floating IP action attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + actions: + - id: 72531856 + status: completed + type: reserve_ip + started_at: '2015-11-21T21:51:09Z' + completed_at: '2015-11-21T21:51:09Z' + resource_id: 758604197 + resource_type: floating_ip + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc3 + links: {} + meta: + total: 1 + floating_ip_action: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard floating IP action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + allOf: + - $ref: '#/components/schemas/action' + - type: object + properties: + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the reserved IP + currently belongs. + example: + action: + id: 72531856 + status: completed + type: assign_ip + started_at: '2015-11-12T17:51:03Z' + completed_at: '2015-11-12T17:51:14Z' + resource_id: 758604968 + resource_type: floating_ip + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc3 + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + list_namespaces: + description: >- + An array of JSON objects with a key called `namespaces`. Each object + represents a namespace and contains + + the properties associated with it. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + namespaces: + type: array + items: + $ref: '#/components/schemas/namespace_info' + namespace_created: + description: >- + A JSON response object with a key called `namespace`. The object + contains the properties associated + + with the namespace. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + namespace: + $ref: '#/components/schemas/namespace_info' + namespace_bad_request: + description: Bad Request. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: 'Invalid request payload: missing label field' + request_id: 4851a473-1621-42ea-b2f9-5071c0ea8414 + namespace_limit_reached: + description: Limit Reached + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: unprocessable_entity + message: namespace limit reached + request_id: a3275238-3d04-4405-a123-55c389b406c0 + namespace_not_allowed: + description: Not Allowed. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: forbidden + message: not allowed to get namespace + request_id: b11e45a4-892c-48c9-9001-b6cffe9fe795 + namespace_not_found: + description: Bad Request. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: not_found + message: namespace not found + request_id: 88d17b7a-630b-4083-99ce-5b91045efdb4 + list_triggers: + description: >- + An array of JSON objects with a key called `namespaces`. Each object + represents a namespace and contains + + the properties associated with it. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + triggers: + type: array + items: + $ref: '#/components/schemas/trigger_info' + trigger_response: + description: >- + A JSON response object with a key called `trigger`. The object contains + the properties associated + + with the trigger. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + trigger: + $ref: '#/components/schemas/trigger_info' + trigger_bad_request: + description: Bad Request. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: >- + validating create trigger: validation error: missing trigger name, + missing function name, missing source details + request_id: 4851a473-1621-42ea-b2f9-5071c0ea8414 + trigger_limit_reached: + description: Limit Reached + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: unprocessable_entity + message: triggers limit reached + request_id: 7ba99a43-6618-4fe0-9af7-092752ad0d56 + trigger_not_found: + description: Bad Request. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + examples: + namespace not found: + value: + id: not_found + message: namespace not found + request_id: 88d17b7a-630b-4083-99ce-5b91045efdb4 + trigger not found: + value: + id: not_found + message: trigger not found + request_id: 88d17b7a-630b-4083-99ce-5b91045efdb4 + access_key_list: + description: A JSON response containing a list of access keys for the namespace. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + access_keys: + type: array + items: + $ref: '#/components/schemas/access_key' + count: + type: integer + description: Total number of access keys + examples: + With Keys: + value: + access_keys: + - id: dof_v1-xxxx-xxxx-xxxx-xxxxxxxxxxxx + name: my-function-access-key + expires_at: '2026-12-19T10:30:00Z' + created_at: '2025-12-19T10:30:00Z' + updated_at: '2025-12-19T10:30:00Z' + - id: dof_v1-xxxx-xxxx-xxxx-xxxxxxxxxxxx + name: my-function-access-key-2 + expires_at: null + created_at: '2025-11-15T08:00:00Z' + updated_at: '2025-11-15T08:00:00Z' + count: 2 + Empty List: + value: + access_keys: [] + count: 0 + access_key_create: + description: A JSON response containing details about the newly created access key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + access_key: + $ref: '#/components/schemas/access_key_create_response' + examples: + New Access Key: + value: + access_key: + id: dof_v1-xxxx-xxxx-xxxx-xxxxxxxxxxxx + name: my-function-access-key + secret: DOSECRETKEYEXAMPLE + expires_at: '2026-12-19T10:30:00Z' + created_at: '2025-12-19T10:30:00Z' + updated_at: '2025-12-19T10:30:00Z' + access_key_update: + description: A JSON response containing the updated access key details. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + access_key: + $ref: '#/components/schemas/access_key' + examples: + Updated Access Key: + value: + access_key: + id: dof_v1-xxxx-xxxx-xxxx-xxxxxxxxxxxx + name: updated-key-name + expires_at: '2026-12-19T10:30:00Z' + created_at: '2025-12-19T10:30:00Z' + updated_at: '2025-12-19T16:00:00Z' + all_images: + description: >- + The response will be a JSON object with a key called `images`. This + will be set to an array of image objects, each of which will contain the + standard image attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + images: + type: array + items: + $ref: '#/components/schemas/image' + required: + - images + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All: + $ref: '#/components/examples/images_all' + Snapshots: + $ref: '#/components/examples/images_snapshots' + Distribution: + $ref: '#/components/examples/images_distribution' + Custom: + $ref: '#/components/examples/images_custom' + Application: + $ref: '#/components/examples/images_application' + Tagged: + $ref: '#/components/examples/images_tagged' + new_custom_image: + description: >- + The response will be a JSON object with a key set to `image`. The value + of this will be an image object containing a subset of the standard + image attributes as listed below, including the image's `id` and + `status`. After initial creation, the `status` will be `NEW`. Using the + image's id, you may query the image's status by sending a `GET` request + to the `/v2/images/$IMAGE_ID` endpoint. When the `status` changes to + `available`, the image will be ready for use. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + image: + $ref: '#/components/schemas/image' + example: + image: + created_at: '2018-09-20T19:28:00Z' + description: Cloud-optimized image w/ small footprint + distribution: Ubuntu + error_message: '' + id: 38413969 + name: ubuntu-18.04-minimal + regions: [] + type: custom + tags: + - base-image + - prod + status: NEW + existing_image: + description: >- + The response will be a JSON object with a key called `image`. The value + of this will be an image object containing the standard image + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + image: + $ref: '#/components/schemas/image' + required: + - image + example: + image: + id: 6918990 + name: 14.04 x64 + distribution: Ubuntu + slug: ubuntu-16-04-x64 + public: true + regions: + - nyc1 + - ams1 + - sfo1 + - nyc2 + - ams2 + - sgp1 + - lon1 + - nyc3 + - ams3 + - nyc3 + created_at: '2014-10-17T20:24:33Z' + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + updated_image: + description: >- + The response will be a JSON object with a key set to `image`. The value + of this will be an image object containing the standard image + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + image: + $ref: '#/components/schemas/image' + required: + - image + example: + image: + id: 7938391 + name: new-image-name + distribution: Ubuntu + slug: null + public: false + regions: + - nyc3 + - nyc3 + created_at: '2014-11-14T16:44:03Z' + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + images_post_account_transfer_created: + description: >- + The response will be a JSON object with a key called `transfer_id`. The + value of this will be a number that identifies the initiated transfer. + If the value is `0`, then the transfer has been accepted. Otherwise, the + transfer is pending and waiting for the recipient to accept it. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + transfer_id: + $ref: '#/components/schemas/transfer_id' + example: + transfer_id: 3164444 + get_image_actions_response: + description: >- + 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. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + actions: + - id: 29410565 + status: completed + type: transfer + started_at: '2014-07-25T15:04:21Z' + completed_at: '2014-07-25T15:10:20Z' + resource_id: 7555620 + resource_type: image + region: + name: New York 2 + slug: nyc2 + sizes: + - s-1vcpu-3gb + - m-1vcpu-8gb + - s-3vcpu-1gb + - s-1vcpu-2gb + - s-2vcpu-2gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-1vcpu-1gb + - c-1vcpu-2gb + - s-24vcpu-128gb + features: + - private_networking + - backups + - ipv6 + - metadata + - server_id + - install_agent + - storage + - image_transfer + available: true + region_slug: nyc2 + links: + pages: + last: >- + https://api.digitalocean.com/v2/images/7555620/actions?page=5&per_page=1 + next: >- + https://api.digitalocean.com/v2/images/7555620/actions?page=2&per_page=1 + meta: + total: 5 + post_image_action_response: + description: >- + The response will be a JSON object with a key called `action`. The value + of this will be an object containing the standard image action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/action' + example: + action: + id: 36805527 + status: in-progress + type: transfer + started_at: '2014-11-14T16:42:45Z' + completed_at: null + resource_id: 7938269 + resource_type: image + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-3gb + - m-1vcpu-8gb + - s-3vcpu-1gb + - s-1vcpu-2gb + - s-2vcpu-2gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-1vcpu-1gb + - c-1vcpu-2gb + - s-24vcpu-128gb + features: + - private_networking + - backups + - ipv6 + - metadata + - server_id + - install_agent + - storage + - image_transfer + available: true + region_slug: nyc3 + get_image_action_response: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard image action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/action' + example: + action: + id: 36805527 + status: in-progress + type: transfer + started_at: '2014-11-14T16:42:45Z' + completed_at: null + resource_id: 7938269 + resource_type: image + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-3gb + - m-1vcpu-8gb + - s-3vcpu-1gb + - s-1vcpu-2gb + - s-2vcpu-2gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-1vcpu-1gb + - c-1vcpu-2gb + - s-24vcpu-128gb + features: + - private_networking + - backups + - ipv6 + - metadata + - server_id + - install_agent + - storage + - image_transfer + available: true + region_slug: nyc3 + all_clusters: + description: > + The response will be a JSON object with a key called + `kubernetes_clusters`. + + This will be set to an array of objects, each of which will contain the + + standard Kubernetes cluster attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + kubernetes_clusters: + type: array + items: + $ref: '#/components/schemas/cluster_read' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Kubernetes Clusters: + $ref: '#/components/examples/kubernetes_clusters_all' + cluster_create: + description: > + The response will be a JSON object with a key called + `kubernetes_cluster`. The + + value of this will be an object containing the standard attributes of a + + Kubernetes cluster. + + + The IP address and cluster API server endpoint will not be available + until the + + cluster has finished provisioning. The initial value of the cluster's + + `status.state` attribute will be `provisioning`. When the cluster is + ready, + + this will transition to `running`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + kubernetes_cluster: + $ref: '#/components/schemas/cluster' + examples: + Kubernetes Cluster Response: + $ref: '#/components/examples/kubernetes_clusters_create_basic_response' + Kubernetes Cluster with Multiple Node Pools Response: + $ref: '#/components/examples/kubernetes_clusters_multi_pool_response' + existing_cluster: + description: > + The response will be a JSON object with a key called + `kubernetes_cluster`. The + + value of this will be an object containing the standard attributes of a + + Kubernetes cluster. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + kubernetes_cluster: + $ref: '#/components/schemas/cluster_read' + examples: + Single Kubernetes Cluster: + $ref: '#/components/examples/kubernetes_single' + updated_cluster: + description: > + The response will be a JSON object with a key called + `kubernetes_cluster`. The + + value of this will be an object containing the standard attributes of a + + Kubernetes cluster. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + kubernetes_cluster: + $ref: '#/components/schemas/cluster' + examples: + Updated Kubernetes Cluster: + $ref: '#/components/examples/kubernetes_updated' + associated_kubernetes_resources_list: + description: >- + The response will be a JSON object containing `load_balancers`, + `volumes`, and `volume_snapshots` keys. Each will be set to an array of + objects containing the standard attributes for associated resources. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/associated_kubernetes_resources' + kubeconfig: + description: A kubeconfig file for the cluster in YAML format. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/yaml: + example: | + apiVersion: v1 + clusters: + - cluster: + certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURUxCUUF3TXpFVk1CTUdBMVVFQ2ftTVJHbG4KYVhSaGJFOWpaV0Z1TVJvd0dUSREERXhGck9ITmhZWE1nUTJ4MWMzUmxjaUJEUVRBZUZ3MHhPREV4TVRVeApOakF3TWpCYUZ3MHpPREV4TVRVeE5qQXdNakJhTURNeEZUQVRCZ05WQkFvVERFUnBaMmwwWVd4UFkyVmhiakVhCk1CZ0dBMVVFQXhNUmF6aHpZV0Z6SUVOc2RYTjBaWElnUTBFd2dnRWlNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0SUIKRHdBd2dnRUtBb0lCQVFDK2Z0L05Nd3pNaUxFZlFvTFU2bDgrY0hMbWttZFVKdjl4SmlhZUpIU0dZOGhPZFVEZQpGd1Zoc0pDTnVFWkpJUFh5Y0orcGpkU3pYc1lFSE03WVNKWk9xNkdaYThPMnZHUlJjN2ZQaUFJaFBRK0ZpUmYzCmRhMHNIUkZlM2hCTmU5ZE5SeTliQ2VCSTRSUlQrSEwzRFR3L2I5KytmRkdZQkRoVTEvTTZUWWRhUHR3WU0rdWgKb1pKcWJZVGJZZTFhb3R1ekdnYUpXaXRhdFdHdnNJYU8xYWthdkh0WEIOOHFxa2lPemdrSDdvd3RVY3JYM05iawozdmlVeFU4TW40MmlJaGFyeHNvTnlwdGhHOWZLMi9OdVdKTXJJS2R0Mzhwc0tkdDBFbng0MWg5K0dsMjUzMzhWCk1mdjBDVDF6SG1JanYwblIrakNkcFd0eFVLRyt0YjYzZFhNbkFnTUJBQUdqUlRCRE1BNEdBMVVkRHdFQi93UUUKQXdJQmhqQVNCZ05WSFJNQkFmOEVDREFHQVFIL0FnRUFNQjBHQTFVZERnUVdCQlNQMmJrOXJiUGJpQnZOd1Z1NQpUL0dwTFdvOTdEQU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFEVjFMSGZyc1JiYVdONHE5SnBFVDMxMlluRDZ6Cm5rM3BpU1ZSYVEvM09qWG8wdHJ6Z2N4KzlVTUQxeDRHODI1RnYxc0ROWUExZEhFc2dHUmNyRkVmdGZJQWUrUVYKTitOR3NMRnQrOGZrWHdnUlpoNEU4ZUJsSVlrdEprOWptMzFMT25vaDJYZno0aGs3VmZwYkdvVVlsbmVoak1JZApiL3ZMUk05Y2EwVTJlYTB5OTNveE5pdU9PcXdrZGFjU1orczJtb3JNdGZxc3VRSzRKZDA3SENIbUFIeWpXT2k4ClVOQVUyTnZnSnBKY2RiZ3VzN2I5S3ppR1ZERklFUk04cEo4U1Nob1ZvVFFJd3d5Y2xVTU9EUUJreFFHOHNVRk8KRDE3ZjRod1dNbW5qVHY2MEJBM0dxaTZRcjdsWVFSL3drSEtQcnZjMjhoNXB0NndPWEY1b1M4OUZkUT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K + server: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + name: do-nyc1-prod-cluster-01 + contexts: + - context: + cluster: do-nyc1-prod-cluster-01 + user: do-nyc1-prod-cluster-01-admin + name: do-nyc1-prod-cluster-01 + current-context: do-nyc1-prod-cluster-01 + kind: Config + preferences: {} + users: + - name: do-nyc1-prod-cluster-01-admin + user: + token: 403d085aaa80102277d8da97ffd2db2b6a4f129d0e2146098fdfb0cec624babc + credentials: + description: A JSON object containing credentials for a cluster. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/credentials' + available_upgrades: + description: > + The response will be a JSON object with a key called + + `available_upgrade_versions`. The value of this will be an array of + objects, + + representing the upgrade versions currently available for this cluster. + + + If the cluster is up-to-date (i.e. there are no upgrades currently + available) + + `available_upgrade_versions` will be `null`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + available_upgrade_versions: + type: array + nullable: true + items: + $ref: '#/components/schemas/kubernetes_version' + all_node_pools: + description: > + The response will be a JSON object with a key called `node_pools`. This + will + + be set to an array of objects, each of which will contain the standard + node + + pool attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + node_pools: + type: array + items: + $ref: '#/components/schemas/kubernetes_node_pool' + example: + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: running + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: running + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: running + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: f49f4379-7e7f-4af5-aeb6-0354bd840778 + name: backend-pool + size: g-4vcpu-16gb + count: 2 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + auto_scale: true + min_nodes: 2 + max_nodes: 5 + nodes: + - id: 3385619f-8ec3-42ba-bb23-8d21b8ba7518 + name: affectionate-nightingale-3nif + status: + state: running + droplet_id: '205545373' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: 4b8f60ff-ba06-4523-a6a4-b8148244c7e6 + name: affectionate-nightingale-3niy + status: + state: running + droplet_id: '205545374' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + node_pool_create: + description: > + The response will be a JSON object with a key called `node_pool`. The + value of + + this will be an object containing the standard attributes of a node + pool. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + node_pool: + $ref: '#/components/schemas/kubernetes_node_pool' + example: + node_pool: + id: cdda885e-7663-40c8-bc74-3a036c66545d + name: new-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - front-end + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: true + min_nodes: 3 + max_nodes: 6 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: ' ' + status: + state: provisioning + droplet_id: ' ' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: ' ' + status: + state: provisioning + droplet_id: ' ' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: ' ' + status: + state: provisioning + droplet_id: ' ' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + existing_node_pool: + description: > + The response will be a JSON object with a key called `node_pool`. The + value + + of this will be an object containing the standard attributes of a node + pool. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + node_pool: + $ref: '#/components/schemas/kubernetes_node_pool' + example: + node_pool: + id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + taints: + - key: priority + value: high + effect: NoSchedule + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: running + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: running + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: running + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + node_pool_update: + description: > + The response will be a JSON object with a key called `node_pool`. The + value of + + this will be an object containing the standard attributes of a node + pool. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + node_pool: + $ref: '#/components/schemas/kubernetes_node_pool' + example: + node_pool: + id: cdda885e-7663-40c8-bc74-3a036c66545d + name: renamed-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - front-end + - new-tag + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: true + min_nodes: 3 + max_nodes: 6 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: running + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: running + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: running + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + cluster_user: + description: > + The response will be a JSON object with a key called + `kubernetes_cluster_user` + + containing the username and in-cluster groups that it belongs to. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/user' + all_options: + description: > + The response will be a JSON object with a key called `options` which + contains + + `regions`, `versions`, and `sizes` objects listing the available options + and + + the matching slugs for use when creating a new cluster. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/kubernetes_options' + examples: + All Kubernetes Options: + $ref: '#/components/examples/kubernetes_options' + clusterlint_results: + description: > + The response is a JSON object which contains the diagnostics on + Kubernetes + + objects in the cluster. Each diagnostic will contain some metadata + information + + about the object and feedback for users to act upon. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/clusterlint_results' + clusterlint_run: + description: >- + The response is a JSON object with a key called `run_id` that you can + later use to fetch the run results. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + run_id: + type: string + example: 50c2f44c-011d-493e-aee5-361a4a0d1844 + description: >- + ID of the clusterlint run that can be used later to fetch the + diagnostics. + status_messages: + description: > + The response is a JSON object which contains status messages for a + Kubernetes cluster. Each message object contains a timestamp and an + indication of what issue the cluster is experiencing at a given time. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + messages: + type: array + items: + $ref: '#/components/schemas/status_messages' + all_load_balancers: + description: >- + A JSON object with a key of `load_balancers`. This will be set to an + array of objects, each of which will contain the standard load balancer + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + load_balancers: + type: array + items: + $ref: '#/components/schemas/load_balancer' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Load Balancers: + $ref: '#/components/examples/load_balancers_all' + load_balancer_create: + description: Accepted + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + load_balancer: + $ref: '#/components/schemas/load_balancer' + examples: + Basic Create Response: + $ref: '#/components/examples/load_balancer_basic_response' + SSL Termination Create Response: + $ref: '#/components/examples/load_balancer_ssl_termination_response' + Create Response Using Droplet Tag: + $ref: '#/components/examples/load_balancer_using_tag_response' + Sticky Sessions and Custom Health Check: + $ref: >- + #/components/examples/load_balancer_sticky_sessions_and_health_check_response + existing_load_balancer: + description: > + The response will be a JSON object with a key called `load_balancer`. + The + + value of this will be an object that contains the standard attributes + + associated with a load balancer + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + load_balancer: + $ref: '#/components/schemas/load_balancer' + examples: + load_balancer_basic_response: + $ref: '#/components/examples/load_balancer_basic_response' + updated_load_balancer: + description: > + The response will be a JSON object with a key called `load_balancer`. + The + + value of this will be an object containing the standard attributes of a + + load balancer. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + load_balancer: + $ref: '#/components/schemas/load_balancer' + examples: + load_balancer_update_response: + $ref: '#/components/examples/load_balancer_update_response' + list_alert_policy_response: + description: A list of alert policies. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/list_alert_policy' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + policies: + - alerts: + email: + - bob@example.com + slack: + - channel: Production Alerts + url: >- + https://example.invalid/redacted-slack-webhook" + compare: GreaterThan + description: CPU Alert + enabled: true + entities: + - 192018292 + tags: + - production_droplets + type: v1/insights/droplet/cpu + uuid: 78b3da62-27e5-49ba-ac70-5db0b5935c64 + value: 80 + window: 5m + links: + first: >- + https//api.digitalocean.com/v2/monitoring/alerts?page=1&per_page=10 + prev: >- + https//api.digitalocean.com/v2/monitoring/alerts?page=2&per_page=10 + next: >- + https//api.digitalocean.com/v2/monitoring/alerts?page=4&per_page=10 + last: >- + https//api.digitalocean.com/v2/monitoring/alerts?page=5&per_page=10 + meta: + total: 50 + alert_policy_response: + description: An alert policy. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + policy: + $ref: '#/components/schemas/alert_policy' + droplet_bandwidth_metric_response: + description: >- + The response will be a JSON object with a key called `data` and + `status`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/metrics' + examples: + Inbound Private Bandwidth: + $ref: '#/components/examples/inbound_private_droplet_bandwidth' + Inbound Public Bandwidth: + $ref: '#/components/examples/inbound_public_droplet_bandwidth' + Outbound Private Bandwidth: + $ref: '#/components/examples/outbound_private_droplet_bandwidth' + Outbound Public Bandwidth: + $ref: '#/components/examples/outbound_public_droplet_bandwidth' + droplet_cpu_metric_response: + description: >- + The response will be a JSON object with a key called `data` and + `status`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/metrics' + examples: + CPU: + $ref: '#/components/examples/droplet_cpu' + droplet_filesystem_metric_response: + description: >- + The response will be a JSON object with a key called `data` and + `status`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/metrics' + examples: + Filesystem: + $ref: '#/components/examples/droplet_filesystem' + metric_response: + description: >- + The response will be a JSON object with a key called `data` and + `status`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/metrics' + app_metric_response: + description: >- + The response will be a JSON object with a key called `data` and + `status`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/metrics' + examples: + Memory: + $ref: '#/components/examples/app_memory_percentage' + monitoring_list_destinations: + description: The response is a JSON object with a `destinations` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + destinations: + type: array + items: + $ref: '#/components/schemas/destination_omit_credentials' + destination: + description: The response is a JSON object with a `destination` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + destination: + $ref: '#/components/schemas/destination_omit_credentials' + list_sinks: + description: The response is a JSON object with a `sinks` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + sinks: + type: array + description: List of sinks identified by their URNs. + items: + $ref: '#/components/schemas/sinks_response' + sinks: + description: The response is a JSON object with a `sink` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + sink: + $ref: '#/components/schemas/sinks_response' + nfs_list: + description: >- + The response will be a JSON object with a key called `shares`. The + value will be an array of objects, each containing the standard + attributes associated with an NFS share. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_list_response' + nfs_create: + description: A JSON response containing details about the new NFS share. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_create_response' + bad_request-2: + description: Size must be greater than or equal to 50Gib + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: The value for 'size_gib' must be greater than or equal to 50Gib. + nfs_get: + description: >- + The response will be a JSON object with a key called `share`. The value + will be an object containing the standard attributes associated with an + NFS share. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_get_response' + examples: + Active Share: + value: + share: + id: 0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d + name: sammy-share-drive + size_gib: 1024 + region: atl1 + status: ACTIVE + created_at: '2023-01-01T00:00:00Z' + vpc_ids: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + mount_path: /123456/your-nfs-share-uuid + host: 10.128.32.2 + nfs_actions: + description: The response will be a JSON object with a key called `action`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_actions_response' + nfs_snapshot_list: + description: >- + The response will be a JSON object with a key called `snapshots`. The + value will be an array of objects, each containing the standard + attributes associated with an NFS snapshot. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_snapshot_list_response' + nfs_snapshot_get: + description: >- + The response will be a JSON object with a key called `snapshot`. The + value will be an object containing the standard attributes associated + with an NFS snapshot. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/nfs_snapshot_get_response' + all_partner_attachments: + description: |- + The response will be a JSON object with a `partner_attachments` key + that contains an array of all partner attachments + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + partner_attachments: + type: array + items: + $ref: '#/components/schemas/partner_attachment' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + partner_attachments: + - name: env.prod-partner-network-connect + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + urn: do:partner_attachment:5a4981aa-9653-4bd1-bef5-d6bff52042e4 + state: active + created_at: '2020-03-13T19:20:47.442049222Z' + connection_bandwidth_in_mbps: 10000 + region: nyc + naas_provider: MEGAPORT + vpc_ids: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + bgp: + local_asn: 65432 + local_router_ip: 169.254.0.1/29 + peer_asn: 133937 + peer_router_ip: 169.254.0.6/29 + - id: e0fe0f4d-596a-465e-a902-571ce57b79fa + urn: do:partner_attachment:e0fe0f4d-596a-465e-a902-571ce57b79fa + state: active + name: env.test-partner-network-connect + created_at: '2020-03-13T19:29:20Z' + connection_bandwidth_in_mbps: 10000 + region: nyc + naas_provider: MEGAPORT + vpc_ids: + - e9eef79d-eb6f-4de1-a5b2-38d7468c75c0 + - ac1a3d83-349f-4f67-8214-c2803cec0cff + bgp: + local_asn: 65432 + local_router_ip: 169.254.0.9/29 + peer_asn: 133937 + peer_router_ip: 169.254.0.14/29 + links: {} + meta: + total: 2 + single_partner_attachment: + description: >- + The response will be a JSON object with details about the partner + attachment + + including attached VPC network IDs and BGP configuration information + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + partner_attachment: + $ref: '#/components/schemas/partner_attachment' + example: + partner_attachment: + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + name: env.prod-partner-network-connect + state: CREATED + created_at: '2025-03-27T13:03:53Z' + connection_bandwidth_in_mbps: 1000 + region: NYC + naas_provider: MEGAPORT + vpc_ids: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + bgp: + local_asn: 65000 + local_router_ip: 2.2.2.2/29 + peer_asn: 65001 + peer_router_ip: 3.3.3.3/29 + single_partner_attachment_deleting: + description: >- + The response will be a JSON object with details about the partner + attachment + + and `"state": "DELETING"` to indicate that the partner attachment is + being deleted. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + partner_attachment: + $ref: '#/components/schemas/partner_attachment' + example: + partner_attachment: + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + name: env.prod-partner-network-connect + state: DELETING + created_at: '2025-03-27T13:03:53Z' + connection_bandwidth_in_mbps: 1000 + region: NYC + naas_provider: MEGAPORT + vpc_ids: + - 796c6fe3-2a1d-4da2-9f3e-38239827dc91 + bgp: + local_asn: 65000 + local_router_ip: 2.2.2.2/29 + peer_asn: 65001 + peer_router_ip: 3.3.3.3/29 + single_partner_attachment_bgp_auth_key: + description: >- + The response will be a JSON object with a `bgp_auth_key` object + containing a + + `value` field with the BGP auth key value + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + bgp_auth_key: + type: object + items: + $ref: '#/components/schemas/partner_attachment_service_key' + example: + bgp_auth_key: + value: secret + all_partner_attachment_remote_routes: + description: >- + The response will be a JSON object with a `remote_routes` array + containing + + information on all the remote routes associated with the partner + attachment + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + remote_routes: + type: array + items: + $ref: '#/components/schemas/partner_attachment_remote_route' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + remote_routes: + - cidr: 10.10.10.0/24 + - cidr: 10.10.10.10/24 + links: {} + meta: + total: 2 + single_partner_attachment_service_key: + description: >- + The response will be a JSON object with a `service_key` object + containing + + the service key value and creation information + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + service_key: + type: object + items: + $ref: '#/components/schemas/partner_attachment_service_key' + example: + service_key: + created_at: '2020-03-13T19:20:47.442049222Z' + value: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + state: CREATED + empty_json_object: + description: The response is an empty JSON object. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: {} + example: {} + projects_list: + description: >- + The response will be a JSON object with a key called `projects`. The + value of this will be an object with the standard project attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + projects: + type: array + items: + $ref: '#/components/schemas/project' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + projects: + - id: 4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679 + owner_uuid: 99525febec065ca37b2ffe4f852fd2b2581895e7 + owner_id: 258992 + name: my-web-api + description: My website API + purpose: Service or API + environment: Production + is_default: false + created_at: '2018-09-27T20:10:35Z' + updated_at: '2018-09-27T20:10:35Z' + - id: addb4547-6bab-419a-8542-76263a033cf6 + owner_uuid: 99525febec065ca37b2ffe4f852fd2b2581895e7 + owner_id: 258992 + name: Default + description: Default project + purpose: Just trying out DigitalOcean + environment: Development + is_default: true + created_at: '2017-10-19T21:44:20Z' + updated_at: '2019-11-05T18:50:03Z' + links: + pages: + first: https://api.digitalocean.com/v2/projects?page=1 + last: https://api.digitalocean.com/v2/projects?page=1 + meta: + total: 2 + existing_project: + description: >- + The response will be a JSON object with a key called `project`. The + value of this will be an object with the standard project attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + project: + $ref: '#/components/schemas/project' + default_project: + description: >- + The response will be a JSON object with a key called `project`. The + value of this will be an object with the standard project attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + project: + $ref: '#/components/schemas/project' + example: + project: + id: addb4547-6bab-419a-8542-76263a033cf6 + owner_uuid: 99525febec065ca37b2ffe4f852fd2b2581895e7 + owner_id: 258992 + name: Default + description: Default project + purpose: Just trying out DigitalOcean + environment: Development + is_default: true + created_at: '2017-10-19T21:44:20Z' + updated_at: '2019-11-05T18:50:03Z' + precondition_failed: + description: Only an empty project can be deleted. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: precondition_failed + message: >- + cannot delete a project with resources. move or remove the + resources first + resources_list: + description: > + The response will be a JSON object with a key called `resources`. + + The value of this will be an object with the standard resource + attributes. + + + Only resources that you are authorized to see will be returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + resources: + description: >- + The resources that are assigned to this project. Only + resources that you are authorized to see will be returned. + type: array + items: + $ref: '#/components/schemas/resource' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + resources: + - urn: do:droplet:13457723 + assigned_at: '2018-09-28T19:26:37Z' + links: + self: https://api.digitalocean.com/v2/droplets/13457723 + status: ok + - urn: do:domain:example.com + assigned_at: '2019-03-31T16:24:14Z' + links: + self: https://api.digitalocean.com/v2/domains/example.com + status: ok + links: + pages: + first: >- + https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1 + last: >- + https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1 + meta: + total: 2 + assigned_resources_list: + description: > + The response will be a JSON object with a key called `resources`. + + The value of this will be an object with the standard resource + attributes. + + + Only resources that you are authorized to see will be returned. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + resources: + description: >- + All resources, including the ones added in the request, that + are assigned to the project. Only resources that you are + authorized to see will be returned. + type: array + items: + $ref: '#/components/schemas/resource' + example: + resources: + - urn: do:droplet:13457723 + assigned_at: '2018-09-28T19:26:37Z' + links: + self: https://api.digitalocean.com/v2/droplets/13457723 + status: ok + - urn: do:domain:example.com + assigned_at: '2019-03-31T16:24:14Z' + links: + self: https://api.digitalocean.com/v2/domains/example.com + status: ok + all_regions: + description: >- + A JSON object with a key set to `regions`. The value is an array of + `region` objects, each of which contain the standard `region` + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + regions: + type: array + items: + $ref: '#/components/schemas/region' + required: + - regions + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + regions: + - name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + links: + pages: + last: https://api.digitalocean.com/v2/regions?page=13&per_page=1 + next: https://api.digitalocean.com/v2/regions?page=2&per_page=1 + meta: + total: 13 + all_registries_info: + description: >- + The response will be a JSON object with the key `registry` containing + information about your registry. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + registries: + type: array + items: + oneOf: + - $ref: '#/components/schemas/registry' + multiregistry_info: + description: >- + The response will be a JSON object with the key `registry` containing + information about your registry. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + registry: + $ref: '#/components/schemas/multiregistry' + docker_credentials: + description: A Docker `config.json` file for the container registry. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/docker_credentials' + subscription_response: + description: >- + The response will be a JSON object with a key called `subscription` + containing information about your subscription. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + subscription: + $ref: '#/components/schemas/subscription' + registry_options_response: + description: >- + The response will be a JSON object with a key called `options` which + contains a key called `subscription_tiers` listing the available tiers. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + options: + type: object + properties: + available_regions: + type: array + items: + type: string + example: + - nyc3 + subscription_tiers: + type: array + items: + allOf: + - $ref: '#/components/schemas/subscription_tier_base' + - $ref: '#/components/schemas/subscription_tier_extended' + example: + options: + available_regions: + - nyc3 + - sfo3 + - ams3 + - sgp1 + - fra1 + subscription_tiers: + - name: Starter + slug: starter + included_repositories: 1 + included_storage_bytes: 524288000 + allow_storage_overage: false + included_bandwidth_bytes: 524288000 + monthly_price_in_cents: 0 + eligible: false + eligibility_reasons: + - OverRepositoryLimit + - name: Basic + slug: basic + included_repositories: 5 + included_storage_bytes: 5368709120 + allow_storage_overage: true + included_bandwidth_bytes: 5368709120 + monthly_price_in_cents: 500 + eligible: true + - name: Professional + slug: professional + included_repositories: 0 + included_storage_bytes: 107374182400 + allow_storage_overage: true + included_bandwidth_bytes: 107374182400 + monthly_price_in_cents: 2000 + eligible: true + garbage_collection: + description: >- + The response will be a JSON object with a key of `garbage_collection`. + This will be a json object with attributes representing the + currently-active garbage collection. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + garbage_collection: + $ref: '#/components/schemas/garbage_collection' + garbage_collections: + description: >- + The response will be a JSON object with a key of `garbage_collections`. + This will be set to an array containing objects representing each past + garbage collection. Each will contain the standard Garbage Collection + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + garbage_collections: + type: array + items: + $ref: '#/components/schemas/garbage_collection' + example: + garbage_collections: + - uuid: eff0feee-49c7-4e8f-ba5c-a320c109c8a8 + registry_name: example + status: requested + created_at: '2020-10-30T21:03:24.000Z' + updated_at: '2020-10-30T21:03:44.000Z' + blobs_deleted: 42 + freed_bytes: 667 + meta: + total: 1 + all_repositories_v2: + description: >- + The response body will be a JSON object with a key of `repositories`. + This will be set to an array containing objects each representing a + repository. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + repositories: + type: array + items: + $ref: '#/components/schemas/repository_v2' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + repositories: + - registry_name: example + name: repo-1 + tag_count: 57 + manifest_count: 82 + latest_manifest: + digest: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + registry_name: example + repository: repo-1 + compressed_size_bytes: 1972332 + size_bytes: 2816445 + updated_at: '2021-04-09T23:54:25Z' + tags: + - v1 + - v2 + blobs: + - digest: >- + sha256:14119a10abf4669e8cdbdff324a9f9605d99697215a0d21c360fe8dfa8471bab + compressed_size_bytes: 1471 + - digest: >- + sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e + compressed_size_byte: 2814446 + - digest: >- + sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a + compressed_size_bytes: 528 + meta: + total: 5 + links: + pages: + next: >- + https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=2&page_token=JPZmZzZXQiOjB9&per_page=1 + last: >- + https://api.digitalocean.com/v2/registry/example/repositoriesV2?page=5&per_page=1 + repository_tags: + description: >- + The response body will be a JSON object with a key of `tags`. This will + be set to an array containing objects each representing a tag. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + tags: + type: array + items: + $ref: '#/components/schemas/repository_tag' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + tags: + - registry_name: example + repository: repo-1 + tag: latest + manifest_digest: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + compressed_size_bytes: 2803255 + size_bytes: 5861888 + updated_at: '2020-04-09T23:54:25Z' + meta: + total: 1 + repository_manifests: + description: >- + The response body will be a JSON object with a key of `manifests`. This + will be set to an array containing objects each representing a manifest. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + manifests: + type: array + items: + $ref: '#/components/schemas/repository_manifest' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + manifests: + - digest: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + registry_name: example + repository: repo-1 + compressed_size_bytes: 1972332 + size_bytes: 2816445 + updated_at: '2021-04-09T23:54:25Z' + tags: + - v1 + - v2 + blobs: + - digest: >- + sha256:14119a10abf4669e8cdbdff324a9f9605d99697215a0d21c360fe8dfa8471bab + compressed_size_bytes: 1471 + - digest: >- + sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e + compressed_size_byte: 2814446 + - digest: >- + sha256:69704ef328d05a9f806b6b8502915e6a0a4faa4d72018dc42343f511490daf8a + compressed_size_bytes: 528 + meta: + total: 3 + links: + pages: + first: >- + https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=1&per_page=1 + prev: >- + https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=1&per_page=1 + next: >- + https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=3&per_page=1 + last: >- + https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests?page=3&per_page=1 + registry_info: + description: >- + The response will be a JSON object with the key `registry` containing + information about your registry. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + registry: + $ref: '#/components/schemas/registry' + registries_precondition_fail: + description: There are more than one registries in the DO account. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: precondition_failed + message: >- + This API is not supported if you have created multiple registries. + Please use + + ‘/v2/registries/{registry_name}’ instead. Refer to + + https://docs.digitalocean.com/reference/api/digitalocean/#tag/Container-Registry + for more info. + registries_over_limit: + description: There are more than one registries in the DO account. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: precondition_failed + message: 'registry is not eligible for tier because: [OverRegistryLimit]' + all_repositories: + description: >- + The response body will be a JSON object with a key of `repositories`. + This will be set to an array containing objects each representing a + repository. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + repositories: + type: array + items: + $ref: '#/components/schemas/repository' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + repositories: + - registry_name: example + name: repo-1 + latest_tag: + registry_name: example + repository: repo-1 + tag: latest + manifest_digest: >- + sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221 + compressed_size_bytes: 2803255 + size_bytes: 5861888 + updated_at: '2020-04-09T23:54:25Z' + tag_count: 1 + meta: + total: 1 + droplet_neighbors_ids: + description: A JSON object with an `neighbor_ids` key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/neighbor_ids' + reserved_ip_list: + description: >- + The response will be a JSON object with a key called `reserved_ips`. + This will be set to an array of reserved IP objects, each of which will + contain the standard reserved IP attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + reserved_ips: + type: array + items: + $ref: '#/components/schemas/reserved_ip' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + reserved_ips: + - ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: {} + meta: + total: 1 + reserved_ip_created: + description: >- + The response will be a JSON object with a key called `reserved_ip`. The + value of this will be an object that contains the standard attributes + associated with a reserved IP. + + When assigning a reserved IP to a Droplet at same time as it created, + the response's `links` object will contain links to both the Droplet and + the assignment action. The latter can be used to check the status of the + action. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + reserved_ip: + $ref: '#/components/schemas/reserved_ip' + links: + type: object + properties: + droplets: + type: array + items: + $ref: '#/components/schemas/action_link' + actions: + type: array + items: + $ref: '#/components/schemas/action_link' + examples: + reserved_ip_assigning: + $ref: '#/components/examples/reserved_ip_assigning' + reserved_ip_reserving: + $ref: '#/components/examples/reserved_ip_reserving' + reserved_ip: + description: >- + The response will be a JSON object with a key called `reserved_ip`. The + value of this will be an object that contains the standard attributes + associated with a reserved IP. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + reserved_ip: + $ref: '#/components/schemas/reserved_ip' + examples: + reserved_ip_assigned: + $ref: '#/components/examples/reserved_ip_assigned' + reserved_ip_reserved: + $ref: '#/components/examples/reserved_ip_reserved' + reserved_ip_actions: + description: >- + 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 reserved IP action attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/action' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + actions: + - id: 72531856 + status: completed + type: reserve_ip + started_at: '2015-11-21T21:51:09Z' + completed_at: '2015-11-21T21:51:09Z' + resource_id: 758604197 + resource_type: reserved_ip + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc3 + links: {} + meta: + total: 1 + reserved_ip_action: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard reserved IP action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + allOf: + - $ref: '#/components/schemas/action' + - type: object + properties: + project_id: + type: string + format: uuid + example: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + description: >- + The UUID of the project to which the reserved IP + currently belongs. + example: + action: + id: 72531856 + status: completed + type: assign_ip + started_at: '2015-11-12T17:51:03Z' + completed_at: '2015-11-12T17:51:14Z' + resource_id: 758604968 + resource_type: reserved_ip + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc3 + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + reserved_ipv6_list: + description: >- + The response will be a JSON object with a key called `reserved_ipv6s`. + This will be set to an array of reserved IP objects, each of which will + contain the standard reserved IP attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/reserved_ipv6_list' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + links: {} + meta: + total: 1 + reserved_ipv6s: + - ip: fd53:616d:6d60::dc9:c001 + region_slug: nyc3 + reserved_at: '2020-01-01T00:00:00Z' + - ip: fd53:616d:6d60::dc9:c002 + region_slug: nyc1 + reserved_at: '2020-01-01T00:00:00Z' + reserved_ipv6_create: + description: >- + The response will be a JSON object with key `reserved_ipv6`. The value + of this will be an object that contains the standard attributes + associated with a reserved IPv6. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + reserved_ipv6: + type: object + properties: + ip: + type: string + format: ipv6 + example: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + description: >- + The public IP address of the reserved IPv6. It also serves + as its identifier. + region_slug: + type: string + description: >- + The region that the reserved IPv6 is reserved to. When you + query a reserved IPv6,the region_slug will be returned. + example: nyc3 + reserved_at: + type: string + format: date-time + example: '2024-11-20T11:08:30Z' + examples: + reserved_ipv6_reserved: + $ref: '#/components/examples/reserved_ipv6_reserved' + reserved_ipv6: + description: >- + The response will be a JSON object with key `reserved_ipv6`. The value + of this will be an object that contains the standard attributes + associated with a reserved IPv6. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + reserved_ipv6: + $ref: '#/components/schemas/reserved_ipv6' + examples: + reserved_ipv6_assigned: + $ref: '#/components/examples/reserved_ipv6_assigned' + reserved_ipv6_reserved: + $ref: '#/components/examples/reserved_ipv6_reserved' + reserved_ipv6_action: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard reserved IP action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + allOf: + - $ref: '#/components/schemas/action' + - type: object + properties: + resource_id: + type: integer + example: 758604968 + description: >- + The ID of the resource that the action is being taken + on. + resource_type: + type: string + example: reserved_ipv6 + description: >- + The type of resource that the action is being taken + on. + region_slug: + type: string + example: nyc3 + description: >- + The slug identifier for the region the resource is + located in. + example: + action: + id: 72531856 + status: completed + type: assign_ip + started_at: '2015-11-12T17:51:03Z' + completed_at: '2015-11-12T17:51:14Z' + resource_id: 758604968 + resource_type: reserved_ipv6 + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc3 + byoip_prefix_list: + description: List of BYOIP prefixes as an array of BYOIP prefix JSON objects + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + example: + byoip_prefixes: + - uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 + status: active + region: nyc3 + prefix: 203.0.113.0/24 + validations: [] + failure_reason: '' + advertised: true + locked: false + project_id: 12345678-1234-1234-1234-123456789012 + - uuid: 123e4567-e89b-12d3-a456-426614174001 + status: in_progress + region: sfo2 + prefix: 203.1.113.0/24 + validations: [] + failure_reason: '' + advertised: false + locked: false + project_id: 12345678-1234-1234-1234-123456789012 + links: {} + meta: + total: 2 + schema: + allOf: + - type: object + properties: + byoip_prefixes: + type: array + items: + $ref: '#/components/schemas/byoip_prefix' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + byoip_prefix_create: + description: >- + BYOIP prefix request accepted, response will contain the details of the + created prefix. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + example: + byoip_prefix: + uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 + status: in_progress + region: nyc3 + schema: + type: object + properties: + uuid: + type: string + description: The unique identifier for the BYOIP prefix + example: 123e4567-e89b-12d3-a456-426614174000 + region: + type: string + description: The region where the prefix is created + example: nyc3 + status: + type: string + description: The status of the BYOIP prefix + example: in_progress + byoip_prefix_get: + description: Details of the requested BYOIP prefix + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + example: + byoip_prefix: + uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 + status: active + region: nyc3 + prefix: 203.0.113.0/24 + validations: [] + failure_reason: '' + advertised: true + locked: false + project_id: 12345678-1234-1234-1234-123456789012 + schema: + type: object + properties: + byoip_prefix: + $ref: '#/components/schemas/byoip_prefix' + byoip_prefix_update: + description: Details of the updated BYOIP prefix + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + example: + byoip_prefix: + uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 + status: active + region: nyc3 + prefix: 203.0.113.0/24 + validations: [] + failure_reason: '' + advertised: true + locked: false + project_id: 12345678-1234-1234-1234-123456789012 + schema: + type: object + properties: + byoip_prefix: + $ref: '#/components/schemas/byoip_prefix' + byoip_prefix_list_resources: + description: >- + List of IP addresses assigned to resources (such as Droplets) in a BYOIP + prefix + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + example: + ips: + - id: 11111023 + byoip: 203.0.113.2 + region: nyc3 + resource: do:droplet:fa3c10b-58cc-4372-a567-0e02b2c3d479 + assigned_at: '2025-06-25T12:00:00Z' + - id: 11111024 + byoip: 203.0.113.3 + region: nyc3 + resource: do:droplet:fa3c10b-58cc-4372-a567-0e02b2c3d480 + assigned_at: '2025-06-25T13:00:00Z' + links: {} + meta: + total: 2 + schema: + allOf: + - type: object + properties: + ips: + type: array + items: + $ref: '#/components/schemas/byoip_prefix_resource' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + scans: + description: >- + The response will be a JSON object with a key called `scans`. This will + be set to an array of objects, each of which will contain the standard + attributes associated with a scan. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + scans: + type: array + items: + $ref: '#/components/schemas/scan' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + scan: + description: The response will be a JSON object with a key called `scan`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + scan: + $ref: '#/components/schemas/scan' + affected_resources: + description: >- + The response will be a JSON object with a key called + `affected_resources`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + affected_resources: + type: array + items: + $ref: '#/components/schemas/affected_resource' + settings: + description: The response will be a JSON object with scan settings. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/settings' + tier_coverage: + description: The response will be a JSON object with updated tier coverage. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + tier_coverage: + type: object + additionalProperties: + type: object + properties: + resources: + type: array + items: + type: string + example: + - do:droplet:fe3a2fd7-903d-46e6-ada3-3e4f285fb89d + tags: + type: array + items: + type: string + example: + - production + suppressed_resources: + description: The response will be a JSON object containing suppressed resources. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/suppressed_resource_root' + all_sizes: + description: >- + 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. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + sizes: + type: array + items: + $ref: '#/components/schemas/size' + required: + - sizes + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + sizes: + - slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + disk_info: + - type: local + size: + amount: 25 + unit: gib + links: + pages: + last: https://api.digitalocean.com/v2/sizes?page=64&per_page=1 + next: https://api.digitalocean.com/v2/sizes?page=2&per_page=1 + meta: + total: 64 + snapshots: + description: A JSON object with a key of `snapshots`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + snapshots: + type: array + items: + $ref: '#/components/schemas/snapshots' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Snapshots: + $ref: '#/components/examples/snapshots_all' + Droplets Snapshots: + $ref: '#/components/examples/snapshots_droplets_only' + Volume Snapshots: + $ref: '#/components/examples/snapshots_volumes_only' + snapshots_existing: + description: | + A JSON object with a key called `snapshot`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + snapshot: + $ref: '#/components/schemas/snapshots' + not_a_snapshot: + description: Bad Request + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: the resource is not a snapshot + request_id: bbd8d7d4-2beb-4be1-a374-338e6165e32d + key_list: + description: A JSON response containing a list of keys. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + keys: + type: array + items: + $ref: '#/components/schemas/key' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + keys: + - name: my-access-key + access_key: DOACCESSKEYEXAMPLE + grants: + - bucket: my-bucket + permission: read + created_at: '2018-07-19T15:04:16Z' + links: {} + meta: + total: 1 + key_create: + description: A JSON response containing details about the new key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + key: + $ref: '#/components/schemas/key_create_response' + examples: + Read Only Key: + value: + key: + name: read-only-key + access_key: DOACCESSKEYEXAMPLE + secret_key: DOSECRETKEYEXAMPLE + grants: + - bucket: my-bucket + permission: read + created_at: '2018-07-19T15:04:16Z' + Full Access Key: + value: + key: + name: full-access-key + access_key: DOACCESSKEYEXAMPLE + secret_key: DOSECRETKEYEXAMPLE + grants: + - bucket: '' + permission: fullaccess + created_at: '2018-07-19T15:04:16Z' + Mixed Permission Access Key: + value: + key: + name: custom-bucket-key + access_key: DOACCESSKEYEXAMPLE + secret_key: DOSECRETKEYEXAMPLE + grants: + - bucket: my-bucket + permission: readwrite + - bucket: my-other-bucket + permission: read + created_at: '2018-07-19T15:04:16Z' + bad_request-3: + description: Cannot mix fullaccess permission with scoped permissions + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: bad_request + message: cannot mix fullaccess permission with scoped permissions. + key_get: + description: A JSON response containing details about the key. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + keys: + type: array + items: + $ref: '#/components/schemas/key' + examples: + Read Only Key: + value: + key: + name: read-only-key + access_key: DOACCESSKEYEXAMPLE + grants: + - bucket: my-bucket + permission: read + created_at: '2018-07-19T15:04:16Z' + key_update: + description: The response will be a JSON object + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + key: + $ref: '#/components/schemas/key' + examples: + Read Only Key: + value: + key: + name: new-key-name + access_key: DOACCESSKEYEXAMPLE + grants: + - bucket: my-bucket + permission: read + created_at: '2018-07-19T15:04:16Z' + tags_all: + description: To list all of your tags, you can send a `GET` request to `/v2/tags`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + tags: + type: array + items: + $ref: '#/components/schemas/tags' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + tags: + - name: extra-awesome + resources: + count: 5 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + droplets: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/droplets/3164444 + images: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + volumes: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/volumes/3d80cb72-342b-4aaa-b92e-4e4abb24a933 + volume_snapshots: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/snapshots/1f6f46e8-6b60-11e9-be4e-0a58ac144519 + databases: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/databases/b92438f6-ba03-416c-b642-e9236db91976 + links: {} + meta: + total: 1 + tags_new: + description: >- + The response will be a JSON object with a key called tag. The value of + this will be a tag object containing the standard tag attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + tag: + $ref: '#/components/schemas/tags' + example: + tag: + name: extra-awesome + resources: + count: 0 + droplets: + count: 0 + images: + count: 0 + volumes: + count: 0 + volume_snapshots: + count: 0 + databases: + count: 0 + tags_bad_request: + description: Bad Request + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + x-request-id: + $ref: '#/components/headers/x-request-id' + content: + application/json: + schema: + $ref: '#/components/schemas/error_with_root_causes' + examples: + InvalidCharacters: + value: + error: >- + Error validating resource tag: \"tag-name \\\"здорово\\\" + contains invalid characters\" + messages: null + root_causes: + - >- + rpc error: code = InvalidArgument desc = Error validating + resource tag: \"tag-name \\\"здорово\\\" contains invalid + characters\" + tags_existing: + description: > + The response will be a JSON object with a key called `tag`. + + The value of this will be a tag object containing the standard tag + attributes. + + + Tagged resources will only include resources that you are authorized to + see. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + tag: + $ref: '#/components/schemas/tags' + example: + tag: + tag: + name: extra-awesome + resources: + count: 5 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + droplets: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/droplets/3164444 + images: + count: 1 + last_tagged_uri: https://api.digitalocean.com/v2/images/7555620 + volumes: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/volumes/3d80cb72-342b-4aaa-b92e-4e4abb24a933 + volume_snapshots: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/snapshots/1f6f46e8-6b60-11e9-be4e-0a58ac144519 + databases: + count: 1 + last_tagged_uri: >- + https://api.digitalocean.com/v2/databases/b92438f6-ba03-416c-b642-e9236db91976 + volumes: + description: >- + The response will be a JSON object with a key called `volumes`. This + will be set to an array of volume objects, each of which will contain + the standard volume attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + volumes: + type: array + items: + $ref: '#/components/schemas/volume_full' + description: Array of volumes. + required: + - volumes + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + All Volumes: + $ref: '#/components/examples/volumes_all' + Filtered by Name: + $ref: '#/components/examples/volumes_filtered_by_name' + Filtered by Region: + $ref: '#/components/examples/volumes_filtered_by_region' + volume: + description: >- + The response will be a JSON object with a key called `volume`. The value + will be an object containing the standard attributes associated with a + volume. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + volume: + $ref: '#/components/schemas/volume_full' + example: + volume: + id: 506f78a4-e098-11e5-ad9f-000f53306ae1 + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + droplet_ids: [] + name: example + description: Block store for examples + size_gigabytes: 10 + filesystem_type: ext4 + filesystem_label: example + created_at: '2020-03-02T17:00:49Z' + volumeAction: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard volume action + attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + action: + $ref: '#/components/schemas/volumeAction' + examples: + volume_action_attach_response: + $ref: '#/components/examples/volume_action_attach_response' + VolumeActionDetachResponse: + $ref: '#/components/examples/volume_action_detach_response' + volumeSnapshot: + description: >- + You will get back a JSON object that has a `snapshot` key. This will + contain the standard snapshot attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + snapshot: + $ref: '#/components/schemas/snapshots' + example: + snapshot: + id: 8fa70202-873f-11e6-8b68-000f533176b1 + name: big-data-snapshot1475261774 + regions: + - nyc1 + created_at: '2020-09-30T18:56:14Z' + resource_id: 82a48a18-873f-11e6-96bf-000f53315a41 + resource_type: volume + min_disk_size: 10 + size_gigabytes: 10 + tags: + - aninterestingtag + volumeActions: + description: >- + The response will be an object with a key called `action`. The value of + this will be an object that contains the standard volume action + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + actions: + type: array + items: + $ref: '#/components/schemas/volumeAction' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + actions: + - id: 72531856 + status: completed + type: attach_volume + started_at: '2020-11-21T21:51:09Z' + completed_at: '2020-11-21T21:51:09Z' + resource_type: volume + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc1 + links: {} + meta: + total: 1 + volumeSnapshots: + description: >- + 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 + snapshot attributes + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + snapshots: + type: array + items: + $ref: '#/components/schemas/snapshots' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + snapshots: + - id: 8eb4d51a-873f-11e6-96bf-000f53315a41 + name: big-data-snapshot1475261752 + regions: + - nyc1 + created_at: '2020-09-30T18:56:12Z' + resource_id: 82a48a18-873f-11e6-96bf-000f53315a41 + resource_type: volume + min_disk_size: 10 + size_gigabytes: 0 + tags: null + links: {} + meta: + total: 1 + all_vpcs: + description: >- + The response will be a JSON object with a key called `vpcs`. This will + be set to an array of objects, each of which will contain the standard + attributes associated with a VPC. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + vpcs: + type: array + items: + $ref: '#/components/schemas/vpc' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + vpcs: + - name: env.prod-vpc + description: VPC for production environment + region: nyc1 + ip_range: 10.10.10.0/24 + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + urn: do:vpc:5a4981aa-9653-4bd1-bef5-d6bff52042e4 + default: false + created_at: '2020-03-13T19:20:47.442049222Z' + - id: e0fe0f4d-596a-465e-a902-571ce57b79fa + urn: do:vpc:e0fe0f4d-596a-465e-a902-571ce57b79fa + name: default-nyc1 + description: '' + region: nyc1 + ip_range: 10.102.0.0/20 + created_at: '2020-03-13T19:29:20Z' + default: true + - id: d455e75d-4858-4eec-8c95-da2f0a5f93a7 + urn: do:vpc:d455e75d-4858-4eec-8c95-da2f0a5f93a7 + name: default-nyc3 + description: '' + region: nyc3 + ip_range: 10.100.0.0/20 + created_at: '2019-11-19T22:19:35Z' + default: true + links: {} + meta: + total: 3 + existing_vpc: + description: >- + The response will be a JSON object with a key called `vpc`. The value of + this will be an object that contains the standard attributes associated + with a VPC. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + vpc: + $ref: '#/components/schemas/vpc' + vpc_members: + description: > + The response will be a JSON object with a key called members. This will + be set + + to an array of objects, each of which will contain the standard + attributes + + associated with a VPC member. + + + Only resources that you are authorized to see will be returned (e.g. to + see Droplets, + + you must have `droplet:read`). + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + members: + type: array + items: + $ref: '#/components/schemas/vpc_member' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + members: + - urn: do:loadbalancer:fb294d78-d193-4cb2-8737-ea620993591b + name: nyc1-load-balancer-01 + created_at: '2020-03-13T19:30:48Z' + - urn: do:dbaas:13f7a2f6-43df-4c4a-8129-8733267ddeea + name: db-postgresql-nyc1-55986 + created_at: '2020-03-13T19:30:18Z' + - urn: do:kubernetes:da39d893-96e1-4e4d-971d-1fdda33a46b1 + name: k8s-nyc1-1584127772221 + created_at: '2020-03-13T19:30:16Z' + - urn: do:droplet:86e29982-03a7-4946-8a07-a0114dff8754 + name: ubuntu-s-1vcpu-1gb-nyc1-01 + created_at: '2020-03-13T19:29:20Z' + links: {} + meta: + total: 4 + vpc_peerings: + description: >- + The response will be a JSON object with a key called `peerings`. This + will be set to an array of objects, each of which will contain the + standard attributes associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + peerings: + type: array + items: + $ref: '#/components/schemas/vpc_peering' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + peerings: + - id: 6b5c619c-359c-44ca-87e2-47e98170c01d + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: ACTIVE + - id: c212b274-911c-44cc-a117-23b7da4a2922 + name: another-vpc-peering + vpc_ids: + - 5a100736-b085-4f69-81fd-feee325784bb + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + created_at: '2024-01-10T13:29:58Z' + status: ACTIVE + links: {} + meta: + total: 2 + vpc_peering: + description: >- + The response will be a JSON object with a key called `peering`, + containing the standard attributes associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + peering: + $ref: '#/components/schemas/vpc_peering' + example: + peering: + id: 6b5c619c-359c-44ca-87e2-47e98170c01d + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: PROVISIONING + all_vpc_peerings: + description: >- + The response will be a JSON object with a key called `vpc_peerings`. + This will be set to an array of objects, each of which will contain the + standard attributes associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + vpc_peerings: + type: array + items: + $ref: '#/components/schemas/vpc_peering' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + example: + vpc_peerings: + - id: 6b5c619c-359c-44ca-87e2-47e98170c01d + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: ACTIVE + - id: c212b274-911c-44cc-a117-23b7da4a2922 + name: another-vpc-peering + vpc_ids: + - 5a100736-b085-4f69-81fd-feee325784bb + - c140286f-e6ce-4131-8b7b-df4590ce8d6a + created_at: '2024-01-10T13:29:58Z' + status: ACTIVE + links: {} + meta: + total: 2 + provisioning_vpc_peering: + description: >- + The response will be a JSON object with a key called `vpc_peering`. The + value of this will be an object that contains the standard attributes + associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + vpc_peering: + $ref: '#/components/schemas/vpc_peering' + example: + vpc_peering: + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: PROVISIONING + active_vpc_peering: + description: >- + The response will be a JSON object with a key called `vpc_peering`. The + value of this will be an object that contains the standard attributes + associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + vpc_peering: + $ref: '#/components/schemas/vpc_peering' + example: + vpc_peering: + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: ACTIVE + deleting_vpc_peering: + description: >- + The response will be a JSON object with a key called `vpc_peering`. The + value of this will be an object that contains the standard attributes + associated with a VPC peering. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + vpc_peering: + $ref: '#/components/schemas/vpc_peering' + example: + vpc_peering: + id: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + name: example-vpc-peering + vpc_ids: + - 997615ce-132d-4bae-9270-9ee21b395e5d + - e51aed59-3bb1-4a6a-8de0-9d1329e9c997 + created_at: '2024-01-09T20:44:32Z' + status: DELETING + vpc_nat_gateways: + description: A JSON object with a key of `vpc_nat_gateways`. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + vpc_nat_gateways: + type: array + items: + $ref: '#/components/schemas/vpc_nat_gateway_get' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + examples: + VPC NAT Gateways List Response: + $ref: '#/components/examples/vpc_nat_gateways' + vpc_nat_gateway_create: + description: > + The response will be a JSON object with a key called `vpc_nat_gateway`. + This will be + + set to a JSON object that contains the standard VPC NAT gateway + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + vpc_nat_gateway: + $ref: '#/components/schemas/vpc_nat_gateway_create' + examples: + VPC NAT Gateway Response: + $ref: '#/components/examples/vpc_nat_gateway_create' + vpc_nat_gateway: + description: > + The response will be a JSON object with a key called `vpc_nat_gateway`. + This will be + + set to a JSON object that contains the standard VPC NAT gateway + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + vpc_nat_gateway: + $ref: '#/components/schemas/vpc_nat_gateway_get' + examples: + VPC NAT Gateway Response: + $ref: '#/components/examples/vpc_nat_gateway' + vpc_nat_gateway_update: + description: > + The response will be a JSON object with a key called `vpc_nat_gateway`. + This will be + + set to a JSON object that contains the standard VPC NAT gateway + attributes. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + properties: + vpc_nat_gateway: + $ref: '#/components/schemas/vpc_nat_gateway_update' + examples: + VPC NAT Gateway Update Response: + $ref: '#/components/examples/vpc_nat_gateway_update' + all_checks: + description: >- + The response will be a JSON object with a key called `checks`. This will + be set to an array of objects, each of which will contain the standard + attributes associated with an uptime check + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + checks: + type: array + items: + $ref: '#/components/schemas/check' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + existing_check: + description: >- + The response will be a JSON object with a key called `check`. The value + of this will be an object that contains the standard attributes + associated with an uptime check. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + check: + $ref: '#/components/schemas/check' + existing_check_state: + description: >- + The response will be a JSON object with a key called `state`. The value + of this will be an object that contains the standard attributes + associated with an uptime check's state. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + state: + $ref: '#/components/schemas/state' + all_alerts: + description: >- + The response will be a JSON object with a key called `alerts`. This will + be set to an array of objects, each of which will contain the standard + attributes associated with an uptime alert. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + allOf: + - type: object + properties: + alerts: + type: array + items: + $ref: '#/components/schemas/alert' + - $ref: '#/components/schemas/pagination' + - $ref: '#/components/schemas/meta' + existing_alert: + description: >- + The response will be a JSON object with a key called `alert`. The value + of this will be an object that contains the standard attributes + associated with an uptime alert. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + type: object + properties: + alert: + $ref: '#/components/schemas/alert' + forbidden: + description: > + The authenticated principal does not have permission to perform this + action on the requested resource. + headers: + ratelimit-limit: + $ref: '#/components/headers/ratelimit-limit' + ratelimit-remaining: + $ref: '#/components/headers/ratelimit-remaining' + ratelimit-reset: + $ref: '#/components/headers/ratelimit-reset' + content: + application/json: + schema: + $ref: '#/components/schemas/error' + example: + id: forbidden + message: You do not have permission to perform this action. + links: + sshKeys_get_by_id: + operationId: sshKeys_get_by_id + parameters: + ssh_key_identifier: $response.body#/ssh_key/id + description: >- + The `id` value returned in the response can be used as the + `ssh_key_identifier` parameter in `GET + /v2/account/keys/{ssh_key_identifier}`. + sshKeys_get_by_fingerprint: + operationId: sshKeys_get_by_fingerprint + parameters: + ssh_key_identifier: $response.body#/ssh_key/fingerprint + description: >- + The `fingerprint` value returned in the response can be used as the + `ssh_key_identifier` parameter in `GET + /v2/account/keys/{ssh_key_identifier}`. + sshKeys_delete_by_id: + operationId: sshKeys_delete_by_id + parameters: + ssh_key_identifier: $response.body#/ssh_key/id + description: >- + The `id` value returned in the response can be used as the + `ssh_key_identifier` parameter in `DELETE + /v2/account/keys/{ssh_key_identifier}`. + sshKeys_delete_by_fingerprint: + operationId: ssh_keys_delete_by_fingerprint + parameters: + ssh_key_identifier: $response.body#/ssh_key/fingerprint + description: >- + The `fingerprint` value returned in the response can be used as the + `ssh_key_identifier` parameter in `DELETE + /v2/account/keys/{ssh_key_identifier}`. + examples: + apps: + value: + apps: + - id: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + owner_uuid: ff36cbc6fd350fe12577f5123133bb5ba01a2419 + spec: + name: sample-php + services: + - name: sample-php + git: + repo_clone_url: https://github.com/digitalocean/sample-php.git + branch: main + run_command: heroku-php-apache2 + environment_slug: php + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + domains: + - domain: sample-php.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + default_ingress: https://sample-php-iaj87.ondigitalocean.app + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + active_deployment: + id: 3aa4d20e-5527-4c00-b496-601fbd22520a + spec: + name: sample-php + services: + - name: sample-php + git: + repo_clone_url: https://github.com/digitalocean/sample-php.git + branch: main + run_command: heroku-php-apache2 + environment_slug: php + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: fra + domains: + - domain: sample-php.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + services: + - name: sample-php + source_commit_hash: 54d4a727f457231062439895000d45437c7bb405 + phase_last_updated_at: '2020-12-01T00:42:12Z' + created_at: '2020-12-01T00:40:05Z' + updated_at: '2020-12-01T00:42:12Z' + cause: app spec updated + pending_deployment: + id: 3aa4d20e-5527-4c00-b496-601fbd22520a + spec: + name: sample-php + services: + - name: sample-php + git: + repo_clone_url: https://github.com/digitalocean/sample-php.git + branch: main + run_command: heroku-php-apache2 + environment_slug: php + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: fra + domains: + - domain: sample-php.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + services: + - name: sample-php + source_commit_hash: 54d4a727f457231062439895000d45437c7bb405 + phase_last_updated_at: '2020-12-01T00:42:12Z' + created_at: '2020-12-01T00:40:05Z' + updated_at: '2020-12-01T00:42:12Z' + progress: + success_steps: 6 + total_steps: 6 + steps: + - name: build + status: SUCCESS + steps: + - name: initialize + status: SUCCESS + started_at: '2020-12-01T00:40:11.979305214Z' + ended_at: '2020-12-01T00:40:12.470972033Z' + - name: components + status: SUCCESS + steps: + - name: sample-php + status: SUCCESS + started_at: '0001-01-01T00:00:00Z' + ended_at: '0001-01-01T00:00:00Z' + component_name: sample-php + message_base: Building service + started_at: '2020-12-01T00:40:12.470996857Z' + ended_at: '2020-12-01T00:41:26.180360487Z' + started_at: '2020-12-01T00:40:11.979257919Z' + ended_at: '2020-12-01T00:41:26.653989756Z' + phase: ACTIVE + tier_slug: basic + last_deployment_created_at: '2020-12-01T00:40:05Z' + live_url: https://sample-php.example.com + region: + slug: fra + label: Frankfurt + flag: germany + continent: Europe + data_centers: + - fra1 + tier_slug: basic + live_url_base: https://sample-php.example.com + live_domain: sample-php.example.com + domains: + - id: 0831f444-a1a7-11ed-828c-ef59494480b5 + phase: ACTIVE + spec: + domain: sample-php.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + rotate_validation_records: false + certificate_expires_at: '2024-01-29T23:59:59Z' + progress: + steps: + - ended_at: '0001-01-01T00:00:00Z' + name: default-ingress-ready + started_at: '2023-01-30T22:15:45.021896292Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-zone + started_at: '2023-01-30T22:15:45.022017004Z' + status: SUCCESS + - ended_at: '2023-01-30T15:42:28.50752065Z' + name: ensure-ns-records + started_at: '2023-01-30T22:15:45.025567874Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: verify-nameservers + started_at: '2023-01-30T22:15:45.033591906Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-record + started_at: '2023-01-30T22:15:45.156750604Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.258626422Z' + name: ensure-alias-record + started_at: '2023-01-30T22:15:45.165933869Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.258808279Z' + name: ensure-wildcard-record + started_at: '2023-01-30T22:15:45.166093422Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: verify-cname + started_at: '2023-01-30T22:15:45.166205559Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.475903785Z' + name: ensure-ssl-txt-record-saved + started_at: '2023-01-30T22:15:45.295237186Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.476017236Z' + name: ensure-ssl-txt-record + started_at: '2023-01-30T22:15:45.295315291Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.476094058Z' + name: ensure-renewal-email + started_at: '2023-01-30T22:15:45.295374087Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-CA-authorization + started_at: '2023-01-30T22:15:45.295428101Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-certificate + started_at: '2023-01-30T22:15:45.978756406Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:52.570612857Z' + name: create-deployment + started_at: '0001-01-01T00:00:00Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:31.333582377Z' + name: configuration-alert + started_at: '2023-01-30T22:15:46.278987808Z' + status: SUCCESS + dedicated_ips: + - ip: 192.168.1.1 + id: c24d8f48-3bc4-49f5-8ca0-58e8164427ac + status: ASSIGNED + - ip: 192.168.1.2 + id: 4768fb15-2837-4dda-9be5-3951df4bc3d0 + status: ASSIGNED + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + links: + pages: {} + meta: + total: 1 + app: + value: + app: + id: c2a93513-8d9b-4223-9d61-5e7272c81cf5 + owner_uuid: a4e16f25-cdd1-4483-b246-d77f283c9209 + spec: + name: sample-golang + disable_edge_cache: true + enhanced_threat_control_enabled: true + services: + - name: web + github: + repo: ChiefMateStarbuck/sample-golang + branch: main + run_command: bin/sample-golang + environment_slug: go + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: ams + domains: + - domain: sample-golang.example.com + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + default_ingress: https://sample-golang-zyhgn.ondigitalocean.app + created_at: '2021-02-10T16:45:14Z' + updated_at: '2021-02-10T17:06:56Z' + active_deployment: + id: 991dfa59-6a23-459f-86d6-67dfa2c6f1e3 + spec: + name: sample-golang + services: + - name: web + github: + repo: ChiefMateStarbuck/sample-golang + branch: main + run_command: bin/sample-golang + environment_slug: go + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: ams + domains: + - domain: sample-golang.example.com + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + services: + - name: web + source_commit_hash: db6936cb46047c576962962eed81ad52c21f35d7 + phase_last_updated_at: '2021-02-10T17:06:53Z' + created_at: '2021-02-10T17:05:30Z' + updated_at: '2021-02-10T17:06:53Z' + cause: manual + progress: + success_steps: 6 + total_steps: 6 + steps: + - name: build + status: SUCCESS + steps: + - name: initialize + status: SUCCESS + started_at: '2021-02-10T17:05:35.572347485Z' + ended_at: '2021-02-10T17:05:36.093995229Z' + - name: components + status: SUCCESS + steps: + - name: web + status: SUCCESS + component_name: web + message_base: Building service + started_at: '2021-02-10T17:05:36.094015928Z' + ended_at: '2021-02-10T17:06:19.461737040Z' + started_at: '2021-02-10T17:05:35.572287990Z' + ended_at: '2021-02-10T17:06:19.807834070Z' + - name: deploy + status: SUCCESS + steps: + - name: initialize + status: SUCCESS + started_at: '2021-02-10T17:06:25.143957508Z' + ended_at: '2021-02-10T17:06:26.120343872Z' + - name: components + status: SUCCESS + steps: + - name: web + status: SUCCESS + steps: + - name: deploy + status: SUCCESS + component_name: web + message_base: Deploying service + - name: wait + status: SUCCESS + component_name: web + message_base: Waiting for service + component_name: web + started_at: '2021-02-10T17:06:26.120385561Z' + ended_at: '2021-02-10T17:06:50.029695913Z' + - name: finalize + status: SUCCESS + started_at: '2021-02-10T17:06:50.348459495Z' + ended_at: '2021-02-10T17:06:53.404065961Z' + started_at: '2021-02-10T17:06:25.143932418Z' + ended_at: '2021-02-10T17:06:53.404104185Z' + phase: ACTIVE + tier_slug: basic + last_deployment_created_at: '2021-02-10T17:05:30Z' + live_url: https://sample-golang-zyhgn.ondigitalocean.app + pending_deployment: + id: 3aa4d20e-5527-4c00-b496-601fbd22520a + spec: + name: sample-php + services: + - name: sample-php + git: + repo_clone_url: https://github.com/digitalocean/sample-php.git + branch: main + run_command: heroku-php-apache2 + environment_slug: php + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: fra + domains: + - domain: sample-php.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + region: + slug: ams + label: Amsterdam + flag: netherlands + continent: Europe + data_centers: + - ams3 + tier_slug: basic + live_url_base: https://sample-golang-zyhgn.ondigitalocean.app + live_domain: sample-golang-zyhgn.ondigitalocean.app + project_id: 88b72d1a-b78a-4d9f-9090-b53c4399073f + domains: + - id: e206c64e-a1a3-11ed-9e6e-9b7b6dc9a52b + phase: CONFIGURING + spec: + domain: sample-golang.example.com + type: PRIMARY + zone: example.com + minimum_tls_version: '1.3' + rotate_validation_records: false + certificate_expires_at: '2024-01-29T23:59:59Z' + progress: + steps: + - ended_at: '0001-01-01T00:00:00Z' + name: default-ingress-ready + started_at: '2023-01-30T22:15:45.021896292Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-zone + started_at: '2023-01-30T22:15:45.022017004Z' + status: SUCCESS + - ended_at: '2023-01-30T15:42:28.50752065Z' + name: ensure-ns-records + started_at: '2023-01-30T22:15:45.025567874Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: verify-nameservers + started_at: '2023-01-30T22:15:45.033591906Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-record + started_at: '2023-01-30T22:15:45.156750604Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.258626422Z' + name: ensure-alias-record + started_at: '2023-01-30T22:15:45.165933869Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.258808279Z' + name: ensure-wildcard-record + started_at: '2023-01-30T22:15:45.166093422Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: verify-cname + started_at: '2023-01-30T22:15:45.166205559Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.475903785Z' + name: ensure-ssl-txt-record-saved + started_at: '2023-01-30T22:15:45.295237186Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.476017236Z' + name: ensure-ssl-txt-record + started_at: '2023-01-30T22:15:45.295315291Z' + status: SUCCESS + - ended_at: '2023-01-30T15:43:30.476094058Z' + name: ensure-renewal-email + started_at: '2023-01-30T22:15:45.295374087Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-CA-authorization + started_at: '2023-01-30T22:15:45.295428101Z' + status: SUCCESS + - ended_at: '0001-01-01T00:00:00Z' + name: ensure-certificate + started_at: '2023-01-30T22:15:45.978756406Z' + status: RUNNING + - ended_at: '0001-01-01T00:00:00' + name: create-deployment + started_at: '0001-01-01T00:00:00Z' + status: PENDING + - ended_at: '0001-01-01T00:00:00' + name: configuration-alert + started_at: '0001-01-01T00:00:00' + status: PENDING + dedicated_ips: + - ip: 192.168.1.1 + id: c24d8f48-3bc4-49f5-8ca0-58e8164427ac + status: ASSIGNED + - ip: 192.168.1.2 + id: 4768fb15-2837-4dda-9be5-3951df4bc3d0 + status: ASSIGNED + vpc: + id: c22d8f48-4bc4-49f5-8ca0-58e7164427ac + egress_ips: + - ip: 10.0.0.1 + deployment: + value: + deployment: + id: b6bdf840-2854-4f87-a36c-5f231c617c84 + spec: + name: sample-golang + disable_edge_cache: true + disable_email_obfuscation: true + enhanced_threat_control_enabled: true + services: + - name: web + github: + repo: digitalocean/sample-golang + branch: branch + run_command: bin/sample-golang + environment_slug: go + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 2 + routes: + - path: / + region: ams + services: + - name: web + source_commit_hash: 9a4df0b8e161e323bc3cdf1dc71878080fe144fa + phase_last_updated_at: '0001-01-01T00:00:00Z' + created_at: '2020-07-28T18:00:00Z' + updated_at: '2020-07-28T18:00:00Z' + cause: commit 9a4df0b pushed to github/digitalocean/sample-golang + progress: + pending_steps: 6 + total_steps: 6 + steps: + - name: build + status: PENDING + steps: + - name: initialize + status: PENDING + - name: components + status: PENDING + steps: + - name: web + status: PENDING + component_name: web + message_base: Building service + - name: deploy + status: PENDING + steps: + - name: initialize + status: PENDING + - name: components + status: PENDING + steps: + - name: web + status: PENDING + steps: + - name: deploy + status: PENDING + component_name: web + message_base: Deploying service + - name: wait + status: PENDING + component_name: web + message_base: Waiting for service + component_name: web + - name: finalize + status: PENDING + phase: PENDING_BUILD + tier_slug: basic + logs: + value: + live_url: https://logs-example/build.log + url: https://logs/build.log + historic_logs: + - https://logs-example/archive/build.log + exec: + value: + url: wss://exec/?token=xxx + app_instances: + value: + instances: + - component_name: sample-golang + instance_name: sample-golang-76b84c7fb8-6p8kq + instance_alias: sample-golang-0 + component_type: SERVICE + - component_name: sample-golang + instance_name: sample-golang-76b84c7fb8-ngvpc + instance_alias: sample-golang-1 + component_type: SERVICE + - component_name: sample-php + instance_name: sample-php-767c6b49c4-dkgpt + instance_alias: sample-php-0 + component_type: SERVICE + - component_name: sample-php + instance_name: sample-php-767c6b49c4-z8dll + instance_alias: sample-php-1 + component_type: SERVICE + deployments: + value: + deployments: + - id: b6bdf840-2854-4f87-a36c-5f231c617c84 + spec: + name: sample-golang + disable_edge_cache: true + disable_email_obfuscation: true + enhanced_threat_control_enabled: true + services: + - name: web + github: + repo: digitalocean/sample-golang + branch: branch + run_command: bin/sample-golang + environment_slug: go + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 2 + routes: + - path: / + region: ams + services: + - name: web + source_commit_hash: 9a4df0b8e161e323bc3cdf1dc71878080fe144fa + phase_last_updated_at: '0001-01-01T00:00:00Z' + created_at: '2020-07-28T18:00:00Z' + updated_at: '2020-07-28T18:00:00Z' + cause: commit 9a4df0b pushed to github/digitalocean/sample-golang + progress: + pending_steps: 6 + total_steps: 6 + steps: + - name: build + status: PENDING + steps: + - name: initialize + status: PENDING + - name: components + status: PENDING + steps: + - name: web + status: PENDING + component_name: web + message_base: Building service + - name: deploy + status: PENDING + steps: + - name: initialize + status: PENDING + - name: components + status: PENDING + steps: + - name: web + status: PENDING + steps: + - name: deploy + status: PENDING + component_name: web + message_base: Deploying service + - name: wait + status: PENDING + component_name: web + message_base: Waiting for service + component_name: web + - name: finalize + status: PENDING + phase: PENDING_BUILD + tier_slug: basic + links: + pages: {} + meta: + total: 1 + job_invocations: + value: + job_invocations: + - id: ba32b134-569c-4c0c-ba02-8ffdb0492ece + job_name: good-job + deployment_id: c020763f-ddb7-4112-a0df-7f01c69fc00b + phase: SUCCEEDED + created_at: '2025-09-11T11:04:05Z' + started_at: '2025-09-11T11:04:10Z' + completed_at: '2025-09-11T11:04:40Z' + trigger: + type: SCHEDULE + properties: + type: + type: string + scheduled: + type: object + properties: + schedule: + type: object + properties: + cron: + type: string + example: '*/2 * * * *' + time_zone: + type: string + example: UTC + job_invocation: + value: + job_invocation: + - id: ba32b134-569c-4c0c-ba02-8ffdb0492ece + job_name: good-job + deployment_id: c020763f-ddb7-4112-a0df-7f01c69fc00b + phase: SUCCEEDED + created_at: '2025-09-11T11:04:05Z' + started_at: '2025-09-11T11:04:10Z' + completed_at: '2025-09-11T11:04:40Z' + trigger: + - type: SCHEDULED + scheduled: + - schedule: + cron: '*/2 * * * *' + time_zone: UTC + instance_sizes: + value: + instance_sizes: + - name: Shared 1VCPU 0.5GB + slug: apps-s-1vcpu-0.5gb + cpu_type: SHARED + cpus: '1' + memory_bytes: '536870912' + usd_per_month: '5.00' + usd_per_second: '0.000002066799' + tier_slug: basic + single_instance_only: true + bandwidth_allowance_gib: '50' + - name: Shared 1VCPU 1GB Fixed + slug: apps-s-1vcpu-1gb-fixed + cpu_type: SHARED + cpus: '1' + memory_bytes: '1073741824' + usd_per_month: '10.00' + usd_per_second: '0.000004133598' + tier_slug: basic + single_instance_only: true + bandwidth_allowance_gib: '100' + - name: Shared 1VCPU 1GB + slug: apps-s-1vcpu-1gb + cpu_type: SHARED + cpus: '1' + memory_bytes: '1073741824' + usd_per_month: '12.00' + usd_per_second: '0.000004960317' + tier_slug: professional + bandwidth_allowance_gib: '150' + - name: Shared 1VCPU 2GB + slug: apps-s-1vcpu-2gb + cpu_type: SHARED + cpus: '1' + memory_bytes: '2147483648' + usd_per_month: '25.00' + usd_per_second: '0.000010333995' + tier_slug: professional + bandwidth_allowance_gib: '200' + - name: Shared 2VCPU 4GB + slug: apps-s-2vcpu-4gb + cpu_type: SHARED + cpus: '2' + memory_bytes: '4294967296' + usd_per_month: '50.00' + usd_per_second: '0.000020667989' + tier_slug: professional + bandwidth_allowance_gib: '250' + - name: Dedicated 1VCPU 0.5GB + slug: apps-d-1vcpu-0.5gb + cpu_type: DEDICATED + cpus: '1' + memory_bytes: '536870912' + usd_per_month: '29.00' + usd_per_second: '0.000011987434' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '100' + - name: Dedicated 1VCPU 1GB + slug: apps-d-1vcpu-1gb + cpu_type: DEDICATED + cpus: '1' + memory_bytes: '1073741824' + usd_per_month: '34.00' + usd_per_second: '0.000014054233' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '200' + - name: Dedicated 1VCPU 2GB + slug: apps-d-1vcpu-2gb + cpu_type: DEDICATED + cpus: '1' + memory_bytes: '2147483648' + usd_per_month: '39.00' + usd_per_second: '0.000016121032' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '300' + - name: Dedicated 1VCPU 4GB + slug: apps-d-1vcpu-4gb + cpu_type: DEDICATED + cpus: '1' + memory_bytes: '4294967296' + usd_per_month: '49.00' + usd_per_second: '0.000020254630' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '400' + - name: Dedicated 2VCPU 4GB + slug: apps-d-2vcpu-4gb + cpu_type: DEDICATED + cpus: '2' + memory_bytes: '4294967296' + usd_per_month: '78.00' + usd_per_second: '0.000032242063' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '500' + - name: Dedicated 2VCPU 8GB + slug: apps-d-2vcpu-8gb + cpu_type: DEDICATED + cpus: '2' + memory_bytes: '8589934592' + usd_per_month: '98.00' + usd_per_second: '0.000040509259' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '600' + - name: Dedicated 4VCPU 8GB + slug: apps-d-4vcpu-8gb + cpu_type: DEDICATED + cpus: '4' + memory_bytes: '8589934592' + usd_per_month: '156.00' + usd_per_second: '0.000064484127' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '700' + - name: Dedicated 4VCPU 16GB + slug: apps-d-4vcpu-16gb + cpu_type: DEDICATED + cpus: '4' + memory_bytes: '17179869184' + usd_per_month: '196.00' + usd_per_second: '0.000081018519' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '800' + - name: Dedicated 8VCPU 32GB + slug: apps-d-8vcpu-32gb + cpu_type: DEDICATED + cpus: '8' + memory_bytes: '34359738368' + usd_per_month: '392.00' + usd_per_second: '0.000162037037' + tier_slug: professional + scalable: true + bandwidth_allowance_gib: '900' + instance_size: + value: + instance_size: + name: Shared 1VCPU 0.5GB + slug: apps-s-1vcpu-0.5gb + cpu_type: SHARED + cpus: '1' + memory_bytes: '536870912' + usd_per_month: '5.00' + usd_per_second: '0.000002066799' + tier_slug: basic + single_instance_only: true + bandwidth_allowance_gib: '50' + regions: + value: + regions: + - slug: ams + label: Amsterdam + flag: netherlands + continent: Europe + data_centers: + - ams3 + - slug: nyc + label: New York + flag: usa + continent: North America + data_centers: + - nyc1 + - nyc3 + default: true + - slug: fra + label: Frankfurt + flag: germany + continent: Europe + data_centers: + - fra1 + - slug: sfo + label: San Francisco + flag: usa + continent: North America + data_centers: + - sfo3 + - slug: sgp + label: Singapore + flag: singapore + continent: Asia + data_centers: + - sgp1 + - slug: blr + label: Bangalore + flag: india + continent: Asia + data_centers: + - blr1 + - slug: tor + label: Toronto + flag: canada + continent: North America + data_centers: + - tor1 + - slug: lon + label: London + flag: uk + continent: Europe + data_centers: + - lon1 + propose: + value: + app_name_available: true + existing_static_apps: '2' + max_free_static_apps: '3' + spec: + name: sample-golang + services: + - name: web + github: + repo: digitalocean/sample-golang + branch: branch + run_command: bin/sample-golang + environment_slug: go + instance_size_slug: apps-s-1vcpu-0.5gb + instance_count: 1 + http_port: 8080 + routes: + - path: / + region: ams + app_cost: 5 + alerts: + value: + alerts: + - id: e552e1f9-c1b0-4e6d-8777-ad6f27767306 + spec: + rule: DEPLOYMENT_FAILED + emails: + - sammy@digitalocean.com + phase: ACTIVE + progress: + steps: + - name: alert-configure-insight-alert + status: SUCCESS + started_at: '2020-07-28T18:00:00Z' + ended_at: '2020-07-28T18:00:00Z' + - id: b58cc9d4-0702-4ffd-ab45-4c2a8d979527 + spec: + rule: CPU_UTILIZATION + operator: GREATER_THAN + value: 85 + window: FIVE_MINUTES + emails: + - sammy@digitalocean.com + phase: ACTIVE + progress: + steps: + - name: alert-configure-insight-alert + status: SUCCESS + started_at: '2020-07-28T18:00:00Z' + ended_at: '2020-07-28T18:00:00Z' + alert: + value: + alert: + id: e552e1f9-c1b0-4e6d-8777-ad6f27767306 + spec: + rule: DEPLOYMENT_FAILED + emails: + - sammy@digitalocean.com + phase: ACTIVE + progress: + steps: + - name: alert-configure-insight-alert + status: SUCCESS + started_at: '2020-07-28T18:00:00Z' + ended_at: '2020-07-28T18:00:00Z' + app_bandwidth_usage: + value: + app_bandwidth_usage: + - app_id: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + bandwidth_bytes: '513668' + date: '2023-01-17T00:00:00Z' + app_bandwidth_usage_multiple: + value: + app_bandwidth_usage: + - app_id: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf + bandwidth_bytes: '513668' + - app_id: c2a93513-8d9b-4223-9d61-5e7272c81cf5 + bandwidth_bytes: '254847' + date: '2023-01-17T00:00:00Z' + app_health: + value: + components: + - name: sample-expressjs + cpu_usage_percent: 5.555 + memory_usage_percent: 20.32 + replicas_desired: 1 + replicas_ready: 2 + state: HEALTHY + certificates_all: + value: + certificates: + - id: 892071a0-bb95-49bc-8021-3afd67a210bf + name: web-cert-01 + not_after: '2017-02-22T00:23:00Z' + sha1_fingerprint: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + created_at: '2017-02-08T16:02:37Z' + dns_names: + - '' + state: verified + type: custom + - id: ba9b9c18-6c59-46c2-99df-70da170a42ba + name: web-cert-02 + not_after: '2018-06-07T17:44:12Z' + sha1_fingerprint: 479c82b5c63cb6d3e6fac4624d58a33b267e166c + created_at: '2018-03-09T18:44:11Z' + dns_names: + - www.example.com + - example.com + state: verified + type: lets_encrypt + links: {} + meta: + total: 2 + certificates_custom: + value: + certificate: + id: 892071a0-bb95-49bc-8021-3afd67a210bf + name: web-cert-01 + not_after: '2017-02-22T00:23:00Z' + sha1_fingerprint: dfcc9f57d86bf58e321c2c6c31c7a971be244ac7 + created_at: '2017-02-08T16:02:37Z' + dns_names: + - '' + state: verified + type: custom + certificates_lets_encrypt_pending: + value: + certificate: + id: ba9b9c18-6c59-46c2-99df-70da170a42ba + name: web-cert-02 + not_after: '2018-06-07T17:44:12Z' + sha1_fingerprint: 479c82b5c63cb6d3e6fac4624d58a33b267e166c + created_at: '2018-03-09T18:44:11Z' + dns_names: + - www.example.com + - example.com + state: pending + type: lets_encrypt + certificates_lets_encrypt: + value: + certificate: + id: ba9b9c18-6c59-46c2-99df-70da170a42ba + name: web-cert-02 + not_after: '2018-06-07T17:44:12Z' + sha1_fingerprint: 479c82b5c63cb6d3e6fac4624d58a33b267e166c + created_at: '2018-03-09T18:44:11Z' + dns_names: + - www.example.com + - example.com + state: verified + type: lets_encrypt + domain_records_all: + value: + domain_records: + - id: 28448429 + type: NS + name: '@' + data: ns1.digitalocean.com + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + - id: 28448430 + type: NS + name: '@' + data: ns2.digitalocean.com + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + - id: 28448431 + type: NS + name: '@' + data: ns3.digitalocean.com + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + - id: 28448432 + type: A + name: '@' + data: 1.2.3.4 + priority: null + port: null + ttl: 1800 + weight: null + flags: null + tag: null + links: {} + meta: + total: 4 + droplets_all: + value: + droplets: + - id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + - id: 3164459 + name: assets.example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:42:27Z' + features: + - private_networking + backup_ids: [] + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: + - 506f78a4-e098-11e5-ad9f-000f53306ae1 + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.138 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 162.243.0.4 + netmask: 255.255.255.0 + gateway: 162.243.0.1 + type: public + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - storage + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + - id: 3164412 + name: stage.example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:32:55Z' + features: + - private_networking + backup_ids: [] + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: + - 7724db7c-e098-11e5-b522-000f53304e51 + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.125 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.247.248 + netmask: 255.255.255.0 + gateway: 192.241.247.1 + type: public + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - env:stage + vpc_uuid: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + links: + pages: {} + meta: + total: 3 + droplets_tagged: + value: + droplets: + - id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + - id: 3164459 + name: assets.example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:42:27Z' + features: + - private_networking + backup_ids: [] + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: + - 506f78a4-e098-11e5-ad9f-000f53306ae1 + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.138 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 162.243.0.4 + netmask: 255.255.255.0 + gateway: 162.243.0.1 + type: public + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - storage + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + links: + pages: {} + meta: + total: 2 + gpu_droplets: + value: + droplets: + - id: 448543583 + name: ml-ai-ubuntu-gpu-h100x1-80gb-tor1 + memory: 245760 + vcpus: 20 + disk: 720 + disk_info: + - type: local + size: + amount: 720 + unit: gib + - type: scratch + size: + amount: 5120 + unit: gib + locked: false + status: active + kernel: null + created_at: '2024-09-30T15:23:36Z' + features: + - droplet_agent + - private_networking + backup_ids: [] + next_backup_window: null + snapshot_ids: [] + image: + id: 166407044 + name: AI/ML Ready H100x1 + distribution: Ubuntu + slug: gpu-h100x1-base + public: true + regions: + - nyc3 + - nyc1 + - sfo1 + - nyc2 + - ams2 + - sgp1 + - lon1 + - ams3 + - fra1 + - tor1 + - sfo2 + - blr1 + - sfo3 + - syd1 + created_at: '2024-09-27T15:35:19Z' + min_disk_size: 25 + type: base + size_gigabytes: 18.47 + description: GPU H100 1x Base Image + tags: [] + status: available + volume_ids: [] + size: + slug: gpu-h100x1-80gb + memory: 245760 + vcpus: 20 + disk: 720 + transfer: 15 + price_monthly: 4529.3 + price_hourly: 6.74 + regions: + - tor1 + available: true + description: H100 GPU - 1X + gpu_info: + count: 1 + vram: + amount: 80 + unit: gib + model: nvidia_h100 + disk_info: + - type: local + size: + amount: 720 + unit: gib + - type: scratch + size: + amount: 5120 + unit: gib + size_slug: gpu-h100x1-80gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: [] + region: + name: Toronto 1 + slug: tor1 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + - server_id + - management_networking + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + - gpu-h100x1-80gb + - gpu-h100x8-640gb + tags: [] + vpc_uuid: e2fdd15c-6ae6-4c11-8c5d-72dae2ba1ad1 + gpu_info: + count: 1 + vram: + amount: 80 + unit: gib + model: nvidia_h100 + links: {} + meta: + total: 1 + droplet_create_request: + value: + name: example.com + region: nyc3 + size: s-1vcpu-1gb + image: ubuntu-20-04-x64 + ssh_keys: + - 289794 + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + backups: true + ipv6: true + monitoring: true + tags: + - env:prod + - web + user_data: | + #cloud-config + runcmd: + - touch /test.txt + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + droplet_multi_create_request: + value: + names: + - sub-01.example.com + - sub-02.example.com + region: nyc3 + size: s-1vcpu-1gb + image: ubuntu-20-04-x64 + ssh_keys: + - 289794 + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + backups: true + ipv6: true + monitoring: true + tags: + - env:prod + - web + user_data: | + #cloud-config + runcmd: + - touch /test.txt + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + droplet_create_response: + value: + droplet: + id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: new + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + - monitoring + backup_ids: [] + next_backup_window: null + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: [] + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + links: + actions: + - id: 7515 + rel: create + href: https://api.digitalocean.com/v2/actions/7515 + droplet_multi_create_response: + value: + droplets: + - id: 3164444 + name: sub-01.example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: new + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + - monitoring + backup_ids: [] + next_backup_window: null + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: [] + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + - id: 3164445 + name: sub-02.example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: new + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + - monitoring + backup_ids: [] + next_backup_window: null + snapshot_ids: [] + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: [] + v6: [] + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + links: + actions: + - id: 7515 + rel: create + href: https://api.digitalocean.com/v2/actions/7515 + - id: 7516 + rel: create + href: https://api.digitalocean.com/v2/actions/7516 + droplet_single: + value: + droplet: + id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + disk_info: + - type: local + size: + amount: 25 + unit: gib + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + autoscale_pools_all: + value: + autoscale_pools: + - id: 0d3db13e-a604-4944-9827-7ec2642d32ac + name: test-autoscaler-group-01 + config: + min_instances: 1 + max_instances: 5 + target_cpu_utilization: 0.5 + cooldown_minutes: 10 + droplet_template: + name: droplet-name + size: c-2 + region: tor1 + image: ubuntu-20-04-x64 + tags: + - my-tag + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + with_droplet_agent: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + public_networking: true + ipv6: true + user_data: | + #cloud-config + runcmd: + - touch /test.txt + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + current_utilization: + memory: 0.3588531587713522 + cpu: 0.0007338008770232183 + status: active + active_resources_count: 1 + links: + pages: null + meta: + total: 1 + autoscale_create_request_dynamic: + value: + name: my-autoscale-pool + config: + min_instances: 1 + max_instances: 5 + target_cpu_utilization: 0.5 + cooldown_minutes: 10 + droplet_template: + name: example.com + region: nyc3 + size: c-2 + image: ubuntu-20-04-x64 + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + backups: true + ipv6: true + monitoring: true + tags: + - env:prod + - web + user_data: | + #cloud-config + runcmd: + - touch /test.txt + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + autoscale_create_request_static: + value: + name: my-autoscale-pool + config: + target_number_instances: 2 + droplet_template: + name: example.com + region: nyc3 + size: c-2 + image: ubuntu-20-04-x64 + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + backups: true + ipv6: true + monitoring: true + tags: + - env:prod + - web + user_data: | + #cloud-config + runcmd: + - touch /test.txt + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + autoscale_create_response_dynamic: + value: + autoscale_pool: + id: 0d3db13e-a604-4944-9827-7ec2642d32ac + name: test-autoscaler-group-01 + config: + min_instances: 1 + max_instances: 5 + target_cpu_utilization: 0.5 + cooldown_minutes: 10 + droplet_template: + name: droplet-name + size: c-2 + region: tor1 + image: ubuntu-20-04-x64 + tags: + - my-tag + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + with_droplet_agent: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + public_networking: true + ipv6: true + user_data: | + #cloud-config + runcmd: + - touch /test.txt + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + status: active + active_resources_count: 1 + autoscale_create_response_static: + value: + autoscale_pool: + id: 0d3db13e-a604-4944-9827-7ec2642d32ac + name: test-autoscaler-group-01 + config: + target_number_instances: 1 + droplet_template: + name: droplet-name + size: c-2 + region: tor1 + image: ubuntu-20-04-x64 + tags: + - my-tag + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + with_droplet_agent: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + public_networking: true + ipv6: true + user_data: | + #cloud-config + runcmd: + - touch /test.txt + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + status: active + active_resources_count: 1 + autoscale_pool_single: + value: + autoscale_pool: + id: 0d3db13e-a604-4944-9827-7ec2642d32ac + name: test-autoscaler-group-01 + config: + min_instances: 1 + max_instances: 5 + target_cpu_utilization: 0.5 + cooldown_minutes: 10 + droplet_template: + name: droplet-name + size: c-2 + region: tor1 + image: ubuntu-20-04-x64 + tags: + - my-tag + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + with_droplet_agent: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + public_networking: true + ipv6: true + user_data: | + #cloud-config + runcmd: + - touch /test.txt + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + current_utilization: + memory: 0.3588531587713522 + cpu: 0.0007338008770232183 + status: active + active_resources_count: 1 + autoscale_update_request: + value: + name: my-autoscale-pool + config: + target_number_instances: 2 + droplet_template: + name: example.com + region: nyc3 + size: c-2 + image: ubuntu-20-04-x64 + ssh_keys: + - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 + backups: true + ipv6: true + monitoring: true + tags: + - env:prod + - web + user_data: | + #cloud-config + runcmd: + - touch /test.txt + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + members_all: + value: + droplets: + - droplet_id: 123456 + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + health_status: healthy + status: active + current_utilization: + memory: 0.3588531587713522 + cpu: 0.0007338008770232183 + links: + pages: null + meta: + total: 1 + history_all: + value: + history: + - history_event_id: 01936530-4471-7b86-9634-32d8fcfecbc6 + current_instance_count: 2 + desired_instance_count: 2 + reason: CONFIGURATION_CHANGE + status: success + created_at: '2020-11-19T20:27:18Z' + updated_at: '2020-12-01T00:42:16Z' + links: + pages: null + meta: + total: 1 + floating_ip_assigning: + summary: Assigning to Droplet + value: + floating_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: + droplets: + - id: 213939433 + rel: droplet + href: https://api.digitalocean.com/v2/droplets/213939433 + actions: + - id: 1088924622 + rel: assign_ip + href: https://api.digitalocean.com/v2/actions/1088924622 + floating_ip_reserving: + summary: Reserving to Region + value: + floating_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: {} + floating_ip_assigned: + summary: Assigned to Droplet + value: + floating_ip: + ip: 45.55.96.47 + droplet: + id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + type: base + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + region: + name: New York 3 + slug: nyc3 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + floating_ip_reserved: + summary: Reserved to Region + value: + floating_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + images_all: + value: + images: + - id: 7555620 + name: Nifty New Snapshot + distribution: Ubuntu + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + - id: 7555621 + name: Another Snapshot + distribution: Ubuntu + slug: null + public: false + regions: + - nyc2 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + - id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - nyc2 + - nyc3 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + - id: 7555621 + name: A custom image + distribution: Arch Linux + slug: null + public: false + regions: + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: custom + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + - id: 7555621 + name: An APP image + distribution: Fedora + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + - id: 7555621 + name: A simple tagged image + distribution: CentOS + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: + - simple-image + status: available + error_message: '' + links: + pages: {} + meta: + total: 6 + images_snapshots: + value: + images: + - id: 7555620 + name: Nifty New Snapshot + distribution: Ubuntu + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + - id: 7555621 + name: Another Snapshot + distribution: Ubuntu + slug: null + public: false + regions: + - nyc2 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + links: + pages: {} + meta: + total: 2 + images_distribution: + description: > + **Important:** + + The `type` query parameter is not directly related to the `type` + attribute. + + The main thing to remember here is that DigitalOcean-produced + distribution images will have `snapshot` as the type attribute. + value: + images: + - id: 63663980 + name: 20.04 (LTS) x64 + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - nyc2 + - nyc3 + created_at: '2020-05-15T05:47:50Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + links: + pages: {} + meta: + total: 1 + images_custom: + value: + images: + - id: 7555621 + name: A custom image + distribution: Arch Linux + slug: null + public: false + regions: + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: custom + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + links: + pages: {} + meta: + total: 1 + images_application: + description: > + **Important:** + + The `type` query parameter is not directly related to the `type` + attribute. + value: + images: + - id: 7555621 + name: An APP image + distribution: Fedora + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: [] + status: available + error_message: '' + links: + pages: {} + meta: + total: 1 + images_tagged: + value: + images: + - id: 7555621 + name: A simple tagged image + distribution: CentOS + slug: null + public: false + regions: + - nyc2 + - nyc3 + created_at: '2014-11-04T22:23:02Z' + type: snapshot + min_disk_size: 20 + size_gigabytes: 2.34 + description: '' + tags: + - simple-image + status: available + error_message: '' + links: + pages: {} + meta: + total: 1 + kubernetes_clusters_all: + value: + kubernetes_clusters: + - id: bd5f5959-5e1e-4205-a714-a914373942af + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + cluster_subnet: 10.244.0.0/16 + service_subnet: 10.245.0.0/16 + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + ipv4: 68.183.121.157 + endpoint: >- + https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: provisioning + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: provisioning + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: provisioning + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: f49f4379-7e7f-4af5-aeb6-0354bd840778 + name: backend-pool + size: g-4vcpu-16gb + count: 2 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + taints: [] + auto_scale: true + min_nodes: 2 + max_nodes: 5 + nodes: + - id: 3385619f-8ec3-42ba-bb23-8d21b8ba7518 + name: affectionate-nightingale-3nif + status: + state: provisioning + droplet_id: '205545373' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: 4b8f60ff-ba06-4523-a6a4-b8148244c7e6 + name: affectionate-nightingale-3niy + status: + state: provisioning + droplet_id: '205545374' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + maintenance_policy: + start_time: '00:00' + duration: 4h0m0s + day: any + auto_upgrade: false + status: + state: provisioning + message: provisioning + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + surge_upgrade: false + registry_enabled: false + registries: + - registry-a + - registry-b + ha: false + control_plane_firewall: + enabled: true + allowed_addresses: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + scale_down_utilization_threshold: 0.65 + scale_down_unneeded_time: 1m + expanders: + - priority + - random + routing_agent: + enabled: false + amd_gpu_device_plugin: + enabled: false + amd_gpu_device_metrics_exporter_plugin: + enabled: false + nvidia_gpu_device_plugin: + enabled: false + rdma_shared_dev_plugin: + enabled: false + meta: + total: 1 + kubernetes_clusters_basic_request: + value: + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + node_pools: + - size: s-1vcpu-2gb + count: 3 + name: worker-pool + kubernetes_clusters_multi_pool_request: + description: > + This example request creates a Kubernetes cluster with two node pools. + It + + also demonstrates setting tags, labels, auto scaling, and a maintenance + + policy. + value: + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + tags: + - production + - web-team + node_pools: + - size: s-1vcpu-2gb + count: 3 + name: frontend-pool + tags: + - frontend + - size: g-4vcpu-16gb + count: 2 + name: backend-pool + labels: + service: backend + priority: high + auto_scale: true + min_nodes: 2 + max_nodes: 5 + maintenance_policy: + start_time: '12:00' + day: any + kubernetes_clusters_create_basic_response: + value: + kubernetes_cluster: + id: bd5f5959-5e1e-4205-a714-a914373942af + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + cluster_subnet: 10.244.0.0/16 + service_subnet: 10.245.0.0/16 + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + ipv4: '' + endpoint: '' + tags: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: worker-pool + size: s-1vcpu-2gb + count: 3 + tags: + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + maintenance_policy: + start_time: '00:00' + duration: 4h0m0s + day: any + auto_upgrade: false + status: + state: provisioning + message: provisioning + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + surge_upgrade: false + registry_enabled: false + registries: + - registry-a + - registry-b + ha: false + control_plane_firewall: + enabled: true + allowed_addresses: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + scale_down_utilization_threshold: 0.65 + scale_down_unneeded_time: 1m + expanders: + - priority + - random + routing_agent: + enabled: false + amd_gpu_device_plugin: + enabled: false + amd_gpu_device_metrics_exporter_plugin: + enabled: false + nvidia_gpu_device_plugin: + enabled: false + rdma_shared_dev_plugin: + enabled: false + kubernetes_clusters_multi_pool_response: + value: + kubernetes_clusters: + id: bd5f5959-5e1e-4205-a714-a914373942af + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + cluster_subnet: 10.244.0.0/16 + service_subnet: 10.245.0.0/16 + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + ipv4: '' + endpoint: '' + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - frontend + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: f49f4379-7e7f-4af5-aeb6-0354bd840778 + name: backend-pool + size: g-4vcpu-16gb + count: 2 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + taints: [] + auto_scale: true + min_nodes: 2 + max_nodes: 5 + nodes: + - id: 3385619f-8ec3-42ba-bb23-8d21b8ba7518 + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: 4b8f60ff-ba06-4523-a6a4-b8148244c7e6 + name: '' + status: + state: provisioning + droplet_id: '' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + maintenance_policy: + start_time: '12:00' + duration: 4h0m0s + day: any + auto_upgrade: false + status: + state: provisioning + message: provisioning + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + surge_upgrade: false + registry_enabled: false + registries: + - registry-a + - registry-b + ha: false + control_plane_firewall: + enabled: true + allowed_addresses: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + scale_down_utilization_threshold: 0.65 + scale_down_unneeded_time: 1m + expanders: + - priority + - random + kubernetes_single: + value: + kubernetes_cluster: + id: bd5f5959-5e1e-4205-a714-a914373942af + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + cluster_subnet: 10.244.0.0/16 + service_subnet: 10.245.0.0/16 + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + ipv4: 68.183.121.157 + endpoint: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: running + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: running + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: running + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: f49f4379-7e7f-4af5-aeb6-0354bd840778 + name: backend-pool + size: g-4vcpu-16gb + count: 2 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + taints: [] + auto_scale: true + min_nodes: 2 + max_nodes: 5 + nodes: + - id: 3385619f-8ec3-42ba-bb23-8d21b8ba7518 + name: affectionate-nightingale-3nif + status: + state: running + droplet_id: '205545373' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: 4b8f60ff-ba06-4523-a6a4-b8148244c7e6 + name: affectionate-nightingale-3niy + status: + state: running + droplet_id: '205545374' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + maintenance_policy: + start_time: '00:00' + duration: 4h0m0s + day: any + auto_upgrade: false + status: + state: running + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + surge_upgrade: false + registry_enabled: false + registries: + - registry-a + - registry-b + ha: false + control_plane_firewall: + enabled: true + allowed_addresses: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + scale_down_utilization_threshold: 0.65 + scale_down_unneeded_time: 1m + expanders: + - priority + - random + routing_agent: + enabled: false + amd_gpu_device_plugin: + enabled: false + amd_gpu_device_metrics_exporter_plugin: + enabled: false + nvidia_gpu_device_plugin: + enabled: false + rdma_shared_dev_plugin: + enabled: false + kubernetes_updated: + value: + kubernetes_cluster: + id: bd5f5959-5e1e-4205-a714-a914373942af + name: prod-cluster-01 + region: nyc1 + version: 1.18.6-do.0 + cluster_subnet: 10.244.0.0/16 + service_subnet: 10.245.0.0/16 + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + ipv4: 68.183.121.157 + endpoint: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + node_pools: + - id: cdda885e-7663-40c8-bc74-3a036c66545d + name: frontend-pool + size: s-1vcpu-2gb + count: 3 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: null + taints: [] + auto_scale: false + min_nodes: 0 + max_nodes: 0 + nodes: + - id: 478247f8-b1bb-4f7a-8db9-2a5f8d4b8f8f + name: adoring-newton-3niq + status: + state: running + droplet_id: '205545370' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: ad12e744-c2a9-473d-8aa9-be5680500eb1 + name: adoring-newton-3nim + status: + state: running + droplet_id: '205545371' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: e46e8d07-f58f-4ff1-9737-97246364400e + name: adoring-newton-3ni7 + status: + state: running + droplet_id: '205545372' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: f49f4379-7e7f-4af5-aeb6-0354bd840778 + name: backend-pool + size: g-4vcpu-16gb + count: 2 + tags: + - production + - web-team + - k8s + - k8s:bd5f5959-5e1e-4205-a714-a914373942af + - k8s:worker + labels: + service: backend + priority: high + taints: [] + auto_scale: true + min_nodes: 2 + max_nodes: 5 + nodes: + - id: 3385619f-8ec3-42ba-bb23-8d21b8ba7518 + name: affectionate-nightingale-3nif + status: + state: running + droplet_id: '205545373' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + - id: 4b8f60ff-ba06-4523-a6a4-b8148244c7e6 + name: affectionate-nightingale-3niy + status: + state: running + droplet_id: '205545374' + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + maintenance_policy: + start_time: '00:00' + duration: 4h0m0s + day: any + auto_upgrade: true + status: + state: running + created_at: '2018-11-15T16:00:11Z' + updated_at: '2018-11-15T16:00:11Z' + surge_upgrade: true + registry_enabled: false + registries: + - registry-a + - registry-b + ha: false + control_plane_firewall: + enabled: true + allowed_addresses: + - 1.2.3.4/32 + - 1.1.0.0/16 + cluster_autoscaler_configuration: + scale_down_utilization_threshold: 0.65 + scale_down_unneeded_time: 1m + expanders: + - priority + - random + routing_agent: + enabled: false + amd_gpu_device_plugin: + enabled: false + amd_gpu_device_metrics_exporter_plugin: + enabled: false + nvidia_gpu_device_plugin: + enabled: false + rdma_shared_dev_plugin: + enabled: false + kubernetes_options: + value: + options: + regions: + - name: New York 1 + slug: nyc1 + - name: Singapore 1 + slug: sgp1 + - name: London 1 + slug: lon1 + - name: New York 3 + slug: nyc3 + - name: Amsterdam 3 + slug: ams3 + - name: Frankfurt 1 + slug: fra1 + - name: Toronto 1 + slug: tor1 + - name: San Francisco 2 + slug: sfo2 + - name: Bangalore 1 + slug: blr1 + - name: San Francisco 3 + slug: sfo3 + versions: + - slug: 1.18.8-do.0 + kubernetes_version: 1.18.8 + supported_features: + - cluster-autoscaler + - docr-integration + - token-authentication + - slug: 1.17.11-do.0 + kubernetes_version: 1.17.11 + supported_features: + - cluster-autoscaler + - docr-integration + - token-authentication + - slug: 1.16.14-do.0 + kubernetes_version: 1.16.14 + supported_features: + - cluster-autoscaler + - docr-integration + - token-authentication + sizes: + - name: s-1vcpu-2gb + slug: s-1vcpu-2gb + - name: s-2vcpu-2gb + slug: s-2vcpu-2gb + - name: s-1vcpu-3gb + slug: s-1vcpu-3gb + - name: s-2vcpu-4gb + slug: s-2vcpu-4gb + - name: s-4vcpu-8gb + slug: s-4vcpu-8gb + - name: c-2-4GiB + slug: c-2 + - name: g-2vcpu-8gb + slug: g-2vcpu-8gb + - name: gd-2vcpu-8gb + slug: gd-2vcpu-8gb + - name: s-8vcpu-16gb + slug: s-8vcpu-16gb + - name: s-6vcpu-16gb + slug: s-6vcpu-16gb + - name: c-4-8GiB + slug: c-4 + - name: m-2vcpu-16gb + slug: m-2vcpu-16gb + - name: m3-2vcpu-16gb + slug: m3-2vcpu-16gb + - name: g-4vcpu-16gb + slug: g-4vcpu-16gb + - name: gd-4vcpu-16gb + slug: gd-4vcpu-16gb + - name: m6-2vcpu-16gb + slug: m6-2vcpu-16gb + - name: s-8vcpu-32gb + slug: s-8vcpu-32gb + - name: c-8-16GiB + slug: c-8 + - name: m-4vcpu-32gb + slug: m-4vcpu-32gb + - name: m3-4vcpu-32gb + slug: m3-4vcpu-32gb + - name: g-8vcpu-32gb + slug: g-8vcpu-32gb + - name: s-12vcpu-48gb + slug: s-12vcpu-48gb + - name: gd-8vcpu-32gb + slug: gd-8vcpu-32gb + - name: m6-4vcpu-32gb + slug: m6-4vcpu-32gb + - name: s-16vcpu-64gb + slug: s-16vcpu-64gb + - name: c-16 + slug: c-16 + - name: m-8vcpu-64gb + slug: m-8vcpu-64gb + - name: m3-8vcpu-64gb + slug: m3-8vcpu-64gb + - name: g-16vcpu-64gb + slug: g-16vcpu-64gb + - name: s-20vcpu-96gb + slug: s-20vcpu-96gb + - name: gd-16vcpu-64gb + slug: gd-16vcpu-64gb + - name: m6-8vcpu-64gb + slug: m6-8vcpu-64gb + - name: s-24vcpu-128gb + slug: s-24vcpu-128gb + - name: c-32-64GiB + slug: c-32 + - name: m-16vcpu-128gb + slug: m-16vcpu-128gb + - name: m3-16vcpu-128gb + slug: m3-16vcpu-128gb + - name: g-32vcpu-128gb + slug: g-32vcpu-128gb + - name: s-32vcpu-192gb + slug: s-32vcpu-192gb + - name: gd-32vcpu-128gb + slug: gd-32vcpu-128gb + - name: m-24vcpu-192gb + slug: m-24vcpu-192gb + - name: m6-16vcpu-128gb + slug: m6-16vcpu-128gb + - name: g-40vcpu-160gb + slug: g-40vcpu-160gb + - name: gd-40vcpu-160gb + slug: gd-40vcpu-160gb + - name: m3-24vcpu-192gb + slug: m3-24vcpu-192gb + - name: m-32vcpu-256gb + slug: m-32vcpu-256gb + - name: m6-24vcpu-192gb + slug: m6-24vcpu-192gb + - name: m3-32vcpu-256gb + slug: m3-32vcpu-256gb + - name: m6-32vcpu-256gb + slug: m6-32vcpu-256gb + load_balancers_all: + value: + load_balancers: + - id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: http + entry_port: 80 + target_protocol: http + target_port: 80 + certificate_id: '' + tls_passthrough: false + - entry_protocol: https + entry_port: 443 + target_protocol: https + target_port: 443 + certificate_id: '' + tls_passthrough: true + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: '' + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + - id: 56775c3f-04ab-4fb3-a7ed-40ef9bc8eece + name: prod-web-lb-01 + ip: 45.55.125.24 + size: lb-small + algorithm: round_robin + status: active + created_at: '2020-09-08T18:58:04Z' + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + tls_passthrough: false + health_check: + protocol: https + port: 443 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: cookies + cookie_name: DO-LB + cookie_ttl_seconds: 300 + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: prod:web + droplet_ids: + - 55806512 + - 55806515 + - 55806524 + redirect_http_to_https: true + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: 587d698c-de84-11e8-80bc-3cfdfea9fcd1 + disable_lets_encrypt_dns_records: false + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + http_idle_timeout_seconds: 60 + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + links: {} + meta: + total: 2 + load_balancer_basic_create_request: + description: Passing requests directly through to 80 and 443. + value: + name: example-lb-01 + region: nyc3 + forwarding_rules: + - entry_protocol: http + entry_port: 80 + target_protocol: http + target_port: 80 + - entry_protocol: https + entry_port: 443 + target_protocol: https + target_port: 443 + tls_passthrough: true + droplet_ids: + - 3164444 + - 3164445 + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + http_idle_timeout_seconds: 60 + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + load_balancer_ssl_termination_create_request: + description: >- + Terminating SSL at the load balancer using a managed SSL certificate + specifying Droplets using `droplet_ids`. + value: + name: example-lb-01 + region: nyc3 + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + droplet_ids: + - 3164444 + - 3164445 + load_balancer_using_tag_create_request: + description: >- + Terminating SSL at the load balancer using a managed SSL certificate + specifying Droplets using `tag`. + value: + name: example-lb-01 + region: nyc3 + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + tag: prod:web + load_balancer_sticky_sessions_and_health_check_create_request: + description: >- + Terminating SSL at the load balancer using a managed SSL certificate + specifying Droplets using `tag`. + value: + name: example-lb-01 + region: nyc3 + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + health_check: + protocol: http + port: 8080 + path: /health + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: cookies + cookie_name: LB_COOKIE + cookie_ttl_seconds: 300 + tag: prod:web + load_balancer_basic_response: + value: + load_balancer: + id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: http + entry_port: 80 + target_protocol: http + target_port: 80 + certificate_id: '' + tls_passthrough: false + - entry_protocol: https + entry_port: 443 + target_protocol: https + target_port: 443 + certificate_id: '' + tls_passthrough: true + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: '' + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + http_idle_timeout_seconds: 60 + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + load_balancer_ssl_termination_response: + value: + load_balancer: + id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: '' + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + load_balancer_using_tag_response: + value: + load_balancer: + id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: prod:web + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + load_balancer_sticky_sessions_and_health_check_response: + value: + load_balancer: + id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: https + entry_port: 443 + target_protocol: http + target_port: 8080 + certificate_id: 892071a0-bb95-49bc-8021-3afd67a210bf + health_check: + protocol: http + port: 8080 + path: /health + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: cookies + cookie_name: LB_COOKIE + cookie_ttl_seconds: 300 + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: prod:web + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: false + enable_backend_keepalive: false + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + load_balancer_update_request: + value: + name: updated-example-lb-01 + region: nyc3 + droplet_ids: + - 3164444 + - 3164445 + algorithm: round_robin + forwarding_rules: + - entry_protocol: http + entry_port: 80 + target_protocol: http + target_port: 80 + certificate_id: '' + tls_passthrough: false + - entry_protocol: https + entry_port: 443 + target_protocol: https + target_port: 443 + certificate_id: '' + tls_passthrough: true + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + redirect_http_to_https: false + enable_proxy_protocol: true + enable_backend_keepalive: true + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + http_idle_timeout_seconds: 60 + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + load_balancer_update_response: + value: + load_balancer: + id: 4de7ac8b-495b-4884-9a69-1050c6793cd6 + name: updated-example-lb-01 + ip: 104.131.186.241 + size: lb-small + algorithm: round_robin + status: new + created_at: '2017-02-01T22:22:58Z' + forwarding_rules: + - entry_protocol: http + entry_port: 80 + target_protocol: http + target_port: 80 + certificate_id: '' + tls_passthrough: false + - entry_protocol: https + entry_port: 443 + target_protocol: https + target_port: 443 + certificate_id: '' + tls_passthrough: true + health_check: + protocol: http + port: 80 + path: / + check_interval_seconds: 10 + response_timeout_seconds: 5 + healthy_threshold: 5 + unhealthy_threshold: 3 + sticky_sessions: + type: none + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + available: true + tag: '' + droplet_ids: + - 3164444 + - 3164445 + redirect_http_to_https: false + enable_proxy_protocol: true + enable_backend_keepalive: true + vpc_uuid: c33931f2-a26a-4e61-b85c-4e95a2ec431b + disable_lets_encrypt_dns_records: false + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + http_idle_timeout_seconds: 60 + firewall: + deny: + - cidr:1.2.0.0/16 + - ip:2.3.4.5 + allow: + - ip:1.2.3.4 + - cidr:2.3.4.0/24 + inbound_private_droplet_bandwidth: + value: + status: success + data: + resultType: matrix + result: + - metric: + direction: inbound + host_id: '222651441' + interface: private + values: + - - 1634052360 + - '0.016600450090265357' + - - 1634052480 + - '0.015085955677299055' + - - 1634052600 + - '0.014941163855322308' + - - 1634052720 + - '0.016214285714285712' + inbound_public_droplet_bandwidth: + value: + status: success + data: + resultType: matrix + result: + - metric: + direction: inbound + host_id: '222651441' + interface: public + values: + - - 1634052360 + - '0.016600450090265357' + - - 1634052480 + - '0.015085955677299055' + - - 1634052600 + - '0.014941163855322308' + - - 1634052720 + - '0.016214285714285712' + outbound_private_droplet_bandwidth: + value: + status: success + data: + resultType: matrix + result: + - metric: + direction: outbound + host_id: '222651441' + interface: private + values: + - - 1634052360 + - '0.016600450090265357' + - - 1634052480 + - '0.015085955677299055' + - - 1634052600 + - '0.014941163855322308' + - - 1634052720 + - '0.016214285714285712' + outbound_public_droplet_bandwidth: + value: + status: success + data: + resultType: matrix + result: + - metric: + direction: outbound + host_id: '222651441' + interface: public + values: + - - 1634052360 + - '0.016600450090265357' + - - 1634052480 + - '0.015085955677299055' + - - 1634052600 + - '0.014941163855322308' + - - 1634052720 + - '0.016214285714285712' + droplet_cpu: + value: + status: success + data: + resultType: matrix + result: + - metric: + host_id: '222651441' + mode: idle + values: + - - 1635386880 + - '122901.18' + - - 1635387000 + - '123020.92' + - - 1635387120 + - '123140.8' + - metric: + host_id: '222651441' + mode: iowait + values: + - - 1635386880 + - '14.99' + - - 1635387000 + - '15.01' + - - 1635387120 + - '15.01' + - metric: + host_id: '222651441' + mode: irq + values: + - - 1635386880 + - '0' + - - 1635387000 + - '0' + - - 1635387120 + - '0' + - metric: + host_id: '222651441' + mode: nice + values: + - - 1635386880 + - '66.35' + - - 1635387000 + - '66.35' + - - 1635387120 + - '66.35' + - metric: + host_id: '222651441' + mode: softirq + values: + - - 1635386880 + - '2.13' + - - 1635387000 + - '2.13' + - - 1635387120 + - '2.13' + - metric: + host_id: '222651441' + mode: steal + values: + - - 1635386880 + - '7.89' + - - 1635387000 + - '7.9' + - - 1635387120 + - '7.91' + - metric: + host_id: '222651441' + mode: system + values: + - - 1635386880 + - '140.09' + - - 1635387000 + - '140.2' + - - 1635387120 + - '140.23' + - metric: + host_id: '222651441' + mode: user + values: + - - 1635386880 + - '278.57' + - - 1635387000 + - '278.65' + - - 1635387120 + - '278.69' + droplet_filesystem: + value: + status: success + data: + resultType: matrix + result: + - metric: + device: /dev/vda1 + fstype: ext4 + host_id: '222651441' + mountpoint: / + values: + - - 1635386880 + - '25832407040' + - - 1635387000 + - '25832407040' + - - 1635387120 + - '25832407040' + app_memory_percentage: + value: + status: success + data: + resultType: matrix + result: + - metric: + app_component: sample-application + app_component_instance: sample-application-0 + app_uuid: db3c021-15ad-4088-bfe8-99dc972b9cf6 + values: + - - 1634052360 + - '5.016600450090265357' + - - 1634052480 + - '12.015085955677299055' + - - 1634052600 + - '8.014941163855322308' + - - 1634052720 + - '32.016214285714285712' + reserved_ip_assigning: + summary: Assigning to Droplet + value: + reserved_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: true + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: + droplets: + - id: 213939433 + rel: droplet + href: https://api.digitalocean.com/v2/droplets/213939433 + actions: + - id: 1088924622 + rel: assign_ip + href: https://api.digitalocean.com/v2/actions/1088924622 + reserved_ip_reserving: + summary: Reserving to Region + value: + reserved_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + links: {} + reserved_ip_assigned: + summary: Assigned to Droplet + value: + reserved_ip: + ip: 45.55.96.47 + droplet: + id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + type: base + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + region: + name: New York 3 + slug: nyc3 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + reserved_ip_reserved: + summary: Reserved to Region + value: + reserved_ip: + ip: 45.55.96.47 + droplet: null + region: + name: New York 3 + slug: nyc3 + features: + - private_networking + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + locked: false + project_id: 746c6152-2fa2-11ed-92d3-27aaa54e4988 + reserved_ipv6_reserved: + summary: Reserved to Region + value: + reserved_ipv6: + ip: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + region_slug: nyc3 + reserved_at: '2024-11-20T11:08:30Z' + droplet: null + reserved_ipv6_assigned: + summary: Assigned to Droplet + value: + reserved_ipv6: + ip: 2409:40d0:f7:1017:74b4:3a96:105e:4c6e + reserved_at: '2024-11-20T11:08:30Z' + droplet: + id: 3164444 + name: example.com + memory: 1024 + vcpus: 1 + disk: 25 + locked: false + status: active + kernel: null + created_at: '2020-07-21T18:37:44Z' + features: + - backups + - private_networking + - ipv6 + backup_ids: + - 53893572 + next_backup_window: + start: '2020-07-30T00:00:00Z' + end: '2020-07-30T23:00:00Z' + snapshot_ids: + - 67512819 + image: + id: 63663980 + name: 20.04 (LTS) x64 + type: base + distribution: Ubuntu + slug: ubuntu-20-04-x64 + public: true + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + created_at: '2020-05-15T05:47:50Z' + min_disk_size: 20 + size_gigabytes: 2.36 + description: '' + tags: [] + status: available + error_message: '' + volume_ids: [] + size: + slug: s-1vcpu-1gb + memory: 1024 + vcpus: 1 + disk: 25 + transfer: 1 + price_monthly: 5 + price_hourly: 0.00743999984115362 + regions: + - ams2 + - ams3 + - blr1 + - fra1 + - lon1 + - nyc1 + - nyc2 + - nyc3 + - sfo1 + - sfo2 + - sfo3 + - sgp1 + - tor1 + available: true + description: Basic + size_slug: s-1vcpu-1gb + networks: + v4: + - ip_address: 10.128.192.124 + netmask: 255.255.0.0 + gateway: nil + type: private + - ip_address: 192.241.165.154 + netmask: 255.255.255.0 + gateway: 192.241.165.1 + type: public + v6: + - ip_address: 2604:a880:0:1010::18a:a001 + netmask: 64 + gateway: 2604:a880:0:1010::1 + type: public + region: + name: New York 3 + slug: nyc3 + features: + - backups + - ipv6 + - metadata + - install_agent + - storage + - image_transfer + available: true + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192g + tags: + - web + - env:prod + vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 + region_slug: nyc3 + snapshots_all: + value: + snapshots: + - id: '6372321' + name: web-01-1595954862243 + created_at: '2020-07-28T16:47:44Z' + regions: + - nyc3 + - sfo3 + resource_id: '200776916' + resource_type: droplet + min_disk_size: 25 + size_gigabytes: 2.34 + tags: + - web + - env:prod + - id: fbe805e8-866b-11e6-96bf-000f53315a41 + name: pvc-01-1595954862243 + created_at: '2019-09-28T23:14:30Z' + regions: + - nyc1 + resource_id: 89bcc42f-85cf-11e6-a004-000f53315871 + resource_type: volume + min_disk_size: 2 + size_gigabytes: 0.1008 + tags: + - k8s + links: {} + meta: + total: 2 + snapshots_droplets_only: + value: + snapshots: + - id: '6372321' + name: web-01-1595954862243 + created_at: '2020-07-28T16:47:44Z' + regions: + - nyc3 + - sfo3 + resource_id: '200776916' + resource_type: droplet + min_disk_size: 25 + size_gigabytes: 2.34 + tags: + - web + - env:prod + links: {} + meta: + total: 1 + snapshots_volumes_only: + value: + snapshots: + - id: fbe805e8-866b-11e6-96bf-000f53315a41 + name: pvc-01-1595954862243 + created_at: '2019-09-28T23:14:30Z' + regions: + - nyc1 + resource_id: 89bcc42f-85cf-11e6-a004-000f53315871 + resource_type: volume + min_disk_size: 2 + size_gigabytes: 0.1008 + tags: + - k8s + links: {} + meta: + total: 1 + volumes_all: + value: + volumes: + - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + droplet_ids: [] + name: example + description: Block store for examples + size_gigabytes: 10 + created_at: '2016-03-02T17:00:49Z' + filesystem_type: ext4 + filesystem_label: example + tags: + - aninterestingtag + - id: 506f78a4-e098-11e5-ad9f-000f53305eb2 + region: + name: New York 3 + slug: nyc3 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + droplet_ids: [] + name: example + description: Block store for examples + size_gigabytes: 10 + created_at: '2016-03-02T17:01:49Z' + filesystem_type: ext4 + filesystem_label: example + tags: + - aninterestingtag + links: {} + meta: + total: 2 + volumes_filtered_by_name: + value: + volumes: + - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + droplet_ids: [] + name: example + description: Block store for examples + size_gigabytes: 10 + created_at: '2016-03-02T17:00:49Z' + filesystem_type: ext4 + filesystem_label: example + tags: + - aninterestingtag + links: {} + meta: + total: 1 + volumes_filtered_by_region: + value: + volumes: + - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + droplet_ids: [] + name: example + description: Block store for examples + size_gigabytes: 10 + created_at: '2016-03-02T17:00:49Z' + filesystem_type: ext4 + filesystem_label: example + tags: + - aninterestingtag + links: {} + meta: + total: 1 + volume_action_attach_response: + value: + action: + id: 72531856 + status: completed + type: attach_volume + started_at: '2020-11-12T17:51:03Z' + completed_at: '2020-11-12T17:51:14Z' + resource_type: volume + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc1 + volume_action_detach_response: + value: + action: + id: 68212773 + status: in-progress + type: detach_volume + started_at: '2015-10-15T17:46:15Z' + completed_at: null + resource_id: null + resource_type: backend + region: + name: New York 1 + slug: nyc1 + sizes: + - s-1vcpu-1gb + - s-1vcpu-2gb + - s-1vcpu-3gb + - s-2vcpu-2gb + - s-3vcpu-1gb + - s-2vcpu-4gb + - s-4vcpu-8gb + - s-6vcpu-16gb + - s-8vcpu-32gb + - s-12vcpu-48gb + - s-16vcpu-64gb + - s-20vcpu-96gb + - s-24vcpu-128gb + - s-32vcpu-192gb + features: + - private_networking + - backups + - ipv6 + - metadata + available: true + region_slug: nyc1 + vpc_nat_gateways: + value: + vpc_nat_gateways: + - id: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + name: test-vpc-nat-gateways + type: PUBLIC + state: ACTIVE + region: tor1 + size: 1 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + gateway_ip: 10.118.0.35 + egresses: + public_gateways: + - ipv4: 174.138.113.197 + udp_timeout_seconds: 30 + icmp_timeout_seconds: 30 + tcp_timeout_seconds: 30 + created_at: '2025-08-12T18:43:14Z' + updated_at: '2025-08-12T19:00:04Z' + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + links: {} + meta: + total: 1 + vpc_nat_gateway_create_request: + value: + name: test-vpc-nat-gateways + type: PUBLIC + region: tor1 + size: 1 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + default_gateway: true + udp_timeout_seconds: 30 + icmp_timeout_seconds: 30 + tcp_timeout_seconds: 30 + project_id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30 + vpc_nat_gateway_create: + value: + vpc_nat_gateway: + id: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + name: test-vpc-nat-gateways + type: PUBLIC + state: ACTIVE + region: tor1 + size: 1 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + default_gateway: true + egresses: {} + udp_timeout_seconds: 30 + icmp_timeout_seconds: 30 + tcp_timeout_seconds: 30 + created_at: '2025-08-12T18:43:14Z' + updated_at: '2025-08-12T18:43:14Z' + vpc_nat_gateway: + value: + vpc_nat_gateway: + id: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + name: test-vpc-nat-gateways + type: PUBLIC + state: ACTIVE + region: tor1 + size: 1 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + gateway_ip: 10.118.0.35 + default_gateway: true + egresses: + public_gateways: + - ipv4: 174.138.113.197 + udp_timeout_seconds: 30 + icmp_timeout_seconds: 30 + tcp_timeout_seconds: 30 + created_at: '2025-08-12T18:43:14Z' + updated_at: '2025-08-12T19:00:04Z' + vpc_nat_gateway_update_request: + value: + name: test-vpc-nat-gateways-updated + size: 2 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + default_gateway: false + udp_timeout_seconds: 60 + icmp_timeout_seconds: 60 + tcp_timeout_seconds: 60 + vpc_nat_gateway_update: + value: + vpc_nat_gateway: + id: 70e1b58d-cdec-4e95-b3ee-2d4d95feff51 + name: test-vpc-nat-gateways + type: PUBLIC + state: ACTIVE + region: tor1 + size: 2 + vpcs: + - vpc_uuid: 0eb1752f-807b-4562-a077-8018e13ab1fb + gateway_ip: 10.118.0.35 + egresses: + public_gateways: + - ipv4: 174.138.113.197 + udp_timeout_seconds: 30 + icmp_timeout_seconds: 30 + tcp_timeout_seconds: 30 + created_at: '2025-08-12T18:43:14Z' + updated_at: '2025-08-12T19:00:04Z' +security: + - bearer_auth: []