---
type: developer-guide
service: zindies.co
url: https://zindies.co/build-with-ai
locale: ja
---

# AI で Zindies アプリを作る

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

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

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

## 接続情報

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

- OpenAPI 仕様 (JSON・最優先): https://api.zindies.co/v1/openapi.json
- OpenAPI 仕様 (YAML): https://api.zindies.co/v1/openapi.yaml
- API ドキュメント (Swagger UI): https://api.zindies.co/docs
- 接続情報ディスカバリ (.well-known/mcp.json): https://api.zindies.co/.well-known/mcp.json
- サービス索引 (llms.txt): https://zindies.co/llms.txt
- API ベース URL: https://api.zindies.co/v1
- MCP サーバー: https://mcp.zindies.co/

## 認証

トークンは 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 を使い、個人ツールでも入力欄や安全なストレージから読み込みます。

## CORS (ブラウザ完結アプリ)

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` |

## エンドポイント

**公開 read (認証不要)**

- `GET /v1/creators` — クリエイター
- `GET /v1/creators/:token` — クリエイター
- `GET /v1/creations` — 作品
- `GET /v1/creations/:token` — 作品
- `GET /v1/places` — 店舗
- `GET /v1/places/:token` — 店舗
- `GET /v1/events` — イベント
- `GET /v1/events/:id` — イベント
- `GET /v1/announcements` — Announcement
- `GET /v1/announcements/:id` — Announcement
- `GET /v1/search`

**私領域 (Bearer 必須)**

- `GET /v1/me`
- `GET /v1/me/entities`
- `GET / POST / DELETE /v1/me/favorites`
- `GET /v1/me/collection`
- `GET / POST / DELETE /v1/me/event_participations`
- `GET /v1/me/reservations`

**Anchor 配下の書き込み (scope + Anchor バインディング必須)**

- `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`)

## コンテンツの書き込み (Anchor)

コンテンツの書き込みは 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 でキャッシュできます。

- page (1 始まり・既定 1) と per (既定 12・最大 100) でページネーション
- per は 1 ページあたりの件数 (最大 100)
- random=N (1〜100 のランダム抽出。page / per とは併用不可)
- locale=ja|en|ko|zh-TW でサーバー側翻訳 (既定 ja)
- places の近接検索 — lat / lng / radius_km
- events のフィルタ — from / to (YYYY-MM-DD) / area / kind / event_type=day|period|all
- search は q (2 文字以上必須) / type=creator|creation|place|event|all

レスポンスはすべて JSON です。エラーは { "error": "...", "message": "..." } 形式で、401 = 認証エラー、404 = not_found、400 = パラメータ不正を返します。

## アプリ作成のヒント

- 読み込み中・空・エラーの 3 状態を必ず用意する。
- ページネーションまたは random 表示を実装する。
- 画像は photo_url / photos_urls を使う。
- locale パラメータで多言語表示に対応するとよい。

## やってはいけないこと

- OpenAPI 仕様に無いフィールドやエンドポイントを推測で使わない。
- トークンをソースに埋め込んだり Git にコミットしたりしない。
- 公開エンドポイントに Cookie / credentials を付けない (Bearer のみ)。
- private / 下書き状態のデータを表示しようとしない (API は公開データのみ返す)。