API dla programistów
Zarządzaj projektami, celami, sprawdzeniami, harmonogramami i własnymi danymi dostępowymi dostawców przez REST lub MCP.
OpenAPI 3.1 JSON · Operacje · Błędy · MCP
Uwierzytelnianie
Utwórz wygasający token w API & MCP, podając obecne hasło. Skopiuj token jednorazowo i zachowaj go w tajemnicy. W każdym zapytaniu wysyłaj Authorization: Bearer TOKEN oraz Accept: application/json. Pliki cookie sesji nie uwierzytelniają tego API. Unieważnienie działa natychmiast. Konto musi być aktywne, a e-mail zweryfikowany. Przejmowanie sesji przez administratora jest niedostępne przez API.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
Udane odpowiedzi JSON są opakowane w {"data": ...}. Kolekcje używają stronicowania Laravel wewnątrz data: data.data, data.current_page, data.last_page, data.total. Ustaw page ≥ 1 i per_page od 1 do 100 (domyślnie 25). Identyfikatory innych kont zwracają 404. Sekrety przyjmuje tylko PUT danych dostępowych i nigdy ich nie zwraca. Salda dostawców są buforowane; odświeżenie kolejkuje ograniczoną aktualizację w tle.
Płatne sprawdzenia i ponowienia
Utworzenie uruchomienia wymaga confirm_paid: true oraz unikalnego nagłówka Idempotency-Key lub pola idempotency_key. Użyj ponownie tego samego klucza i identycznej treści, aby odzyskać odpowiedź bez tworzenia kolejnego uruchomienia; zmienione dane z tym samym kluczem zwracają 409. Klucze należą do konta i są przechowywane do jego usunięcia. Uruchomienia utrwalają cele i ustawienia. Zapytania dostawcy mogą być płatne; wznowienie niepewnych wysłań wymaga retry_uncertain: true jako potwierdzenia możliwych podwójnych opłat. Utworzenie harmonogramu też wymaga confirm_paid: true i klucza idempotencji.
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}}'
Eksport CSV jest stronicowany; X-Total-Pages podaje liczbę stron. Pobierz każdą stronę, aby uzyskać pełny eksport. Komórki przypominające formuły są zabezpieczane. Daty używają ISO 8601 UTC; lokalne godziny harmonogramów — jawnej strefy IANA. Dni ISO biegną od Monday=1 do Sunday=7. Nieistniejące lub niejednoznaczne godziny cykliczne DST są pomijane; niejednoznaczne terminy jednorazowe wymagają jawnego przesunięcia.
Operacje
GET /api/v1/frequency — frequency.list
Uprawnienie: frequency:read
POST /api/v1/frequency — frequency.create
Uprawnienie: 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
Uprawnienie: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Uprawnienie: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Uprawnienie: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Uprawnienie: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Uprawnienie: 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
Uprawnienie: 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
Uprawnienie: tokens:read
POST /api/v1/tokens — tokens.issue
Uprawnienie:
{
"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
Uprawnienie: tokens:write
GET /api/v1/admin/settings — admin.settings
Uprawnienie: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Uprawnienie: 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
Uprawnienie: admin:read
GET /api/v1/admin/users/{user} — admin.user
Uprawnienie: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Uprawnienie: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Uprawnienie: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Uprawnienie: admin:read
GET /api/v1/runs/{run}/download — runs.download
Uprawnienie: runs:read
GET /api/v1/account — account.show
Uprawnienie: account:read
PATCH /api/v1/account — account.update
Uprawnienie: 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
}Przykładowa treść:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Uprawnienie: projects:read
POST /api/v1/projects — projects.create
Uprawnienie: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Przykładowa treść:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Uprawnienie: projects:read
PATCH /api/v1/projects/{project} — projects.update
Uprawnienie: 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
Uprawnienie: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Uprawnienie: 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
Uprawnienie: 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
Uprawnienie: 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
Uprawnienie: 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
Uprawnienie: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Uprawnienie: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Przykładowa treść:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Uprawnienie: 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
Uprawnienie: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Uprawnienie: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Uprawnienie: 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
}Przykładowa treść:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Uprawnienie: 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
Uprawnienie: projects:write
GET /api/v1/providers — providers.list
Uprawnienie: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Uprawnienie: 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."
}Przykładowa treść:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Uprawnienie: providers:write
GET /api/v1/balances — balances.list
Uprawnienie: providers:read
POST /api/v1/balances/refresh — balances.refresh
Uprawnienie: providers:write
GET /api/v1/runs — runs.list
Uprawnienie: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Uprawnienie: 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
}Przykładowa treść:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Uprawnienie: runs:read
GET /api/v1/runs/{run}/results — runs.results
Uprawnienie: runs:read
GET /api/v1/runs/{run}/export — runs.export
Uprawnienie: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Uprawnienie: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Uprawnienie: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Przykładowa treść:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Uprawnienie: runs:write
GET /api/v1/schedules — schedules.list
Uprawnienie: schedules:read
POST /api/v1/schedules — schedules.create
Uprawnienie: 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
}Przykładowa treść:
{
"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
Uprawnienie: schedules:read
POST /api/v1/schedules/once — schedules.once
Uprawnienie: 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
}Przykładowa treść:
{
"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
Uprawnienie: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Uprawnienie: 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
Uprawnienie: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Uprawnienie: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Uprawnienie: 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
Uprawnienie: schedules:write
GET /api/v1/healthz — health.show
Uprawnienie:
Błędy i limity
401: brak tokenu bearer, wygasł lub został unieważniony. 403: niewystarczające uprawnienia lub nieaktywne/niezweryfikowane konto. 404: zasób niedostępny, także zasób innego konta. 409: konflikt idempotencji. 422: nieprawidłowe dane; errors jest indeksowane nazwami pól. 429: przekroczono limit zapytań; stosuj Retry-After i wydłużaj odstępy. Nigdy nie używaj nowego klucza idempotencji do płatnego ponowienia tylko dlatego, że utracono odpowiedź.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Połącz się z /mcp przez Streamable HTTP, używając tego samego tokenu Bearer. Dokładne schematy narzędzi odczytaj przez tools/list. Nazwy narzędzi odpowiadają powyższym identyfikatorom operacji, z wyjątkiem runs.start, które odpowiada runs.create. Sekrety dostawców i zarządzanie tokenami celowo nie są dostępne w MCP; użyj interfejsu konta lub endpointu REST danych dostępowych. Uprawnienia odczytu i zapisu są niezależne. Płatne tworzenie wymaga potwierdzenia i klucza idempotencji. Dane dostępowe dostawców nigdy nie są zwracane. Przyznawaj zapis tylko wtedy, gdy klient MCP musi zmieniać Twoje dane.
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"}}}'