Skip to main content

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.

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:
HeaderValue
AuthorizationBearer <SUDO_API_KEY>
Content-Typeapplication/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"
  }
}

​
Next steps

Headers & Auth

Read about authenticating requests

Streaming

See Streaming to deliver tokens to your UI in real-time.