> ## Documentation Index
> Fetch the complete documentation index at: https://developer.swytcho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/chat/completions — Swytcho Chat API Reference

> Send a list of messages and receive a model-generated reply. Supports multi-turn conversations, streaming, tool calls, and fine-grained sampling controls.

The `/v1/chat/completions` endpoint accepts a conversation history as an ordered list of messages and returns a model-generated response. Use it to build chatbots, virtual assistants, multi-turn reasoning flows, or any application where you need a model to respond in context.

## Endpoint

```text theme={null}
POST https://api.swytcho.com/v1/chat/completions
```

## Request Parameters

<ParamField body="model" type="string" required>
  The ID of the model to use. Call [`GET /v1/models`](/api-reference/models) to retrieve the list of models available to your account.
</ParamField>

<ParamField body="messages" type="array" required>
  An ordered array of message objects that make up the conversation history. Each object must include a `role` and `content`.

  <Expandable title="Message object fields">
    <ParamField body="role" type="string" required>
      The role of the message author. One of `system`, `user`, or `assistant`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The text content of the message.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens to generate in the response. When omitted, the model uses its default context limit. Setting this value helps control costs and response length.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between `0` and `2`. Higher values (e.g., `1.4`) produce more varied and creative output; lower values (e.g., `0.2`) produce more deterministic output. Defaults to `1`. Avoid setting both `temperature` and `top_p` at the same time.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling threshold between `0` and `1`. The model considers only the smallest set of tokens whose cumulative probability exceeds `top_p`. Defaults to `1`. Avoid setting both `top_p` and `temperature` at the same time.
</ParamField>

<ParamField body="stream" type="boolean">
  When `true`, the API streams partial message deltas as server-sent events (SSE) and sends a final `[DONE]` message. Defaults to `false`.
</ParamField>

<ParamField body="stop" type="string | array">
  One or more sequences at which the model stops generating further tokens. Pass a single string or an array of up to four strings.
</ParamField>

<ParamField body="tools" type="array">
  A list of tool definitions the model may call during generation. Each tool must conform to the JSON Schema function definition format.

  <Expandable title="Tool object fields">
    <ParamField body="type" type="string" required>
      Must be `"function"`.
    </ParamField>

    <ParamField body="function" type="object" required>
      An object with `name` (string), `description` (string), and `parameters` (JSON Schema object) fields describing the callable function.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls which tool (if any) the model calls. Pass `"none"` to disable tool calls, `"auto"` to let the model decide, or an object `{"type": "function", "function": {"name": "your_function"}}` to force a specific tool.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.swytcho.com/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "swytcho-pro",
      "messages": [
        { "role": "system", "content": "You are a helpful assistant." },
        { "role": "user", "content": "What is the capital of France?" }
      ],
      "max_tokens": 256,
      "temperature": 0.7
    }'
  ```

  ```python Python theme={null}
  import os
  from swytcho import Swytcho

  client = Swytcho(api_key=os.environ["SWYTCHO_API_KEY"])

  response = client.chat.completions.create(
      model="swytcho-pro",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What is the capital of France?"},
      ],
      max_tokens=256,
      temperature=0.7,
  )

  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import Swytcho from "swytcho";

  const client = new Swytcho({ apiKey: process.env.SWYTCHO_API_KEY });

  const response = await client.chat.completions.create({
    model: "swytcho-pro",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "What is the capital of France?" },
    ],
    max_tokens: 256,
    temperature: 0.7,
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

## Response Fields

<ResponseField name="id" type="string">
  A unique identifier for this completion, prefixed with `chatcmpl-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) of when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model ID that was used to generate this response.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of generated response objects. Contains one element unless you request multiple completions.

  <Expandable title="Choice object fields">
    <ResponseField name="index" type="integer">
      Zero-based index of this choice in the array.
    </ResponseField>

    <ResponseField name="message" type="object">
      The generated message object with `role` (`"assistant"`) and `content` (string) fields. When a tool is called, a `tool_calls` array is included instead of or alongside `content`.
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason generation stopped. One of `"stop"` (natural end), `"length"` (hit `max_tokens`), `"tool_calls"` (model invoked a tool), or `"content_filter"` (output blocked by safety policy).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for the request.

  <Expandable title="Usage object fields">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the input messages.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Number of tokens in the generated response.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens consumed (`prompt_tokens` + `completion_tokens`).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "id": "chatcmpl-a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1717200000,
  "model": "swytcho-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37
  }
}
```