AI로 Zindies 앱 만들기

Zindies 공개 API(OAuth / REST)를 사용해 크리에이터와 매장이 자신용 앱(주로 UI)을 만들기 위한 AI용 가이드입니다.

원칙적으로 의존이 적은 단일 HTML + JavaScript로 동작하며 파일을 열면 바로 시험할 수 있는 결과물을 만듭니다.

주요 독자는 AI 코딩 에이전트입니다. 크리에이터와 매장이 자신만을 위한 작은 도구를 빠르게 만들어 쓰는 것을 상정합니다.

AI / 크롤러용 Markdown 버전은 여기 → /build-with-ai.md

연결 정보

먼저 OpenAPI 사양을 가져와 엔드포인트·파라미터·응답의 유일한 정본으로 삼으세요. 필드명을 추측으로 만들지 마세요.

토큰은 두 종류가 있습니다. 용도에 맞게 선택하세요.

PAT — 크리에이터/매장이 자신용 도구를 만들 때 가장 간단합니다. 전체 스코프 상당·Anchor 제약 없음으로 화면에서 발급합니다. (https://zindies.co/user/api)
OAuth 2.0 (Authorization Code + PKCE) — 여러 사용자에게 배포하는 앱용. 스코프와 Anchor(대상 엔티티)로 접근을 제한할 수 있습니다. (https://developer.zindies.co/applications)
scopes: profile:read profile:write creations:read creations:write announcements:read announcements:write events:read events:write analytics:read

토큰을 소스에 직접 적거나 저장소에 포함하지 마세요. 배포 앱은 스코프와 Anchor를 좁힌 OAuth를 사용하고, 개인 도구라도 입력란이나 안전한 저장소에서 읽어 옵니다.

api.zindies.co는 CORS가 설정되어 있어 브라우저 완결 앱에서 직접 호출할 수 있습니다. 인증은 모두 Authorization 헤더의 Bearer 토큰뿐입니다(쿠키 불필요).

범위	허용 메서드	Path
공개 데이터 읽기	`GET`	`/v1/*`
개인 영역 (즐겨찾기·이벤트 참가 등)	`GET / POST / DELETE`	`/v1/me/*`
Anchor 아래 콘텐츠 쓰기 (작품·공지·이벤트)	`GET / POST / PATCH / DELETE`	`/v1/creators/:token/, /v1/places/:token/`

의미 구분: 난색 = 「개별」엔티티(creator / creation / place), 한색 = 「모임·발신」(event / announcement). 상세 필드는 OpenAPI 사양을 참조하세요.

엔티티	역할	주요 필드
크리에이터 `Creator`	크리에이터(만든이). 난색 식별색	`token name title bio photo_url url`
작품 `Creation`	작품(ZINE). 난색 식별색	`token title description released_year price photo_url creators url`
매장 `Place`	매장(취급점). 난색 식별색	`token name address latitude longitude place_type url`
이벤트 `Event`	이벤트(day / period). 한색 식별색	`event_type title started_at start_date place creators booths url`
Announcement `Announcement`	크리에이터/작품/매장의 공지 (polymorphic)	`title body audience announceable_type created_at`

GET / POST / PATCH / DELETE /v1/creators/:creator_token/creations (scope: creations:write)
GET / POST / PATCH / DELETE /v1/creators/:creator_token/announcements (scope: announcements:write)
GET / POST / PATCH / DELETE /v1/creators/:creator_token/events (scope: events:write)
GET / POST / PATCH / DELETE /v1/places/:place_token/announcements (scope: announcements:write)
GET / POST / PATCH / DELETE /v1/places/:place_token/events (scope: events:write)

콘텐츠 쓰기는 creator / place 토큰 아래에 중첩됩니다. OAuth에서는 사용하는 토큰이 대상 크리에이터/매장(Anchor)에 연결되어 있어야 합니다. 대상 토큰은 /v1/me/entities에서 가져올 수 있습니다.

POST   /v1/creators/:creator_token/creations
PATCH  /v1/creators/:creator_token/creations/:id
DELETE /v1/creators/:creator_token/creations/:id

모든 GET 공통 쿼리 규약입니다. 목록은 ETag / Last-Modified를 반환하므로 조건부 GET으로 캐시할 수 있습니다.

응답은 모두 JSON입니다. 오류는 { "error": "...", "message": "..." } 형식이며 401 = 인증 오류, 404 = not_found, 400 = 파라미터 오류를 반환합니다.