> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API guide

> Use the AvraAPI v1 REST API directly with project-scoped credentials and an explicit environment.

```bash REST API Base Endpoint theme={null}
https://avraapi.com/api/v1
```

The REST API is the advanced integration path for backends that need direct HTTP control or do not yet have a matching SDK capability. The `/v1` segment is part of every public service URL.

## URL format and API version

Every service path is appended to the same versioned base endpoint:

```text theme={null}
https://avraapi.com/api/v1/{service-path}
```

Each reviewed operation page shows its complete API URL above the request details so there is no ambiguity about where a request is sent.

## Common request headers

| Header | Required | Purpose |
| - | - | - |
| `X-API-KEY` | Yes | Your project Client ID. |
| `X-API-SECRET` | Yes | Your project Client Secret. Send only from a trusted backend. |
| `X-ENV` | No | Selects the project environment. Omit it for Development. |
| `Accept` | Recommended | Use `application/json` for operations that return JSON. |
| `X-Privacy-Mode` | Optional | Per-request privacy control. Send `1` when you do not want AvraAPI to retain normal request and provider-response observability payload data; billing and usage tracking continue. |

The runtime accepts `dev` or `development` for Development, and `prod` or `production` for Production. Credentials and environment are resolved together: changing `X-ENV` does not turn a Development credential into a Production credential.

```http theme={null}
X-API-KEY: your_project_client_id
X-API-SECRET: your_project_client_secret
X-ENV: development
Accept: application/json
```

## X-Privacy-Mode

`X-Privacy-Mode` is an optional privacy control for an individual API request. Send a truthy value such as `1` when the request contains data that should not be retained in normal observability payload logs.

```http theme={null}
X-Privacy-Mode: 1
```

Privacy Mode does not change authentication, routing, provider execution, billing, rate limiting, or usage tracking. The request runs normally, but AvraAPI does not retain the request body, non-routing request headers, provider response body, or provider response headers for that request. Only the minimum billing and usage metadata needed to operate the service is retained, including the request time, service, project and environment identifiers, credit cost, and response status.

Use it deliberately for sensitive request data. It is not anonymous processing and does not remove the request's billing or usage record. See [X-Privacy-Mode — The Privacy Guarantee](https://avraapi.com/terms-of-service#7-x-privacy-mode-the-privacy-guarantee) for the complete legal terms.

## Common response behaviour

JSON provider operations use AvraAPI response envelopes. A successful operation includes `success`, `request_id`, and its operation-specific `data`. Error responses include `success: false`, `request_id`, a stable `error.code`, and a readable `error.message`. Some infrastructure errors also include `meta`; do not depend on `meta` being present for every operation-level validation error.

The `X-APIX-Request-ID` response header mirrors the request identifier. Keep it when troubleshooting an API issue. Rate-limited operations return `429` and may include `Retry-After`; wait for that period instead of retrying in a tight loop.

Media operations are documented separately because they can return image or PDF content instead of JSON. Their exact request and response media types are defined on the relevant Utilities pages.

<Info>
  **Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
</Info>

## Error-code reference

Handle every non-`2xx` response by HTTP status and `error.code`. Keep the `request_id` with your application logs and support request; it is also returned in the `X-APIX-Request-ID` header.

```json title="Typical JSON error envelope" theme={null}
{
  "success": false,
  "request_id": "01j...",
  "error": {
    "code": "validation_error",
    "message": "The request data is invalid."
  },
  "meta": {
    "provider_override": null
  }
}
```

`meta` is optional. In particular, directly validated operations can return a more specific `error.details` object instead.

### Common platform errors

These codes are produced by the shared API middleware, the common exception renderer, or the Gateway request runtime. They can occur across more than one provider service.

| HTTP | `error.code` | Meaning | Recommended handling |
| - | - | - | - |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | Project credentials are missing, invalid, inactive, or do not match `X-ENV`. | Check the Client ID, Client Secret, and environment. Do not retry unchanged credentials. |
| `402` | <span style={{ whiteSpace: 'nowrap' }}><code>insufficient\_funds</code></span> | The selected paid service cannot reserve the required AvraAPI credits. | Add credits or use an eligible plan, then retry the request once. |
| `403` | <span style={{ whiteSpace: 'nowrap' }}><code>forbidden</code></span> | Credentials are valid but the action is not permitted. | Check the project, environment, service configuration, and operation rules. |
| `404` | <span style={{ whiteSpace: 'nowrap' }}><code>resource\_not\_found</code></span> | The request URL or requested public resource does not exist. | Check the HTTP method, API version, and path parameters. |
| `404` | <span style={{ whiteSpace: 'nowrap' }}><code>wallet\_not\_found</code></span> | A required wallet record is unavailable for a billable request. | Do not retry in a loop. Keep the request ID and contact support. |
| `405` | <span style={{ whiteSpace: 'nowrap' }}><code>method\_not\_allowed</code></span> | The endpoint exists but does not support the HTTP method used. | Use the documented method for that endpoint. |
| `409` | <span style={{ whiteSpace: 'nowrap' }}><code>conflict</code></span> | The request conflicts with the current state of a resource. | Read the endpoint-specific response and reconcile your application state before retrying. |
| `413` | <span style={{ whiteSpace: 'nowrap' }}><code>payload\_too\_large</code></span> | The request body exceeds the allowed size. | Reduce the body size or use the documented media/input alternative. |
| `415` | <span style={{ whiteSpace: 'nowrap' }}><code>unsupported\_media\_type</code></span> | The request content type is not accepted. | Set the endpoint's documented `Content-Type` and body format. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>validation\_error</code></span> | A request did not satisfy framework-level input validation. | Correct the invalid field values and submit a new request. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | No eligible provider integration can be selected for the project environment. | Configure or enable the service provider in the selected environment, then retry. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The configured request limit has been reached. | Wait for `Retry-After` before retrying with backoff. |
| `500` | <span style={{ whiteSpace: 'nowrap' }}><code>internal\_error</code></span> | AvraAPI could not complete the request. | Retry only when your operation is safe to retry; retain the request ID if it continues. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | The project is paused and cannot make API requests. | Reactivate the project before retrying. |

### Operation-specific errors

Some operations expose additional stable errors because they have their own input or service rules. Their endpoint page is the source of truth for those codes and response details.

| Area | Examples | Where to check |
| - | - | - |
| Currency | `invalid_currency_code`, `validation_failed` | The relevant [Currency endpoint](/api-reference/currency/list-codes) page. |
| Location, Security, SMS, and Utilities | Request-field, provider, billing, or media-specific validation errors | The individual provider endpoint page once that API contract is published. |

<Note>
  Some exception names are used internally for observability or billing decisions but are not independently published as stable HTTP `error.code` values. This reference intentionally documents only codes that the public API contract can return to an integration.
</Note>

## Security boundary

Do not call the REST API from public frontend code. Your backend should read Client ID and Client Secret values from environment configuration or a managed secret store, then make the AvraAPI request on behalf of your application.

See [Authentication & credentials](/information/authentication-and-credentials) for credential lifecycle guidance and [API key safety](/security/api-key-safety) for incident response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.