# Справочник API

Базовый адрес всех вызовов: `https://api.justcode.lol/v1`

Шлюз терпим к форме пути: работают `/v1/messages`, `/messages` и даже
`/v1/v1/messages` — клиенты часто дописывают `/v1` сами.

## Аутентификация

Ключ передаётся любым из двух заголовков, оба принимаются на всех эндпоинтах:

```
x-api-key: ВАШ_КЛЮЧ
Authorization: Bearer ВАШ_КЛЮЧ
```

## POST /v1/messages

Anthropic Messages API. Основной путь для Claude Code и агентов на SDK
`anthropic`.

Параметры — как в оригинальном API: `model`, `messages`, `max_tokens`,
`system`, `temperature`, `stream`, `tools`, `tool_choice`, `thinking`,
`stop_sequences`. Поддерживаются блоки `tool_use` и `tool_result`, изображения,
и `cache_control` для кэша промпта.

```bash
curl https://api.justcode.lol/v1/messages \
  -H "x-api-key: $JUSTCODE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "system": "Отвечай кратко.",
    "messages": [{"role": "user", "content": "Что такое вектор?"}],
    "stream": true
  }'
```

При `"stream": true` ответ приходит событиями Server-Sent Events:
`message_start`, `content_block_start`, `content_block_delta`, `message_delta`,
`message_stop`, между ними — служебные `ping`.

## POST /v1/chat/completions

OpenAI Chat Completions API. Через него доступны **все** модели, включая Claude
и Gemini: шлюз переводит формат в обе стороны.

Параметры: `model`, `messages`, `max_tokens`, `temperature`, `top_p`, `stream`,
`tools`, `tool_choice`, `reasoning_effort`, `stop`.

```bash
curl https://api.justcode.lol/v1/chat/completions \
  -H "Authorization: Bearer $JUSTCODE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "system", "content": "Отвечай кратко."},
      {"role": "user", "content": "Что такое вектор?"}
    ],
    "stream": true
  }'
```

## POST /v1/responses

OpenAI Responses API — им ходит Codex CLI. Шлюз сам подставляет набор
инструментов, если клиент прислал пустой `tools`: без этого Codex не может
править файлы, потому что рассчитывает получить обвес от сервера.

## POST /v1/embeddings

Векторные представления, формат OpenAI.

```bash
curl https://api.justcode.lol/v1/embeddings \
  -H "Authorization: Bearer $JUSTCODE_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["первый текст", "второй текст"]
  }'
```

Ответ:

```json
{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.01, -0.03, "..."]}
  ],
  "model": "jc-embed-multilingual",
  "usage": {"prompt_tokens": 14, "total_tokens": 14}
}
```

Размерность вектора 384. Массивы токенов на входе не поддерживаются — передавайте
текст. За один запрос принимается до 256 текстов.

## GET /v1/models

Каталог доступных моделей с размерами окон.

```bash
curl https://api.justcode.lol/v1/models -H "Authorization: Bearer $JUSTCODE_KEY"
```

## POST /v1/messages/count_tokens

Оценка размера запроса до отправки. Считается локально и отвечает за
миллисекунды, деньги не списываются.

## Потоковая передача

Потоковый режим рекомендуется для любых длинных ответов. При выключенном
стриминге клиент ждёт весь ответ молча, и мобильные сети успевают разорвать
простаивающее соединение. Если видите обрывы на длинных ответах — включите
`stream`.