Serpo.one

API nhà phát triển

Quản lý dự án, mục tiêu, kiểm tra, lịch và thông tin xác thực nhà cung cấp qua REST hoặc MCP.

OpenAPI 3.1 JSON · Thao tác · Lỗi · MCP

Xác thực

Tạo token có thời hạn trong API và MCP bằng mật khẩu hiện tại. Sao chép một lần và giữ bí mật. Gửi Authorization: Bearer TOKEN và Accept: application/json trong mỗi yêu cầu. Cookie phiên không xác thực được API này. Thu hồi có hiệu lực ngay. Tài khoản phải hoạt động và email đã xác minh. Không thể truy cập dưới danh nghĩa người dùng bằng quyền quản trị qua API.

curl 'https://serpo.one/api/v1/projects' \
  -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'

JSON thành công được bọc trong {"data": ...}. Tập hợp dùng phân trang Laravel trong data: data.data, data.current_page, data.last_page, data.total. Đặt page ≥ 1 và per_page từ 1 đến 100 (mặc định 25). ID thuộc tài khoản khác trả về 404. Bí mật chỉ được nhận qua PUT thông tin xác thực và không bao giờ trả lại. Số dư được lưu đệm; làm mới xếp hàng một tác vụ nền có giới hạn.

Kiểm tra trả phí và thử lại

Tạo lượt chạy cần confirm_paid: true và tiêu đề Idempotency-Key duy nhất hoặc trường idempotency_key. Dùng lại cùng khóa và nội dung giống hệt để lấy lại phản hồi mà không tạo lượt chạy khác; đổi nội dung với cùng khóa trả về 409. Khóa thuộc tài khoản và được giữ đến khi xóa tài khoản. Mục tiêu và cài đặt được cố định. Nhà cung cấp có thể tính phí; tiếp tục yêu cầu chưa chắc chắn cần retry_uncertain: true để chấp nhận khả năng bị tính phí hai lần. Tạo lịch cũng cần confirm_paid: true và khóa chống lặp.

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

Xuất CSV có phân trang; X-Total-Pages cho biết số trang. Yêu cầu từng trang để xuất đầy đủ. Ô giống công thức được xử lý thoát. Ngày dùng ISO 8601 UTC; giờ địa phương của lịch dùng múi giờ IANA rõ ràng. Ngày ISO từ Thứ Hai=1 đến Chủ Nhật=7. Thời điểm lặp không tồn tại hoặc không rõ ràng do đổi giờ mùa hè bị bỏ qua; lịch một lần không rõ ràng cần độ lệch giờ cụ thể.

Thao tác

GET /api/v1/frequency — frequency.list

Quyền: frequency:read

POST /api/v1/frequency — frequency.create

Quyền: 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

Quyền: frequency:read

GET /api/v1/frequency/{batch}/results — frequency.results

Quyền: frequency:read

GET /api/v1/frequency/{batch}/export — frequency.export

Quyền: frequency:read

POST /api/v1/frequency/{batch}/cancel — frequency.cancel

Quyền: frequency:write

POST /api/v1/frequency/{batch}/retry — frequency.retry

Quyền: 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

Quyền: 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

Quyền: tokens:read

POST /api/v1/tokens — tokens.issue

Quyền:

{
    "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

Quyền: tokens:write

GET /api/v1/admin/settings — admin.settings

Quyền: admin:read

PATCH /api/v1/admin/settings — admin.settings_update

Quyền: 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

Quyền: admin:read

GET /api/v1/admin/users/{user} — admin.user

Quyền: admin:read

PATCH /api/v1/admin/users/{user}/status — admin.status

Quyền: admin:write

{
    "type": "object",
    "properties": {
        "is_active": {
            "type": "boolean"
        }
    },
    "required": [
        "is_active"
    ],
    "additionalProperties": false
}
GET /api/v1/admin/statistics — admin.statistics

Quyền: admin:read

GET /api/v1/admin/users/{user}/balances — admin.balances

Quyền: admin:read

GET /api/v1/runs/{run}/download — runs.download

Quyền: runs:read

GET /api/v1/account — account.show

Quyền: account:read

PATCH /api/v1/account — account.update

Quyền: 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
}

Ví dụ nội dung yêu cầu:

{
    "locale": "en",
    "timezone": "Europe/Moscow"
}
GET /api/v1/projects — projects.list

Quyền: projects:read

POST /api/v1/projects — projects.create

Quyền: projects:write

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "maxLength": 120
        },
        "settings": {
            "$ref": "#/components/schemas/RankSettings"
        }
    },
    "required": [
        "name"
    ],
    "additionalProperties": false
}

Ví dụ nội dung yêu cầu:

{
    "name": "Example",
    "settings": {
        "depth": 10
    }
}
GET /api/v1/projects/{project} — projects.show

Quyền: projects:read

