Format API requests and interpret responses

The automation orchestrator REST API follows consistent conventions for content types, HTTP status codes, authentication headers, and error responses across all endpoints. Review the standard request and response patterns when building integrations.

URL path conventions

All API endpoints use snake_case in URL paths. For example, the authorization introspection endpoints are /api/v1/authz/can_i and /api/v1/authz/resource_actions, not /api/v1/authz/can-i or /api/v1/authz/resource-actions.

Operation ID conventions

Each endpoint in the OpenAPI specification has a unique operation ID that follows the <action>_<resource> format. The action is a verb and the resource is a noun, such as create_workflow, list_workflows, or cancel_execution. When generating client libraries, these operation IDs become method names in the generated code.

Content types

Table 1. API content types
Direction Content type Usage
Request application/json Most request bodies. File upload endpoints usemultipart/form-data instead.
Response (success) application/json All successful responses.
Response (error) application/problem+json All error responses (RFC 9457 Problem Details).

Authentication header

Include a valid JSON Web Token (JWT) access token in the Authorization header for all authenticated requests:

Authorization: Bearer access_token

Requests without a valid token receive a 401 Unauthorized response. Requests with a valid token but insufficient permissions receive a 403 Forbidden response.

HTTP status codes

The following table lists the HTTP status codes returned by the API, organized by category.

Table 2. HTTP status codes
Code Status Description
200 OK The request succeeded. The response body contains the requested data.
201 Created A new resource was created successfully. The response body contains the created resource.
202 Accepted The request was accepted for processing. Returned for asynchronous operations such as canceling an execution.
204 No Content The request succeeded with no response body. Returned for DELETE operations.
400 Bad Request The request body or parameters are malformed. Check thedetail field in the error response for specifics.
401 Unauthorized The request lacks valid authentication credentials. The access token is missing, expired, or invalid.
403 Forbidden The authenticated user lacks the required permissions for this operation. Use the/api/v1/authz/can_i endpoint to diagnose the missing permission.
404 Not Found The requested resource does not exist or is not visible to the authenticated user.
405 Method Not Allowed The HTTP method is not supported for this endpoint.
409 Conflict The request conflicts with the current state of the resource. For example, creating a resource with a name that already exists.
413 Payload Too Large The request body exceeds the maximum allowed size.
422 Unprocessable Entity The request body is valid JSON but contains semantic errors, such as invalid field values or missing required fields.
429 Too Many Requests The user has exceeded the configured rate limit. Retry after the duration specified in theRetry-After header.
500 Internal Server Error An unexpected server error occurred. Check theretryable field to determine whether to retry the request.
502 Bad Gateway A required upstream service, such as a tool provider or the Ansible Automation Platform controller, returned an error.
503 Service Unavailable A required back-end service, such as the database or storage, is temporarily unavailable. Theretryable field is set totrue.

Common query parameters

The following query parameters are available on most list endpoints:

Table 3. Common list endpoint query parameters
Parameter Type Default Description
cursor String None Opaque pagination cursor from a previous response.
limit Integer 20 Maximum number of resources to return per page (1-100).
sort String None Sort field. Prefix with- for descending order. When omitted, results are sorted by creation time in descending order.
include_total Boolean false Include a total count of matching resources.

Error response format

All error responses use the RFC 9457 Problem Details format with the application/problem+json media type. The following example shows a typical error response for an authorization failure:

{
  "type": "https://api.example.com/errors/forbidden",
  "title": "Authorization Denied",
  "detail": "Not authorized to perform create on workflow",
  "code": "AUTHORIZATION_DENIED",
  "retryable": false,
  "instance": "/api/v1/workflows"
}