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

# Overview

> Overview of the Sudo developer API

Sudo's REST API closely mirrors the [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat) specification.\
If you already integrate with OpenAI you can usually **swap the base URL, provide a Sudo API key, and you're done**.

**Base URL**: `https://sudoapp.dev/api`\
**Completions endpoint**: `/v1/chat/completions`

<Note> Some third-party model providers do **not** support every OpenAI feature (for example *tools* or *vision*). Refer to their individual documentation when in doubt. </Note>

***

## Requests

The request body you `POST` to `/v1/chat/completions` accepts the same fields you're used to.
Below is an **example** condensed TypeScript definition (non-exhaustive):

<CodeGroup>
  ```typescript title="Request Schema" theme={null}
  export type ChatCompletionRequest = {
    /* Pick **one** */
    messages: Message[];

    /** Full model identifier – e.g. `gpt-4o` or `claude-4-sonnet` */
    model: string;

    /** Format enforcement – OpenAI-style */
    response_format?: { type: 'json_object' };

    /* Common generation params */
    max_completion_tokens?: number;
    parallel_tool_calls?: boolean;
    tools?: Tool[];
    temperature?: number;
    top_p?: number;
    stop_sequences?: string[];
    stream?: boolean;
  };

  export type Message = {
    role: 'system' | 'user' | 'assistant' | 'tool';
    content: string | ContentPart[];
    name?: string;
    /** Only for tool role */
    tool_call_id?: string;
  };

  export type ContentPart =
    | { type: 'text'; text: string }
    | { type: 'image_url'; image_url: { url: string; detail?: string } };
  ```
</CodeGroup>

For a more exhaustive spec of supported request parameters, see the endpoints in the next section.

### Headers

Only two headers are required:

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <SUDO_API_KEY>` |
| `Content-Type`  | `application/json`      |

### Example

```shell title="curl" theme={null}
curl https://sudoapp.dev/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SUDO_API_KEY" \
  -d '{
  "model": "gpt-4o",
  "messages": [{"role":"user","content":"Hello!"}]
}'
```

***

## Responses

Sudo **normalises** provider responses to match the OpenAI schema.
A non-streaming response looks like this:

```json title="Example Response" theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello there!" },
      "finish_reason": "stop",
      "native_finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 4,
    "total_tokens": 9
  }
}
```

### Finish reasons

`finish_reason` is one of `stop`, `length`, `tool_calls`, `content_filter`, or `error` – mirroring OpenAI's values.

### Error handling

Errors follow the shape:

```json title="Error" theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "api_error"
  }
}
```

***

## Next steps

<Columns cols={2}>
  <Card title="Headers & Auth" icon="lock" href="auth">
    Read about authenticating requests
  </Card>

  <Card title="Streaming" icon="forward" href="streaming">
    See **Streaming** to deliver tokens to your UI in real-time.
  </Card>
</Columns>