API 레퍼런스
플래그
기능 플래그를 만들고, 읽고, 고치고, 지웁니다.
객체 flag
속성
keystring- 코드에서 쓰는 고유하고 URL에 안전한 식별자.
typeenumboolean,string,number,json중 하나.variationsarray- 가능한 값 목록(순서 유지).
environmentsobject- 환경별 상태, 규칙, 출시 비율.
permanentboolean- 오래된 플래그 목록에서 제외.
JSON
{
"key": "new-checkout",
"name": "New checkout",
"type": "boolean",
"variations": [true, false],
"permanent": false,
"tags": ["payments"],
"environments": {
"production": { "on": true, "rollout": { "percent": 25 } },
"development": { "on": true }
},
"createdAt": "2026-08-02T10:14:00Z"
}플래그 목록
GET
/projects/{project}/flags프로젝트의 플래그를 최신순으로 돌려줍니다.
헤더
Authorizationstring필수Bearer <token>
경로 파라미터
projectstring필수- 프로젝트 id. 예:
prj_8d2kq.
쿼리 파라미터
tagstring선택- 이 태그가 있는 플래그만.
staleboolean선택- 오래된 플래그만.
limitinteger선택기본값:20- 페이지 크기, 1–100.
cursorstring선택- 이전 응답의 커서.
요청
Terminal
curl https://api.shoal.dev/v2/projects/prj_8d2kq/flags?limit=2 \
-H "Authorization: Bearer $SHOAL_TOKEN"TypeScript
import { Shoal } from "@shoal/api";
const api = new Shoal(process.env.SHOAL_TOKEN);
const { data, next } = await api.flags.list("prj_8d2kq", { limit: 2 });Python
from shoal import Shoal
api = Shoal(os.environ["SHOAL_TOKEN"])
page = api.flags.list("prj_8d2kq", limit=2)응답
JSON
{
"data": [
{ "key": "new-checkout", "type": "boolean", "permanent": false },
{ "key": "upload-limit-mb", "type": "number", "permanent": true }
],
"next": "cur_9f2a"
}JSON
{
"error": { "code": "unauthorized", "message": "Invalid API token" }
}플래그 만들기
POST
/projects/{project}/flags모든 환경에 꺼진 상태로 플래그를 만듭니다.
헤더
Authorizationstring필수Bearer <token>
경로 파라미터
projectstring필수- 프로젝트 id. 예:
prj_8d2kq.
본문 파라미터
keystring필수- 소문자, 숫자, 대시.
typeenum필수boolean,string,number,json.variationsarray선택- 불리언이 아닌 플래그는 필수.
tagsstring[]선택- 자유 라벨.
요청
Terminal
curl -X POST https://api.shoal.dev/v2/projects/prj_8d2kq/flags \
-H "Authorization: Bearer $SHOAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "key": "new-checkout", "type": "boolean", "tags": ["payments"] }'TypeScript
const flag = await api.flags.create("prj_8d2kq", {
key: "new-checkout",
type: "boolean",
tags: ["payments"],
});Python
flag = api.flags.create("prj_8d2kq", key="new-checkout", type="boolean", tags=["payments"])응답
JSON
{
"key": "new-checkout",
"name": "New checkout",
"type": "boolean",
"variations": [true, false],
"permanent": false,
"tags": ["payments"],
"environments": {
"production": { "on": true, "rollout": { "percent": 25 } },
"development": { "on": true }
},
"createdAt": "2026-08-02T10:14:00Z"
}JSON
{
"error": { "code": "flag_exists", "message": "A flag with key new-checkout already exists" }
}플래그 수정
PATCH
/projects/{project}/flags/{key}한 환경의 상태, 규칙, 출시 비율을 바꿉니다. 생략한 필드는 그대로 둡니다.
헤더
Authorizationstring필수Bearer <token>
경로 파라미터
projectstring필수- 프로젝트 id. 예:
prj_8d2kq. keystring필수- 플래그 키.
본문 파라미터
environmentstring필수- 환경 키. 예:
production. onboolean선택- 플래그 켜기·끄기.
rollout.percentnumber선택- 첫 변형을 받는 사용자 비율(0–100).
commentstring선택- 감사 기록에 표시. 보호 환경에서는 필수.
요청
Terminal
curl -X PATCH https://api.shoal.dev/v2/projects/prj_8d2kq/flags/new-checkout \
-H "Authorization: Bearer $SHOAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "environment": "production", "rollout": { "percent": 50 }, "comment": "Ramp to 50%" }'TypeScript
await api.flags.update("prj_8d2kq", "new-checkout", {
environment: "production",
rollout: { percent: 50 },
comment: "Ramp to 50%",
});Python
api.flags.update("prj_8d2kq", "new-checkout", environment="production", rollout={"percent": 50}, comment="Ramp to 50%")응답
JSON
{
"key": "new-checkout",
"name": "New checkout",
"type": "boolean",
"variations": [true, false],
"permanent": false,
"tags": ["payments"],
"environments": {
"production": { "on": true, "rollout": { "percent": 50 } },
"development": { "on": true }
},
"createdAt": "2026-08-02T10:14:00Z"
}플래그 삭제
DELETE
/projects/{project}/flags/{key}모든 환경에서 플래그를 지웁니다. 이후 SDK는 대체값을 내보냅니다.
헤더
Authorizationstring필수Bearer <token>
경로 파라미터
projectstring필수- 프로젝트 id. 예:
prj_8d2kq. keystring필수- 플래그 키.
요청
Terminal
curl -X DELETE https://api.shoal.dev/v2/projects/prj_8d2kq/flags/new-checkout \
-H "Authorization: Bearer $SHOAL_TOKEN"TypeScript
await api.flags.delete("prj_8d2kq", "new-checkout");Python
api.flags.delete("prj_8d2kq", "new-checkout")응답
— No Content —