Geliştirici API'si
Projeleri, hedefleri, kontrolleri, planları ve kendi sağlayıcı kimlik bilgilerinizi REST veya MCP üzerinden yönetin.
OpenAPI 3.1 JSON · İşlemler · Hatalar · MCP
Kimlik doğrulama
Mevcut parolanızla API & MCP bölümünde süreli bir belirteç oluşturun. Belirteci bir kez kopyalayıp gizli tutun. Her istekte Authorization: Bearer TOKEN ve Accept: application/json gönderin. Oturum çerezleri bu API'de kimlik doğrulayamaz. İptal işlemi hemen geçerli olur. Hesabınız etkin ve e-postanız doğrulanmış olmalıdır. Yönetici tarafından kullanıcı oturumuna geçiş API'de kullanılamaz.
curl 'https://serpo.one/api/v1/projects' \ -H 'Authorization: Bearer TOKEN' -H 'Accept: application/json'
Başarılı JSON yanıtları {"data": ...} içinde sunulur. Koleksiyonlar data içinde Laravel sayfalaması kullanır: data.data, data.current_page, data.last_page, data.total. page ≥ 1 ve per_page 1 ile 100 arasında olmalıdır (varsayılan 25). Diğer hesapların kimlikleri 404 döndürür. Gizli bilgiler yalnızca kimlik bilgileri PUT işleminde kabul edilir ve asla döndürülmez. Sağlayıcı bakiyeleri önbelleğe alınır; yenileme sınırlı bir arka plan güncellemesini kuyruğa ekler.
Ücretli kontroller ve yeniden denemeler
Çalışma oluşturmak için confirm_paid: true ve benzersiz Idempotency-Key başlığı veya idempotency_key alanı gerekir. Başka çalışma oluşturmadan yanıtı geri almak için aynı anahtarı ve aynı gövdeyi kullanın; aynı anahtarla değişen girdi 409 döndürür. Anahtarlar hesabınıza aittir ve hesap silinene kadar tutulur. Çalışmalar hedefleri ve ayarları sabitler. Sağlayıcı istekleri ücretli olabilir; belirsiz gönderimleri sürdürmek, olası mükerrer ücretleri kabul etmek için retry_uncertain: true gerektirir. Plan oluşturmak da confirm_paid: true ve idempotentlik anahtarı gerektirir.
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 dışa aktarımı sayfalanır; X-Total-Pages sayfa sayısını verir. Tam dışa aktarım için her sayfayı isteyin. Formül benzeri hücreler kaçışlanır. Tarihler ISO 8601 UTC kullanır; plan saatleri açık IANA saat dilimini kullanır. ISO hafta günleri Monday=1 ile Sunday=7 arasındadır. Olmayan veya belirsiz DST yineleme saatleri atlanır; belirsiz tek seferlik planlar açık bir saat farkı gerektirir.
İşlemler
GET /api/v1/frequency — frequency.list
İzin: frequency:read
POST /api/v1/frequency — frequency.create
İzin: 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
İzin: frequency:read
GET /api/v1/frequency/{batch}/results — frequency.results
İzin: frequency:read
GET /api/v1/frequency/{batch}/export — frequency.export
İzin: frequency:read
POST /api/v1/frequency/{batch}/cancel — frequency.cancel
İzin: frequency:write
POST /api/v1/frequency/{batch}/retry — frequency.retry
İzin: 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
İzin: 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
İzin: tokens:read
POST /api/v1/tokens — tokens.issue
İzin:
{
"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
İzin: tokens:write
GET /api/v1/admin/settings — admin.settings
İzin: admin:read
PATCH /api/v1/admin/settings — admin.settings_update
İzin: 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
İzin: admin:read
GET /api/v1/admin/users/{user} — admin.user
İzin: admin:read
PATCH /api/v1/admin/users/{user}/status — admin.status
İzin: admin:write
{
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
}
},
"required": [
"is_active"
],
"additionalProperties": false
}GET /api/v1/admin/statistics — admin.statistics
İzin: admin:read
GET /api/v1/admin/users/{user}/balances — admin.balances
İzin: admin:read
GET /api/v1/runs/{run}/download — runs.download
İzin: runs:read
GET /api/v1/account — account.show
İzin: account:read
PATCH /api/v1/account — account.update
İzin: 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
}Örnek gövde:
{
"locale": "en",
"timezone": "Europe/Moscow"
}GET /api/v1/projects — projects.list
İzin: projects:read
POST /api/v1/projects — projects.create
İzin: projects:write
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 120
},
"settings": {
"$ref": "#/components/schemas/RankSettings"
}
},
"required": [
"name"
],
"additionalProperties": false
}Örnek gövde:
{
"name": "Example",
"settings": {
"depth": 10
}
}GET /api/v1/projects/{project} — projects.show
İzin: projects:read
PATCH /api/v1/projects/{project} — projects.update
İzin: 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
İzin: projects:write
POST /api/v1/projects/{project}/domains/import — domains.import
İzin: 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
İzin: 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
İzin: 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
İzin: 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
İzin: projects:read
POST /api/v1/projects/{project}/domains — domains.create
İzin: projects:write
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"maxLength": 2048
},
"group": {
"type": "string",
"maxLength": 255
}
},
"required": [
"domain"
],
"additionalProperties": false
}Örnek gövde:
{
"domain": "example.com"
}PATCH /api/v1/projects/{project}/domains/{item} — domains.update
İzin: 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
İzin: projects:write
GET /api/v1/projects/{project}/keywords — keywords.list
İzin: projects:read
POST /api/v1/projects/{project}/keywords — keywords.create
İzin: 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
}Örnek gövde:
{
"query": "example search",
"group": "Primary"
}PATCH /api/v1/projects/{project}/keywords/{item} — keywords.update
İzin: 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
İzin: projects:write
GET /api/v1/providers — providers.list
İzin: providers:read
PUT /api/v1/providers/{provider}/credentials — credentials.put
İzin: 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."
}Örnek gövde:
{
"provider_user": "123",
"api_key": "REPLACE_WITH_PROVIDER_KEY"
}DELETE /api/v1/providers/{provider}/credentials — credentials.delete
İzin: providers:write
GET /api/v1/balances — balances.list
İzin: providers:read
POST /api/v1/balances/refresh — balances.refresh
İzin: providers:write
GET /api/v1/runs — runs.list
İzin: runs:read
POST /api/v1/projects/{project}/runs — runs.create
İzin: 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
}Örnek gövde:
{
"confirm_paid": true,
"idempotency_key": "check-001",
"settings": {
"depth": 10
}
}GET /api/v1/runs/{run} — runs.show
İzin: runs:read
GET /api/v1/runs/{run}/results — runs.results
İzin: runs:read
GET /api/v1/runs/{run}/export — runs.export
İzin: runs:read
POST /api/v1/runs/{run}/pause — runs.pause
İzin: runs:write
POST /api/v1/runs/{run}/resume — runs.resume
İzin: runs:write
{
"type": "object",
"properties": {
"retry_uncertain": {
"type": "boolean",
"const": true
}
},
"required": [],
"additionalProperties": false
}Örnek gövde:
{
"retry_uncertain": true
}POST /api/v1/runs/{run}/cancel — runs.cancel
İzin: runs:write
GET /api/v1/schedules — schedules.list
İzin: schedules:read
POST /api/v1/schedules — schedules.create
İzin: 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
}Örnek gövde:
{
"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
İzin: schedules:read
POST /api/v1/schedules/once — schedules.once
İzin: 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
}Örnek gövde:
{
"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
İzin: schedules:read
PATCH /api/v1/schedules/once/{schedule} — schedules.once_update
İzin: 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
İzin: schedules:write
GET /api/v1/schedules/{schedule} — schedules.show
İzin: schedules:read
PATCH /api/v1/schedules/{schedule} — schedules.update
İzin: 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
İzin: schedules:write
GET /api/v1/healthz — health.show
İzin:
Hatalar ve sınırlar
401: bearer belirteci eksik, süresi dolmuş veya iptal edilmiş. 403: yetersiz izin veya etkin olmayan/doğrulanmamış hesap. 404: başka hesabın kaynağı dahil kullanılamayan kaynak. 409: idempotentlik çakışması. 422: geçersiz girdi; errors alan adına göre anahtarlanır. 429: istek sınırı aşıldı; Retry-After değerine uyup bekleme süresini artırın. Sırf yanıt kayboldu diye ücretli yeniden denemede yeni idempotentlik anahtarı kullanmayın.
{"message":"The name field is required.","errors":{"name":["The name field is required."]}}
MCP
Aynı Bearer belirteciyle Streamable HTTP kullanarak /mcp adresine bağlanın. Kesin araç şemalarını tools/list ile keşfedin. Araç adları yukarıdaki işlem kimliklerini izler; yalnızca runs.start, runs.create işlemine karşılık gelir. Sağlayıcı sırları ve belirteç yönetimi MCP'de bilerek sunulmaz; hesap arayüzünü veya kimlik bilgileri REST uç noktasını kullanın. Okuma ve yazma izinleri bağımsızdır. Ücretli oluşturma onay ve idempotentlik anahtarı gerektirir. Sağlayıcı kimlik bilgileri asla döndürülmez. Yazma iznini yalnızca MCP istemcisinin verilerinizi değiştirmesi gerekiyorsa verin.
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"}}}'