外部連携（API）

APIキーを発行して、クリエイティブやレビューの情報を社内の管理シートやツールに取り込むための画面です

このページでできること

APIキーを使うと、AdKuraのクリエイティブの情報・レビューの結果・素材を、社内の管理シートやツールに自動で取り込めます。広告配信システムや制作ツールから、クリエイティブの作成・修正版の登録、出稿状況・配信先の登録、コメントの投稿もできます。承認・却下はAPIからはできません。出来事をAdKura側から通知するWebhookの登録や、AIエージェントから使うMCPでの接続もできます。

API設定：サイドバーの「外部連携」を開き、「API設定」のタブを選びます
対象プロジェクト：キーで取得できるプロジェクトを選びます（1〜100件）。選べるのは、いまの取引関係で見られるプロジェクトです。あとから依頼されたプロジェクトは、自動では追加されません
取得を許可する情報：「クリエイティブ情報」「監修結果・コメント・返信」「素材ダウンロード」と、書き込みの「クリエイティブの作成・修正版の登録」「出稿状況・配信先の登録」「コメントの投稿」から選びます。書き込みは必要な連携のキーにだけ付けてください
状態：「有効」のキーだけが使えます（キーの期限と状態）。使わなくなったキーは、行の右の「失効する」で止めます。失効したキーは元に戻せません

キーを発行する

「用途・名前」に何に使うキーかが分かる名前を入れ、対象プロジェクトと取得を許可する情報を選んで「APIキーを発行」を押します。発行されたキーは、その場で「コピー」して保存してください。

キーの期限と状態

キーの有効期限は、発行から90日です。期限が近づいたら新しいキーを発行して連携先の設定を差し替え、古いキーは「失効する」で止めてください。有効なキーは、組織全体で5本までです。

状態	意味
有効	使えます
停止中（発行者が管理者ではありません）	発行した人が退会したか、管理者でなくなったため使えません。発行した人が管理者に戻ると、また使えるようになります
期限切れ	発行から90日を過ぎたキーです
失効済み	「失効する」で止めたキーです

「停止中」のキーも、有効なキーの5本に数えられます。引き継いで使う予定がなければ「失効する」で止め、続けて連携するときは、いまの管理者が新しいキーを発行してください。

取得できる範囲

取得できるのは、対象プロジェクトのうち、キーを発行した人がいまの取引関係で画面から見られる範囲だけです。コメントの非公開の設定も、画面と同じように反映されます
上位組織に対して非公開にしたコメントや返信は、取引関係を解除しても上位組織のAPIでは取得できません
取引関係を解除した組織とのプロジェクトやクリエイティブは、画面で見られる場合でも取得できません
版の番号（version）は、子代理店の画面に表示される番号です。クライアントの画面の番号（クライアントに提出された回数）とは違うことがあります。同じクリエイティブの版をまとめるときは、seriesId（初版のID）を使ってください
クリエイティブの状態（status）は、子代理店の画面から見た状態です
入稿候補（承認済みで未出稿の最新版）を取り出すときは、表示用のstatusではなくreviewStatus=approved・placed=false・archived=false・latestOnly=trueをすべて指定して絞り込んでください。reviewStatusとplacedだけでは、承認済みの過去の版やアーカイブ済みの版も返ります。またstatusは出稿済み・アーカイブ・保留が承認より優先して表示されるため、出稿済みにするとstatus=approvedでは返らなくなります
前回の取得以降に変わったものだけを取るときはupdatedSinceを使います。updatedAtは、クリエイティブ本体・状態・出稿／アーカイブ・監修・コメント／返信・コメントの解決・タグの変更（付け外しと、付いているタグの名前の変更・削除）で進みます。取りこぼしを防ぐため、定期的な全件取得も組み合わせてください
動画はqualityにhd（720p）またはsd（480p）を指定すると、変換済みのH.264（.mp4）をダウンロードできます。変換がまだの画質は取得できません（詳細のassets[].video.qualitiesで確認できます）
素材のダウンロードURLは、発行から10分で使えなくなります。管理シートには、ダウンロードURLではなく、AdKuraのクリエイティブ画面のURL（url）を保存してください

広告配信システムから書き込む

