> ## Documentation Index > Fetch the complete documentation index at: https://docs.hopscotchlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a message (Anthropic Messages API) > Send a request in the Anthropic Messages format. Set `stream: true` for Anthropic's own server-sent event stream. The credential is read from either `Authorization: Bearer` or Anthropic's own `x-api-key` header, so an unmodified Anthropic SDK works whichever way it authenticates. If both headers are present they must carry the same key: two different keys are refused with 401 rather than one being chosen. `max_tokens` is required by Anthropic and is passed through as you send it. It is not defaulted here, and a request that leaves it out is refused by the provider in the provider's own words. It is also the figure the credit held for the request is sized from. An `anthropic-version` header is not forwarded. This route differs from Anthropic's own API in one way: a refusal comes back in the OpenAI error envelope that every other route here uses, so an Anthropic SDK reads the sentence from `error.message`. Only `POST /v1/messages` is served. `POST /v1/messages/count_tokens` is not, and answers 404 with the code `endpoint_not_supported`. Credit is held when the request is admitted and settled against the provider's own token counts when it finishes. You are charged the provider's rate at face value. Nothing is added per request. To read back the tokens and charge of one request afterwards, send the value of the `x-hopscotch-request-id` response header to `GET /v1/usage/{id}`. ## OpenAPI ````yaml /api-reference/openapi.public.json post /v1/messages openapi: 3.0.3 info: title: Hopscotch version: v1 description: >- An OpenAI-compatible inference API. Point an OpenAI client at https://api.hopscotchlabs.ai, give it a Hopscotch API key, and call models across providers on one prepaid balance. Every response, errors included, matches the shape an unmodified OpenAI SDK expects. servers: - url: https://api.hopscotchlabs.ai description: Production security: - customerApiKey: [] tags: - name: Chat description: Chat completions, streamed or not. - name: Models description: What you can call. - name: Completions description: Text completions, streamed or not. - name: Messages description: The Anthropic Messages API, streamed or not. - name: Usage description: What one request recorded and what it cost. paths: /v1/messages: post: tags: - Messages summary: Create a message (Anthropic Messages API) description: >- Send a request in the Anthropic Messages format. Set `stream: true` for Anthropic's own server-sent event stream. The credential is read from either `Authorization: Bearer` or Anthropic's own `x-api-key` header, so an unmodified Anthropic SDK works whichever way it authenticates. If both headers are present they must carry the same key: two different keys are refused with 401 rather than one being chosen. `max_tokens` is required by Anthropic and is passed through as you send it. It is not defaulted here, and a request that leaves it out is refused by the provider in the provider's own words. It is also the figure the credit held for the request is sized from. An `anthropic-version` header is not forwarded. This route differs from Anthropic's own API in one way: a refusal comes back in the OpenAI error envelope that every other route here uses, so an Anthropic SDK reads the sentence from `error.message`. Only `POST /v1/messages` is served. `POST /v1/messages/count_tokens` is not, and answers 404 with the code `endpoint_not_supported`. Credit is held when the request is admitted and settled against the provider's own token counts when it finishes. You are charged the provider's rate at face value. Nothing is added per request. To read back the tokens and charge of one request afterwards, send the value of the `x-hopscotch-request-id` response header to `GET /v1/usage/{id}`. operationId: createMessage parameters: - name: x-api-key in: header required: false description: >- Your Hopscotch API key, as an alternative to `Authorization: Bearer`. If you send both, they must carry the same key. schema: type: string example: ub_live_YOUR_KEY_HERE requestBody: content: application/json: schema: type: object properties: model: type: string description: >- A model id in `provider/model` form, or `profile/{identifier}` for one of your workspace's routing profiles. A bare model id is refused with 400 and the code `model_id_not_pinned`. The catalog must list the model for messages. List what you can call with GET /v1/models. example: anthropic/claude-sonnet-4-5 messages: type: array description: The conversation turns, in Anthropic message form. items: type: object additionalProperties: true max_tokens: type: integer description: >- The most output tokens you will accept. Required, and passed to the provider as sent. The provider owns the ceiling for the model you name. minimum: 1 stream: type: boolean description: >- Return the reply as Anthropic's own event stream instead of one JSON body. default: false system: description: >- A system prompt, as Anthropic's API takes it: a string or an array of content blocks. oneOf: - type: string - type: array items: type: object additionalProperties: true tools: type: array description: Tool definitions, in Anthropic's form. items: type: object additionalProperties: true tool_choice: type: object additionalProperties: true description: How the model may use the tools, in Anthropic's form. required: - model - messages - max_tokens additionalProperties: true description: >- An Anthropic Messages request. Fields beyond the ones named here are forwarded to the provider unchanged, so Anthropic's own documentation describes them. example: model: anthropic/claude-sonnet-4-5 max_tokens: 64 messages: - role: user content: Say hi in five words. required: true responses: '200': description: >- The message, in Anthropic's format as the provider produced it: a `content` array, a `stop_reason`, and a `usage` object with `input_tokens` and `output_tokens`. When `stream` is true the body is `text/event-stream` instead, passed through in Anthropic's own event format. headers: x-hopscotch-served-by: $ref: '#/components/headers/ServedBy' description: >- The full id, "{provider}/{model}", of the model that actually answered: the pinned id when the request named one directly, or the routing-profile chain member that served when the request named a profile. schema: type: string example: anthropic/claude-haiku-4-5-20251001 x-hopscotch-served-via: $ref: '#/components/headers/ServedVia' description: >- Present, with the value `backup`, when a backup route served this request. Absent on every other response, and never sent with any other value, so a client that has never read it sees nothing change about an ordinary request. The provider named on x-hopscotch-provider and in the body is still the one you asked for. schema: type: string enum: - backup example: backup x-hopscotch-request-id: $ref: '#/components/headers/RequestId' x-request-id: $ref: '#/components/headers/SdkRequestId' x-hopscotch-provider: $ref: '#/components/headers/Provider' x-hopscotch-retry-attempt-count: $ref: '#/components/headers/RetryAttemptCount' x-hopscotch-cache-status: $ref: '#/components/headers/CacheStatus' x-hopscotch-trace-id: $ref: '#/components/headers/TraceId' content: application/json: schema: $ref: '#/components/schemas/Message' example: id: msg_EXAMPLE type: message role: assistant model: claude-sonnet-4-5 content: - type: text text: Hello, good to meet you. stop_reason: end_turn stop_sequence: null usage: input_tokens: 12 output_tokens: 9 '400': description: >- The request cannot be served as sent. `code` is null for a missing parameter, with `param` naming it, `model_id_not_pinned` for a model id that names no provider, and `provider_key_refused` when the request ran on your own key for a provider that rejected it or refused this particular call under it. A refusal the provider made about this request, such as a missing `max_tokens`, is relayed with the provider's own status and its own sentence, quoted after the provider's name. On the platform's own provider keys this route also refuses, with `code` null and `param` naming the field and never its value, a field that buys something this platform cannot bill yet: `container`, `mcp_servers`, a hosted tool the provider charges for per call, a one-hour cache write, and the priority, speed and regional processing fields. A request served on your own provider key keeps every one of them. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_model: summary: No model named value: error: message: >- You must provide a model parameter naming the model to call. It is read to work out what the request could cost before it is sent. type: invalid_request_error param: model code: null request_id: REQUEST_ID model_id_not_pinned: summary: The model id does not name its provider value: error: message: >- The model "gpt-4o-mini" does not name its provider. A model field carries either "provider/model", where the part before the first slash is a provider this platform serves and the rest is that provider's own id for the model, for example "anthropic/claude-opus-4-5", or "profile/{identifier}", one of your workspace's routing profiles, for example "profile/fast". GET /v1/models lists the exact strings this key can call. type: invalid_request_error param: model code: model_id_not_pinned request_id: REQUEST_ID max_tokens_missing: summary: The provider refused a request with no max_tokens value: error: message: >- anthropic refused this request: max_tokens: Field required type: invalid_request_error param: null code: null request_id: REQUEST_ID mcp_servers: summary: A field this platform does not meter value: error: message: >- "mcp_servers" asks the provider for something this platform does not meter yet (a priority or fast mode, regional processing, a hosted tool or search, audio, or a one-hour cache write). Remove it, or send the request on your own provider key. type: invalid_request_error param: mcp_servers code: null request_id: REQUEST_ID provider_key_refused: summary: Your own provider key was rejected value: error: message: >- openai rejected your workspace's own openai key (401), so the credential itself was not accepted. Replace it on the Provider keys screen. While your workspace holds a key for openai, every request to openai runs on yours and none is sent on a Hopscotch key, so no other credential was tried for it. Nothing was charged for this request. Remove the key on the Provider keys screen and these requests go back to running on Hopscotch's key and being charged for. type: invalid_request_error param: null code: provider_key_refused request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '401': description: >- No key, a scheme other than Bearer with no `x-api-key` beside it, a key of the wrong shape, or a key we reject. An unknown key and a revoked key are answered with one identical message on purpose. Two different keys, one in `Authorization` and one in `x-api-key`, are refused too, with the same code and a message saying so. A key past its own expiry date is refused with code `key_expired` and a message naming the date. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_api_key: summary: A key we reject value: error: message: Incorrect API key provided. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID no_api_key: summary: No credential in either header value: error: message: >- You did not provide an API key. Send it in an Authorization header using Bearer auth, or in x-api-key. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID two_different_keys: summary: Two different keys value: error: message: >- This request carried two different API keys, in Authorization and x-api-key. Send one credential. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '402': description: >- The request will not be paid for, and nothing was charged. Code `insufficient_credit` is the workspace being out of credit, which stops every key on it. Code `key_limit_exceeded` is the sending key reaching its own credit limit, which leaves every other key in the workspace serving normally; it is refused before any credit is held, and the message names what that key has settled and holds inside its current window. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_credit: summary: The workspace is out of credit value: error: message: >- This account has 54 minor units available and the request needs 55 held. type: insufficient_quota param: null code: insufficient_credit request_id: REQUEST_ID key_limit_exceeded: summary: This key is at its own limit value: error: message: >- This key may spend $20.00 in its current window and has $18.40 settled and $1.70 held against that, so a request needing $0.30 more is refused. Nothing was charged for it and no credit was held. The limit belongs to this key alone, so other keys in the workspace are unaffected. This limit resets monthly on UTC calendar windows, so requests are admitted again when the window rolls. It can also be raised or removed on the Keys screen. type: insufficient_quota param: null code: key_limit_exceeded request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '403': description: >- Refused for a setting the caller owns rather than anything about the model, and `code` names which. A key whose account staff have suspended is refused with code `account_suspended`, before any credit is held or any provider is called; contact support, because retrying will not change the answer. content: application/json: schema: $ref: '#/components/schemas/Error' examples: account_suspended: summary: The key's account is suspended value: error: message: >- This account is suspended, so it cannot send requests. Contact support. Request id REQUEST_ID. type: permission_error param: null code: account_suspended request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '404': description: >- The model cannot be served, and the two cases are told apart by `code`. `model_not_found` means the id is in no catalog at all, which is what a typo produces, so check the spelling or list what this key can call with `GET /v1/models`. `model_not_available` means the id is catalogued and is not being served right now, or that the catalog does not list it for this endpoint. In the second case the message names the endpoint families the catalog does list it for, so move to a model that is listed for this one. No provider was called either way. headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: model_not_found: summary: No model of that id exists value: error: message: >- The model "MODEL_ID" does not exist. Check the spelling, or list the models this key can call with GET /v1/models. type: not_found_error param: null code: model_not_found request_id: REQUEST_ID model_not_available: summary: Known to us, and not being served right now value: error: message: >- The model "MODEL_ID" is not currently available. It is known to this platform and is not being served right now, so retrying later is worth more than changing the request. type: not_found_error param: null code: model_not_available request_id: REQUEST_ID model_not_available_endpoint: summary: Live, and not offered on this endpoint value: error: message: >- "MODEL_ID" is not offered on this endpoint: the catalog lists it for chat_completions and not for messages. type: not_found_error param: null code: model_not_available request_id: REQUEST_ID '405': description: >- A method other than POST on this path. The route boundary answers this before any key is looked at, so it costs nothing and reveals nothing. headers: Allow: schema: type: string enum: - POST description: The methods this path accepts. example: POST x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: GET is not supported for /v1/messages in this release. type: invalid_request_error param: null code: method_not_allowed request_id: REQUEST_ID '413': description: >- The request body is larger than the 8388608 byte maximum this API accepts, so it was refused at the door. A body that declares its length is refused without a byte being read; one that declares none is read only as far as the ceiling and then abandoned. Nothing was parsed, no credit was held, no model was called and nothing was charged. content: application/json: schema: $ref: '#/components/schemas/Error' examples: payload_too_large: summary: The request body is over the ceiling value: error: message: >- This request body is larger than the 8388608 byte maximum this API accepts. Nothing was read, no model was called and nothing was charged. Send fewer messages, a shorter prompt, or fewer inputs. type: invalid_request_error param: null code: payload_too_large request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '429': description: >- A limit refused the request. `rate_limit_exceeded` is this key's own request rate and carries `Retry-After`. `spend_rate_exceeded` is the account spend rate cap, which counts the credit held for requests rather than the credit they settle at; send `max_tokens` to hold less. `provider_key_refused` is your own key for a provider being over its limit there; it clears on its own and carries no `Retry-After`. `upstream_rate_limited` is the model's provider rate-limiting the call: nothing about the request is wrong, nothing is charged, and it carries `Retry-After`. headers: Retry-After: schema: type: integer minimum: 1 description: >- Seconds to wait. Present on `rate_limit_exceeded` and on `upstream_rate_limited`. example: 17 x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: summary: This key's request rate value: error: message: >- Rate limit reached for this key. Try again in 12 seconds. Request id REQUEST_ID. type: rate_limit_error param: null code: rate_limit_exceeded request_id: REQUEST_ID spend_rate_exceeded: summary: The account spend rate cap value: error: message: >- This account has already reserved 5000 minor units in the last 60 seconds, which is at its ceiling of 5000. Requests are admitted again within 60 seconds of the earliest reservation counted, with nothing to do in the meantime. type: rate_limit_error param: null code: spend_rate_exceeded request_id: REQUEST_ID provider_key_refused: summary: Your own provider key is over its limit value: error: message: >- openai refused this request as over its limits, on your workspace's own openai key. This is your account's limit at openai rather than ours. While your workspace holds a key for openai, every request to openai runs on yours and none is sent on a Hopscotch key, so no other credential was tried for it. Nothing was charged for this request. Remove the key on the Provider keys screen and these requests go back to running on Hopscotch's key and being charged for. type: rate_limit_error param: null code: provider_key_refused request_id: REQUEST_ID upstream_rate_limited: summary: The model's provider rate-limited the call value: error: message: >- The provider serving this model is rate-limiting requests right now. Nothing was charged. Retry after the number of seconds in the Retry-After header. Quote the request id if you contact support. type: rate_limit_error param: null code: upstream_rate_limited request_id: REQUEST_ID '500': description: A fault on our side. The request id is the one thing worth keeping. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- The server had an error while processing your request. Sorry about that! Quote the request id if you contact support. type: api_error param: null code: null request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '503': description: >- Ours rather than yours, and `code` names the condition. `paused_by_owner` clears only when somebody lifts the pause, so retrying on a timer will not help. `balance_unavailable` (we could not read the balance, so the request was refused rather than served unmetered), `model_not_priceable` and `model_pricing_unreadable` (a model we list could not be priced for this call) and `no_provider_configured` (we are not currently configured to serve this) all clear without you doing anything. content: application/json: schema: $ref: '#/components/schemas/Error' examples: paused_by_owner: summary: Somebody pressed Pause value: error: message: >- Every request on this account is paused, because somebody with access to it pressed Pause in the dashboard. Nothing was charged for this request and no credit was held for it. It is retryable, and it will be refused the same way until the pause is lifted, so retrying on a timer will not clear it. Requests start working again the moment the pause is lifted from the same control, with nothing else to do and nothing to re-create. type: server_error param: null code: paused_by_owner request_id: REQUEST_ID balance_unavailable: summary: We could not read the balance value: error: message: >- Your credit balance could not be checked while this request was running, so it was stopped rather than left unwatched. This is a fault on our side rather than a problem with your account, and it does not mean you are out of credit. Try again shortly. type: server_error param: null code: balance_unavailable request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '504': description: The request ran past the request deadline and was terminated. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- This request ran longer than the 540 second limit and was terminated. Reduce the amount of work in one call, or stream the response, and try again. type: server_error param: null code: request_deadline_exceeded request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' security: - customerApiKey: [] servers: - url: https://api.hopscotchlabs.ai description: Production components: headers: ServedBy: description: >- The full id, "{provider}/{model}", of the model that actually answered: the id you pinned, or the member of the routing profile that served. Present on every served reply, streamed or not, which is the only place a streamed request can read it. schema: type: string example: openai/gpt-4o-mini ServedVia: description: >- Present, with the value `backup`, when a backup route served this request. Absent on every other response, and never sent with any other value, so a client that has never read it sees nothing change about an ordinary request. The provider named on x-hopscotch-provider and in the body is still the one you asked for. schema: type: string enum: - backup example: backup RequestId: description: >- Our id for this request. Quote it when you contact support. Present on every response, errors included. schema: type: string SdkRequestId: description: >- The same value as x-hopscotch-request-id, on the header the official OpenAI SDKs surface on their error objects. schema: type: string Provider: description: Which provider answered. schema: type: string RetryAttemptCount: description: How many attempts were made before the response you received. schema: type: string CacheStatus: description: Whether the reply came from cache. schema: type: string TraceId: description: A trace id for this request. schema: type: string schemas: Message: type: object description: An Anthropic message, as the provider produced it. additionalProperties: true properties: id: type: string type: type: string example: message role: type: string example: assistant model: type: string content: type: array items: type: object additionalProperties: true stop_reason: type: string nullable: true stop_sequence: type: string nullable: true usage: type: object additionalProperties: true properties: input_tokens: type: integer output_tokens: type: integer Error: type: object description: The error envelope. One top-level `error` key, always, at every status. required: - error additionalProperties: false properties: error: type: object required: - message - type - param - code additionalProperties: false properties: message: type: string description: Prose for a person. It may be reworded, so do not branch on it. type: type: string description: The category an SDK branches on. A closed set. enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - api_error - insufficient_quota - server_error param: type: string nullable: true description: >- The request field at fault, or null. Present and null rather than absent. code: type: string nullable: true description: The stable machine-readable reason. Branch on this. request_id: type: string description: >- Our id for this request, the same value as the x-hopscotch-request-id header. Quote it when you contact support. securitySchemes: customerApiKey: type: http scheme: bearer description: >- A workspace API key in an `Authorization: Bearer` header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.