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)。其他账户的 ID 返回 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 星期编号从 Monday=1 到 Sunday=7。夏令时导致不存在或有歧义的重复时间将跳过;有歧义的一次性计划需明确指定时差。

操作

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 获取准确的工具结构。工具名遵循上方操作 ID,但 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"}}}'