Sensara Models API

Quick start

Set your key, list the models it can use, then send a chat request.

export SENSARA_API_KEY="<your API key>"   # from your dashboard

curl https://api.sensara.sh/v1/models \
  -H "Authorization: Bearer $SENSARA_API_KEY"

curl https://api.sensara.sh/v1/chat/completions \
  -H "Authorization: Bearer $SENSARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sensara-max",
    "messages": [{"role": "user", "content": "Explain backpressure in two sentences."}]
  }'

The API is public over HTTPS. You don't need Tailscale or a VPN.

Getting access

1. Register with the email your invitation went to. Register
2. Confirm your email from the link we send. Links are single-use.
3. Wait for approval. An admin reviews the request and sets which models you can use and your limits.
4. Create an API key on your dashboard. Your dashboard also shows your usage by model.

Authentication

Send your API key as a bearer token on every request.

• The full key is shown once, when you create it. Afterwards the dashboard shows only its prefix. If you lose it, revoke it and create another.
• Keep keys in a secret manager or environment variable. Never ship one in a browser or mobile app.
• Use one key per machine or service so you can revoke one without interrupting the rest. Revoking takes effect immediately.

Models and hardware

A model ID is either an alias, which lets Sensara choose the machine, or a hardware ID, which pins one machine. Your key can use only the IDs your account was granted; GET /v1/models lists them.

• sensara-max is the smartest model, with the longest context (1M tokens). It runs on Atlas, four DGX Sparks.
• sensara-fast answers fastest and handles many requests at once (256K tokens). It runs on Nova, an M5 Ultra.
• sensara-lite is a smaller model for light requests (256K tokens). It runs on Pico, an M5 Pro.
• sensara-auto picks the first healthy backend with capacity that supports the request. Use it when response time matters more than which machine answers.
• Pinned IDs atlas/sensara-max, nova/sensara-fast and pico/sensara-lite always run on that machine and wait in its queue when it is busy. Older names such as sensara-quality still work but are no longer listed.

Your dashboard shows which backend served each request. Treat the live /v1/models response as authoritative. It reports the context, output, reasoning, and input modalities for the currently loaded runtime.

Endpoints

Python

Use the official openai package with Sensara's base URL.

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.sensara.sh/v1",
    api_key=os.environ["SENSARA_API_KEY"],
)

reply = client.chat.completions.create(
    model="sensara-max",
    messages=[{"role": "user", "content": "Write a haiku about latency."}],
)
print(reply.choices[0].message.content)

Streaming and tools

Set stream to receive tokens as server-sent events while the answer is generated.

stream = client.chat.completions.create(
    model="sensara-auto",
    messages=[{"role": "user", "content": "Count to five slowly."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

curl -N https://api.sensara.sh/v1/chat/completions \
  -H "Authorization: Bearer $SENSARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sensara-auto", "stream": true,
       "messages": [{"role": "user", "content": "Count to five."}]}'

Tool calls use the standard tools parameter. The model returns tool_calls; run the tool yourself and send its result back as a tool message.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

reply = client.chat.completions.create(
    model="sensara-max",
    messages=[{"role": "user", "content": "Is it raining in Lisbon?"}],
    tools=tools,
)
for call in reply.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)

Responses API

POST /v1/responses currently runs on Atlas only. sensara-max and sensara-auto route to Atlas for it, and atlas/sensara-max works directly. sensara-fast, sensara-lite and their pinned IDs aren't supported on this endpoint; use Chat Completions for them.

response = client.responses.create(
    model="sensara-max",
    input="Summarize the CAP theorem in one paragraph.",
)
print(response.output_text)

CLI

The sensara command stores your key, lists and selects models, sends prompts from the terminal, and sets up other tools to use Sensara Models. It is a client for the API, not a coding agent. A (text) marker means the model currently does not accept image input; model IDs themselves never change.

Install

curl -fsSL https://sensara.sh/cli/install.sh | sh

Set up and use

sensara set-key                 # paste the key from your dashboard
sensara models                  # IDs and live input capabilities
sensara use sensara-auto        # default model for sensara run
sensara run "Explain mmap in one paragraph" --stream

Update

sensara update

Use with Codex or Pi

# Pi: configure the real files Pi reads
sensara set-key
sensara configure pi
pi

# Choose the other public alias for one session
pi --provider sensara --model sensara-auto

sensara configure pi merges the sensara provider into ~/.pi/agent/models.json and sets the default in ~/.pi/agent/settings.json. Existing Pi providers and settings remain in place. Pi reads the key from the local Sensara CLI config, so no export is required. Run the command again after a model change to refresh context, output, and image capability metadata.

Limits

Your access policy, shown on your dashboard, sets three limits:

Requests per minute

Across all your keys, counted over the rate limit window.

Active requests per backend

How many of your requests each machine runs at once.

Queued requests per backend

How many more wait in each machine's queue.

Concurrency limits apply to each backend separately, so with sensara-auto your requests can run on several machines at once. A request over a limit returns 429; retry after a short, increasing delay.

Errors

Errors use standard HTTP status codes with an OpenAI-style JSON body:

{ "error": { "code": "rate_limited", "message": "Too many requests." } }

401

Missing, revoked or unknown API key.

403

The account isn't approved, or the model isn't in its policy.

429

A rate or concurrency limit was reached.