---
title: "API v3 developer document"
date: "2026-08-14T07:59:59+00:00"
summary: "Explore Acquia API v3 for MEO workloads: stability tiers, OAuth2 auth, rate limits, and OpenAPI spec guidance for developers."
image:
type: "page"
url: "/resources/api-v3-developer-document"
id: "97158638-d47e-4417-8e9e-a5d5ce698cea"
---

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](/resources/api-v3 "API v3").

### 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."
    }