API
기계가 읽을 수 있는 계약이 필요할 때 OpenAPI와 직접 HTTP를 사용합니다.
SDK가 맞지 않거나 TypeScript가 아닌 서비스에 기계가 읽을 수 있는 계약이 필요할 때 직접 HTTP를 escape hatch로 사용합니다. shell 사용 coding agent는 discovery, output, error가 기계 안정적으로 유지되도록 CLI를 사용합니다.
계약 소스
| 리소스 | 사용처 |
|---|---|
/api/openapi | endpoint path, parameter, auth, response, example |
https://api.01.software | production API origin |
/developers/cli.mdx | shell 사용 agent를 위한 기계 판독 CLI 가이드 |
/llms-full.txt | AI 도구용 넓은 사람이 읽는 맥락 |
/api/search | 좁은 범위의 문서 검색 |
인증
- 브라우저 읽기는 Publishable Key와 허용 origin을 사용합니다.
- 서버 쓰기는 신뢰할 수 있는 서버 자격 증명이 필요합니다.
- 사용자 범위 작업은 현재 사람 사용자와 연결된 상태를 유지합니다.
- Agent CLI 자격 증명은 서버 SDK 작업과 같은 신뢰 가능한 secret 경계를 사용합니다.
- hosted MCP는 읽기 전용 discovery로 제한되며 OpenAPI는 직접 HTTP 계약입니다.
공개 읽기 캐시와 최신 조회
Publishable Key로 인증 없이 조회하는 일부 컬렉션 GET 응답은 CDN에 캐시됩니다.
Console에서 저장한 변경 사항이 공개 읽기 응답에 바로 반영되지 않을 수 있습니다.
캐시를 갱신하는 동안 이전 응답이 반환될 수 있으며, 무효화가 지연되거나 실패하면 캐시 만료와 재검증까지 반영이 늦어질 수 있습니다.
Authorization 헤더가 있는 요청과 Payload 세션 쿠키(payload-token)가 있는 요청은 이 CDN 캐시를 사용하지 않습니다.
인증과 접근 권한 검사는 그대로 적용됩니다.
변경 직후 CDN에 남은 이전 응답을 피해야 한다면, 신뢰할 수 있는 서버에서 읽기 권한이 있는 Secret Key로 조회하세요.
서버 SDK 클라이언트를 사용하거나, 직접 HTTP 요청에 X-Publishable-Key와 Authorization: Bearer <Secret Key>를 함께 전달합니다.
Secret Key는 서버 경계 안에 보관하고, 애플리케이션 자체의 조회 캐시도 별도로 갱신하세요.
API 요청 속도 제한
Publishable Key 요청은 키가 속한 워크스페이스 기준으로 분당·시간당 제한을 공유합니다. 아래는 현재 운영 플랜의 Live 기준이며, 월 API 제공량이나 요금제 개편안과는 별개입니다.
| 현재 플랜 | 분당 요청 | 시간당 요청 |
|---|---|---|
| Free | 600 | 10,000 |
| Starter | 1,200 | 30,000 |
| Basic | 3,000 | 100,000 |
| Pro | 6,000 | 200,000 |
| Enterprise | 적용 계약·프로젝트 권한 확인 | 적용 계약·프로젝트 권한 확인 |
Sandbox는 플랜 제한과 분당 300회·시간당 3,000회 중 더 엄격한 값을 적용합니다. 월 API 제공량은 별도로 집계하며, 위 수치는 추가 요금 단가나 무제한 이용 약속이 아닙니다. 로그인 등 별도 보호 경로의 제한도 별개입니다.
요청 속도 제한으로 거절되면 429와 rate_limit_exceeded를 반환합니다.
응답의 Retry-After(초)를 기다린 뒤 재시도하고,
X-RateLimit-Limit와 X-RateLimit-Window(minute 또는 hour)로 해당 제한을 확인하세요.
응답 처리
- validation error는 그대로 고객 문구로 쓰지 말고 제품 문구 입력으로 다룹니다.
- secret 없이 request id와 status category를 기록합니다.
- retry는 가능한 한 bounded/idempotent하게 만듭니다.
SDK가 프로젝트에 맞으면 SDK를 우선 사용합니다. 직접 HTTP는 service-to-service, generated client, 비 TypeScript 연동에 사용합니다.
생성 coverage와 한계
/api/openapi에서 지원하는 HTTP 메서드와 경로, 요청 본문, 응답, 인증 요건을 확인하세요. Commerce, 고객 인증, membership, Events, 고객 그룹, 외부 작업 기록, 설치 암호문, 외부 고객 연결이 포함됩니다.
일반 Payload 오류는 errors[]를 사용합니다. 작업별 전용 엔드포인트는 error/reason/requestId 응답을 사용하며 일부 경로는 기존 code 응답을 유지합니다. 각 엔드포인트의 요청, 응답, 오류 형식은 일반 컬렉션 작업과 별도로 확인하세요.
Ecommerce SDK catalog 예제는 생성된 GET /api/products/detail/catalog operation, Publishable Key 인증, ProductDetailCatalog 성공 body에 대응합니다. Cart의 서버 credential 변형은 canonical cart path를 공유합니다. Checkout 생성은 POST /api/orders/checkout, 상세 조회는 POST /api/checkouts/detail, 서버 query는 POST /api/checkouts/query를 사용합니다. 이전 cart /server/* 및 checkout /create, /retrieve, /server/* alias는 지원 transport가 아닙니다.
제외된 shaped operation
Community detail, Gallery storefront, Video playback, embedded-admin configuration은 생성된 OpenAPI 계약에서 제외됩니다. 해당 SDK·연동 안내가 OpenAPI coverage를 뜻하지 않으므로 소유 reference를 사용하세요. 이 기능의 요청과 응답 형식은 일반 컬렉션 경로와 별도로 해당 참조에서 확인하세요. 모든 SDK helper에 별도 HTTP operation이 있다는 보장도 아닙니다.
같은 path에서 credential별 request·response·security 차이는 x-credential-variants에 있습니다. 사용하는 client generator가 이 확장을 소비하는지 확인하세요. 내부 operator session은 공개 연동 인증 scheme이 아닙니다. Collection CRUD 등 proxy 계층의 transport 오류는 전부 모델링되지 않았으므로 나열된 response를 완전한 실패 catalog로 해석하지 마세요.