# samreshuuu API

Integrate AI capabilities into your product: text generation, agents, document processing, and task automation.

## Getting Started

### Install dependencies

```bash
# No SDK required — the API is plain HTTP + Server-Sent Events.
# Python: pip install requests
# Node.js: built-in fetch (Node 18+)
```

### Set environment variables

```bash
export SAMRESHUUU_API_KEY="sk-org-your_api_key"
export SAMRESHUUU_BASE_URL="https://samreshuuu.ru/api/v1"
```

### Spawn a turn

`POST /sessions/stream` starts the turn and returns `202` with its identifiers — it does not stream. Use the returned `session_id` and `message_id` to subscribe in the next step.

**Python**

```python
import requests, os

API_KEY = os.environ["SAMRESHUUU_API_KEY"]
BASE = os.environ["SAMRESHUUU_BASE_URL"]
headers = {"Authorization": f"Bearer {API_KEY}"}

spawn = requests.post(
    f"{BASE}/sessions/stream",
    headers=headers,
    json={"message": "Summarize the key points of this contract"},
).json()
session_id, message_id = spawn["session_id"], spawn["message_id"]
```

**Node.js**

```typescript
const API_KEY = process.env.SAMRESHUUU_API_KEY;
const BASE = process.env.SAMRESHUUU_BASE_URL;
const headers = { Authorization: `Bearer ${API_KEY}` };

const spawn = await fetch(`${BASE}/sessions/stream`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Summarize the key points of this contract" }),
}).then((r) => r.json());
const { session_id, message_id } = spawn;
```

**cURL**

```bash
curl -X POST "$SAMRESHUUU_BASE_URL/sessions/stream" \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the key points of this contract" }'
# → { "session_id": "ses_abc123", "message_id": "msg_def456", "kind": "new_turn" }
```

### Stream the events

Subscribe to the turn's durable event log over SSE. Each frame is a `data:` line with a JSON `type`. See [Streaming (SSE)](/docs/streaming) for the full event taxonomy and resume semantics.

**Python**

```python
with requests.get(
    f"{BASE}/sessions/{session_id}/messages/{message_id}/stream",
    headers=headers,
    stream=True,
) as resp:
    for line in resp.iter_lines():
        if line:
            print(line.decode())
```

**cURL**

```bash
curl -N "$SAMRESHUUU_BASE_URL/sessions/$SESSION_ID/messages/$MESSAGE_ID/stream" \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY"
```

```json
data: {"type": "start", "session_id": "ses_abc123"}

data: {"type": "delta", "content": "Here are the key points of the contract:\n\n"}

data: {"type": "delta", "content": "1. **Term**: 24 months starting March 2026\n"}

data: {"type": "complete", "session_id": "ses_abc123", "final_response": "Here are the key points...", "total_input_tokens": 150, "total_output_tokens": 89}
```

## Supported Models

samreshuuu provides access to leading models for different use cases. The authoritative, always-current catalogue — with availability and pricing — is returned by the `GET /api/v1/models` endpoint.

| Model | ID | Notes |
| --- | --- | --- |
| DeepSeek V4 Flash | `deepseek` | Platform default |
| MiniMax M3 | `minimax` | |
| NVIDIA Nemotron 3 Super | `nvidia` | |
| NVIDIA Nemotron 3 Ultra | `nvidia_ultra` | |
| Sber GigaChat 2 | `gigachat` | |
| YandexGPT | `yandexgpt` | |

[View all models and pricing →](/docs/reference)

**Quick Links**

- [Authentication — Bearer tokens and organization context](/docs/authentication)
- [Agents — create agents, attach connectors, grant credentials](/docs/agents)
- [Errors & Rate Limits — error envelope, HTTP codes, retry logic](/docs/reference)

## FAQ

### Do I need an SDK to use the samreshuuu API?

No. The API is plain HTTP plus Server-Sent Events. In Python you can use `requests`; in Node.js 18+ the built-in `fetch` works. An OpenAI-compatible endpoint is also available if you prefer the OpenAI SDK.

### How do I start a turn and read the response?

`POST /api/v1/sessions/stream` spawns the turn and returns `202` with a `session_id` and `message_id` — it does not stream. Subscribe to `GET /sessions/{session_id}/messages/{message_id}/stream` over SSE to read the events.

### Which models are available?

DeepSeek V4 Flash (the platform default), MiniMax M3, NVIDIA Nemotron 3 Super and Ultra, Sber GigaChat 2, and YandexGPT. The always-current list with availability and pricing is returned by `GET /api/v1/models`.

### How is the base URL structured?

The native API lives under `https://samreshuuu.ru/api/v1`. The OpenAI-compatible endpoint uses `https://samreshuuu.ru/v1`.