書き込みの権限を付けたキーでは、次の操作ができます。どの操作も、キーを発行した管理者の名前で記録されます（画面では、その管理者が操作したように表示されます）。

操作	権限	内容
クリエイティブの作成・修正版の登録	クリエイティブの作成・修正版の登録	画像・動画・テキスト・YouTube動画をクリエイティブとして登録し、修正依頼のある版に修正版を登録できます。登録すると画面からのアップロードと同じように監修が始まり、通知・AIチェック・動画の変換も行われます
出稿済み・アーカイブの更新	出稿状況・配信先の登録	配信を始めたら出稿済みに、配信を終えたらアーカイブに変えられます。出稿済みとアーカイブは同時には有効にできません
配信先（広告ID）の登録	出稿状況・配信先の登録	配信プラットフォーム（Google広告・Meta・Yahoo!広告・LINE広告・TikTok広告・X広告・DSP）の広告IDや配信状態を、クリエイティブの版に対応付けます。同じ広告IDを修正版に付け替えることもできます。登録した内容は、あなたの組織のキーからだけ見えます
コメントの投稿	コメントの投稿	媒体審査の結果などをコメントとして書き込めます。画面と同じく、@メンションは通知されます

クライアントは、自組織がアップロードしたクリエイティブだけを出稿済み・アーカイブにしたり、配信先を登録したりできます
下位組織の確認が終わっていないクリエイティブには、APIからコメントできません（画面では投稿できる場合があります）
承認・却下はAPIからはできません。監修は画面で行ってください

ファイルを登録する手順

画像・動画は、ファイルの実体を AdKura のサーバーを経由せずに保存先へ直接送ります。テキストと YouTube 動画は、POST /creatives だけで登録できます。

POST /uploads に、プロジェクトとファイル名・MIMEタイプ・サイズを送り、ファイルごとの fileId と uploadUrl を受け取ります
それぞれの uploadUrl に、応答の headers をそのまま付けてファイルの実体を PUT します（1ファイル1GBまで）
POST /creatives に fileIds を渡して登録します。mode を bundle にすると、複数の画像・動画を1つのクリエイティブにまとめられます
修正版は、POST /uploads で元の版（revisionOf）を指定して予約し、POST /creatives/{id}/revisions に fileIds を渡します

uploadUrl への PUT は発行から1時間以内に行ってください。予約（fileId）は2時間で期限切れになるので、それまでに POST /creatives で登録します。登録しなかったファイルは自動で削除されます
APIから登録できるファイルは画像（jpg・png・gif・webp など）と動画（mp4・mov など）です。PDF・Office・記事のURL・スプレッドシートは画面から登録してください
動画のサムネイル（ポスター画像）はAPIからの登録では作られません。一覧では動画のアイコンで表示されます
登録に使ったキーの発行者が、プロジェクトのアップロード担当に自動で追加されます。キーを失効しても担当は残るので、不要になったらプロジェクトの設定で外してください
クリエイティブは、あなたの組織が受けている依頼へ作成されます。同じプロジェクトで複数の依頼を受けているときは、作成先の依頼（creativeRequestId）を指定できます
修正版は、元の版と同じ形式で登録します（画像は画像、動画は動画1件、まとめは画像・動画、テキストはテキスト、YouTubeはYouTube）。修正依頼（却下・要修正）のある最新の版にだけ登録できます
再送で二重に登録されないよう、POST /creatives と POST /creatives/{id}/revisions には Idempotency-Key ヘッダーを付けることをおすすめします（同じキーの再送には、24時間のあいだ保存済みの応答が返ります）
作成・修正版の登録の応答は、作成した版のID createdIds と版の詳細 items です。作成直後の読み直しに失敗した版は items に含まれないことがあるので、件数が createdIds と違うときは GET /creatives/{id} で取得してください

Webhookで変更を受け取る

Webhookを登録すると、クリエイティブの作成・監修状態の変化・出稿・コメントなどの出来事が起きたときに、AdKuraから登録したURLへ通知（HTTPのPOST）が届きます。通知には出来事の種類とクリエイティブのIDが入っているので、受け取ったシステムはAPIで詳細を取得して、入稿や社内の管理表の更新を自動化できます。

