API v3 is the native API for Multi-Experience Operations (MEO) workloads. Developers building on MEO must use API v3.

API Exposure Directive

API v3 operations explicitly declare maturity, audience, and availability through the x-acquia-exposure directive.The following example shows the canonical directive:

x-acquia-exposure:
  stability: production
  audience:
    - public
  channels:
    rest:
      enabled: true
    cli:
      enabled: true
      command: sites:list

Stability and Compatibility

API v3 classifies all endpoints into three contractual stability tiers to indicate safe endpoints for production automation.

• Prototype: These endpoints provide early access to experimental features. Because Acquia actively refines these features, Acquia can modify or remove these endpoints without advance notice. To ensure system stability, use prototype endpoints exclusively in test environments rather than production workflows.
• Development: These denote endpoints under active development. Updates that maintain compatibility can occur. Advance notice is provided before compatibility changes or removal are introduced.
• Production: These denote stable endpoints. Stable endpoints do not introduce compatibility changes within the major API version. Advance notice is provided before deprecation or compatibility changes are made.

Audience

The x-acquia-exposure directive includes an audience field that controls which consumers can discover and invoke the endpoint. Supported values are:

• public: Exposed to external consumers and integrators.

• Custom Scopes: Extensible values such as partner or fedramp.

Deprecation

Deprecated operations in API v3 are marked using the standard OpenAPI deprecated: true flag in the API specification. Acquia CLI (ACLI) surfaces runtime warnings when a caller invokes a deprecated operation. Developers should monitor these warnings and migrate to replacement endpoints as they become available.

Versioning

All resource endpoints are versioned in the API. Endpoints that reach production stability do not introduce breaking changes within the major API version, whereas non-production endpoints do not provide versioning guarantees for changes. API v3 is a separate API line from API v2 and the two coexist independently.

Interaction Channels

The channels block within the x-acquia-exposure directive defines the communication mediums where the operation is available.

• rest.enabled: The operation is accessible through standard HTTP REST requests.
• cli.enabled: The operation is accessible through Acquia CLI (ACLI).
• cli.command: A string that maps the endpoint to its corresponding ACLI command name (for example, sites:list).

Rate Limits

Rate limiting for API v3 is enforced at the API Gateway level on a per-service basis. If a caller exceeds the configured threshold, the API Gateway rejects the request with a 429 Too Many Requests status code. Callers must implement exponential backoff and respect the Retry-After response header.

Authentication

All API v3 operations require authentication through Acquia ID using OAuth2 protocols. Service specifications must integrate standard security schemes defined in the canonical OpenAPI 3.1 specification. To learn more about setup and credentials, refer to Acquia Cloud API Authentication.

Errors

In addition to standard error codes, some endpoints return a 503 Service Unavailable status code when dependent services are unavailable, returning the following JSON payload:

application/hal+json
{
    "error": "system",
    "message": "This action is currently unavailable. Please try again later."
}

API v3 developer document

x-acquia-exposure:
  stability: production
  audience:
    - public
  channels:
    rest:
      enabled: true
    cli:
      enabled: true
      command: sites:list

application/hal+json
{
    "error": "system",
    "message": "This action is currently unavailable. Please try again later."
}