API توسعهدهندگان
پروژهها، هدفها، بررسیها، برنامهها و اطلاعات احراز هویت خود را با REST یا MCP مدیریت کنید.
OpenAPI 3.1 JSON · عملیات · خطاها · MCP
احراز هویت
با رمز فعلی در API و MCP توکن دارای انقضا بسازید. یک بار کپی و محرمانه نگه دارید. با هر درخواست Authorization: Bearer TOKEN و Accept: application/json بفرستید. کوکی نشست این API را احراز هویت نمیکند. لغو اعتبار فوری است. حساب باید فعال و ایمیل تأییدشده باشد. ورود مدیر بهجای کاربر از API ممکن نیست.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
JSON موفق در {"data": ...} قرار میگیرد. مجموعهها از صفحهبندی Laravel داخل data استفاده میکنند: 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 است. نوبتهای ناموجود یا مبهم در تغییر ساعت تابستانی رد میشوند؛ برنامهٔ یکبارهٔ مبهم به اختلاف زمانی صریح نیاز دارد.
عملیات
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
با Streamable HTTP و همان توکن Bearer به /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"}}}'