OpenAPI

このドキュメントのすべてのエンドポイントは、機械可読な OpenAPI 3.1 ドキュメントとしても公開されています。表を手作業で書き写す代わりに、コントラクトからツールを動かせます。

コピー	URL	備考
ドキュメント	`https://docs.zelnum.com/openapi.yaml`	このドメイン上で安定して提供されています。このサイトの読者にとっての正規版です。
プラットフォーム	`https://app.zelnum.com/docs/openapi.yaml`	上流です。ドキュメント側のコピーは、これとバイト単位で同一のミラーです。

両方のファイルは同一のドキュメントです。ミラーがあるのは、いま読んでいるホスト上に、ツールが見つけられるパスで仕様を置くためです。

ドキュメントに含まれるもの

項目	数	内容
Servers	1	`https://api.zelnum.com/api/v1`
Paths	10	文書化された9つのエンドポイントと、レガシーのリアルタイムエイリアス
Tags	3	`Common`、`Realtime`、`Bulk` — ナビゲーションが使っているのと同じ区分です
Schemas	9	エラーのエンベロープを含む、リクエストボディとレスポンスボディ
セキュリティスキーム	2	`X-API-Key` と `Authorization: Bearer`

オペレーションレベルの詳細はドキュメント自体にあります。必須ヘッダー、配列の minItems/maxItems、series、mode、status、billing_status の enum、そして deprecated: true フラグが POST /v1/realtime/detect に付いています。

API ツールへの取り込み

Postman — Import → File → openapi.yaml。Postman はベース URL 用の環境変数を持つコレクションを作成します。キーをコレクションレベルの X-API-Key ヘッダーとして設定すると、すべてのリクエストがそれを継承します。

Insomnia — Create → Import From → File を選び、次に X-API-Key をコレクションヘッダーとして追加します。

Bruno / HTTPie / curl ジェネレーター — いずれも OpenAPI 3.1 を直接読み込みます：

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

型付きクライアントの生成

ファーストパーティの SDK はありません — API は HTTPS 上のプレーンな JSON であり、生成されたクライアントは言語の慣習に従うため、通常は手書きのものより適しています。

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

生成されたクライアントはベース URL とセキュリティスキームをドキュメントから読み取るため、実行時に指定するのは API キーだけです。

ミラーの正確さを保つ

ミラーは上流に追従し、ここで編集されることはありません。公開されたコントラクトとそのドキュメントの乖離こそが、このページが防ぐために存在する障害です。そのため、コピーは信頼されるのではなく、上流と照合されます：

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check はネットワークアクセスを必要とし、サイトビルドには意図的に含めていません — プラットフォームホストの一時的な不調でデプロイが失敗してはならないからです。ビルドが強制するのは、不変条件のオフライン側の半分です：このドキュメントが記述するすべてのエンドポイントは、ベンダリング済みのドキュメントに存在しなければなりません。これにより、コントラクトにないオペレーションをページが文書化することはできません。

バージョニングと非推奨化 — レガシーエンドポイントの deprecated フラグがあなたにとって何を意味するか
レスポンス形式 — すべてのエンドポイントが共有するエンベロープ