API 문서

SW_DEV의 서비스를 외부 프로그램에서 API로 호출하는 방법을 안내합니다. Planet에서 발급한 API 키 하나로, 키의 범위에 넣은 서비스를 호출합니다.

사용할 수 있는 서비스

Access · Secret · Report 등 다른 서비스는 아직 API 키로 호출할 수 없습니다.

API 키 발급

  1. Planet의 Access > API 키에서 키 발급을 누릅니다. API 키 화면은 기본적으로 Planet의 Owner · Admin이 쓸 수 있습니다.
  2. 이름과 범위를 고릅니다. 범위는 이 키로 호출할 수 있는 서비스입니다(Gateway · Agent). 조회 권한이 없는 서비스는 범위로 고를 수 없습니다.
  3. 필요하면 만료일을 정합니다. 비워 두면 만료되지 않습니다.
  4. 발급된 키 원문(swd_…)은 이때 한 번만 표시됩니다. 안전한 곳에 보관하고, 코드나 저장소에 그대로 넣지 마십시오.

키는 발급한 Planet에 속합니다. 키로 부르는 모델 · 에이전트와 사용량은 모두 그 Planet의 것입니다.

인증

요청마다 Authorization: Bearer 헤더나 x-api-key 헤더에 키를 넣습니다. 둘 중 하나만 있으면 됩니다.

curl
curl https://swdev.co.kr/api/llm/v1/models \
  -H "Authorization: Bearer $SWDEV_API_KEY"

키를 환경 변수로 두면 코드에 원문이 남지 않습니다.

셸
export SWDEV_API_KEY="swd_…"

키 관리

  • 수정: 이름 · 범위 · 만료일을 바꿉니다. 키 원문은 그대로입니다.
  • 재발급: 새 원문을 발급하고, 이전 원문은 바로 쓸 수 없게 됩니다.
  • 폐기: 키를 더 이상 쓸 수 없게 하고 목록에서 뺍니다. 되돌릴 수 없습니다.
  • 확인 결과를 최대 60초 동안 저장해 두므로, 수정 · 재발급 · 폐기는 최대 60초 뒤에 반영됩니다. 만료는 만료 시각에 바로 반영됩니다.

공통 오류

오류 본문의 형식은 서비스마다 다릅니다. Gateway는 OpenAI SDK가 그대로 읽을 수 있는 OpenAI 형식, Agent는 SW_DEV 공통 형식입니다.

HTTP언제설명
401키 없음 · 틀림 · 만료 · 폐기키를 확인하십시오. 폐기 · 재발급한 키는 다시 쓸 수 없습니다.
403범위 없음키의 범위에 그 서비스가 없습니다. Access > API 키에서 범위를 고치십시오.
429한도 초과요청 한도나 사용 한도를 넘었습니다. retry-after 헤더가 있으면 그만큼 기다린 뒤 다시 보내십시오.
503키 확인 불가잠시 키를 확인할 수 없습니다. 잠시 후 다시 보내십시오.
Gateway 오류 (OpenAI 형식)
{
  "error": {
    "message": "이 API 키의 범위에 Gateway 가 없습니다 (Access > API 키)",
    "type": "permission_error",
    "param": null,
    "code": "scope_not_allowed"
  }
}
Agent 오류 (SW_DEV 공통 형식)
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "이 API 키의 범위에 Agent 가 없습니다. (Access > API 키)",
  "code": "SCOPE_NOT_ALLOWED",
  "instance": "/api/agent/v1/agents"
}