---
title: "Chat Completions (OpenAI-compatible)"
method: POST
path: "/v1/chat/completions"
tags: ["OpenAI Compatible"]
---

# Chat Completions (OpenAI-compatible)

`POST /v1/chat/completions`

## Request

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

OpenAI-compatible chat completions endpoint. Accepts the standard OpenAI request schema and returns the standard OpenAI response schema. Supports both streaming (SSE) and non-streaming modes. Works as a drop-in replacement with the OpenAI Python and TypeScript SDKs.

## Headers

- `x-api-key` string, required

## Request body

- ChatCompletionRequest
  - `model` string, required: Model to use for completion
  - `messages` ChatMessage[], required: A list of messages comprising the conversation
    - `role` string, required: The role of the message author (system, developer, user, assistant, tool). System and developer messages are joined, in order, into the system prompt.
    - `content` union: The content of the message
      - string
      - unknown[]
        - unknown
    - `name` string, nullable: An optional name for the participant
    - `tool_calls` object[], nullable: Tool calls the assistant asked for, in OpenAI function-calling shape
    - `tool_call_id` string, nullable: On a tool message, the id of the call this result answers
  - `temperature` number, nullable: Sampling temperature (0 to 2)
  - `top_p` number, nullable: Nucleus sampling parameter
  - `n` integer, nullable: Number of completions to generate
  - `stream` boolean, nullable: Whether to stream partial results
  - `max_tokens` integer, nullable: Maximum tokens to generate
  - `max_completion_tokens` integer, nullable: Maximum completion tokens (takes precedence over max_tokens)
  - `presence_penalty` number, nullable: Presence penalty
  - `frequency_penalty` number, nullable: Frequency penalty
  - `stop` union: Up to 4 sequences where the model stops generating further tokens
    - string
    - string[]
  - `user` string, nullable: Unique identifier for the end-user
  - `max_loops` integer, nullable: Maximum number of agent reasoning loops (Swarms extension). Defaults to 1 (single pass), at most 50. Use via extra_body in the OpenAI SDK.
  - `tools` object[], nullable: Function-calling tool definitions, in OpenAI schema
  - `tool_choice` union: Tool selection strategy: 'auto', 'none', 'required', or a specific function
    - string
    - object

## Response `200`

Successful Response

- ChatCompletionResponse
  - `id` string, required
  - `object` string
  - `created` integer, required
  - `model` string, required
  - `choices` ChatCompletionChoice[], required
    - `index` integer
    - `message` ChatMessage, required
      - `role` string, required: The role of the message author (system, developer, user, assistant, tool). System and developer messages are joined, in order, into the system prompt.
      - `content` union: The content of the message
        - string
        - unknown[]
          - unknown
      - `name` string, nullable: An optional name for the participant
      - `tool_calls` object[], nullable: Tool calls the assistant asked for, in OpenAI function-calling shape
      - `tool_call_id` string, nullable: On a tool message, the id of the call this result answers
    - `finish_reason` string, nullable
  - `usage` CompletionUsage, required
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `500c79520e41`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/changes/v1/chat/completions/post.md)

---

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