API
기계가 읽을 수 있는 계약이 필요할 때 OpenAPI와 직접 HTTP를 사용합니다.
API
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 계약입니다.
API 요청 속도 제한
Publishable Key 요청은 키가 속한 tenant 기준으로 분당·시간당 제한을 공유합니다. 아래는 현재 운영 플랜의 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는 현재 생성된 계약을 제공합니다. Generic path는 SDK collection bucket에서, shaped operation의 method/path identity는 공유 HTTP manifest에서 유도합니다. 생성 계약에는 Commerce, 고객 인증, membership, Events, 고객 그룹, 외부 작업 기록, 설치 암호문, 외부 고객 연결이 포함됩니다. Generic Payload 오류는 errors[], shaped endpoint는 error/reason/requestId envelope를 쓰며 일부 기존 path는 legacy code 응답을 유지합니다. Generic collection operation에서 DTO나 오류 형태를 추측하지 마세요.
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를 사용하세요. Generic collection path는 이 제외된 shaped DTO를 설명하지 않습니다. 모든 SDK helper에 별도 HTTP operation이 있다는 보장도 아닙니다.
같은 path에서 credential별 request·response·security 차이는 x-credential-variants에 있습니다. 사용하는 client generator가 이 확장을 소비하는지 확인하세요. 내부 operator session은 공개 연동 인증 scheme이 아닙니다. Collection CRUD 등 proxy 계층의 transport 오류는 전부 모델링되지 않았으므로 나열된 response를 완전한 실패 catalog로 해석하지 마세요.