KO
개발자 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 요일은 Monday=1부터 Sunday=7까지입니다. DST로 존재하지 않거나 모호한 반복 시간은 건너뛰며 모호한 일회성 일정에는 명시적인 오프셋이 필요합니다.
작업
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"}}}'