API の概要

ベース URL https://api.sofia-post.com/api · OpenAPI ドキュメント

Sofia API を使うと、コードから Sofia のアカウントにアクセスできます。Workspace の店舗、その接続済みネットワーク、メディアライブラリ、投稿、統計です。HTTPS の REST API で、リクエストとレスポンスは JSON です。次のことができます。

• 公開する：今すぐ、日時を指定して、または下書きとして、1 つまたは複数のネットワークに同時に公開します。
• 公開前に確認する：ドライランで、何も書き込まずに、各ネットワークが投稿を受け付けるかどうかが分かります。
• メディアを管理する：ファイルをアップロードするか、URL から店舗のメディアライブラリにインポートします。
• 投稿を追跡する：ネットワークごとの状態、パーマリンク、失敗の理由を取得できます。署名つき Webhook で通知を受けることもできます。
• 統計を取得する：接続済みアカウントごとに、Sofia が収集した最新の数値を取得します。
• ネットワークを接続する：ホスト型のリンクを作成し、オーナーが足りないネットワークを接続できるようにします。

SDK と連携

• `sofia` CLI：npm で sofia-post として公開されている CLI で、ターミナルから Sofia を操作します。
• MCP サーバー：Sofia を AI エージェントにつなぎます。
• Zapier：Sofia の連携は、個人キーで接続します。トリガーは「Post Published」と「Post Failed」、アクションは「Create Post」（公開、予約、下書き保存）、検索は「Find Post」です。Zapier の公開ディレクトリには、まだ申請していません。

認証

すべての呼び出しで、Authorization ヘッダーに Bearer トークンを付けます。Sofia は呼び出しのたびに、トークンに紐づく権限を再確認します。Workspace から外されたメンバーや、取り消された許可は、次のリクエストからトークンが無効になります。

認証の方法は 2 つあります。

API キー

自分の Workspace を自動化するなら、個人キーで十分です。Sofia アプリで設定 › API を開き、個人アクセスタブでキーを作成します。名前、有効期限、権限を選びます。キーは一度しか表示されません。コピーして、コードの中ではなくシークレットの保管庫に保存してください。

設定 › API › 個人アクセスでキーを作成します。キーは、あなたのすべての Workspace で、あなたの代わりに動作します。指定した店舗によって Workspace が決まり、その中でのあなたのロールが、キーにできることを決めます。

キーは、Bearer トークンとして Authorization ヘッダーに入れて送ります。

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

`GET /v1/me` で、キーが誰のために動作するか、その Workspace と権限が分かります。

必要な権限（スコープ）がない呼び出しには、403 insufficient_scope が返ります。

OAuth2 トークン

利用者の Workspace で、利用者のために動作する SaaS プロダクトでは、OAuth クライアントを登録します。ユーザーが自分で選んだ Workspace で、あなたのアプリを許可します。OAuth のアクセストークンは sofia_live_at_… で始まり、有効期間は 1 時間で、使い方は同じです。

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_live_at_…"

ほかの Sofia アカウントが接続するアプリを作りますか？PKCE つきの認可コードフロー、クライアントクレデンシャル、スコープはOAuth2で説明しています。

ベース URL

すべてのエンドポイントは、1 つのベース URL の下にあります。

https://api.sofia-post.com/api/v1

レート制限

Sofia API は、15 分、24 時間、30 日の 3 つの期間でリクエストを数えます。

ヘッダー

すべてのレスポンスで、IETF 形式で残りが分かります。

RateLimit: "15m";r=144;t=43, "24h";r=994;t=13543, "30d";r=9994;t=13543
RateLimit-Policy: "15m";q=150;w=900, "24h";q=1000;w=86400, "30d";q=10000;w=2592000

r は残りのリクエスト数、t は期間がリセットされるまでの秒数、q はクォータ、w は期間の秒数です。

期間の上限に達した時

レスポンスは 429 rate_limit_exceeded で、Retry-After ヘッダーと、上限に達した期間が details に含まれます。その時間だけ待ってから再試行してください。

API を効率よく使う

• 投稿を繰り返し確認する代わりに、Webhook を登録します。
• limit を最大 100 まで使い、一覧を少ないページ数で読み込みます。
• めったに変わらないものはキャッシュします：プラットフォーム、店舗、接続済みアカウント。

エラー

すべてのエラーは、HTTP ステータスと同じ JSON エンベロープで返ります。code はコードが読む契約で、message は人間向けに書かれており、変わることがあります。

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

• details は詳細を示します：拒否されたフィールド、ネットワークの理由、上限に達した期間。
• docUrl は、このページにあるコードの説明へのリンクです。
• requestId はリクエストを識別します。サポートに伝えてください。

エラーコード

投稿が拒否される理由

post_refused は、details[].code に各理由を一覧します。

エラーを処理する

• ロジックは code に基づき、message には決して基づかせないでください。
• 429 は Retry-After の後に、5xx は指数バックオフで再試行します。
• 4xx を同じ内容で再試行してはいけません。まずリクエストを直してください。
• 失敗するたびに requestId をログに記録します。

ページネーション

一覧（GET /v1/posts、GET /v1/media）は、新しい順に 1 ページずつ返ります。limit でページサイズを 1〜100（既定は 20）で指定します。

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTI3VDE1OjExOjU5LjAxN1oiLCIx…"
}

nextCursor を cursor として渡すと、次のページを読めます。nextCursor がなければ、最後に達しています。

let cursor;
do {
  const url = new URL('https://api.sofia-post.com/api/v1/posts');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await globalThis.fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  handle(page.data);
  cursor = page.nextCursor;
} while (cursor);

カーソルは不透明な値です。作成したり変更したりしないでください。Sofia が返していないカーソルには 400 invalid_cursor が返ります。

冪等性

ネットワークエラーのせいで、投稿が作成されたか分からなくなることがあります。POST /v1/posts と POST /v1/media に Idempotency-Key ヘッダーを付け、同じキーで再試行してください。Sofia は最初と同じレスポンスを返し、重複して作成することはありません。

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d @post.json

• 新しい投稿ごとに新しいランダムなキー（UUID）を使い、その投稿の再試行では同じキーを使います。
• 同じキーで異なるボディを送ると、422 idempotency_key_reused が返ります。
• 最初のリクエストが処理中の間は、同じキーに 409 idempotency_in_progress が返ります。少し待って再試行してください。

テストモードとドライラン

ドライラン。POST /v1/posts に ?dry_run=true を付けると、Sofia は実際の投稿と同じチェック（各ネットワークのルール、接続済みアカウント、メディア、日付、プラン）を行い、何も保存も送信もしません。レスポンスの詳細は公開するページにあります。

テストモード。 テストモード（トークンは sofia_test_at_…）で作成したアプリは、本物の Workspace を読み取れますが、書き込みは一切しません。投稿はシミュレートされ、同じルールで判定され、実際の書き込みには 403 live_mode_required が返ります。設定 › API で作成したキーとクライアントはライブモードです。公開せずに確認するには、ドライランを使ってください。