ڈویلپر 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": ...} میں لپیٹا جاتا ہے۔ مجموعے 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 دن پیر=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
اسی 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"}}}'