डेवलपर 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"}}}'