Serpo.one

واجهة 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"}}}'