Справочник REST API
Read-only JSON API поверх живых данных о ценах. Базовый URL /api/v1. Работает без ключа на анонимном тире; бесплатный ключ pr_live_ поднимает лимиты.
Базовый URL и конвенции
Базовый URL: /api/v1 - все эндпоинты ниже отсчитываются от него. Ответы - application/json.
- Все цены - десятичные строки в USD за 1M токенов (единица usd_per_1m_tokens), никогда не float.
- ID моделей - стабильные слаги вида provider:model-slug - канонический id, который печатается на карточке модели, в CSV-дампе и во всех фидах (например openai:openai-gpt-5-mini). Собственный api id провайдера тоже резолвится (openai:gpt-5-mini), как и переименованные слаги, - через алиасы.
- Отдаются только опубликованные данные; каждая строка цены несёт last_verified_at и флаг is_stale.
- Каждый ответ - один и тот же конверт: {schema_version, as_of, data, pagination, truncated, hint}. as_of - время последней публикации конвейера, а не время HTTP-ответа.
- Пагинация - keyset через непрозрачный cursor; смена фильтров между страницами возвращает INVALID_CURSOR. Offset-пагинации нет.
- GET-ответы кэшируемы (данные меняются только при публикациях конвейера).
{
"schema_version": "1",
"as_of": "2026-07-06T10:33:11Z",
"data": { ... },
"pagination": {"count": 20, "total_count": 336, "has_more": true, "next_cursor": "eyJz..."},
"truncated": false,
"hint": "optional next-step suggestion"
}Эндпоинты
GET /api/v1/models
MCP-близнец: priceradar_list_models
Поиск и фильтрация моделей с текущими ценами API. С пагинацией, сортировка по выбранному ключу.
| Query-параметры | Тип | По умолчанию | Описание |
|---|---|---|---|
| query | string | - | Свободный поиск по именам, слагам и алиасам. |
| provider | string | - | Слаг провайдера (например openai). Неизвестные слаги возвращают подсказки did-you-mean. |
| modality | text | image | audio | video | - | Фильтр по входной модальности. |
| status | active | deprecated | retired | all | active | Фильтр по статусу жизненного цикла. |
| channel | official | openrouter | aws_bedrock | azure | vertex | together | fireworks | groq | novita | - | Фильтр по каналу цены. |
| min_context | int ≥ 1 | - | Минимальное контекстное окно, в токенах. |
| max_input_price | decimal string | - | Максимальная цена входа, USD за 1M токенов. |
| sort | price_input_asc | price_output_asc | price_blended_asc | context_desc | updated_desc | updated_desc | Ключ сортировки. Blended-цена = (3×вход + выход) / 4. |
| limit | int, 1-100 | 20 | Размер страницы. |
| cursor | string | - | Непрозрачный keyset-курсор из pagination.next_cursor предыдущей страницы. |
curl -s "https://techagent.net/api/v1/models?sort=price_blended_asc&min_context=200000&limit=10"
GET /api/v1/models/{model_id}
MCP-близнец: priceradar_get_model
Полная карточка одной модели по стабильному id provider:model-slug: текущие цены по каналам, контекстное окно, статус депрекации. Неизвестные id возвращают подсказки did-you-mean.
| Query-параметры | Тип | По умолчанию | Описание |
|---|---|---|---|
| include | CSV of pricing | deprecation | benchmarks | aliases | history_summary | - | Дополнительные секции ответа, через запятую. |
curl -s "https://techagent.net/api/v1/models/openai:gpt-5-mini?include=pricing,history_summary"
GET /api/v1/models/{model_id}/history
MCP-близнец: priceradar_price_history
Опубликованные события изменения цены одной модели за окно дат (максимум 365 дней на вызов).
| Query-параметры | Тип | По умолчанию | Описание |
|---|---|---|---|
| component | input | output | cached_input | all | all | Компонент цены. |
| channel | official | openrouter | aws_bedrock | azure | vertex | together | fireworks | groq | novita | - | Фильтр по каналу цены. |
| since | date (ISO 8601) | - | Начало окна. Окно since..until не может превышать 365 дней. |
| until | date (ISO 8601) | - | Конец окна (по умолчанию - сегодня). |
| granularity | changes | daily | changes | changes возвращает только сами события изменений; daily - ежедневный ряд цен. |
| limit | int, 1-100 | 50 | Размер страницы. |
| cursor | string | - | Непрозрачный keyset-курсор из pagination.next_cursor предыдущей страницы. |
curl -s "https://techagent.net/api/v1/models/openai:gpt-5-mini/history?component=input&since=2026-01-01"
GET /api/v1/compare
MCP-близнец: priceradar_compare
Сравнение 2-5 моделей бок о бок: цены, контекстное окно, балл бенчмарка и цена за балл.
| Query-параметры | Тип | По умолчанию | Описание |
|---|---|---|---|
| ids | CSV of 2-5 model ids | - | Модели для сравнения. При неизвестном id - ошибка с подсказками. |
| metrics | CSV of price_input | price_output | price_blended | context_window | benchmark_score | price_per_point | - | Какие метрики включить (по умолчанию все). |
| benchmark | string | aggregate | Бенчмарк для метрик на основе баллов. |
curl -s "https://techagent.net/api/v1/compare?ids=openai:gpt-5-mini,openai:gpt-5"
POST /api/v1/estimate
MCP-близнец: priceradar_estimate_cost
Оценка месячной стоимости токен-нагрузки в USD. Передайте пресет задачи или явные объёмы токенов на запрос; возвращается разбивка стоимости по моделям (10 самых дешёвых активных текстовых моделей, если model_ids не задан). Допущения возвращаются в ответе.
| JSON-тело | Тип | По умолчанию | Описание |
|---|---|---|---|
| requests_per_month | int ≥ 1 (required) | - | Объём нагрузки. |
| preset | chatbot | summarization | extraction | coding_agent | translation | rag_qa | classification | - | Пресет задачи с типовыми объёмами токенов; альтернатива явным объёмам. |
| input_tokens_per_request | int ≥ 1 | - | Явный объём входа на запрос. |
| output_tokens_per_request | int ≥ 1 | - | Явный объём выхода на запрос. |
| cache_hit_rate | float 0-1 | 0 | Доля входных токенов из кэша. |
| batch_share | float 0-1 | 0 | Доля трафика по batch-ценам. |
| model_ids | array, ≤ 10 ids | - | Модели, для которых считать оценку. |
curl -s -X POST "https://techagent.net/api/v1/estimate" -H "Content-Type: application/json" \
-d '{"requests_per_month": 100000, "preset": "chatbot", "model_ids": ["openai:gpt-5-mini"]}'GET /api/v1/changes
MCP-близнец: priceradar_recent_changes
Лента опубликованных ценовых и жизненных событий: снижения и повышения цен, депрекации, снятия, новые модели, изменения лимитов. Новые сверху - те же данные, что в публичных RSS/JSON-фидах изменений.
| Query-параметры | Тип | По умолчанию | Описание |
|---|---|---|---|
| since | date (ISO 8601) | - | Начало окна. Окно since..until не может превышать 365 дней. |
| until | date (ISO 8601) | - | Конец окна (по умолчанию - сегодня). |
| event_type | price_change | price_change_scheduled | deprecation | retirement | model_launch | limit_change | all | all | Фильтр по типу события. |
| provider | string | - | Фильтр по слагу провайдера. |
| min_significance | int 0-100 | 0 | Минимальный балл значимости. |
| limit | int, 1-100 | 20 | Размер страницы. |
| cursor | string | - | Непрозрачный keyset-курсор из pagination.next_cursor предыдущей страницы. |
curl -s "https://techagent.net/api/v1/changes?since=2026-06-01&min_significance=50"
GET /api/v1/health
Проба живости сервиса: без авторизации, не считается в квоты. Возвращает {status, db, as_of}; 503, когда база недоступна.
curl -s "https://techagent.net/api/v1/health"
Аутентификация
- Ключ не обязателен: без него запросы идут на анонимном тире (квота на IP).
- API-ключи выглядят как pr_live_… и передаются в заголовке X-API-Key, как Authorization: Bearer pr_live_… или запасным путём ?key= (query-форма попадает в access-логи - предпочитайте заголовки).
- Один ключ работает и для REST, и для MCP; квота общая на оба канала.
- Невалидный или истёкший ключ получает HTTP 401 (INVALID_API_KEY) на REST; на MCP запрос молча падает на анонимный тир.
Лимиты и квоты
Каждый ответ /api/v1 (кроме /health) несёт заголовки лимитов, перечисленные ниже. Квоты общие для REST и MCP.
| Заголовок | Значение |
|---|---|
| X-RateLimit-Limit | Квота вашего тира на текущее окно (запросов). |
| X-RateLimit-Remaining | Сколько запросов осталось в текущем окне. |
| X-RateLimit-Reset | Unix-время (секунды), когда квота восстановится полностью. |
| Retry-After | Только при 429: сколько секунд подождать до следующего запроса. |
| Тир | Ключ | Квота | Частота |
|---|---|---|---|
| Анонимный | ключ не нужен | 60 req/hour per IP | 2 req/s |
| Бесплатный ключ | pr_live_ (бесплатно, по запросу) | 1,000 req/day | 5 req/s |
Ошибки
Ошибки действенные: HTTP-статус + машиночитаемый объект error {code, message, next_step}.
| Код | HTTP | Когда | Подсказка |
|---|---|---|---|
| MODEL_NOT_FOUND | 404 | model_id не резолвится ни слагом, ни алиасами | Ответ содержит подсказки did_you_mean; валидные id - через /api/v1/models?query=… |
| PROVIDER_NOT_FOUND | 404 | Неизвестный слаг провайдера | Ответ содержит did_you_mean; уберите provider, чтобы увидеть валидные слаги. |
| NO_PRICE_DATA | 404 | Модель есть, но нет строк цены для запрошенного канала/тира | Проверьте карточку модели; попробуйте channel=official. |
| INVALID_CURSOR | 400 | Курсор повреждён или фильтры сменились между страницами | Начните листинг заново, без курсора. |
| WINDOW_TOO_LARGE | 400 | Окно since..until превышает 365 дней | Разбейте запрос на окна не длиннее 365 дней. |
| INVALID_ARGUMENT | 400 | Значение вне enum или диапазона | Сообщение называет параметр и допустимые значения. |
| INVALID_API_KEY | 401 | Ключ передан, но неизвестен или истёк (только REST) | Запросите новый бесплатный ключ или уберите ключ - анонимный тир работает без него. |
| RATE_LIMITED | 429 | Превышена квота тира или мгновенная частота | Подождите Retry-After секунд; бесплатный ключ поднимает лимит. |
OpenAPI
Машиночитаемая спека OpenAPI 3 генерируется автоматически и доступна на /api/v1/openapi.json.