Entwickler-API
Verwalte Projekte, Ziele, Prüfungen, Zeitpläne und eigene Anbieterzugangsdaten über REST oder MCP.
OpenAPI 3.1 JSON · Operationen · Fehler · MCP
Authentifizierung
Erstelle unter API und MCP mit deinem aktuellen Passwort ein befristetes Token. Einmal kopieren und geheim halten. Sende Authorization: Bearer TOKEN und Accept: application/json. Sitzungscookies authentifizieren diese API nicht. Widerruf gilt sofort. Konto muss aktiv und E-Mail bestätigt sein. Administrative Benutzerübernahme ist nicht verfügbar.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
Erfolgreiches JSON liegt in {"data": ...}. Sammlungen verwenden Laravel-Paginierung: data.data, data.current_page, data.last_page, data.total. page ≥ 1; per_page 1–100, Standard 25. Fremde Ressourcen liefern 404. Geheimnisse werden nur per Zugangsdaten-PUT angenommen und nie ausgegeben. Guthaben ist zwischengespeichert; Aktualisierung reiht eine begrenzte Hintergrundaufgabe ein.
Kostenpflichtige Prüfungen und Wiederholungen
Lauf- und Zeitplanerstellung verlangen confirm_paid: true und einen eindeutigen Idempotency-Key oder idempotency_key. Gleicher Schlüssel und Inhalt liefern die Antwort ohne neuen Lauf; veränderter Inhalt ergibt 409. Schlüssel bleiben bis zur Kontolöschung. Ziele und Einstellungen werden eingefroren. Anbieter können Gebühren verlangen; unsichere Anfragen erfordern retry_uncertain: true wegen möglicher doppelter Kosten.
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 ist paginiert; X-Total-Pages nennt die Seitenzahl. Lade alle Seiten. Formelähnliche Zellen werden maskiert. Datum: ISO 8601 UTC; Zeitpläne: explizite IANA-Zeitzone. Montag=1 bis Sonntag=7. Fehlende oder mehrdeutige Sommerzeit-Termine werden übersprungen; einmalige mehrdeutige Termine benötigen einen expliziten Offset.
Operationen
GET /api/v1/frequency — frequency.list
Berechtigung: frequency:read
POST /api/v1/frequency — frequency.create
Berechtigung: 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
Berechtigung: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Berechtigung: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Berechtigung: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Berechtigung: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Berechtigung: 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
Berechtigung: 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
Berechtigung: tokens:read
POST /api/v1/tokens — tokens.issue
Berechtigung:
{
"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
Berechtigung: tokens:write
GET /api/v1/admin/settings — admin.settings
Berechtigung: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Berechtigung: 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
Berechtigung: admin:read
GET /api/v1/admin/users/{user} — admin.user
Berechtigung: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Berechtigung: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Berechtigung: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Berechtigung: admin:read
GET /api/v1/runs/{run}/download — runs.download
Berechtigung: runs:read
GET /api/v1/account — account.show
Berechtigung: account:read
PATCH /api/v1/account — account.update
Berechtigung: 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
}Beispielinhalt:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Berechtigung: projects:read
POST /api/v1/projects — projects.create
Berechtigung: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Beispielinhalt:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Berechtigung: projects:read
PATCH /api/v1/projects/{project} — projects.update
Berechtigung: 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
Berechtigung: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Berechtigung: 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
Berechtigung: 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
Berechtigung: 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
Berechtigung: 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
Berechtigung: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Berechtigung: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Beispielinhalt:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Berechtigung: 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
Berechtigung: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Berechtigung: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Berechtigung: 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
}Beispielinhalt:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Berechtigung: 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
Berechtigung: projects:write
GET /api/v1/providers — providers.list
Berechtigung: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Berechtigung: 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."
}Beispielinhalt:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Berechtigung: providers:write
GET /api/v1/balances — balances.list
Berechtigung: providers:read
POST /api/v1/balances/refresh — balances.refresh
Berechtigung: providers:write
GET /api/v1/runs — runs.list
Berechtigung: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Berechtigung: 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
}Beispielinhalt:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Berechtigung: runs:read
GET /api/v1/runs/{run}/results — runs.results
Berechtigung: runs:read
GET /api/v1/runs/{run}/export — runs.export
Berechtigung: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Berechtigung: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Berechtigung: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Beispielinhalt:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Berechtigung: runs:write
GET /api/v1/schedules — schedules.list
Berechtigung: schedules:read
POST /api/v1/schedules — schedules.create
Berechtigung: 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
}Beispielinhalt:
{
"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
Berechtigung: schedules:read
POST /api/v1/schedules/once — schedules.once
Berechtigung: 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
}Beispielinhalt:
{
"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
Berechtigung: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Berechtigung: 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
Berechtigung: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Berechtigung: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Berechtigung: 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
Berechtigung: schedules:write
GET /api/v1/healthz — health.show
Berechtigung:
Fehler und Grenzen
401: Token fehlt, abgelaufen oder widerrufen. 403: Rechte fehlen oder Konto inaktiv/unbestätigt. 404: Ressource nicht verfügbar oder fremd. 409: Idempotenzkonflikt. 422: Ungültige Eingabe, errors je Feld. 429: Limit; Retry-After beachten. Bei verlorener Antwort kostenpflichtige Wiederholungen nie mit neuem Idempotenzschlüssel senden.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Verbinde /mcp per Streamable HTTP mit demselben Bearer-Token. Schemas: tools/list. Namen entsprechen den Operations-IDs; runs.start entspricht runs.create. Geheimnisse und Tokenverwaltung fehlen in MCP: Konto oder REST verwenden. Lese- und Schreibrechte sind unabhängig. Kostenpflichtige Erstellung erfordert Bestätigung und Idempotenz. Zugangsdaten werden nie ausgegeben. Schreibrechte nur bei Bedarf vergeben.
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"}}}'