Serpo.one

ڈویلپر 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"}}}'