Developer API
Manage projects, targets, checks, schedules and your own provider credentials over REST or MCP.
OpenAPI 3.1 JSON · Operations · Errors · MCP
Authentication
Create an expiring token in API & MCP using your current password. Copy the token once and keep it secret. Send Authorization: Bearer TOKEN and Accept: application/json on every request. Session cookies cannot authenticate this API. Revocation takes effect immediately. Your account must be active and its email verified. Administrator impersonation is unavailable through the API.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
Successful JSON is wrapped in {"data": ...}. Collections use Laravel pagination inside data: data.data, data.current_page, data.last_page, data.total. Set page ≥ 1 and per_page from 1 to 100 (default 25). Other accounts’ IDs return 404. Secrets are accepted only by credential PUT and never returned. Provider balances are cached; refresh queues a bounded background update.
Paid checks and retries
Run creation requires confirm_paid: true and a unique Idempotency-Key header or idempotency_key field. Reuse the same key and identical body to recover a response without creating another run; changed input with the same key returns 409. Keys belong to your account and are retained until account deletion. Runs freeze targets and settings. Provider requests may incur charges; resuming uncertain submissions requires retry_uncertain: true to acknowledge possible duplicate charges. Schedule creation also requires confirm_paid: true and an idempotency key.
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 export is paginated; X-Total-Pages gives the page count. Request every page for a complete export. Formula-like cells are escaped. Dates use ISO 8601 UTC; schedule wall times use the explicit IANA timezone. ISO weekdays run from Monday=1 through Sunday=7. Missing or ambiguous DST recurrence times are skipped; ambiguous one-time schedules require an explicit offset.
Operations
GET /api/v1/frequency — frequency.list
Permission: frequency:read
POST /api/v1/frequency — frequency.create
Permission: 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
Permission: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Permission: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Permission: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Permission: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Permission: 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
Permission: 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
Permission: tokens:read
POST /api/v1/tokens — tokens.issue
Permission:
{
"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
Permission: tokens:write
GET /api/v1/admin/settings — admin.settings
Permission: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Permission: 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
Permission: admin:read
GET /api/v1/admin/users/{user} — admin.user
Permission: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Permission: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Permission: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Permission: admin:read
GET /api/v1/runs/{run}/download — runs.download
Permission: runs:read
GET /api/v1/account — account.show
Permission: account:read
PATCH /api/v1/account — account.update
Permission: 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
}Example body:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Permission: projects:read
POST /api/v1/projects — projects.create
Permission: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Example body:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Permission: projects:read
PATCH /api/v1/projects/{project} — projects.update
Permission: 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
Permission: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Permission: 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
Permission: 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
Permission: 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
Permission: 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
Permission: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Permission: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Example body:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Permission: 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
Permission: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Permission: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Permission: 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
}Example body:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Permission: 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
Permission: projects:write
GET /api/v1/providers — providers.list
Permission: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Permission: 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."
}Example body:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Permission: providers:write
GET /api/v1/balances — balances.list
Permission: providers:read
POST /api/v1/balances/refresh — balances.refresh
Permission: providers:write
GET /api/v1/runs — runs.list
Permission: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Permission: 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
}Example body:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Permission: runs:read
GET /api/v1/runs/{run}/results — runs.results
Permission: runs:read
GET /api/v1/runs/{run}/export — runs.export
Permission: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Permission: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Permission: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Example body:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Permission: runs:write
GET /api/v1/schedules — schedules.list
Permission: schedules:read
POST /api/v1/schedules — schedules.create
Permission: 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
}Example body:
{
"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
Permission: schedules:read
POST /api/v1/schedules/once — schedules.once
Permission: 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
}Example body:
{
"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
Permission: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Permission: 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
Permission: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Permission: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Permission: 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
Permission: schedules:write
GET /api/v1/healthz — health.show
Permission:
Errors and limits
401: missing, expired or revoked bearer token. 403: insufficient permissions or inactive/unverified account. 404: unavailable resource, including another account’s resource. 409: idempotency conflict. 422: invalid input; errors is keyed by field. 429: request limit exceeded; follow Retry-After and back off. Never use a new idempotency key for a paid retry just because a response was lost.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Connect to /mcp using Streamable HTTP with the same Bearer token. Discover exact tool schemas through tools/list. Tool names follow the operation IDs above, except runs.start corresponds to runs.create. Provider secrets and token administration are intentionally absent from MCP; use the account interface or credential REST endpoint. Read and write permissions are independent. Paid creation requires confirmation and an idempotency key. Provider credentials are never returned. Grant write permissions only when the MCP client needs to change your data.
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"}}}'