API operations and compatibility
Use this guidance when moving from an exploratory API request to a reliable integration. The API can accept a request before a deployment, workflow, or provider operation has finished, so transport success and workflow success must be handled separately.
Retries
- Retry only transient transport or service failures, using bounded exponential backoff.
- Do not blindly retry a mutation after a timeout or connection failure. The server may have accepted it.
- When the workflow exposes a resource or operation status, read that state before submitting another mutation.
- Keep retry budgets and deadlines in the calling system so an unavailable provider cannot create an unbounded queue.
The platform does not currently publish a single global rate-limit, timeout, or idempotency contract for every API surface. Treat limits and retryability as operation- and deployment-specific until the target workflow documents them.
Asynchronous operations
Infrastructure and provider actions may return before execution completes. Persist the returned resource or operation identifier, then monitor the associated state through the relevant REST response, GraphQL query, subscription, or product workflow.
Do not treat a 2xx response alone as proof that a deployment is ready. Handle terminal failure states, authorization failures, provider errors, and cancellation explicitly.
GraphQL subscriptions
The main GraphQL WebSocket endpoint is /graphql. Subscribe only to events exposed by the live schema, and reconnect with bounded backoff when the connection closes. A subscription event is a status signal. Query the associated resource when the integration needs the current authoritative state.
Compatibility and versioning
REST versioning is expressed by route families such as /api/projects/v1. It is not one universal /v1/ prefix. Virtual-machine and some compliance routes currently use different paths. GraphQL uses the live schema and may vary with feature flags, authorization, and deployment configuration.
Before upgrading an integration:
- Compare the route or schema available in the target environment.
- Test authentication, authorization, validation, and terminal workflow states.
- Keep unknown response fields forward-compatible and avoid depending on human-readable error text.
- Treat removed or changed fields as an integration change requiring review. No universal public deprecation schedule is currently documented.