Codykata API v1

시작하기

개인 API 토큰으로 스크립트·CLI·에이전트에서 내 계정의 정보를 읽고, 제출하고, 문제를 등록합니다.

토큰 만들기

Codykata에 로그인한 뒤 계정 메뉴의 설정 → 「API 토큰」에서 토큰을 만듭니다. 이름, 권한, 수명(7일·30일·90일·1년·날짜 직접 선택·만료 없음)을 고르면 토큰이 한 번만 표시되니 바로 복사해 안전한 곳에 보관하세요. 같은 화면에서 언제든 폐기할 수 있습니다.

API 토큰 설정 열기

권한	할 수 있는 일
`read`	내 제출 기록과 내가 출제한 문제 조회
`submit`	공개 문제에 코드 제출
`studio`	문제 등록·수정과 내 문제·검토 상태 조회

어떤 토큰이든 내 정보, 공개 문제, 출처·라이선스 목록은 조회할 수 있습니다. 필요한 권한만 고르세요.

인증

모든 요청의 Authorization 헤더에 토큰을 넣습니다. 기본 주소는 https://api.codykata.com/v1이고 요청·응답 본문은 JSON입니다.

curl -H "Authorization: Bearer $CODYKATA_TOKEN" \
  https://api.codykata.com/v1/me

토큰은 비밀번호처럼 다룹니다. 코드 저장소에 커밋하지 말고 환경 변수나 비밀 저장소에 두세요. 유출이 의심되면 바로 폐기하고 새로 만드세요. 토큰은 관리자 권한을 갖지 않으며, 「다른 기기에서 로그아웃」을 해도 토큰은 그대로 남습니다.

경로

경로는 https://api.codykata.com/v1 기준입니다. 요청·응답 형식과 예시는 API 레퍼런스에서 확인하고 바로 호출해 볼 수 있습니다. API 레퍼런스 열기

경로	설명 · 권한
`GET` `/me`	내 정보 권한: 모든 토큰
`GET` `/problems`	공개 문제 목록 권한: 모든 토큰
`GET` `/problems/:id`	문제 본문 권한: 모든 토큰
`GET` `/sources`	출처 목록 권한: 모든 토큰
`GET` `/licenses`	라이선스 목록 권한: 모든 토큰
`GET` `/submissions`	내 제출 목록 권한: read
`POST` `/submissions`	코드 제출 권한: submit
`GET` `/submissions/:id`	채점 상태와 결과 권한: read
`GET` `/submissions/:id/code`	제출한 코드 권한: read
`GET` `/studio/problems`	내가 출제한 문제 권한: read 또는 studio
`GET` `/studio/problems/:id`	출제한 문제의 마지막 저장본 권한: read 또는 studio
`POST` `/problems`	문제 등록 권한: studio
`PUT` `/studio/problems/:id`	문제 수정 권한: studio

에이전트나 클라이언트 생성 도구에는 OpenAPI 문서를 그대로 넘기세요. openapi.json

예시

내 티어 확인

curl -s -H "Authorization: Bearer $CODYKATA_TOKEN" https://api.codykata.com/v1/me

{
  "user_id": "…",
  "name": "…",
  "tier": "Gold",
  "current_sp": 412,
  "next_tier": { "tier": "Platinum", "required_sp": 700 },
  "solved_count": 58,
  "current_streak": 6,
  "longest_streak": 21,
  "rank": { "points": 37 },
  "token": { "id": "…", "name": "…", "scopes": ["read"], "expires_at": null }
}

rank.points는 SP 랭킹 순위이며 프로필이 비공개면 null입니다. 응답의 token으로 이 토큰의 권한과 만료를 확인할 수 있습니다.

제출하고 결과 기다리기

먼저 문제를 조회해 problem_version_id를 얻고, 그 버전으로 제출합니다. 채점은 비동기이므로 status가 FINISHED나 SYSTEM_FAILED가 될 때까지 몇 초 간격으로 조회합니다.

curl -s -X POST https://api.codykata.com/v1/submissions \
  -H "Authorization: Bearer $CODYKATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"problem_id":"…","problem_version_id":"…","language":"python","code":"print(1)"}'

curl -s -H "Authorization: Bearer $CODYKATA_TOKEN" https://api.codykata.com/v1/submissions/<submission_id>

언어는 cpp, c, python, javascript, typescript 중 하나입니다. 제출에는 멱등 키가 없어 응답을 못 받고 다시 보내면 중복 제출될 수 있으니, 다시 보내기 전에 /submissions 목록을 확인하세요.

문제 등록

POST /problems는 검토 요청을 만들고, 관리자가 승인하면 문제가 공개됩니다. 요청마다 새 request_id(UUID)를 만들고, 응답을 못 받았을 때는 같은 request_id와 같은 내용으로 다시 보내면 처음 결과를 돌려받습니다. 본문 형식은 웹의 문제 만들기와 같은 ProblemPackage v2이며 최대 32 MiB입니다. 수정은 PUT /studio/problems/:id에 마지막으로 저장한 버전을 expected_version_id로 보냅니다.

오류

오류 응답은 {"error": "...", "message": "..."} 형식입니다. 먼저 HTTP 상태로 판단하고, error는 업무 사유를 구분할 때만 쓰세요. message는 사람이 읽는 설명이라 바뀔 수 있습니다.

상태	error · 의미
400	`INVALID_REQUEST · INVALID` 요청 형식이나 값이 계약과 맞지 않습니다.
401	`INVALID_REQUEST` 토큰이 없거나 틀렸거나, 만료·폐기됐거나, 계정이 정지됐습니다. 응답에 WWW-Authenticate: Bearer가 붙습니다.
403	`INSUFFICIENT_SCOPE · FORBIDDEN` 토큰에 필요한 권한이 없거나, 비공개 문제처럼 볼 수 없는 대상입니다.
404	`NOT_FOUND` 대상이 없습니다.
409	`CONFLICT` 같은 request_id를 다른 내용으로 다시 썼거나, 그사이 문제가 수정됐습니다.
429	`CAPACITY · INVALID_REQUEST` 채점 대기 중인 제출이 10개이거나(CAPACITY) 요청 한도를 넘었습니다.

한도

읽기 요청은 토큰마다 분당 120회입니다.
쓰기 요청은 웹에서의 쓰기와 합쳐 계정당 분당 30회입니다. 토큰을 여러 개 만들어도 늘지 않습니다.
채점이 끝나지 않은 제출은 계정당 10개까지입니다.
토큰으로 보내는 문제 등록·수정은 계정당 UTC 기준 하루 10회입니다.
계정당 활성 토큰은 20개까지입니다.

429를 받으면 잠시 기다렸다가 다시 시도하세요. 제출은 자동으로 다시 보내지 마세요.

호환성

v1 안에서는 응답에 선택 필드만 추가합니다. 필드를 없애거나 이름·타입을 바꾸는 변경은 새 버전 경로로 냅니다. 모르는 필드는 무시하도록 클라이언트를 작성하세요.