Overview

Sudo’s REST API closely mirrors the OpenAI Chat Completions 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

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

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):

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 } };

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

curl

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:

Example Response

{
  "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:

Error

{
  "error": {
    "message": "Invalid API key",
    "type": "api_error"
  }
}

SDKs

API Reference

Overview

Requests

Headers

Example

Responses

Finish reasons

Error handling

Next steps

Headers & Auth

Streaming

​Requests

​Headers

​Example

​Responses

​Finish reasons

​Error handling

​Next steps

Headers & Auth

Streaming

Requests

Headers

Example

Responses

Finish reasons

Error handling

Next steps