API nhà phát triển
Quản lý dự án, mục tiêu, kiểm tra, lịch và thông tin xác thực nhà cung cấp qua REST hoặc MCP.
OpenAPI 3.1 JSON · Thao tác · Lỗi · MCP
Xác thực
Tạo token có thời hạn trong API và MCP bằng mật khẩu hiện tại. Sao chép một lần và giữ bí mật. Gửi Authorization: Bearer TOKEN và Accept: application/json trong mỗi yêu cầu. Cookie phiên không xác thực được API này. Thu hồi có hiệu lực ngay. Tài khoản phải hoạt động và email đã xác minh. Không thể truy cập dưới danh nghĩa người dùng bằng quyền quản trị qua API.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
JSON thành công được bọc trong {"data": ...}. Tập hợp dùng phân trang Laravel trong data: data.data, data.current_page, data.last_page, data.total. Đặt page ≥ 1 và per_page từ 1 đến 100 (mặc định 25). ID thuộc tài khoản khác trả về 404. Bí mật chỉ được nhận qua PUT thông tin xác thực và không bao giờ trả lại. Số dư được lưu đệm; làm mới xếp hàng một tác vụ nền có giới hạn.
Kiểm tra trả phí và thử lại
Tạo lượt chạy cần confirm_paid: true và tiêu đề Idempotency-Key duy nhất hoặc trường idempotency_key. Dùng lại cùng khóa và nội dung giống hệt để lấy lại phản hồi mà không tạo lượt chạy khác; đổi nội dung với cùng khóa trả về 409. Khóa thuộc tài khoản và được giữ đến khi xóa tài khoản. Mục tiêu và cài đặt được cố định. Nhà cung cấp có thể tính phí; tiếp tục yêu cầu chưa chắc chắn cần retry_uncertain: true để chấp nhận khả năng bị tính phí hai lần. Tạo lịch cũng cần confirm_paid: true và khóa chống lặp.
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}}'
Xuất CSV có phân trang; X-Total-Pages cho biết số trang. Yêu cầu từng trang để xuất đầy đủ. Ô giống công thức được xử lý thoát. Ngày dùng ISO 8601 UTC; giờ địa phương của lịch dùng múi giờ IANA rõ ràng. Ngày ISO từ Thứ Hai=1 đến Chủ Nhật=7. Thời điểm lặp không tồn tại hoặc không rõ ràng do đổi giờ mùa hè bị bỏ qua; lịch một lần không rõ ràng cần độ lệch giờ cụ thể.
Thao tác
GET /api/v1/frequency — frequency.list
Quyền: frequency:read
POST /api/v1/frequency — frequency.create
Quyền: 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
Quyền: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Quyền: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Quyền: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Quyền: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Quyền: 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
Quyền: 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
Quyền: tokens:read
POST /api/v1/tokens — tokens.issue
Quyền:
{
"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
Quyền: tokens:write
GET /api/v1/admin/settings — admin.settings
Quyền: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Quyền: 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
Quyền: admin:read
GET /api/v1/admin/users/{user} — admin.user
Quyền: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Quyền: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Quyền: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Quyền: admin:read
GET /api/v1/runs/{run}/download — runs.download
Quyền: runs:read
GET /api/v1/account — account.show
Quyền: account:read
PATCH /api/v1/account — account.update
Quyền: 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
}Ví dụ nội dung yêu cầu:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Quyền: projects:read
POST /api/v1/projects — projects.create
Quyền: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Ví dụ nội dung yêu cầu:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Quyền: projects:read
PATCH /api/v1/projects/{project} — projects.update
Quyền: 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
Quyền: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Quyền: 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
Quyền: 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
Quyền: 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
Quyền: 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
Quyền: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Quyền: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Ví dụ nội dung yêu cầu:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Quyền: 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
Quyền: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Quyền: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Quyền: 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
}Ví dụ nội dung yêu cầu:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Quyền: 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
Quyền: projects:write
GET /api/v1/providers — providers.list
Quyền: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Quyền: 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."
}Ví dụ nội dung yêu cầu:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Quyền: providers:write
GET /api/v1/balances — balances.list
Quyền: providers:read
POST /api/v1/balances/refresh — balances.refresh
Quyền: providers:write
GET /api/v1/runs — runs.list
Quyền: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Quyền: 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
}Ví dụ nội dung yêu cầu:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Quyền: runs:read
GET /api/v1/runs/{run}/results — runs.results
Quyền: runs:read
GET /api/v1/runs/{run}/export — runs.export
Quyền: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Quyền: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Quyền: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Ví dụ nội dung yêu cầu:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Quyền: runs:write
GET /api/v1/schedules — schedules.list
Quyền: schedules:read
POST /api/v1/schedules — schedules.create
Quyền: 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
}Ví dụ nội dung yêu cầu:
{
"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
Quyền: schedules:read
POST /api/v1/schedules/once — schedules.once
Quyền: 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
}Ví dụ nội dung yêu cầu:
{
"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
Quyền: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Quyền: 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
Quyền: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Quyền: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Quyền: 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
Quyền: schedules:write
GET /api/v1/healthz — health.show
Quyền:
Lỗi và giới hạn
401: thiếu token Bearer, token hết hạn hoặc đã thu hồi. 403: thiếu quyền hoặc tài khoản không hoạt động/chưa xác minh. 404: tài nguyên không có sẵn, kể cả tài nguyên tài khoản khác. 409: xung đột chống lặp. 422: dữ liệu không hợp lệ; errors theo từng trường. 429: vượt giới hạn yêu cầu; tuân thủ Retry-After và tăng thời gian chờ. Không dùng khóa chống lặp mới cho lần thử trả phí chỉ vì mất phản hồi.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Kết nối /mcp qua Streamable HTTP với cùng token Bearer. Xem lược đồ công cụ chính xác qua tools/list. Tên công cụ theo ID thao tác phía trên, riêng runs.start tương ứng runs.create. Bí mật nhà cung cấp và quản lý token không có trong MCP; dùng giao diện tài khoản hoặc điểm cuối REST thông tin xác thực. Quyền đọc và ghi độc lập. Tạo thao tác trả phí cần xác nhận và khóa chống lặp. Thông tin xác thực không bao giờ được trả lại. Chỉ cấp quyền ghi khi ứng dụng khách MCP cần đổi dữ liệu.
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"}}}'