MasterOS API가 노출하는 실제 REST endpoint를 리소스별로 정리했습니다. 모두 /v1 prefix 아래에 있습니다.
오늘 기준 실제 endpoint입니다
이 레퍼런스는 지금 실제로 구현되어 있는 그대로의 API를 문서화합니다. 이는 손으로 작성된 것이며, API 자체의 실제
OpenAPI spec으로부터 생성된 것이 아닙니다 (그 spec이 실제로 어디에 있는지는 Versioning
참고) — 둘 사이의 변경 사항(drift)은 Changelog를 통해 확인하세요.
모든 endpoint는 API의 base URL을 기준으로 하며, /v1 prefix 아래에 있습니다 (Versioning
참고). 인증이 필요한 모든 endpoint는 POST /v1/auth/verify-login-code으로 설정되는 httpOnly session cookie를 사용합니다 —
오늘은 별도의 API key 인증이 없습니다 (Authentication 참고).
auth
| Method | Path | Auth | 비고 |
|---|
| POST | /v1/auth/request-login-code | — | { email }. 6자리 코드를 이메일로 보내며 처음 사용하는 경우 계정을 생성합니다. 항상 동일한 메시지를 반환합니다. IP와 이메일 기준으로 각각 독립적으로 rate-limit됩니다. |
| POST | /v1/auth/verify-login-code | — | { email, code }. session cookie를 설정합니다. IP와 이메일 기준으로 각각 독립적으로 rate-limit됩니다. |
| POST | /v1/auth/logout | session | session cookie를 삭제합니다. |
| GET | /v1/auth/me | session | 현재 사용자를 반환합니다. |
| GET | /v1/auth/google | — | Google OAuth로 리디렉션합니다. |
| GET | /v1/auth/google/callback | — | OAuth callback; 성공 시 앱으로 리디렉션합니다. |
| GET | /v1/auth/facebook | — | Facebook OAuth로 리디렉션합니다. |
| GET | /v1/auth/facebook/callback | — | OAuth callback; 성공 시 앱으로 리디렉션합니다. |
| POST | /v1/auth/forgot-password | — | { email }. 이메일 등록 여부와 관계없이 항상 동일한 메시지를 반환합니다. |
| POST | /v1/auth/reset-password | — | { token, password }. token은 일회용이며 만료됩니다. |
chat
| Method | Path | Auth | 비고 |
|---|
| POST | /v1/chat | session | { model, messages, conversationId?, idempotencyKey }. plain-text response body를 스트리밍합니다. response의 x-conversation-id 헤더가 conversation id를 담고 있습니다. idempotencyKey는 필수입니다 — 동일한 key로 재시도된 request는 절대 다시 청구되거나 provider를 다시 호출하지 않습니다. |
skills
| Method | Path | Auth | 비고 |
|---|
| POST | /v1/skills | session | { name, instruction, input_schema?, output_schema? }. 자신의 계정에 비공개인 Skill을 생성합니다. |
| GET | /v1/skills | session | 자신의 Skill 목록을 조회합니다. |
| GET | /v1/skills/templates | session | 자신의 Skill로 복제할 수 있는 시작용 템플릿 목록을 조회합니다. |
| POST | /v1/skills/templates/:id/duplicate | session | 템플릿을 복사해 자신의 새 Skill을 만듭니다. |
| POST | /v1/skills/import | session | { name, instruction, input_schema?, output_schema?, version? } — GET /v1/skills/:id/export가 생성하는 것과 정확히 동일한 형태이므로 export → import가 round-trip됩니다. 그 외의 필드(id, owner_id, organization_id, allowed_tools)는 즉시 거부됩니다. import된 Skill은 파일에 있던 tool binding을 절대 가져오지 않습니다. |
| GET | /v1/skills/:id | session | 자신이 소유한 Skill과 그 모든 version을 조회합니다. |
| GET | /v1/skills/:id/export | session | import endpoint의 input과 일치하는, 이동 가능한 { name, instruction, input_schema, output_schema, version } 형태를 반환합니다. |
| POST | /v1/skills/:id/versions | session | { instruction, input_schema?, output_schema? }. 새로운 불변 version을 게시합니다. |
| POST | /v1/skills/:id/run | session | { model, input, conversationId?, idempotencyKey }. POST /v1/chat과 동일한 chat pipeline으로 다시 들어가며, input이 하나의 사용자 메시지를 대신합니다 — 동일한 idempotency/quota/ledger 동작을 따릅니다. |
conversations
| Method | Path | Auth | 비고 |
|---|
| GET | /v1/conversations | session | 자신의 대화 목록을 조회합니다. |
| GET | /v1/conversations/:id | session | 하나의 대화와 그 메시지들을 조회합니다. 소유하지 않은 대화에 대해서는 404를 반환합니다. |
files
| Method | Path | Auth | 비고 |
|---|
| GET | /v1/files | session | 자신이 업로드한 파일 목록을 조회합니다. |
| POST | /v1/files | session | Multipart 업로드이며, field 이름은 file입니다. 일반 텍스트, Markdown, PDF, .docx를 최대 20 MB까지 허용합니다. |
| DELETE | /v1/files/:id | session | 소유한 파일을 삭제합니다(storage object + 레코드). |
plans
| Method | Path | Auth | 비고 |
|---|
| GET | /v1/plans | — (공개) | 가격 및 허용된 모델과 함께 플랜 목록을 조회합니다 — 로그인 전에도 가격이 보이도록 의도적으로 공개되어 있습니다. |
billing
| Method | Path | Auth | 비고 |
|---|
| POST | /v1/billing/checkout | session | { planId, provider: "sepay" | "paddle" }. 청구 금액은 항상 서버 측 plan 조회 결과에서 가져오며, client에서 오지 않습니다. Free 및 Enterprise 플랜은 이 방식으로 checkout할 수 없습니다. |
| GET | /v1/billing/quota | session | 현재 일일 quota 한도와 남은 잔액을 조회합니다. |
실행 중인 API에는 두 개의 리소스가 더 존재하지만, 여기서는 고객 대상 표면으로 문서화하지 않습니다: /v1/webhooks/*
(수신 전용이며 SePay/Paddle이 호출합니다 — 사용자가 직접 호출하는 것이 아닙니다)와 /v1/admin/*(내부용, admin
전용)입니다.
