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"}}}'