---
title: "Messages (Anthropic-compatible)"
method: POST
path: "/v1/messages"
tags: ["Anthropic Compatible"]
---

# Messages (Anthropic-compatible)

`POST /v1/messages`

## Request

- Base URL: `https://api.swarms.world`
- URL: `https://api.swarms.world/v1/messages`
- Auth: none declared. Required headers: `x-api-key`

Anthropic Messages API format, non-streaming text only. Code written for the Anthropic SDK runs with base_url and api_key changed. Streaming, images, documents, tools, thinking, assistant prefill and any other field not listed here are rejected with a 400.

## Headers

- `x-api-key` string, required

## Request body

- MessagesRequest
  - `model` string, required: Model to use
  - `max_tokens` integer, required: Maximum tokens to generate
  - `messages` Message[], required: Alternating user and assistant turns
    - `role` 'user' | 'assistant', required: Who wrote the turn
    - `content` union, required: A string, or a list of content blocks. Only {"type": "text", "text": "..."} blocks are accepted; any other block type is rejected with a 400.
      - string
      - object[]
  - `system` union: System prompt: a string or text blocks
    - string
    - object[]
  - `temperature` number, nullable: Sampling temperature
  - `top_p` number, nullable: Nucleus sampling cutoff

## Response `200`

Successful Response

- MessagesResponse: A completed message in the Anthropic Messages API shape.
  - `id` string, required: Unique id, prefixed msg_
  - `type` 'message'
  - `role` 'assistant'
  - `model` string, required: The model that answered
  - `content` TextBlock[], required: Always a single text block
    - `type` 'text'
    - `text` string, required: The generated text
  - `stop_reason` 'end_turn' | 'max_tokens', required: end_turn when the model finished, max_tokens when it hit the max_tokens limit
  - `stop_sequence` string, nullable: Always null; stop sequences are not supported
  - `usage` MessagesUsage, required
    - `input_tokens` integer, required: Tokens in the prompt, system included
    - `output_tokens` integer, required: Tokens the model generated

## Other responses

- `400`: An unsupported field or content block, named in the message, or messages that don't end with a user turn
- `402`: Not enough credits
- `404`: Unknown model
- `422`: Validation Error
- `429`: Rate limit exceeded

## Changes

- **2026-10-25** `2534b8ba042e`: 1 breaking, 12 info
  - the response's body type changed from no type to `object` for status `200`
  - added the non-success response with the status `400`
  - added the non-success response with the status `402`
  - added the non-success response with the status `404`
  - …9 more
- **2026-10-22** `90470f3738e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/swarms/apis/swarms-api/changes/v1/messages/post.md)

---

[API](https://skmtc.dev/swarms/apis/swarms-api.md) - [All operations](https://skmtc.dev/swarms/apis/swarms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/swarms/apis/swarms-api/revisions/fca99f497199?raw)