---
sidebar:
  order: 1
title: "HTTP API"
description: "既存のHTTP APIで認証し、ツールを検出して変更を確定します。"
---

製品APIのリクエストは、`https://influence.so`などの信頼できるInfluenceオリジンに送信します。ドキュメントのドメインでは製品APIのリクエストを受け付けません。以下のパスをそのまま使い、クエリパラメータは付けないでください。

## 必要な権限のAPIキーを作成する

[Influenceの設定](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer)から「アプリと自動化」→「APIキー」を開き、必要な権限と有効期限を選びます。キーは一度しか表示されません。シークレットストアに`PUBLISH_API_TOKEN`として保存してください。`Authorization: Bearer …`で送信し、URL、リクエスト本文、チャットには含めないでください。不要になったら失効させます。

## ツールを検出してデータを読み取る

`PUBLISH_API_URL`に信頼できるオリジンを設定します。以下の例は、プロセスに`PUBLISH_API_TOKEN`が渡されていることを前提とします。`accountList`には`integrations:read`が必要です。次のページは返されたページング用フィールドに従って取得してください。

```sh
export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'
```

## リクエストのパス

| メソッド | パス | 用途 |
| --- | --- | --- |
| `GET` | `/api/v1/tools` | この認証情報で利用できるツールを取得します。 |
| `POST` | `/api/v1/tools/{tool}/call` | 読み取り専用ツールを呼び出します。 |
| `POST` | `/api/v1/tools/{tool}/prepare` | 指定どおりの変更を実行せずに準備します。 |
| `POST` | `/api/v1/tools/{tool}/confirm` | 準備済みの変更を確定します。 |
| `POST` | `/api/v1/media/import` | 準備済みの小さな画像のバイナリアップロードを確定します。 |

JSONのツールリクエストには`Content-Type: application/json`を指定し、本文には`input`のみを含めます：`{"input":{…}}`。各ツールの入力スキーマは現在のカタログで確認できます。

## 変更を準備して確定する

1. 実行したい操作の正確な入力を`/prepare`に送信します。成功すると`status: "confirmation_required"`、`confirmationCapability`、`expiresAt`、`inputDigest`と、省略可能な`summary`が返ります。
2. 有効期限内に、同じ入力を`/confirm`に送信します。返された確認用の値を`X-Publish-Confirmation`に、クライアントで新たに生成したキーを`Idempotency-Key`に指定します。
3. 入力、確認用の値、キーを一緒に保持します。確認処理が中断されたり結果が不明になったりした場合は、同じリクエストにこの3つを再利用してください。結果不明の操作を復旧するために、代わりの操作を新しく準備しないでください。

冪等性キーは`A–Z`、`a–z`、`0–9`、`.`、`_`、`:`、`-`の16〜200文字で構成します。確認用の値は解釈せずに扱う機密情報です。`/call`や`/prepare`にキーを送っても、確定処理を予約することにはなりません。

リクエストの確定と公開の承認は別の手順です。公開や日時変更では、最新の内容を含む完全なレビューを作成して表示します。テキストの公開には、その後の新たな承認が必要です。画像や動画は、対応するレビュー画面かログイン後のInfluenceで本人が実物を確認して承認する必要があります。レビューの準備だけでは公開されません。次の操作の前に保存された結果を確認してください。`needs_review`では再送せず、何が起きたかを確認します。

## エラーと結果不明の操作を扱う

HTTPステータスと本文の両方を確認します。成功時は`{"ok":true,"toolName":"…","output":{…}}`が返ります。ツールの失敗は`{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}`で、HTTP 200の場合もあります。通信処理の失敗は`{"error":{"code":"…","message":"…","retryable":false}}`となり、`ok`や`toolName`は含まれません。

401は認証が必要な状態です。有効期限や失効を確認してください。権限不足には適切な許可が必要で、リクエストを繰り返しても解決しません。503はその環境でAPIを利用できない状態です。返されたエラーと再試行の案内に従ってください。タイムアウトは変更の失敗を意味しません。確認データを保持し、再送前に現在の状態を読み取ります。受付済み、予約済み、公開済みは異なる結果です。

## メディアをアップロードする

ローカルファイルにはSDKの`uploadMedia`かCLIの`media:upload`を推奨します。同じ分割アップロードツールを使い、再試行でも`clientKey`を保持します。添付できるのは、準備完了で`assetId`を持つ結果だけです。許可されたHTTPSファイル参照には`mediaImport`を使います。ローカルパスはダウンロードURLではありません。

`POST /api/v1/media/import`は既存の小さな画像用の転送に対応します。正確なアップロード記述子で`mediaImport`を準備し、同じバイト列を`application/octet-stream`で送ります。`X-Publish-Confirmation`、`Idempotency-Key`、URIエンコードしたJSON記述子を持つ`X-Publish-Upload`を含めます。サイズとSHA-256がバイト列と一致する必要があります。上限は3 MiBです。それより大きい対応ファイルにはアップロードヘルパーを使ってください。アップロードによって公開が承認されることはありません。

[APIリファレンスを開く](/ja/api-reference)、または[OpenAPI仕様をダウンロードする](/specs/influence.openapi.json)。