AI で Zindies アプリを作る

Zindies の公開 API (OAuth / REST) を使って、クリエイターや店舗が自分用のアプリ (主に UI) を作るための AI 向けガイドです。

原則として依存の少ない単一 HTML + JavaScript で動き、ファイルを開けばすぐ試せる成果物を作ります。

主な読み手は AI コーディングエージェントです。クリエイターや店舗が「自分専用の小さなツール」を素早く作って使うことを想定しています。

AI / クローラ向けの Markdown 版はこちら → /build-with-ai.md

接続情報

まず OpenAPI 仕様を取得し、エンドポイント・パラメータ・レスポンスはそこを唯一の正としてください。フィールド名を推測で作らないこと。

トークンは 2 種類あります。用途に合わせて選んでください。

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 トークンのみ (Cookie 不要) です。

範囲	許可メソッド	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 = パラメータ不正を返します。