> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/merge-agent-handler/agent-handler/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# API overview

> Reference for the Agent Handler REST API: base URL, auth header format, error shape, rate limits, idempotency, and pagination.

The Agent Handler REST API is the management plane - your backend uses it to create Registered Users, manage Tool Packs, mint Link tokens, and configure the rest of your account. The MCP server is a separate surface (it's what your agent talks to); see [MCP integration](/merge-agent-handler/build/connecting-agents/mcp-integration) for that side.

This page covers the conventions that apply across every endpoint. Per-endpoint reference is in the sidebar - Connectors, Credentials, Tool Packs, Registered Users, and so on.

## Base API URL

All API endpoints in the reference documentation are relative to the following base URL:

```
https://ah-api.merge.dev/api/v1
```

If you are using our EU tenant, all API endpoints in the reference documentation are relative to the following base URL:

```
https://ah-api-eu.merge.dev/api/v1
```

## Authentication

Every request needs an [Access Key](/merge-agent-handler/administer/access-keys) in the `Authorization` header:

```
Authorization: Bearer <YOUR_API_KEY>
```

The word `Bearer` is required. Tokens are not URL parameters - never put them in the path or query string.

Two key environments:

* **Production keys** call against production data. Any number, and each one can be scoped to specific Tool Packs or Registered Users.
* **Test keys** call against a sandbox. Test Registered Users, test credentials, isolated audit log. Any number of test keys.

Mixing them produces `404 not_found` on resources that exist in the other environment. Pick the right one for the call you're making.

## Errors

Every error response uses the same shape:

```json
{
  "error": {
    "type": "validation_error",
    "code": "origin_user_id_required",
    "message": "origin_user_id is required when creating a Registered User.",
    "documentation_url": "https://docs.merge.dev/merge-agent-handler/resources/troubleshooting"
  }
}
```

| HTTP status             | When it fires                                                                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` Bad Request       | Validation failure. The `code` field names the specific check (`origin_user_id_required`, `invalid_company_for_shared_scope`). Don't retry without fixing the input. |
| `401` Unauthorized      | Missing or invalid API key. Don't retry - fix the credential.                                                                                                        |
| `403` Forbidden         | Authenticated but not allowed. Tool the Registered User can't call, resource in the wrong environment, role missing the permission. Don't retry.                     |
| `404` Not Found         | Resource doesn't exist (or exists in the other environment).                                                                                                         |
| `409` Conflict          | Idempotency conflict - e.g., creating a Registered User with an `origin_user_id` already taken in the same environment. The body includes the existing resource.     |
| `429` Too Many Requests | Rate limit hit. Retry with backoff after the duration in the `Retry-After` header.                                                                                   |
| `5xx`                   | Agent Handler issue. Retry with exponential backoff.                                                                                                                 |

Errors are stable - when we add a new variant, we add a new `code` value rather than changing existing ones, so you can match on `code` safely.

## Rate limits

Default limits per organization:

| Endpoint family                             | Limit                                                                                                       |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Read endpoints (`GET`)                      | 600 requests per minute                                                                                     |
| Write endpoints (`POST`, `PATCH`, `DELETE`) | 120 requests per minute                                                                                     |
| MCP tool calls                              | Limited per organization and per Registered User, so one user cannot saturate the organization's throughput |

When you exceed a limit, the response is `429` with these headers:

```
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714838531
```

Honor `Retry-After`. Backing off by the suggested amount keeps you well-behaved; aggressive retry through a `429` will keep getting `429`s until the bucket refills.

These limits are separate from your monthly credit allotment, which is what [Billing and usage](/merge-agent-handler/administer/billing) covers: a `429` means you are calling too fast, a `402` means you are out of credits. Contact your account team if the defaults aren't enough.

## Idempotency

`POST` endpoints that create resources are idempotent on a stable client-supplied key:

* **`/registered-users`** - idempotent on `origin_user_id`. A repeat call with the same `origin_user_id` returns the existing Registered User (status `200`), not a duplicate (status `201`).
* **`/registered-users/{id}/link-token`** - not idempotent. Each call mints a new link token; tokens are single-use and short-lived.
* **`/credentials/export`** - not idempotent.

For endpoints that aren't idempotent on a natural key, you can pass a request-scoped `Idempotency-Key` header with any unique value. Repeat requests with the same key within a 24-hour window return the original response without re-executing.

```
Idempotency-Key: 7b8e8c01-9c0e-44b3-b7a2-2b5d2f7d8e1c
```

Use UUIDs or any other globally-unique value. Don't reuse keys across logically distinct calls.

## Pagination

List endpoints are cursor-paginated. The response shape is consistent across resources:

```json
{
  "data": [ /* up to `limit` items */ ],
  "next_cursor": "eyJpZCI6ICJmOTgxM2RkNS0...",
  "has_more": true
}
```

Pass `next_cursor` as the `cursor` query parameter on the next request. When `has_more` is `false`, you've reached the end.

Default `limit` is 50; max is 250. The cursor is opaque - don't try to decode or construct your own.

## Versioning

The current API version is `v1`. New, backwards-compatible fields and endpoints are added without bumping the version. Breaking changes (renaming a field, removing an endpoint, changing semantics) ship under `v2` - both versions run side by side during a migration window.

When breaking changes are coming, you'll see them announced in the changelog with at least 90 days of notice and a migration guide.

## Webhooks

Outbound webhooks fire from a separate domain (`https://ah-api.merge.dev/webhooks/...` is for inbound; outbound originates from Agent Handler to your endpoint). Verify signatures before trusting payloads - see [Webhooks](/merge-agent-handler/observe/webhooks) for the full guide.

## SDKs

Official SDKs are in development. For now, the API is callable directly with any HTTP client - examples in the per-endpoint reference cover cURL, Python, and TypeScript.

For MCP-side integration (the agent's view, not the management API), see [MCP integration](/merge-agent-handler/build/connecting-agents/mcp-integration).

## Status and support

API status, incidents, and uptime live at [status.merge.dev](https://status.merge.dev). For support, file from the dashboard - include the request ID from the `X-Request-ID` header on the response and we can find your call in our logs immediately.

> Build once. Connect to every API, tool, and LLM. Ship products and agents to production without owning the integration stack.


## API Docs

- Agent Handler > Connectors [List connectors](https://docs.merge.dev/merge-agent-handler/agent-handler/connectors/connectors-list.md)
- Agent Handler > Connectors [Register a remote MCP server](https://docs.merge.dev/merge-agent-handler/agent-handler/connectors/connectors-create.md)
- Agent Handler > Connectors [Get connector](https://docs.merge.dev/merge-agent-handler/agent-handler/connectors/connectors-retrieve.md)
- Agent Handler > Connectors [Delete a remote MCP server](https://docs.merge.dev/merge-agent-handler/agent-handler/connectors/connectors-destroy.md)
- Agent Handler > Application credentials [List application credentials](https://docs.merge.dev/merge-agent-handler/agent-handler/application-credentials/application-credentials-list.md)
- Agent Handler > Application credentials [Create application credential](https://docs.merge.dev/merge-agent-handler/agent-handler/application-credentials/application-credentials-create.md)
- Agent Handler > Application credentials [Get application credential](https://docs.merge.dev/merge-agent-handler/agent-handler/application-credentials/application-credentials-retrieve.md)
- Agent Handler > Application credentials [Delete application credential](https://docs.merge.dev/merge-agent-handler/agent-handler/application-credentials/application-credentials-destroy.md)
- Agent Handler > Application credentials [Update application credential](https://docs.merge.dev/merge-agent-handler/agent-handler/application-credentials/application-credentials-partial-update.md)
- Agent Handler > Credentials [Delete credentials](https://docs.merge.dev/merge-agent-handler/agent-handler/credentials/registered-users-connectors-destroy.md)
- Agent Handler > Access keys [List access keys](https://docs.merge.dev/merge-agent-handler/agent-handler/access-keys/access-keys-list.md)
- Agent Handler > Access keys [Create access key](https://docs.merge.dev/merge-agent-handler/agent-handler/access-keys/access-keys-create.md)
- Agent Handler > Access keys [Get access key](https://docs.merge.dev/merge-agent-handler/agent-handler/access-keys/access-keys-retrieve.md)
- Agent Handler > Access keys [Regenerate access key secret](https://docs.merge.dev/merge-agent-handler/agent-handler/access-keys/regenerate.md)
- Agent Handler > Access keys [Revoke access key](https://docs.merge.dev/merge-agent-handler/agent-handler/access-keys/access-keys-revoke.md)
- Agent Handler > Audit log [List audit log events](https://docs.merge.dev/merge-agent-handler/agent-handler/audit-log/audit-log-list.md)
- Agent Handler > Registered Users [List Registered Users](https://docs.merge.dev/merge-agent-handler/agent-handler/registered-users/registered-users-list.md)
- Agent Handler > Registered Users [Create Registered User](https://docs.merge.dev/merge-agent-handler/agent-handler/registered-users/registered-users-create.md)
- Agent Handler > Registered Users [Get Registered User](https://docs.merge.dev/merge-agent-handler/agent-handler/registered-users/registered-users-retrieve.md)
- Agent Handler > Registered Users [Delete Registered User](https://docs.merge.dev/merge-agent-handler/agent-handler/registered-users/registered-users-destroy.md)
- Agent Handler > Registered Users [Update Registered User](https://docs.merge.dev/merge-agent-handler/agent-handler/registered-users/registered-users-partial-update.md)
- Agent Handler > Link token [Create Link token](https://docs.merge.dev/merge-agent-handler/agent-handler/link-token/create-for-registered-user.md)
- Agent Handler > Connections [List Connections](https://docs.merge.dev/merge-agent-handler/agent-handler/connections/connections-list.md)
- Agent Handler > Connections [Retrieve Connection](https://docs.merge.dev/merge-agent-handler/agent-handler/connections/connections-retrieve.md)
- Agent Handler > Connections [Revoke Connection](https://docs.merge.dev/merge-agent-handler/agent-handler/connections/connections-revoke.md)
- Agent Handler > Connections [Update Connection Access](https://docs.merge.dev/merge-agent-handler/agent-handler/connections/update.md)
- Agent Handler > Tool Packs [List Tool Packs](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/tool-packs-list.md)
- Agent Handler > Tool Packs [Create Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/tool-packs-create.md)
- Agent Handler > Tool Packs [Get Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/tool-packs-retrieve.md)
- Agent Handler > Tool Packs [Delete Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/tool-packs-destroy.md)
- Agent Handler > Tool Packs [Update Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/tool-packs-partial-update.md)
- Agent Handler > Tool Packs [List connectors in a Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/list-connectors.md)
- Agent Handler > Tool Packs [Update connectors in a Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/replace-connectors.md)
- Agent Handler > Tool Packs [Update connectors in a Tool Pack (partial)](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/bulk-upsert-delete-connectors.md)
- Agent Handler > Tool Packs [Remove a connector from a Tool Pack](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-packs/delete-connector.md)
- Agent Handler > Tool description overrides [List tool description overrides (connector)](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-description-overrides/tool-description-overrides-list.md)
- Agent Handler > Tool description overrides [Bulk upsert/delete tool description overrides (connector)](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-description-overrides/bulk-upsert-delete.md)
- Agent Handler > Tool description overrides [List tool description overrides (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-description-overrides/list-tool-pack.md)
- Agent Handler > Tool description overrides [Bulk upsert/delete tool description overrides (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-description-overrides/bulk-upsert-delete-tool-pack.md)
- Agent Handler > MCP [MCP endpoint - list tools & call tool](https://docs.merge.dev/merge-agent-handler/agent-handler/mcp/endpoint-post.md)
- Agent Handler > Tool search [Search tools](https://docs.merge.dev/merge-agent-handler/agent-handler/tool-search/search-tools.md)
- Agent Handler > Standard entity rules [List standard entity rules](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/list-standard-entity-rules.md)
- Agent Handler > Standard entity rules [Get standard entity rule](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/get-standard-entity-rule.md)
- Agent Handler > Standard entity rules [Update standard entity rule](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/update-standard-entity-rule.md)
- Agent Handler > Standard entity rules [List standard entity rules (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/list-standard-entity-rules-tool-pack.md)
- Agent Handler > Standard entity rules [Get standard entity rule (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/get-standard-entity-rule-tool-pack.md)
- Agent Handler > Standard entity rules [Create or update standard entity rule override (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/upsert-standard-entity-rule-override-tool-pack.md)
- Agent Handler > Standard entity rules [Delete standard entity rule override (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/standard-entity-rules/delete-standard-entity-rule-override-tool-pack.md)
- Agent Handler > Custom regex rules [List custom regex rules](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/list-custom-regex-rules.md)
- Agent Handler > Custom regex rules [Create custom regex rule](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/create-custom-regex-rule.md)
- Agent Handler > Custom regex rules [Get custom regex rule](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/get-custom-regex-rule.md)
- Agent Handler > Custom regex rules [Delete custom regex rule](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/delete-custom-regex-rule.md)
- Agent Handler > Custom regex rules [Update custom regex rule](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/update-custom-regex-rule.md)
- Agent Handler > Custom regex rules [List custom regex rules (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/list-custom-regex-rules-tool-pack.md)
- Agent Handler > Custom regex rules [Create custom regex rule (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/create-custom-regex-rule-tool-pack.md)
- Agent Handler > Custom regex rules [Get custom regex rule (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/get-custom-regex-rule-tool-pack.md)
- Agent Handler > Custom regex rules [Delete custom regex rule (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/delete-custom-regex-rule-tool-pack.md)
- Agent Handler > Custom regex rules [Update custom regex rule (Tool Pack)](https://docs.merge.dev/merge-agent-handler/agent-handler/custom-regex-rules/update-custom-regex-rule-tool-pack.md)
- Agent Handler > Usage [Get total usage](https://docs.merge.dev/merge-agent-handler/agent-handler/usage/usage-total.md)
- Agent Handler > Usage [List usage by registered user](https://docs.merge.dev/merge-agent-handler/agent-handler/usage/usage-registered-users-list.md)
- Agent Handler > Usage [Get usage for a registered user](https://docs.merge.dev/merge-agent-handler/agent-handler/usage/usage-registered-users-retrieve.md)
- Agent Handler > Usage [List usage by tool](https://docs.merge.dev/merge-agent-handler/agent-handler/usage/usage-tools-list.md)
- Agent Handler > Files [Download file](https://docs.merge.dev/merge-agent-handler/agent-handler/files/files-download.md)
- Agent Handler > Files [Reserve a file upload](https://docs.merge.dev/merge-agent-handler/agent-handler/files/files-reserve.md)
- Agent Handler > Files [Upload the reserved file](https://docs.merge.dev/merge-agent-handler/agent-handler/files/files-upload.md)
- Agent Handler > Agent [Agent signup](https://docs.merge.dev/merge-agent-handler/agent-handler/agent/agent-signup.md)
- Agent Handler > Agent [Re-issue claim link](https://docs.merge.dev/merge-agent-handler/agent-handler/agent/agent-claim-reissue.md)
- Agent Handler > Logs [List API request logs](https://docs.merge.dev/merge-agent-handler/agent-handler/logs/api-calls.md)
- Agent Handler > Logs [List tool call logs](https://docs.merge.dev/merge-agent-handler/agent-handler/logs/tool-calls.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.merge.dev/merge-agent-handler/agent-handler/openapi.json)
- [OpenAPI YAML](https://docs.merge.dev/merge-agent-handler/agent-handler/openapi.yaml)