A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Anthropic API is how an app or AI agent works with Claude: sending a conversation and getting the next message back, running large jobs as asynchronous batches, listing models, counting tokens, and uploading files to reuse across calls. Access is granted through an API key, where a workspace key reaches the model and file methods and a separate Admin key manages people, workspaces, and keys, with the workspace as the boundary. The API does not push events to a webhook, so an integration polls a batch for its status or streams a message as it is generated.
How an app or AI agent connects to the Anthropic API determines what it can reach. The model and file methods use a workspace API key, while the methods that manage an organization use a separate Admin key, and each is governed by the key behind it.
The REST API answers at https://api.anthropic.com. A call sends a JSON body and authenticates with a workspace API key in the x-api-key header, plus the anthropic-version header on every request. The Messages method can stream its reply as server-sent events when stream is set to true.
The Admin API manages an organization's people, workspaces, and keys under https://api.anthropic.com/v1/organizations. It accepts an Admin key (sk-ant-admin...) in the x-api-key header or an org:admin OAuth token, never a workspace API key, and is unavailable for individual accounts.
Anthropic defines the Model Context Protocol (MCP), the open standard for connecting models to tools, and Claude acts as an MCP client. The Messages method can connect to a remote MCP server an integration names, so Claude calls that server's tools during a response. There is no first-party MCP server that fronts the Anthropic API itself.
A workspace API key authenticates the model and file methods, sent in the x-api-key header. It carries no per-method scopes; the workspace it belongs to is the boundary, and workspaces segment keys and control spend by use case. A live key is revealed only once, when it is created.
An Admin key authenticates the organization-management methods, sent in the x-api-key header. It cannot call the model, and a workspace API key cannot call the Admin API. Only members with the admin role can create one, and the Admin API is unavailable for individual accounts.
An app can send a short-lived bearer token in the Authorization header instead of an API key, obtained through Workload Identity Federation. An org:admin scoped token grants access to the whole organization and can call the Admin API in place of an Admin key.
The Anthropic API is split into areas an agent can act on, like sending messages to Claude, running large jobs in batches, listing models, counting tokens, and managing files. A separate set of organization methods, reached only with an Admin key, manages people, workspaces, and keys.
Send a conversation to Claude and get the next message back, in one response or streamed token by token, and count the tokens a request would use before sending it.
Submit many message requests as one asynchronous batch, list and retrieve batches, fetch their results, and cancel or delete a batch.
List the models available to the account and read a single model's details and capabilities.
Upload a file once and reference it across calls, list files, read a file's metadata, download its content, and delete it.
List the people in an organization, change a member's role, and remove a member. Reached only with an Admin key.
List and read workspaces, create a workspace, and manage the members of a workspace. Reached only with an Admin key.
List the organization's API keys, read a single key, and update a key's name or status. Reached only with an Admin key.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MessagesSend a conversation to Claude and get the next message back, in one response or streamed token by token, and count the tokens a request would use before sending it.2 | ||||||
| POST | /v1/messages | Send a conversation to Claude and receive the next message. The same method streams the reply token by token when stream is set to true. | write | API key | Current | |
Authenticated with a workspace API key in the x-api-key header. The key carries no per-method scopes; the workspace it belongs to is the boundary. Setting stream to true returns the reply as server-sent events. Acts onmessage Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitPer-model RPM, ITPM, and OTPM by tier SourceOfficial documentation ↗ | ||||||
| POST | /v1/messages/count_tokens | Count the tokens a Messages request would use, before sending it, to estimate cost and stay within rate limits. | read | API key | Current | |
Authenticated with a workspace API key. Does not generate a reply or spend output tokens; it only returns the input token count. Acts ontoken count Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Message BatchesSubmit many message requests as one asynchronous batch, list and retrieve batches, fetch their results, and cancel or delete a batch.6 | ||||||
| POST | /v1/messages/batches | Submit a batch of Messages requests to process asynchronously, at half the standard cost. A batch can take up to 24 hours to complete. | write | API key | Current | |
Authenticated with a workspace API key. Each request in the batch carries a developer-set custom_id used to match results back to requests. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitShared batch RPM and a cap on queued batch requests by tier SourceOfficial documentation ↗ | ||||||
| GET | /v1/messages/batches | List the Message Batches in a workspace, most recently created first. | read | API key | Current | |
Authenticated with a workspace API key. Cursor-paginated through after_id and before_id. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/messages/batches/{message_batch_id} | Retrieve a single Message Batch, including its processing status and a tally of how many requests succeeded, errored, expired, or were canceled. | read | API key | Current | |
Authenticated with a workspace API key. Polling this is how an integration learns a batch has ended, since the API does not push events. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/messages/batches/{message_batch_id}/results | Stream the results of a completed Message Batch as a JSONL file. Results are not guaranteed to be in request order, so each is matched by its custom_id. | read | API key | Current | |
Authenticated with a workspace API key. Available only once the batch has ended, at the results_url returned on the batch. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/messages/batches/{message_batch_id}/cancel | Begin canceling a Message Batch that is still processing. Requests already in progress may still complete. | write | API key | Current | |
Authenticated with a workspace API key. The batch moves to a canceling status before it ends. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/messages/batches/{message_batch_id} | Delete a Message Batch. A batch can be deleted only once its processing has ended. | write | API key | Current | |
Authenticated with a workspace API key. A batch still in progress must be canceled before it can be deleted. Acts onmessage batch Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ModelsList the models available to the account and read a single model's details and capabilities.2 | ||||||
| GET | /v1/models | List the models available to the account, most recently released first, with each model's display name and capabilities. | read | API key | Current | |
Authenticated with a workspace API key. Read-only; cursor-paginated. Acts onmodel Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/models/{model_id} | Read a single model's details, including its display name, release date, context window, and capabilities. | read | API key | Current | |
Authenticated with a workspace API key. Read-only. Acts onmodel Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FilesUpload a file once and reference it across calls, list files, read a file's metadata, download its content, and delete it.5 | ||||||
| POST | /v1/files | Upload a file once so it can be referenced across multiple calls without resending it. | write | API key | Current | |
Authenticated with a workspace API key. The Files API is in beta and requires the anthropic-beta: files-api-2025-04-14 header. Acts onfile Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files | List the files stored on the account. | read | API key | Current | |
Authenticated with a workspace API key. Requires the anthropic-beta: files-api-2025-04-14 header. Acts onfile Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/{file_id} | Read a file's metadata, such as its filename, MIME type, and size. | read | API key | Current | |
Authenticated with a workspace API key. Returns metadata only, not the file's bytes. Requires the anthropic-beta: files-api-2025-04-14 header. Acts onfile Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/{file_id}/content | Download a file's content. Only files the API created, such as code execution output, are downloadable. | read | API key | Current | |
Authenticated with a workspace API key. A file is downloadable only when its downloadable flag is true. Requires the anthropic-beta: files-api-2025-04-14 header. Acts onfile Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/files/{file_id} | Delete a stored file. | write | API key | Current | |
Authenticated with a workspace API key. Requires the anthropic-beta: files-api-2025-04-14 header. Acts onfile Permission (capability) API keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization members (Admin)List the people in an organization, change a member's role, and remove a member. Reached only with an Admin key.3 | ||||||
| GET | /v1/organizations/users | List the people in an organization, with each member's email, name, and role. | read | Admin key | Current | |
Reached only with an Admin key (sk-ant-admin...) or an org:admin OAuth token, not a workspace API key. The Admin API is unavailable for individual accounts. Acts onorganization member Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/organizations/users/{user_id} | Update an organization member's role. | write | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Members with the admin role cannot be changed or removed through the API. Acts onorganization member Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/organizations/users/{user_id} | Remove a member from an organization. | write | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. The admin role cannot be removed through the API. Acts onorganization member Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workspaces (Admin)List and read workspaces, create a workspace, and manage the members of a workspace. Reached only with an Admin key.3 | ||||||
| GET | /v1/organizations/workspaces | List the workspaces in an organization. | read | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Acts onworkspace Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/organizations/workspaces | Create a workspace, a way to segment API keys and control spend by use case. | write | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Acts onworkspace Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/organizations/workspaces/{workspace_id}/members | Add a member to a workspace with a chosen workspace role. | write | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Acts onworkspace member Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
API keys (Admin)List the organization's API keys, read a single key, and update a key's name or status. Reached only with an Admin key.3 | ||||||
| GET | /v1/organizations/api_keys | List the organization's API keys, filterable by status and workspace. | read | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. New keys cannot be created through the API, only managed. Acts onapi key Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/organizations/api_keys/{api_key_id} | Read a single API key's details. | read | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Does not reveal the secret value of the key. Acts onapi key Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/organizations/api_keys/{api_key_id} | Update an API key's name or status, for example setting it inactive to disable it. | write | Admin key | Current | |
Reached only with an Admin key or an org:admin OAuth token. Setting a key inactive cuts off every call made with it. Acts onapi key Permission (capability) Admin keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The Anthropic API does not push events to a webhook. An app or AI agent learns the outcome of a long-running batch job by polling its status, or receives a streamed message as it is generated.
| Event | What it signals | Triggered by |
|---|
Anthropic limits how fast and how much an app or AI agent can call, through per-model ceilings on requests per minute and on input and output tokens per minute, set by the organization's usage tier.
Anthropic sets rate limits per model, by the organization's usage tier, on three measures: requests per minute, input tokens per minute, and output tokens per minute. The tiers run from Tier 1, where Claude Opus models share 50 requests per minute and 500,000 input tokens per minute, up to Tier 4, where the same models reach 4,000 requests per minute and 10,000,000 input tokens per minute, and an organization advances tiers automatically as its cumulative spend grows. On most models only uncached input tokens count toward the input limit, so prompt caching raises effective throughput, and the max_tokens value does not count toward the output limit. The Message Batches API has its own shared request limit and a cap on how many batch requests can be queued at once. Each response carries anthropic-ratelimit headers reporting the limit, the amount remaining, and when it resets, and going over returns a 429 with a retry-after header.
List methods are cursor-based through after_id and before_id, with a limit parameter that defaults to 20 and ranges from 1 to 1,000. The response carries first_id and last_id to use as cursors and a has_more flag that signals whether more pages remain. Batch results come back as a JSONL file rather than a paginated list, matched to requests by custom_id.
The maximum request size is 32 MB for Messages and Token Counting, 256 MB for the Batches API, and 500 MB for the Files API, and going over returns a 413 request_too_large error. A Message Batch holds up to 100,000 requests and is retained for 24 hours before it expires. The context window an individual request can use is set per model and reported on the Models method.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request_error | The format or content of the request was wrong, for example a missing parameter or an unsupported option like prefilling an assistant message on a model that does not allow it. | Read the message in the error object, fix the request, and resend. It is not retryable as-is. |
| 401 | authentication_error | There is a problem with the API key, such as a missing, invalid, or revoked key. | Confirm a valid key is sent in the x-api-key header, and rotate the key if it is compromised. |
| 403 | permission_error | The key does not have permission to use the requested resource, for example calling an Admin method with a workspace key. | Use the right kind of key, an Admin key for organization methods or a workspace key for model and file methods. |
| 404 | not_found_error | The requested resource was not found. | Confirm the path and the object id, and that the key's workspace can see the resource. |
| 413 | request_too_large | The request exceeded the maximum allowed size: 32 MB for Messages and Token Counting, 256 MB for Batches, and 500 MB for Files. | Reduce the request below the per-endpoint limit, for example by uploading large content through the Files API. |
| 429 | rate_limit_error | A per-minute request or token limit was hit, or an acceleration limit triggered by a sharp increase in usage. | Wait the number of seconds in the retry-after header, then retry, and ramp traffic up gradually. |
| 500 | api_error | An unexpected error inside Anthropic's systems. | Retry with backoff, and contact support with the request_id if it persists. |
| 529 | overloaded_error | The API is temporarily overloaded, which can happen during high traffic across all users. | Back off and retry later with exponential backoff. |
Anthropic versions its API by date through the anthropic-version header, which every request must send. The current documented version is 2023-06-01, and a new dated version is minted only when behavior changes in a way an integration would notice.
The current dated API version, sent in the anthropic-version header. It introduced the current format for streaming server-sent events, where completions are incremental and each event is a named event, and removed the legacy data: [DONE] event along with the legacy exception and truncated response values. Within a version Anthropic adds optional inputs and new output values without breaking existing usage.
The first dated API version, sent in the anthropic-version header. Anthropic recommends using the latest version, and earlier versions are considered deprecated and may be unavailable to new users.
An integration pins a version in the anthropic-version header and moves up when it chooses to.
Anthropic API versions ↗Bollard AI sits between a team's AI agents and the Anthropic API. Grant each agent exactly the access it needs, read or write, method by method, and every call is checked and logged.