واجهة API للمطورين
أدر المشاريع والأهداف وعمليات التحقق والجداول وبيانات اعتماد مزودك عبر REST أو MCP.
OpenAPI 3.1 JSON · العمليات · الأخطاء · MCP
المصادقة
أنشئ رمزًا محدود الصلاحية في API وMCP باستخدام كلمة مرورك الحالية. انسخه مرة واحدة واحتفظ بسريته. أرسل Authorization: Bearer TOKEN وAccept: application/json مع كل طلب. لا تصادق ملفات تعريف ارتباط الجلسة على هذه الواجهة. يسري الإلغاء فورًا. يجب أن يكون حسابك نشطًا وبريده مؤكدًا. لا يتاح الدخول الإداري بصفة مستخدم عبر 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
اتصل بـ /mcp عبر Streamable HTTP برمز Bearer نفسه. استكشف مخططات الأدوات الدقيقة عبر 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"}}}'