GraphQL API

GraphQL API

Query resource relationships and submit revisioned mutations through a typed schema.

The GraphQL endpoint exposes the same authorized resource model and operation lifecycle as the REST API. It runs at /api/v1/graphql on the control-plane origin.

Request a resource graph

POST/graphql
Auth
Bearer API key; scopes follow the selected fields and mutations

Evaluates authorized resource queries or mutations through the GraphQL schema.

Send a POST with bearer authorization and a JSON object containing query, optional operationName, and variables. Use variables for IDs and input data instead of constructing query text from user values.

To read placement and the active operation for one droplet, use this query:

GraphQL
query DropletPlacement($organizationId: ID!, $projectId: ID!, $dropletId: ID!) {
  organization(id: $organizationId) {
    project(id: $projectId) {
      droplet(id: $dropletId) {
        id
        revision
        state
        placement {
          nodeId
          zoneId
        }
        activeOperation {
          id
          state
        }
      }
    }
  }
}

Connections use first and after; pageInfo.endCursor and hasNextPage control pagination. First defaults to 50 and accepts 1–200. Cursors are opaque and not interchangeable between connection fields.

Mutations

Mutation inputs carry organization and project identity explicitly. Revisioned updates require expectedRevision; accepted asynchronous changes return an operation reference. A mutation returning an operation is not evidence that its node action finished.

Supply the HTTP Idempotency-Key for one intended mutation. Separate independent writes into separate requests when they need distinct idempotency identities. A GraphQL document containing several mutations is not a transaction across infrastructure resources.

Errors and partial data

Transport and authentication errors can use ordinary HTTP error statuses. Field evaluation errors appear in errors with a field path and machine-readable code. A response can contain both partial data and errors; checking HTTP 200 alone is insufficient.

Forbidden relationships are not made visible merely because the root object was readable. Handle null fields and error paths according to the schema's nullability rather than substituting empty healthy objects.

Schema and limits

Download the authenticated schema from Developer tools → GraphQL for the installed release. Query depth, complexity, and result limits are enforced before expensive work; rejected queries identify the limiting condition.

Prefer explicit selections over fetching every nested relationship. See REST conventions, operation polling, and SDKs for shared authorization and retry behavior.