# SuperJob API: Найти вакансии по запросу

Сценарий из mcp-everything. Актуально на 2026-10-24.

Поиск вакансий SuperJob для своего сайта, бота или агрегатора.

1. Зарегистрируй приложение на api.superjob.ru и передавай секретный ключ в заголовке X-Api-App-Id в каждом запросе.
2. Ищи: GET /2.0/vacancies/ с keyword, town (название или ID города), payment_from, no_agreement = 1 (скрыть «по договорённости»), period, count (до 100) и page.
3. В ответе objects, total и more — признак следующей страницы. При опечатке в запросе придёт corrected_keyword.
4. Всего через API доступно не больше 500 записей выдачи (page × count) — сужай фильтры, если нужно больше. Лимит — 120 запросов в минуту с одного IP.
5. Контакты работодателя в вакансиях приходят только с авторизацией пользователя.

```bash
curl -G https://api.superjob.ru/2.0/vacancies/ \
  -H "X-Api-App-Id: $SJ_APP_KEY" \
  --data-urlencode 'keyword=бухгалтер' \
  --data-urlencode 'town=Москва' \
  -d payment_from=80000 -d no_agreement=1 -d count=50 -d page=0
```

## Базовые URL

- Боевой: `https://api.superjob.ru`
- Формат: `https://api.superjob.ru/:version/method_name/:params`

## Авторизация

Тип: OAuth 2.0

- Секретный ключ приложения передаётся в каждом запросе в заголовке `X-Api-App-Id`.
- Для методов с авторизацией — `Authorization: Bearer <access_token>`.
- Авторизация пользователя: `GET https://www.superjob.ru/authorize/` (`client_id`, `redirect_uri`, `state`) → код → `https://api.superjob.ru/2.0/oauth2/access_token/` (`code`, `client_id`, `client_secret`, `redirect_uri`).
- Обновление: `GET https://api.superjob.ru/2.0/oauth2/refresh_token/` (`refresh_token`, `client_id`, `client_secret`).
- Для desktop-приложений — вход по паролю `POST /2.0/oauth2/password/`.

## Методы сценария

### GET /2.0/vacancies/ — Поиск вакансий

Также поддерживается POST. Контакты в вакансиях — только с авторизацией. В ответе: `objects`, `total`, `more`, при опечатке — `corrected_keyword`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `X-Api-App-Id` | header | string | да | Секретный ключ приложения |
| `keyword` | query | string | нет | Поиск по всему тексту вакансии |
| `keywords` | query | array | нет | Расширенный поиск: блок, тип совпадения, исключаемые слова |
| `town` | query | string | нет | Город (название или ID) |
| `t` | query | array | нет | ID городов |
| `o` | query | array | нет | ID областей |
| `c` | query | array | нет | ID стран |
| `m` | query | array | нет | ID станций метро |
| `catalogues` | query | string | нет | Отрасли (ключи из справочника каталогов) |
| `payment_from` | query | integer | нет | Зарплата от |
| `payment_to` | query | integer | нет | Зарплата до |
| `no_agreement` | query | integer | нет | 1 — скрыть вакансии «по договорённости» |
| `experience` | query | integer | нет | Опыт работы |
| `type_of_work` | query | integer | нет | Тип занятости |
| `place_of_work` | query | integer | нет | Место работы |
| `education` | query | integer | нет | Образование |
| `period` | query | integer | нет | Период публикации: 24 часа, 3 дня, неделя или всё время |
| `order_field` | query | string | нет | date или payment |
| `order_direction` | query | string | нет | asc или desc (по умолчанию) |
| `page` | query | integer | нет | 0–500, по умолчанию 0 |
| `count` | query | integer | нет | 1–100, по умолчанию 20 |

## Нюансы

- Через API можно получить не больше 500 записей выдачи (`page` × `count`).
- В поиске вакансий массив `ids` — не больше 500 ID.
- Параметры `published`, `published_all`, `archive`, `not_archive` работают только при авторизации работодателя при поиске своих вакансий.
- Ошибки авторизации дополнительно возвращают машиночитаемый `error` (например, `invalid_token`) и заголовок `X-Oauth-Error`.
- Документация помечена как актуальная для версии 2.20; свежая версия — `https://api.superjob.ru/doc/`.

## Другие сценарии

- [Найти компанию работодателя](https://mcp-everything.ru/integrations/superjob/scenarios/nayti-kompaniyu-rabotodatelya.md)
- [Авторизовать пользователя и показать контакты вакансии](https://mcp-everything.ru/integrations/superjob/scenarios/avtorizovat-polzovatelya-i-pokazat.md)

---

Если этого недостаточно — официальная документация: https://api.superjob.ru/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/superjob.md