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

# Use the Replier API

> Create an API key in Manage account, call the Replier REST API from your own code, and handle errors, retries and rate limits.

The Replier API lets your own code or an automation tool do what you can do in Replier: list workspaces, accounts and posts, create and change automations, read results and contacts, and send catch-up or one-time replies. To use Replier from ChatGPT, Claude or another AI app, [connect it as an AI app](https://docs.usereplier.com/guides/ai-connections.md) instead.

The [API reference](https://docs.usereplier.com/api-reference/workspaces/list-workspaces.md) lists every endpoint with its parameters and responses.

## Create an API key

1. In Replier, open your account menu and choose **Manage account → Integrations**.
2. Under **API keys**, select **Create API key**.
3. Enter a name you will recognize later, choose its access, and select **Create key**.
4. Copy the key. Replier shows it only once.

Anyone who has the key can use Replier as you, so keep it out of code you share and out of your browser. If a key leaks, delete it and create a new one.

A key that can only view your data is refused when it tries to change something. A key that can also make changes can create, edit, turn on or off and delete automations, save your default message text, reorder the next-post queue, upload reply photos, and send catch-up and one-time replies. Either way, a key acts with your role in each workspace, so it can't do more than you can.

## Make a request

Send the key as a bearer token to `https://api.usereplier.com/v1`:

```bash theme={null}
curl https://api.usereplier.com/v1/workspaces \
  -H "Authorization: Bearer $REPLIER_API_KEY"
```

Every other request is made in one workspace. Use a workspace `id` from that list:

```bash theme={null}
curl https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/accounts \
  -H "Authorization: Bearer $REPLIER_API_KEY"
```

Requests that change something send JSON:

```bash theme={null}
curl -X PATCH https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/automations/$AUTOMATION_ID \
  -H "Authorization: Bearer $REPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

Automations made or changed through the API have the same limits as in Replier: up to 24 targets, three buttons, an optional photo, and message flows in Studio workspaces.

## Errors

A refused request answers with an HTTP status and a body like this:

```json theme={null}
{
  "error": {
    "code": "AUTOMATION_NOT_FOUND",
    "message": "Automation not found in this workspace."
  }
}
```

`code` stays the same; `message` may be reworded. Some errors add fields beside them, such as the automation that already has the post you chose.

| Status | Meaning |
| - | - |
| 400 | The request is invalid. For `INVALID_REQUEST`, the message names the field. |
| 401 | `INVALID_API_KEY`: the key is missing, wrong, paused or deleted. |
| 403 | The key or your role doesn't allow this, for example `WRITE_ACCESS_REQUIRED` for a key that can only view. |
| 404 | The workspace, account or automation doesn't exist or you can't access it, for example `WORKSPACE_NOT_FOUND`. |
| 409 | It conflicts with the current state, for example `VERSION_CONFLICT` when the automation changed since you read it. |
| 429 | `RATE_LIMITED`: more than 300 requests in a minute with this key. Wait the seconds in the `Retry-After` header and try again. |
| 500 | Replier had an error. Try again with the same `Idempotency-Key`. |

## Retry safely

Requests that change something take an `Idempotency-Key` header. Send a new random value, such as a UUID, for each operation, and the same value when you retry it. A retry with the same key returns the first result instead of creating a second automation or sending replies twice. Sending catch-up, backfill or one-time replies, and creating a one-time automation, require the header; without it the request is refused with `IDEMPOTENCY_KEY_REQUIRED`.

```bash theme={null}
curl -X POST https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/catch-up \
  -H "Authorization: Bearer $REPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-8a7b-4c3d-9e1f-2a6b5c8d7e0f" \
  -d @items.json
```

To avoid overwriting someone else's change, send `expected_version` with the version you read. If the automation changed since, the request is refused with `VERSION_CONFLICT`. Deleting an automation requires it.

## Changes to the API

Within `/v1`, Replier only adds: new endpoints, new optional parameters, new response fields and new values in fields that list states or reasons. Ignore fields and values you don't know. A change that would break existing code comes as `/v2`.

## Pause or delete a key

In **Manage account → Integrations**, each key shows its access and when it was last used. Choose **Pause access** to refuse its requests until you choose **Resume access**. Choose **Delete key** to remove it for good; code using it loses access right away. Automations it created keep running.


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