Serpo.one

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"}}}'