REST API 개요·인증·한도

REST API는 OasisW 프로젝트의 에셋·씬·체크포인트·빌드를 프로그램에서 읽고 쓰는 HTTP 인터페이스입니다. 스크립트 파일을 외부 편집기나 빌드 도구에서 올리거나, 공개한 앱 목록을 가져오는 데 씁니다. 에디터로 게임을 만드는 데는 필요하지 않습니다.

기본 주소

https://oasisw.ai/api/rest

토큰 만들기

1. oasisw.ai 대시보드 왼쪽에서 설정을 누릅니다.
2. API 토큰 묶음의 토큰 발급을 누릅니다. 묶음에는 나만 보임 표시와 "관리하는 워크스페이스까지, 내가 열 수 있는 프로젝트 전부에 닿습니다."라는 설명이 있습니다.
3. API 토큰 발급 창의 토큰 이름에 어디에 쓸 토큰인지 적습니다(1~40자, 예: 빌드 스크립트). 발급을 누릅니다.
4. 지금 복사해 두세요. 창을 닫으면 다시 볼 수 없습니다.와 함께 영문 소문자·숫자 32자 토큰이 나옵니다. 복사를 눌러 안전한 곳에 둔 뒤 완료를 누릅니다.

창을 닫으면 목록에는 토큰 이름과 만든 때만 남고, 줄마다 이름 바꾸기와 폐기가 있습니다. 목록 아래에는 모두 폐기가 생깁니다.

토큰 폐기

더 쓰지 않거나 토큰이 새었으면 줄의 폐기를 누르고, "토큰 이름" 토큰을 폐기할까요? 쓰던 곳은 접근이 끊깁니다. 창에서 폐기를 누릅니다. 실측에서 폐기한 토큰으로 바로 다시 호출하자 401이 돌아왔습니다(1회).

API 문서에는 "조직 ACCOUNT의 API Tokens에서 GENERATE TOKEN"이라고 적혀 있지만, 2026-10-29 화면은 위의 설정 → API 토큰 → 토큰 발급이었습니다.

인증

모든 요청의 헤더에 토큰을 넣습니다.

Authorization: Bearer <토큰>

API 문서에는 토큰이 조직의 신원으로 동작하고 조직이 소유한 프로젝트만 보인다고 적혀 있지만, 실측에서는 개인 워크스페이스에서 발급한 토큰으로 내 개인 프로젝트를 읽고 쓸 수 있었습니다. 존재하지 않는 프로젝트 ID로 부르면 404 {"error":"Project not found"}가 왔습니다. 에셋은 브랜치를 가리지 않습니다(API 문서: branchId를 받지만 무시합니다).

오류

오류 응답은 { "error": "..." } 형식입니다.

호출 한도

분당 한도는 세 등급입니다. 각 엔드포인트의 등급은 엔드포인트 레퍼런스에 있습니다.

응답 헤더 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset으로 남은 양을 봅니다. 실측에서 에셋 목록과 씬 목록을 차례로 부르자 X-RateLimit-Limit: 240, X-RateLimit-Remaining이 239, 238로 줄었고, 에셋 파일을 바꾸는 PUT은 120이었습니다. GET /api/rest/ratelimits는 등급별 분당 한도 {"limits":{"normal":240,"strict":10,"assets":120}}를 돌려줍니다. 이 주소만은 토큰 없이도 200이었습니다.

예: 프로젝트의 에셋 목록

curl -H "Authorization: Bearer $OASISW_TOKEN" \
  "https://oasisw.ai/api/rest/projects/<프로젝트 ID>/assets?limit=100"

프로젝트 ID는 에디터 주소 oasisw.ai/editor/<프로젝트 ID>/<씬 ID>의 첫 번째 값입니다. 실측 응답은 다음 모양이었습니다(값 줄임).

{
  "result": [
    { "id": "…", "name": "playHit.js", "type": "script", "state": "ready",
      "preload": true, "file": { … }, "parent": … , … }
  ],
  "pagination": { "skip": 0, "limit": 16, "total": 14 }
}

limit를 주지 않으면 16개씩 옵니다. 전체 수는 pagination.total로 봅니다.

다음으로

• 엔드포인트 레퍼런스