Automation API

Request conventions, asynchronous changes, pagination, concurrency, and errors.

The Infra API manages organization and project resources through JSON requests. Use resource IDs for references and read operations to determine the outcome of asynchronous changes.

Resource referenceCopy link

Compute and fleetCopy link

Use enrollment tokens for new host identities and nodes for inventory and admission. Placement groups constrain guest destinations. Images manage regional boot artifacts; templates pin reusable configuration revisions.

StorageCopy link

Storage pools manage organization devices and repair. Volumes manage project disks and attachments. Snapshots and consistency groups establish captured recovery sets. Backup policies select and retain independent copies; runs and verification report whether a usable copy was actually produced and tested.

NetworkingCopy link

A network owns subnets, interface allocations, and routes. Firewalls authorize paths independently of forwarding. Public addresses, load balancers, and DNS publish endpoints with separate lifecycles.

Organization controlCopy link

Projects define workload ownership. Service accounts and keys authorize machine access; secrets store write-only integration material. Connectors expose the linked hosted authorization boundary.

Observation and executionCopy link

Metric queries return measurements with source and resolution. Journal queries return component events and resumable streams. Alert rules evaluate conditions; audit exports record accountable requests. Maintenance plans bind protected execution to reviewed revisions and approvals.

Base URL and pathsCopy link

The API uses the control-plane origin followed by /api/v1. A self-hosted installation uses its configured public URL. Hosted credentials must be used with the endpoint shown in the organization's API settings.

Organization resources use /api/v1/organizations/{organization_id}. Project resources add /projects/{project_id} beneath that prefix. The resource references document paths relative to /api/v1.

Fleet resources belong to the organization path; application resources belong to a project path. Supplying another project's ID does not change the authenticated principal's access.

Send Authorization: Bearer <token> and Accept: application/json. Requests with JSON bodies require Content-Type: application/json. See API authentication for token creation and scopes.

Response envelopesCopy link

Successful single-resource reads return data. List reads return a data array and a pagination object. Mutations accepted for execution return HTTP 202 with a resource summary and an operation reference.

An accepted asynchronous mutation returns a response such as:

{
  "data": { "id": "drp_web01", "state": "provisioning" },
  "operation": { "id": "op_create01", "state": "queued" },
  "request_id": "req_deploy01"
}

A 202 response means the request was accepted. It does not mean the resource is running. Poll the operation endpoint before beginning a dependent action.

Pagination and filteringCopy link

List endpoints accept limit, an integer from 1 through 200, inclusive, with default 50, and an opaque cursor. Invalid limits or cursors return 422. Pass pagination.next_cursor unchanged to request the next page. A null cursor means there are no more pages in that traversal.

Lists support the filters documented for each resource. Unknown filter names are rejected. Pagination is not a frozen inventory snapshot; concurrent changes can alter later pages. Deduplicate by ID when building a durable inventory and use a bounded export when a fixed report is required.

IdempotencyCopy link

Creation and action endpoints accept Idempotency-Key. Use a unique key for each intended change and reuse it with the identical path and body after a network failure. Keys are scoped to the authenticated organization and retained for 24 hours after the first accepted request.

An identical replay returns the original accepted result and operation reference. Reusing a key with a different path or body returns 409 idempotency_conflict. Replays recheck current authorization and cannot return another principal's protected data merely because the caller knows a key. Use different keys for independent automation owners within the same organization.

After expiry, the same key can be treated as a new request. Store resource and operation IDs so recovery does not depend only on the retention window.

Concurrent updatesCopy link

Resource reads return an ETag for the configuration revision. Configuration updates require that value in If-Match. Missing conditions return 428; a stale revision returns 412 revision_conflict without applying the update. Read the latest configuration and reconcile the intended change before retrying.

Resource locks are separate from revisions. A current revision can still receive 409 operation_conflict while a migration or other conflicting operation runs.

ErrorsCopy link

A rejected request returns a machine-readable error and request ID:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Requested memory exceeds the project quota.",
    "details": { "dimension": "memory_mib", "requested": 4096 }
  },
  "request_id": "req_deploy02"
}

Use the HTTP status and machine-readable code to select a recovery action:

Rate limits and retriesCopy link

Responses expose RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset for the applicable credential bucket. A 429 response includes Retry-After in seconds. Use that value rather than a fixed polling loop.

Retry transport errors and eligible 5xx responses with exponential backoff and jitter. Reuse the idempotency key for writes. Do not retry validation or policy failures until the request or environment changes. Include request_id and operation IDs in diagnostic logs, excluding bearer credentials.

Data conventionsCopy link

Timestamps use RFC 3339 UTC strings. Memory uses integer MiB; volume size uses integer GiB; durations identify seconds explicitly. Enum values use lowercase strings. Unknown writable fields are rejected. Response objects can add fields; clients should ignore fields they do not use.

Use Droplet API, Volume API, Operation API, and Webhooks for resource details.

Specialized resource APIsCopy link

Hardware policies cover dedicated CPU, NUMA, memory backing, scratch disks, and device reservations. Guest access issues terminal sessions and rescue actions; SSH keys manage public provisioning keys.

Quota overrides control admission accounting. Temporary grants and role bindings control who can act; governance exceptions and holds control policy exceptions and recovery retention. Those endpoints do not substitute for each other's permission checks.

Backup destinations configure archive identity and capability tests. Blueprint plans coordinate mapped resource ownership. Webhook endpoints manage subscriptions and replay without fabricating new infrastructure events.

Additional automation surfacesCopy link

GraphQL uses the same identity and operation model with typed relationship queries. Go, Python, and TypeScript SDKs expose client polling and error handling. Terraform and Pulumi retain their own deployment state and must not compete with blueprint ownership.

Object storage manages bucket identity and data credentials. Replication manages regional recovery checkpoints. Autoscaling manages bounded member groups and their reconciliation blockers.