Serpo.one

Әзірлеушілерге арналған 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"}}}'