Quickstart

Get your first Sansa API response in under 2 minutes.

Create an API key

Create an API key in your dashboard. Store it somewhere safe, then export it as an environment variable:

export SANSA_API_KEY="sk-sansa-..."

Install the OpenAI SDK

Sansa uses an OpenAI compatable API.

npm install openai

pip install openai

Make your first request

Create a file and copy in the example from the code panel. The only difference from OpenAI is baseURL and your Sansa API key.

Run it. You should see a response in a few seconds.

Stream a response

Set stream: "true" to get tokens as they're generated. See the code panel for a full example.

Streaming uses Server-Sent Events and works with the OpenAI SDK. See the Streaming docs for chunk format and error handling.

Call a function

Define tools and the model will call them when relevant. Your code executes the function and sends the result back. See the code panel for the flow.

Full details in the Tools docs.

Next steps

Completions Reference — Full parameter reference
Streaming — SSE format, chunk shape, error handling
Tools — Function calling and agentic loops
Reasoning — Extended thinking tokens

Make your first request

curl -X POST https://api.trysansa.com/v1/chat/completions \
  -H "Authorization: Bearer $SANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sansa-auto",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1708300000,
  "model": "sansa-auto",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}

Stream a response

const stream = await client.chat.completions.create({
  model: 'sansa-auto',
  messages: [{ role: 'user', content: 'Write a haiku about code.' }],
  stream: true,
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
}

Stream Response Chunk

{
  "id": "chatcmpl-xyz",
  "object": "chat.completion.chunk",
  "created": 1708300000,
  "model": "sansa-auto",
  "choices": [{
    "index": 0,
    "delta": { "content": "Code is " },
    "finish_reason": null
  }]
}

Call a function

const response = await client.chat.completions.create({
  model: 'sansa-auto',
  messages: [{ role: 'user', content: "What's the weather in Tokyo?" }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string' },
        },
        required: ['location'],
      },
    },
  }],
});

// Model responds with tool_calls — execute the
// function, then send the result back. See the
// Tools docs for the full loop.

Tool Call Response

{
  "id": "chatcmpl-def456",
  "object": "chat.completion",
  "created": 1708300000,
  "model": "sansa-auto",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\": \"Tokyo\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 68,
    "completion_tokens": 18,
    "total_tokens": 86
  }
}