Әзірлеушілерге арналған 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": ...} түрінде беріледі. Жинақтар data ішінде Laravel беттеуін пайдаланады: 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 апта күндері: дүйсенбі=1, жексенбі=7. Сағат ауысқан кездегі жоқ немесе екіұшты қайталану уақыты өткізіледі; бір реттік кестедегі екіұшты уақыт үшін нақты offset қажет.
Операциялар
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
Сол Bearer токенімен Streamable HTTP арқылы /mcp мекенжайына қосылыңыз. Құралдардың нақты схемаларын 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"}}}'