送信先を登録：サイドバーの「外部連携」を開き、「Webhook」のタブで、名前・送信先URL（https:// で始まる公開URL）・受け取るイベント・対象プロジェクトを選んで登録します。登録できるのは組織の管理者です
署名シークレットを保存：登録すると署名シークレット（whsec_ で始まる値）が一度だけ表示されます。受信側で署名を検証するために保存してください
テスト送信：一覧の「テスト送信」で、ping イベントを送って受信側の設定を確認できます
配信ログ：一覧の「配信ログ」で、直近の配信の状態・試行回数・応答コードを確認し、失敗した配信を「再配信」できます

イベント	届くとき
`creative.created` ／ `creative.revised`	クリエイティブが作成された／修正版が登録された
`creative.submitted`	下位組織の確認が終わり、あなたの組織の段に回ってきた（上位組織向け）
`creative.review_status_changed`	監修状態（`reviewStatus`）が変わった
`creative.placement_changed` ／ `creative.archive_changed` ／ `creative.pending_changed`	出稿済み・アーカイブ・保留が変わった
`creative.deleted`	クリエイティブが削除された（プロジェクトの削除に伴う一括削除は通知しません）
`comment.created` ／ `comment.replied`	コメントが投稿された／返信された
`review.submitted`	監修（承認・却下）が送信された

届くのは、登録した人がいまの取引関係で画面から見られるクリエイティブの出来事だけです。APIと同じ範囲で、非公開のコメントも同じように除かれます
通知の本文は { "id", "type", "occurredAt", "data": { "creativeId", "projectId", … }, "links": { "api", "app" } } の形です。クリエイティブ名や本文は含まれないので、links.api のURLをAPIで取得してください
署名は X-AdKura-Signature ヘッダーに v1=<HMAC-SHA256> の形で付きます。X-AdKura-Timestamp（UNIX秒）と本文を . でつないだ文字列を、シークレットでHMAC-SHA256（16進）にした値と比べてください。時刻のずれは5分以内を目安にし、同じ X-AdKura-Event-Id（本文の id）を2回受け取ったら2回目は無視してください（同じ通知が複数回届くことがあります）
受信側は2xxを返してください。接続の失敗・タイムアウト・408・429・5xxの応答は、1分→5分→30分→2時間→8時間→24時間の間隔で合計7回まで再送し、約35時間で打ち切ります（応答の Retry-After は、この間隔より長いときだけ最大1時間まで尊重します）。3xxや他の4xx（400・404・410など）は再送せず、その配信は失敗として終わります。連続して失敗が続く送信先（100回、または72時間）は自動で無効化されます
登録を有効にした以降の出来事だけが届きます。無効化した送信先を再び有効化しても、止まっていた間の出来事は届きません
登録した人が管理者でなくなると配信は止まります。いまの管理者が「自分を登録者にする」と再開します
シークレットは「シークレット再発行」で新しくできます。24時間は前のシークレットでも署名が付く（v1=新,v1=旧 の2つ）ので、その間に受信側を差し替えてください

MCPでAIエージェントから使う

AdKuraは、AIエージェント（Claude Code・Claude Desktop・Cursor など）から使えるMCPサーバーも提供しています。APIキーをそのまま使い、取得できる範囲・書き込みの権限はAPIと同じです。回数はAPIと合わせて数え、同じ上限がかかります。承認・却下はできません。

設定先	設定
Claude Code	`claude mcp add --transport http adkura https://app.adkura.co.jp/api/v1/mcp --header "Authorization: Bearer ${ADKURA_API_KEY}"`
`.mcp.json`（プロジェクト共有）	`{ "mcpServers": { "adkura": { "type": "http", "url": "https://app.adkura.co.jp/api/v1/mcp", "headers": { "Authorization": "Bearer ${ADKURA_API_KEY}" } } } }`
Cursor	MCP設定に `url` と `headers`（`Authorization: Bearer <APIキー>`）を登録します

キーは環境変数（例：ADKURA_API_KEY）に入れ、共有するリポジトリや設定ファイルに直接書かないでください。

