# Prism by Ssimplifi — Full API Documentation

> Prism is an AI API proxy that routes queries to the optimal model across Anthropic, OpenAI, and Google. OpenAI-compatible. Adds intelligent classification, session memory, automatic failover, and a quality floor across three quality modes (Eco / Balanced / Sport).

- Production API base URL: `https://api.ssimplifi.com`
- Dashboard: `https://ssimplifi.com`
- Auth: API key in `Authorization: Bearer prism_sk_...` header

---

## Why Prism

Developers calling Anthropic, OpenAI, or Google directly have to:
- Pick a model up front (and overpay when the task is simple)
- Build their own session memory
- Build their own failover when a provider is down
- Track costs across three dashboards

Prism solves this with one OpenAI-compatible endpoint. You send a quality mode (eco, balanced, sport); Prism classifies the query, routes to the optimal model, manages session memory in Redis, and falls back to another provider if the primary is down.

---

## Authentication

All API calls require an API key. Format: `prism_sk_` followed by 32 hex characters. Stored hashed (SHA-256). Shown only once on creation.

```
Authorization: Bearer prism_sk_<your_key>
```

Create keys in the dashboard at `https://ssimplifi.com/dashboard/settings`.

---

## Quality Modes

Send the mode via the `X-Prism-Mode` header. Required on every request.

| Mode | Markup | Use case |
|------|--------|----------|
| `eco` | 15% | Cost-optimized, still maintains quality floor for complex tasks |
| `balanced` | 20% | Good default for production apps |
| `sport` | 30% | Best quality, routes complex tasks to top models |

### Routing table

| Task type | Eco | Balanced | Sport |
|-----------|-----|----------|-------|
| simple | gemini-flash | claude-haiku | claude-sonnet |
| code | claude-haiku | claude-sonnet | claude-sonnet |
| reasoning | claude-haiku | claude-sonnet | claude-opus |
| complex | claude-sonnet | claude-sonnet | claude-opus |

Classification is rule-based (code blocks, reasoning keywords, token length). No AI call is made for classification, so it adds zero latency.

---

## Endpoint: POST /v1/chat/completions

OpenAI-compatible. Drop-in replacement — point your existing OpenAI SDK at `https://api.ssimplifi.com/v1` and set the API key to a Prism key.

### Request headers

- `Authorization: Bearer prism_sk_...` (required)
- `X-Prism-Mode: eco | balanced | sport` (required)
- `X-Prism-Session: <session_id>` (optional — enables session memory)
- `Content-Type: application/json`

### Request body parameters

- `messages` (array, required): OpenAI-format messages with `role` (`system`, `user`, `assistant`) and `content`.
- `max_tokens` (integer, optional): Max output tokens. Free tier capped at 4096.
- `temperature` (number, optional): 0–2, default 1.
- `stream` (boolean, optional): If true, response is SSE stream of OpenAI-format deltas. Paid tier only.
- `top_p`, `frequency_penalty`, `presence_penalty`, `stop`: Passed through to provider.

### Response (non-streaming)

OpenAI-format `chat.completion` object with the actual model used (e.g. `claude-sonnet-4-5`).

### Response headers

- `X-Prism-Model`: Actual model used
- `X-Prism-Cost`: Cost in USD cents (with markup)
- `X-Prism-Tokens-In`: Input tokens
- `X-Prism-Tokens-Out`: Output tokens
- `X-Prism-Task-Type`: Classified task type (`simple`, `code`, `reasoning`, `complex`)
- `X-Prism-Failover`: `true` if a fallback provider was used
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

### curl example

```bash
curl https://api.ssimplifi.com/v1/chat/completions \
  -H "Authorization: Bearer prism_sk_..." \
  -H "X-Prism-Mode: balanced" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain quicksort in 2 sentences"}
    ],
    "max_tokens": 200
  }'
```

### Python (OpenAI SDK)

```python
from openai import OpenAI

client = OpenAI(
    api_key="prism_sk_...",
    base_url="https://api.ssimplifi.com/v1",
)

response = client.chat.completions.create(
    model="prism",  # ignored — Prism picks the model
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "X-Prism-Mode": "balanced",
        "X-Prism-Session": "user_42_chat_1",
    },
)
print(response.choices[0].message.content)
```

### Streaming

Set `stream: true`. Response is SSE with OpenAI-format `chat.completion.chunk` events terminated by `data: [DONE]`. Paid tier only.

---

## Session Memory

Prism manages conversation memory server-side in Redis. Pass any string as `X-Prism-Session`. Prism stores the message history under that ID and automatically prepends it on subsequent calls.

- TTL: 30 minutes, refreshed on each access
- Free tier: 5 messages per session
- Paid tier: 100 messages per session
- Auto-summarization at 90 messages on paid tier
- System messages persist across the session

You no longer need to send the entire history with each request. Just send the new user message and the same session ID.

### Session endpoints

- `GET /v1/sessions/{id}` — fetch current session messages and metadata
- `DELETE /v1/sessions/{id}` — clear a session

---

## Billing endpoints

- `GET /v1/balance` — current USD balance and tier
- `GET /v1/usage` — usage logs (date range, mode, task type filters)
- `GET /v1/usage/export` — CSV export of usage logs

---

## API key endpoints

- `POST /v1/keys` — create a new key (returned in plaintext once)
- `GET /v1/keys` — list keys (hashes only)
- `DELETE /v1/keys/{id}` — revoke a key

---

## Free tier

- 50,000 input tokens / day
- 10,000 output tokens / day
- Eco mode only
- No streaming
- 5 messages per session
- 4096 max_tokens per request
- 1 API key max

No credit card required. Auto-upgraded to paid on first Razorpay top-up ($5 minimum).

## Paid tier

Unlocked on first successful payment. Unlimited keys, all modes, streaming, no daily token limits, 100 messages per session, low-balance email warnings.

---

## Error responses

All errors return JSON in this shape:

```json
{ "error": { "type": "invalid_api_key", "message": "Invalid API key" } }
```

Error types:
- `invalid_api_key`
- `missing_mode_header`
- `insufficient_balance`
- `free_tier_limit`
- `rate_limited`
- `provider_error`
- `invalid_request`
- `not_found`

---

## Failover

If the primary provider returns a 5xx, times out, or rate-limits, Prism automatically retries on a fallback provider of equivalent or higher capability and sets `X-Prism-Failover: true` on the response. Your request still succeeds.

---

## Pricing

You pay provider list price plus a small markup based on the mode:
- Eco: 15%
- Balanced: 20%
- Sport: 30%

There is no monthly fee, no per-seat charge, and no minimum commitment beyond the $5 first top-up.

---

## Links

- API docs (HTML): https://ssimplifi.com/docs
- Sign up: https://ssimplifi.com/signup
- Blog — How I Cut My AI API Costs by 40%: https://ssimplifi.com/blog/cut-ai-api-costs-40-percent
- Privacy: https://ssimplifi.com/privacy
- Terms: https://ssimplifi.com/terms