API pengembang
Kelola proyek, target, pemeriksaan, jadwal, dan kredensial penyedia Anda melalui REST atau MCP.
OpenAPI 3.1 JSON · Operasi · Kesalahan · MCP
Autentikasi
Buat token dengan masa berlaku di API dan MCP menggunakan kata sandi saat ini. Salin sekali dan rahasiakan. Kirim Authorization: Bearer TOKEN dan Accept: application/json pada setiap permintaan. Cookie sesi tidak dapat mengautentikasi API ini. Pencabutan langsung berlaku. Akun harus aktif dan email terverifikasi. Masuk sebagai pengguna oleh administrator tidak tersedia melalui API.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
JSON berhasil dibungkus dalam {"data": ...}. Koleksi memakai paginasi Laravel di dalam data: data.data, data.current_page, data.last_page, data.total. Atur page ≥ 1 dan per_page dari 1 sampai 100 (bawaan 25). ID milik akun lain menghasilkan 404. Rahasia hanya diterima melalui PUT kredensial dan tidak pernah dikembalikan. Saldo penyedia disimpan dalam cache; pembaruan mengantrekan tugas latar belakang terbatas.
Pemeriksaan berbayar dan percobaan ulang
Pembuatan proses memerlukan confirm_paid: true dan header Idempotency-Key unik atau kolom idempotency_key. Gunakan kembali kunci dan isi yang sama untuk memulihkan respons tanpa membuat proses baru; isi berbeda dengan kunci sama menghasilkan 409. Kunci milik akun Anda disimpan sampai akun dihapus. Target dan pengaturan dibekukan. Permintaan penyedia dapat dikenai biaya; melanjutkan pengiriman tidak pasti memerlukan retry_uncertain: true sebagai persetujuan potensi biaya ganda. Pembuatan jadwal juga memerlukan confirm_paid: true dan kunci idempotensi.
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}}'
Ekspor CSV memakai paginasi; X-Total-Pages menunjukkan jumlah halaman. Minta setiap halaman untuk ekspor lengkap. Sel menyerupai rumus di-escape. Tanggal memakai ISO 8601 UTC; waktu lokal jadwal memakai zona waktu IANA eksplisit. Hari ISO dari Senin=1 hingga Minggu=7. Waktu berulang yang tidak ada atau ambigu akibat pergantian waktu musim panas dilewati; jadwal sekali jalan yang ambigu memerlukan offset eksplisit.
Operasi
GET /api/v1/frequency — frequency.list
Izin: frequency:read
POST /api/v1/frequency — frequency.create
Izin: 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
Izin: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
Izin: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
Izin: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
Izin: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
Izin: 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
Izin: 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
Izin: tokens:read
POST /api/v1/tokens — tokens.issue
Izin:
{
"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
Izin: tokens:write
GET /api/v1/admin/settings — admin.settings
Izin: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
Izin: 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
Izin: admin:read
GET /api/v1/admin/users/{user} — admin.user
Izin: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
Izin: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
Izin: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
Izin: admin:read
GET /api/v1/runs/{run}/download — runs.download
Izin: runs:read
GET /api/v1/account — account.show
Izin: account:read
PATCH /api/v1/account — account.update
Izin: 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
}Contoh isi permintaan:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
Izin: projects:read
POST /api/v1/projects — projects.create
Izin: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Contoh isi permintaan:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
Izin: projects:read
PATCH /api/v1/projects/{project} — projects.update
Izin: 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
Izin: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
Izin: 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
Izin: 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
Izin: 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
Izin: 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
Izin: projects:read
POST /api/v1/projects/{project}/domains — domains.create
Izin: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Contoh isi permintaan:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
Izin: 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
Izin: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
Izin: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
Izin: 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
}Contoh isi permintaan:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
Izin: 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
Izin: projects:write
GET /api/v1/providers — providers.list
Izin: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
Izin: 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."
}Contoh isi permintaan:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
Izin: providers:write
GET /api/v1/balances — balances.list
Izin: providers:read
POST /api/v1/balances/refresh — balances.refresh
Izin: providers:write
GET /api/v1/runs — runs.list
Izin: runs:read
POST /api/v1/projects/{project}/runs — runs.create
Izin: 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
}Contoh isi permintaan:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
Izin: runs:read
GET /api/v1/runs/{run}/results — runs.results
Izin: runs:read
GET /api/v1/runs/{run}/export — runs.export
Izin: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
Izin: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
Izin: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Contoh isi permintaan:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
Izin: runs:write
GET /api/v1/schedules — schedules.list
Izin: schedules:read
POST /api/v1/schedules — schedules.create
Izin: 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
}Contoh isi permintaan:
{
"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
Izin: schedules:read
POST /api/v1/schedules/once — schedules.once
Izin: 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
}Contoh isi permintaan:
{
"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
Izin: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
Izin: 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
Izin: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
Izin: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
Izin: 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
Izin: schedules:write
GET /api/v1/healthz — health.show
Izin:
Kesalahan dan batas
401: token Bearer tidak ada, kedaluwarsa, atau dicabut. 403: izin tidak cukup atau akun tidak aktif/belum terverifikasi. 404: sumber daya tidak tersedia, termasuk milik akun lain. 409: konflik idempotensi. 422: input tidak valid; errors dikelompokkan per kolom. 429: batas permintaan terlampaui; patuhi Retry-After dan tambah jeda. Jangan gunakan kunci idempotensi baru untuk mengulang pembayaran hanya karena respons hilang.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Hubungkan ke /mcp melalui Streamable HTTP dengan token Bearer yang sama. Temukan skema alat melalui tools/list. Nama alat mengikuti ID operasi di atas, kecuali runs.start yang sesuai dengan runs.create. Rahasia penyedia dan administrasi token tidak tersedia di MCP; gunakan antarmuka akun atau endpoint REST kredensial. Izin baca dan tulis terpisah. Pembuatan berbayar memerlukan konfirmasi dan kunci idempotensi. Kredensial penyedia tidak pernah dikembalikan. Beri izin tulis hanya jika klien MCP perlu mengubah data.
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"}}}'