PATCH /api/v1/projects/{project} — projects.update

Quyền: 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

Quyền: projects:write

POST /api/v1/projects/{project}/domains/import — domains.import

Quyền: 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

Quyền: 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

Quyền: 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

Quyền: 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

Quyền: projects:read

POST /api/v1/projects/{project}/domains — domains.create

Quyền: projects:write

{
    "type": "object",
    "properties": {
        "domain": {
            "type": "string",
            "maxLength": 2048
        },
        "group": {
            "type": "string",
            "maxLength": 255
        }
    },
    "required": [
        "domain"
    ],
    "additionalProperties": false
}

Ví dụ nội dung yêu cầu:

{
    "domain": "example.com"
}
PATCH /api/v1/projects/{project}/domains/{item} — domains.update

Quyền: 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

Quyền: projects:write

GET /api/v1/projects/{project}/keywords — keywords.list

Quyền: projects:read

POST /api/v1/projects/{project}/keywords — keywords.create

Quyền: 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
}

Ví dụ nội dung yêu cầu:

{
    "query": "example search",
    "group": "Primary"
}
PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update

Quyền: 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

Quyền: projects:write

GET /api/v1/providers — providers.list

Quyền: providers:read

PUT /api/v1/providers/{provider}/credentials — credentials.put

Quyền: 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."
}

Ví dụ nội dung yêu cầu:

{
    "provider_user": "123",
    "api_key": "REPLACE_WITH_PROVIDER_KEY"
}
DELETE /api/v1/providers/{provider}/credentials — credentials.delete

Quyền: providers:write

GET /api/v1/balances — balances.list

Quyền: providers:read

POST /api/v1/balances/refresh — balances.refresh

Quyền: providers:write

GET /api/v1/runs — runs.list

Quyền: runs:read

POST /api/v1/projects/{project}/runs — runs.create

Quyền: 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
}

Ví dụ nội dung yêu cầu:

{
    "confirm_paid": true,
    "idempotency_key": "check-001",
    "settings": {
        "depth": 10
    }
}
GET /api/v1/runs/{run} — runs.show

Quyền: runs:read

GET /api/v1/runs/{run}/results — runs.results

Quyền: runs:read

GET /api/v1/runs/{run}/export — runs.export

Quyền: runs:read

POST /api/v1/runs/{run}/pause — runs.pause

Quyền: runs:write

POST /api/v1/runs/{run}/resume — runs.resume

Quyền: runs:write

{
    "type": "object",
    "properties": {
        "retry_uncertain": {
            "type": "boolean",
            "const": true
        }
    },
    "required": [],
    "additionalProperties": false
}

Ví dụ nội dung yêu cầu:

{
    "retry_uncertain": true
}
POST /api/v1/runs/{run}/cancel — runs.cancel

Quyền: runs:write

GET /api/v1/schedules — schedules.list

Quyền: schedules:read

POST /api/v1/schedules — schedules.create

Quyền: 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
}

Ví dụ nội dung yêu cầu:

{
    "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

Quyền: schedules:read

POST /api/v1/schedules/once — schedules.once

Quyền: 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
}

Ví dụ nội dung yêu cầu:

{
    "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

Quyền: schedules:read

PATCH /api/v1/schedules/once/{schedule} — schedules.once_update

Quyền: 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

Quyền: schedules:write

GET /api/v1/schedules/{schedule} — schedules.show

Quyền: schedules:read

PATCH /api/v1/schedules/{schedule} — schedules.update

Quyền: 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

Quyền: schedules:write

GET /api/v1/healthz — health.show

Quyền:

Lỗi và giới hạn

401: thiếu token Bearer, token hết hạn hoặc đã thu hồi. 403: thiếu quyền hoặc tài khoản không hoạt động/chưa xác minh. 404: tài nguyên không có sẵn, kể cả tài nguyên tài khoản khác. 409: xung đột chống lặp. 422: dữ liệu không hợp lệ; errors theo từng trường. 429: vượt giới hạn yêu cầu; tuân thủ Retry-After và tăng thời gian chờ. Không dùng khóa chống lặp mới cho lần thử trả phí chỉ vì mất phản hồi.

{"message":"The name field is required.","errors":{"name":["The name field is required."]}}

MCP

Kết nối /mcp qua Streamable HTTP với cùng token Bearer. Xem lược đồ công cụ chính xác qua tools/list. Tên công cụ theo ID thao tác phía trên, riêng runs.start tương ứng runs.create. Bí mật nhà cung cấp và quản lý token không có trong MCP; dùng giao diện tài khoản hoặc điểm cuối REST thông tin xác thực. Quyền đọc và ghi độc lập. Tạo thao tác trả phí cần xác nhận và khóa chống lặp. Thông tin xác thực không bao giờ được trả lại. Chỉ cấp quyền ghi khi ứng dụng khách MCP cần đổi dữ liệu.

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