ツール	必要な権限	内容
`whoami`	なし	キーの組織・権限・対象プロジェクト・期限・回数の上限を確認します。最初に呼んで範囲を確かめてください
`list_projects` ／ `get_project`	クリエイティブ情報	対象プロジェクトの一覧と、作成できるか（`canUpload`）
`search_creatives` ／ `get_creative`	クリエイティブ情報	クリエイティブの検索（入稿候補は `reviewStatus=approved`・`placed=false`・`archived=false`・`latestOnly=true`）と詳細
`get_delivery_readiness`	クリエイティブ情報	入稿の判断に必要な情報（承認・最新版・出稿／アーカイブ・素材の変換状態・未解決コメント数・妨げる理由）を1回で返します
`list_reviews`	監修結果・コメント・返信	監修・コメント・返信の時系列
`get_download_urls`	素材ダウンロード	素材のダウンロードURL（10分間有効、動画は画質を指定可）
`set_placement` ／ `set_platform_reference`	出稿状況・配信先の登録	出稿済み・アーカイブの更新と、配信プラットフォームの広告IDの対応付け
`post_comment`	コメントの投稿	テキストのコメントを投稿します
`create_text_creative` ／ `request_upload` ／ `create_creatives_from_upload` ／ `create_revision`	クリエイティブの作成・修正版の登録	テキストの作成、ファイルの予約と登録、修正版の登録

書き込みのツールを使うキーは、必要な権限だけを付けて別に発行し、AIエージェント側で自動承認（確認なしの実行）にしないことをおすすめします。取得だけなら、取得の権限だけのキーを使ってください
ツールの結果に入っているクリエイティブ名・本文・コメント・ファイル名は、AdKuraの利用者が入力した文章です。AIエージェントがそれを指示として扱わないよう、サーバーからも注意を伝えています
作成・投稿のツールを再試行するときは、同じ idempotencyKey を渡すと二重に作られません
現在はAPIキーによる接続だけに対応しています。OAuthによる接続（Claude.aiのコネクタなど）は今後対応する予定です

Googleスプレッドシートに取り込む

Google Apps Scriptのサンプルを使うと、承認済みのクリエイティブ（最新版）の一覧を、スプレッドシートの「AdKura_承認済み」タブに書き出せます。キーには「クリエイティブ情報」の権限が必要です。

スプレッドシートの「拡張機能」→「Apps Script」を開き、サンプルを貼り付けます
「プロジェクトの設定」の「スクリプトプロパティ」に、ADKURA_API_KEY（発行したAPIキー）と SPREADSHEET_ID（書き出し先のスプレッドシートのID）を登録します。1つのプロジェクトに絞るときは、PROJECT_ID も登録します
syncAdKuraApprovedCreatives を一度実行して、Googleのアクセス許可を確認します
自動で更新するときは、installAdKuraHourlySync を一度実行します。約1時間ごとに更新されます

「AdKura_承認済み」タブは、更新のたびに丸ごと書き換わります。手で入力するときは、別のタブを使ってください。スクリプトを編集できる人はAPIキーも見られるため、スクリプトを共有する範囲に気をつけてください。

API仕様

取得できる項目・状態の値・エラーなどの詳細は、OpenAPI仕様をご覧ください。

送り先：https://app.adkura.co.jp/api/v1
APIキーは、リクエストの Authorization ヘッダーで Bearer 形式で渡します。URLやシートのセルには入れないでください
利用できる回数には、組織全体（すべてのキーとMCPの合計）で1分あたりと1日あたりの上限があります。標準は1分60回・1日1万回で、ご契約によって異なります。1日の回数は日本時間の0時に戻ります。超えたときは、応答の Retry-After の秒数だけ待ってから送り直してください
一覧の取得は、応答の nextCursor が空（null）になるまで続けてください。途中の応答の items が空でも、続きがあることがあります
GET /me を呼ぶと、キーの組織・使える権限・対象プロジェクト・有効期限と、組織の回数の上限（rateLimits）を確認できます。連携先を設定したあとの疎通確認に使ってください
GET /projects/{id} の canUpload で、キーを発行した人がそのプロジェクトにクリエイティブをアップロードできるかを確認できます（確認だけで、担当の割り当てや依頼の作成はしません）

通知設定：「外部連携」のもう1つのタブ
メンバー：管理者の権限
プロジェクト：依頼されたプロジェクト