API 레퍼런스
예측 가능한 리소스, 표준 메서드, 커서 페이지네이션. 아래 레이트 리밋은 희망 수치가 아니라 서버가 실제로 강제하는 값입니다.
워크스페이스 범위의 Bearer 토큰입니다. 토큰은 생성한 사람의 역할을 상속하므로, editor의 토큰은 무엇을 호출하든 승인할 수 없습니다. 이 규칙은 클라이언트가 아니라 서버에서 강제됩니다.
curl https://api.untactit.com/v1/assets \ -H "Authorization: Bearer $TOKEN"
로그인 자체는 SSO 전용입니다(SAML 또는 OIDC). 비밀번호를 보관하지 않으므로 비밀번호 엔드포인트도 없고, 유출될 것도 없습니다.
오프셋이 아닌 커서 방식입니다. 이전 응답에서 받은 cursor 값을 has_more 가 false가 될 때까지 전달합니다. 페이지당 최대 100개 항목입니다.
{
"data": [ /* up to 100 items */ ],
"has_more": true,
"next_cursor": "cur_01H8X..."
}
리소스는 여섯 개입니다. 역할 요건은 서버가 강제하며, 권한이 부족하면 오류에 필요한 역할이 명시됩니다.
| 리소스 | 다루는 범위 | 최소 역할 |
|---|---|---|
assets |
목록 조회, 읽기, 생성, 업데이트. 자산별 전체 버전 이력 제공. | viewer / editor |
approvals |
제안, 승인, 반려. 워크스페이스의 승인 정책을 따릅니다. | editor / approver |
deployments |
계획, 실행, dry-run, 드리프트를 포함한 배포 상태 조회. | 승인권자 |
targets |
연결된 플랫폼과 그 범위. | admin |
members |
워크스페이스 구성원과 역할 할당. | admin |
audit |
행위자·작업·시간 필터를 갖춘 감사 로그. CSV 내보내기. | admin |
오류
오류에는 안정적인 code 가 담겨 있어 코드 기준으로 분기할 수 있습니다. 권한이 문제인 경우에는 어떤 역할이었으면 됐는지를 응답에 명시하므로, 추측 없이 바로잡을 수 있습니다.
403 insufficient role: 필요한 역할과 현재 역할을 함께 명시413 페이로드 4 MB 초과429 레이트 리밋 초과409 conflict: 작업 중이던 버전이 이미 변경됨{
"error": {
"code": "insufficient_role",
"message": "Approving requires the approver role.",
"required_role": "approver",
"actual_role": "editor",
"request_id": "req_01H8X..."
}
}
지원 문의 메일에 request_id 값을 포함해 주세요. 문제를 재현해 달라고 요청하지 않고도 해당 호출을 정확히 찾아낼 수 있습니다.
워크스페이스별 토큰 버킷이 경로 그룹 단위로 적용됩니다. 지속 속도만큼 계속 충전되며, 버스트는 유휴 상태 뒤 한 번에 쓸 수 있는 양입니다.
읽기 및 자산 쓰기. 버스트 50회. 전체 인벤토리를 상시 동기화하면서, 편집 중 저장을 의식하지 않아도 될 만큼의 여유입니다.
구조를 바꾸는 작업. 버스트 5회. 역할 변경, 워크스페이스 설정 등 누가 무엇을 할 수 있는지를 바꾸는 모든 작업이 해당됩니다.
배포, 실행, 외부 호출. 작업 비용에 비례합니다. 배포는 몇 대의 머신에 도달하든 호출 한 번으로 계산됩니다.
4 MB를 초과하는 요청은 413으로 거부됩니다. 구체적인 사용 패턴이 있는 Enterprise 워크스페이스는 한도 상향이 가능합니다. 워크로드를 설명해 주시면, 근거 없는 숫자를 부르는 대신 실제 규모에 맞춰 산정합니다.
공개적으로 약속할 수 있는 날짜는 아직 없습니다. 엔진은 이미 돌아가고 있고, 남은 것은 안정적인 계약과 사용 중단 보장입니다. API 접근이 도입 평가의 필수 조건이라면 알려 주세요. 그만큼 우선순위가 올라갑니다.
별도의 샌드박스는 없습니다. 무료 플랜으로 워크스페이스를 하나 더 만들어 테스트 환경으로 쓰세요. 동작은 동일하고, 프로덕션 데이터에는 위험이 없습니다.
경로에 버전을 명시합니다. 호환성이 깨지는 변경은 새 버전으로 나가며, 이전 버전은 12개월간 병행 유지됩니다. 필드 추가는 예고 없이 이루어질 수 있으므로 방어적으로 파싱해야 합니다.
네. 구현과 같은 소스에서 생성되므로 실제 동작과 어긋날 수 없습니다. 손으로 관리하는 명세는 결국 거짓말을 하게 되는 문서입니다.