Skip to Content

버전 정책과 변경 이력

버전 정책

API 경로는 /v1로 버전을 나눕니다.

  • 추가 변경은 같은 버전에서 허용합니다. 새 경로, 응답에 새 필드, 새 이벤트 종류, 새 오류 코드, 선택 입력 추가가 해당합니다. 클라이언트는 모르는 필드와 모르는 이벤트 종류, 모르는 오류 코드를 무시하거나 안전하게 처리해야 합니다.
  • 필수 입력, enum 값, 필드의 의미를 깨는 변경은 새 major 버전(/v2)에서만 합니다. 이런 변경은 같은 /v1에서 하지 않습니다.
  • 새 major 버전을 내면 이전 버전의 지원 종료 일정을 먼저 공지합니다.
  • OpenAPI 파일과 공개 예제가 실제 서비스와 어긋나지 않는지 검증하며, 어긋나면 파일을 기준으로 바로잡습니다.

Private Beta 동안

Beta에는 위 정책의 예외가 있습니다. Beta 동안에는 계약, 한도, 경로가 바뀔 수 있습니다. 바뀌는 내용은 이 페이지에 먼저 기록합니다. 운영에 쓰는 Project는 이 페이지를 주기적으로 확인하세요.

지원 종료 공지

  • 지원이 끝나는 경로, 필드, 동작은 이 페이지에 지원 종료 예정으로 먼저 올립니다.
  • 공지에는 대체 방법과 종료 일정을 함께 적습니다.
  • 공지 전에 이미 제거된 것은 없도록 하는 것이 목표지만, Private Beta 동안에는 보안이나 안정성 때문에 예고 없이 바뀔 수 있습니다.

변경 이력

날짜내용
2026-10오류 표에 결과 검사 코드(OUTPUT_URL_INVALID, OUTPUT_CONTAINS_CREDENTIALS, INVALID_FILENAME, UNSUPPORTED_FILE_TYPE 등)와 WORKFLOW_UNAVAILABLE을 더하고, 파일 보존 기간(미리 올린 파일 24시간, Session 파일 30일)을 한도와 데이터에 적었습니다.
2026-10OpenAPI 1.3.0. GET /v1/usage 응답에 준비 비용 칸 preparations를 더했습니다. 조직 업무 준비 비용을 실행 비용과 따로 보여 주며, 기존 칸(status, total_su, categories 등)의 뜻은 그대로입니다. 실행 필터(deployment_id, session_id, turn_id, run_id)를 주면 null입니다. works 전용 키에 usage:read를 더해도 Deployment 없이 만들 수 있습니다. 사용량을 보세요.
2026-10OpenAPI 1.2.0. 조직 업무 만들기 경로를 더했습니다: POST /v1/works, GET /v1/preparations, GET /v1/preparations/{preparation_id}, POST /v1/preparations/{preparation_id}/answers. 새 scope works:read, works:write, works:approve와 Deployment 없이 만드는 works 전용 키, 오류 코드 REVISION_CONFLICT, PREPARATION_IN_PROGRESS, INVALID_TRANSITION, QUESTION_NOT_FOUND, PACKAGE_CHANGED, INVALID_SPEC, INVALID_REQUEST를 더했습니다. 기존 경로의 요청과 응답은 그대로입니다. 조직 업무 만들기를 보세요.
2026-10실행 환경 준비 단계가 시간 안에 끝나지 않아 실패한 Turn은 error.code가 SESSION_SANDBOX_UNAVAILABLE이고, 그 Turn을 쓰는 Run도 대개 같은 코드입니다. 전에는 Turn은 USAGE_PENDING이나 EXECUTION_TIMEOUT, Run은 USAGE_PENDING이나 EXTERNAL_EFFECT_UNKNOWN으로 보였습니다. 준비 중 보낸 요청의 결과를 확인하지 못한 Run은 지금도 EXTERNAL_EFFECT_UNKNOWN이고, 앞선 실행을 기다리다 시간이 다 된 경우는 지금도 EXECUTION_TIMEOUT입니다. 오류 표와 다음 행동 표에 더했습니다.
2026-10AI 도구용 요약 llms.txt와 실패한 실행 뒤 코드별 다음 행동 표를 추가했습니다. 실행 상세에 보일 수 있는 종결 코드 6개(EXECUTION_FAILED, CANCELED, AUTHORIZATION_REVOKED, SESSION_DELETED, RUNTIME_CONTEXT_MISMATCH, USAGE_PENDING)를 오류 표에 더했습니다.
2026-10GET /v1/deployments와 GET /v1/deployments/{deployment_id} 응답에서 source_agent_id를 뺐습니다. 호출에는 Deployment id만 씁니다.
2026-10Private Beta 문서 공개. Session과 Turn, Workflow와 Run, 이벤트와 SSE, 웹훅, 파일 입출력, 오류와 한도를 다룹니다.
핵심 개념