API для розробників
Керуйте проєктами, цілями, перевірками, розкладами й власними обліковими даними провайдерів через REST або MCP.
OpenAPI 3.1 JSON · Операції · Помилки · MCP
Автентифікація
Створіть токен зі строком дії в API & MCP, використовуючи поточний пароль. Скопіюйте токен один раз і тримайте його в таємниці. У кожному запиті надсилайте Authorization: Bearer TOKEN та Accept: application/json. Сеансові файли cookie не можуть автентифікувати це API. Відкликання діє негайно. Обліковий запис має бути активним, а пошта — підтвердженою. Вхід адміністратора від імені користувача через API недоступний.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
Успішні JSON-відповіді обгорнуто в {"data": ...}. Колекції використовують пагінацію Laravel усередині data: data.data, data.current_page, data.last_page, data.total. Задайте page ≥ 1 і per_page від 1 до 100 (типово 25). Ідентифікатори інших облікових записів повертають 404. Секрети приймає лише PUT облікових даних, і вони ніколи не повертаються. Баланси провайдерів кешуються; оновлення додає до черги обмежене фонове завдання.
Платні перевірки й повторні спроби
Створення запуску потребує confirm_paid: true та унікального заголовка Idempotency-Key або поля idempotency_key. Повторно використовуйте той самий ключ та ідентичне тіло, щоб відновити відповідь без нового запуску; змінені дані з тим самим ключем повертають 409. Ключі належать вашому обліковому запису й зберігаються до його видалення. Запуски фіксують цілі й налаштування. Запити провайдера можуть бути платними; відновлення невизначених надсилань потребує retry_uncertain: true як згоди з можливим повторним стягненням. Створення розкладу теж потребує confirm_paid: true та ключа ідемпотентності.
curl -X POST 'https://serpo.one/api/v1/projects/1/runs' \
-H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' \
-H 'Accept: application/json' -H 'Idempotency-Key: check-2026-11-20-001' \
-d '{"confirm_paid":true,"settings":{"depth":10}}'
Експорт CSV розбито на сторінки; X-Total-Pages указує їх кількість. Запитайте кожну сторінку для повного експорту. Комірки, схожі на формули, екрануються. Дати використовують ISO 8601 UTC; місцевий час розкладу — явно вказаний часовий пояс IANA. Дні ISO тривають від Monday=1 до Sunday=7. Відсутні чи неоднозначні повторювані часи DST пропускаються; неоднозначні одноразові розклади потребують явного зміщення.
Операції
GET /api/v1/frequency — frequency.list
Дозвіл: frequency:read
POST /api/v1/frequency — frequency.create
Дозвіл: frequency:write
{
"type": "object",
"properties": {
"queries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 400
},
"minItems": 1,
"maxItems": 1000
},
"project": {
"type": "integer",
"minimum": 1
},
"keyword_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 1000,
"uniqueItems": true
},
"provider": {
"enum": [
"xmlriver",
"xmlstock"
]
},
"modes": {
"type": "array",
"items": {
"enum": [
"broad",
"phrase",
"exact"
]
},
"minItems": 1,
"maxItems": 3,
"uniqueItems": true
},
"region": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 2147483647
},
"device": {
"enum": [
"all",
"desktop",
"phone",
"tablet"
]
},
"period": {
"enum": [
"month",
"week",
"day"
]
},
"start": {
"type": [
"string",
"null"
],
"format": "date"
},
"end": {
"type": [
"string",
"null"
],
"format": "date"
},
"threads": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"confirm_paid": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [
"modes",
"confirm_paid"
],
"additionalProperties": false
}GET /api/v1/frequency/{batch} — frequency.show
Дозвіл: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Дозвіл: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Дозвіл: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Дозвіл: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Дозвіл: frequency:write
{
"type": "object",
"properties": {
"confirm_paid": {
"type": "boolean",
"const": true
},
"retry_uncertain": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [
"confirm_paid"
],
"additionalProperties": false
}POST /api/v1/account/password — account.password
Дозвіл: account:write
{
"type": "object",
"properties": {
"current_password": {
"type": "string",
"maxLength": 72,
"writeOnly": true
},
"password": {
"type": "string",
"maxLength": 72,
"writeOnly": true,
"minLength": 12
},
"password_confirmation": {
"type": "string",
"maxLength": 72,
"writeOnly": true
},
"revoke_other_tokens": {
"type": "boolean",
"default": false
}
},
"required": [
"current_password",
"password",
"password_confirmation"
],
"additionalProperties": false
}GET /api/v1/tokens — tokens.list
Дозвіл: tokens:read
POST /api/v1/tokens — tokens.issue
Дозвіл:
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"password": {
"type": "string",
"maxLength": 72,
"writeOnly": true
},
"name": {
"type": "string",
"maxLength": 100
},
"abilities": {
"type": "array",
"items": {
"enum": [
"account:read",
"account:write",
"admin:read",
"admin:write",
"frequency:read",
"frequency:write",
"nullable|regex:/^[+-]\\d{2}:\\d{2}$/",
"nullable|string|max:2048",
"projects:read",
"projects:write",
"providers:read",
"providers:write",
"required|array|min:1|max:100",
"required|array|min:1|max:1000",
"required|array|min:1|max:20",
"required|integer|min:1|distinct",
"required|integer|min:1|max:365",
"required|string|max:100",
"required|string|max:30",
"required|string|max:400",
"runs:read",
"runs:write",
"schedules:read",
"schedules:write",
"sometimes|array|min:1|max:100",
"sometimes|integer|min:1|max:100",
"sometimes|integer|min:1|max:100000",
"sometimes|nullable|string|max:255",
"sometimes|required|string|max:120",
"tokens:read",
"tokens:write"
]
},
"minItems": 1,
"maxItems": 20,
"uniqueItems": true
},
"expires_in_days": {
"type": "integer",
"minimum": 1,
"maximum": 365
}
},
"required": [
"email",
"password",
"name",
"abilities",
"expires_in_days"
],
"additionalProperties": false
}DELETE /api/v1/tokens/{token} — tokens.revoke
Дозвіл: tokens:write
GET /api/v1/admin/settings — admin.settings
Дозвіл: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Дозвіл: admin:write
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"start": {
"type": "string",
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
},
"end": {
"type": "string",
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
}
},
"required": [],
"additionalProperties": false,
"minProperties": 1
}GET /api/v1/admin/users — admin.users
Дозвіл: admin:read
GET /api/v1/admin/users/{user} — admin.user
Дозвіл: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Дозвіл: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Дозвіл: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Дозвіл: admin:read
GET /api/v1/runs/{run}/download — runs.download
Дозвіл: runs:read
GET /api/v1/account — account.show
Дозвіл: account:read
PATCH /api/v1/account — account.update
Дозвіл: account:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"locale": {
"enum": [
"en",
"ru",
"kk",
"es",
"pt",
"de",
"fr",
"it",
"pl",
"tr",
"uk",
"zh",
"ja",
"ko",
"ar",
"hi",
"id",
"vi",
"th",
"nl",
"bn",
"ur",
"fa",
"cs"
]
},
"timezone": {
"type": "string",
"maxLength": 80
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [],
"additionalProperties": false
}Приклад тіла:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Дозвіл: projects:read
POST /api/v1/projects — projects.create
Дозвіл: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Приклад тіла:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Дозвіл: projects:read
PATCH /api/v1/projects/{project} — projects.update
Дозвіл: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [],
"additionalProperties": false
}DELETE /api/v1/projects/{project} — projects.delete
Дозвіл: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Дозвіл: projects:write
{
"type": "object",
"properties": {
"format": {
"enum": [
"txt",
"csv",
"json"
]
},
"mode": {
"enum": [
"append",
"replace"
]
},
"content": {
"type": "string",
"maxLength": 2000000
}
},
"required": [
"format",
"mode",
"content"
],
"additionalProperties": false
}POST /api/v1/projects/{project}/domains/bulk-delete — domains.bulk_delete
Дозвіл: projects:write
{
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 1000,
"uniqueItems": true
}
},
"required": [
"ids"
],
"additionalProperties": false
}POST /api/v1/projects/{project}/keywords/import — keywords.import
Дозвіл: projects:write
{
"type": "object",
"properties": {
"format": {
"enum": [
"txt",
"csv",
"json"
]
},
"mode": {
"enum": [
"append",
"replace"
]
},
"content": {
"type": "string",
"maxLength": 2000000
}
},
"required": [
"format",
"mode",
"content"
],
"additionalProperties": false
}POST /api/v1/projects/{project}/keywords/bulk-delete — keywords.bulk_delete
Дозвіл: projects:write
{
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 1000,
"uniqueItems": true
}
},
"required": [
"ids"
],
"additionalProperties": false
}GET /api/v1/projects/{project}/domains — domains.list
Дозвіл: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Дозвіл: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Приклад тіла:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Дозвіл: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}DELETE /api/v1/projects/{project}/domains/{item} — domains.delete
Дозвіл: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Дозвіл: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Дозвіл: projects:write
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 400
},
"domain": {
"type": [
"string",
"null"
],
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"query"
],
"additionalProperties": false
}Приклад тіла:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Дозвіл: projects:write
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 400
},
"domain": {
"type": [
"string",
"null"
],
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"query"
],
"additionalProperties": false
}DELETE /api/v1/projects/{project}/keywords/{item} — keywords.delete
Дозвіл: projects:write
GET /api/v1/providers — providers.list
Дозвіл: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Дозвіл: providers:write
{
"type": "object",
"properties": {
"provider_user": {
"type": "string",
"maxLength": 255,
"writeOnly": true
},
"api_key": {
"type": "string",
"maxLength": 2000,
"writeOnly": true
},
"frequency_api_key": {
"type": "string",
"maxLength": 2000,
"writeOnly": true,
"deprecated": true,
"description": "Deprecated compatibility alias for api_key for both providers; conflicting values return 422."
},
"balance_api_key": {
"type": "string",
"maxLength": 2000,
"writeOnly": true,
"deprecated": true,
"description": "Deprecated compatibility alias for api_key for both providers; conflicting values return 422; never returned."
}
},
"required": [],
"additionalProperties": false,
"description": "Both XMLRiver and XMLStock use one api_key for SERP, Wordstat and balance. Legacy frequency_api_key and balance_api_key are aliases only; conflicting values and masked placeholders return 422. Blank or omitted keys preserve the saved primary key. provider_user is required for first connection; blank or omitted provider_user preserves the saved ID. Masked IDs are rejected."
}Приклад тіла:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Дозвіл: providers:write
GET /api/v1/balances — balances.list
Дозвіл: providers:read
POST /api/v1/balances/refresh — balances.refresh
Дозвіл: providers:write
GET /api/v1/runs — runs.list
Дозвіл: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Дозвіл: runs:write
{
"type": "object",
"properties": {
"confirm_paid": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
},
"keyword_id": {
"type": "integer",
"minimum": 1
},
"domain_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
}
},
"required": [
"confirm_paid"
],
"additionalProperties": false
}Приклад тіла:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Дозвіл: runs:read
GET /api/v1/runs/{run}/results — runs.results
Дозвіл: runs:read
GET /api/v1/runs/{run}/export — runs.export
Дозвіл: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Дозвіл: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Дозвіл: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Приклад тіла:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Дозвіл: runs:write
GET /api/v1/schedules — schedules.list
Дозвіл: schedules:read
POST /api/v1/schedules — schedules.create
Дозвіл: schedules:write
{
"type": "object",
"properties": {
"project_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
},
"domain_ids": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
}
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
},
"frequency": {
"enum": [
"daily",
"weekly"
]
},
"weekdays": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"uniqueItems": true
},
"local_time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}$"
},
"timezone": {
"type": "string",
"maxLength": 80
},
"enabled": {
"type": "boolean"
},
"confirm_paid": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [
"project_ids",
"frequency",
"local_time",
"timezone",
"confirm_paid"
],
"additionalProperties": false
}Приклад тіла:
{
"idempotency_key": "schedule-001",
"project_ids": [
1
],
"frequency": "weekly",
"weekdays": [
1,
3,
5
],
"local_time": "09:00",
"timezone": "Europe/Moscow",
"enabled": true,
"confirm_paid": true
}GET /api/v1/schedules/once — schedules.once_list
Дозвіл: schedules:read
POST /api/v1/schedules/once — schedules.once
Дозвіл: schedules:write
{
"type": "object",
"properties": {
"project_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
},
"scheduled_for": {
"type": "string",
"maxLength": 30
},
"timezone": {
"type": "string",
"maxLength": 80
},
"offset": {
"type": "string",
"pattern": "^[+-]\\d{2}:\\d{2}$"
},
"confirm_paid": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [
"project_ids",
"scheduled_for",
"timezone",
"confirm_paid"
],
"additionalProperties": false
}Приклад тіла:
{
"idempotency_key": "once-001",
"project_ids": [
1
],
"scheduled_for": "2027-01-20T09:00",
"timezone": "Europe/Moscow",
"confirm_paid": true
}GET /api/v1/schedules/once/{schedule} — schedules.once_show
Дозвіл: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Дозвіл: schedules:write
{
"type": "object",
"properties": {
"scheduled_for": {
"type": "string",
"maxLength": 30
},
"timezone": {
"type": "string",
"maxLength": 80
},
"offset": {
"type": "string",
"pattern": "^[+-]\\d{2}:\\d{2}$"
}
},
"required": [
"scheduled_for",
"timezone"
],
"additionalProperties": false
}DELETE /api/v1/schedules/once/{schedule} — schedules.once_delete
Дозвіл: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Дозвіл: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Дозвіл: schedules:write
{
"type": "object",
"properties": {
"project_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
},
"domain_ids": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"minItems": 1,
"maxItems": 100,
"uniqueItems": true
}
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
},
"frequency": {
"enum": [
"daily",
"weekly"
]
},
"weekdays": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"uniqueItems": true
},
"local_time": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}$"
},
"timezone": {
"type": "string",
"maxLength": 80
},
"enabled": {
"type": "boolean"
},
"confirm_paid": {
"type": "boolean",
"const": true
},
"idempotency_key": {
"type": "string",
"maxLength": 100,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [],
"additionalProperties": false
}DELETE /api/v1/schedules/{schedule} — schedules.delete
Дозвіл: schedules:write
GET /api/v1/healthz — health.show
Дозвіл:
Помилки й обмеження
401: токен bearer відсутній, прострочений або відкликаний. 403: недостатньо дозволів або обліковий запис неактивний/непідтверджений. 404: ресурс недоступний, зокрема ресурс іншого облікового запису. 409: конфлікт ідемпотентності. 422: неправильні дані; errors індексується назвами полів. 429: перевищено ліміт запитів; дотримуйтеся Retry-After і збільшуйте паузу. Ніколи не використовуйте новий ключ ідемпотентності для платного повтору лише через втрату відповіді.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Підключайтеся до /mcp через Streamable HTTP з тим самим токеном Bearer. Точні схеми інструментів отримуйте через tools/list. Назви інструментів відповідають ідентифікаторам операцій вище, крім runs.start, що відповідає runs.create. Секрети провайдерів і керування токенами навмисно відсутні в MCP; використовуйте інтерфейс облікового запису або REST-ендпойнт облікових даних. Дозволи читання й запису незалежні. Платне створення потребує підтвердження й ключа ідемпотентності. Облікові дані провайдерів ніколи не повертаються. Надавайте запис лише коли клієнту MCP потрібно змінювати ваші дані.
curl -X POST 'https://serpo.one/mcp' \
-H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'