recoup-api

Recoupable API

Recoupable の本番 API を呼び出して、アーティストデータ、ソーシャル指標、組織のコンテキスト、リサーチを取得し、プラットフォームの操作を実行します。

• ベース URL： https://api.recoupable.com/api
• LLM 可読ドキュメント： https://developers.recoupable.com — Mintlify サイトです。エンドポイントの一覧には /llms.txt、すべてのコンテンツには /llms-full.txt を使用してください。また、機械可読なスキーマには、以下に記載された OpenAPI JSON を使用してください。

認証

Recoup は、どちらか一方の認証情報を受け付けます。両方ある場合は、API キーを優先してください。

認証情報	ヘッダー	入手元
RECOUP_API_KEY (recoup_sk_…)	-H "x-api-key: $RECOUP_API_KEY"	API キーのインストール（recoup-setup）／エージェントのサインアップ
RECOUP_ACCESS_TOKEN	-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"	有効期間の短い open-agents サンドボックスのトークン

AUTH 配列を一度作成し、すべての呼び出しで再利用してください。

if [ -n "$RECOUP_API_KEY" ]; then
  AUTH=(-H "x-api-key: $RECOUP_API_KEY")
elif [ -n "$RECOUP_ACCESS_TOKEN" ]; then
  AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN")
else
  echo "No Recoup credential set — ask the user to authenticate; do not retry blindly." >&2
fi
# Use as:  curl -sS "${AUTH[@]}" "https://api.recoupable.com/api/artists/{id}/socials"

どちらも設定されていない場合、ユーザーは認証されていません。再試行するのではなく、サインインするよう伝えてください。（後述の例では Authorization: Bearer $RECOUP_ACCESS_TOKEN を直接使用しています。代わりに API キーを使う場合は、"${AUTH[@]}" に置き換えてください。）

アーティストを扱う — まずモードを選ぶ

アーティストに関するタスクの前に、ユーザーがどのケースを意味しているかを判断してください。ここで推測すると、実在しないアーティストをエージェントが捏造したり、実在するアーティストに架空の人物像を作り上げたりすることになります。

モード	ユーザーの意図…	トリガーとなるフレーズ	対応方法
A · 任意のアーティスト（リサーチ）	自分のアーティストとは限らない、任意のアーティストを調べたい	「Xを調べて」「Xの調子はどう？」「XとYを比較して」	Research エンドポイント（または recoup-artist-research スキル）を使用します。名前から検索でき、ロスターの照合は不要です。
B · 自分のロスターを閲覧	自分のアカウントに登録されているアーティストを一覧表示したい	「自分のロスター」「自分のアーティスト」「誰が登録されてる？」「自分のアーティストから選んで」	以下の ロスターの確認 を実行してから、一覧を提示します。
C · ロスターに登録された特定のアーティスト	自分のアーティストの一人に対して操作したい	「<name> のコンテンツを作って」「<name> のブランドを更新して」	ロスターの確認 を実行し、名前を照合して account_id と行の id を取得します。一致しない場合、そのアーティストはまだロスターに登録されていません（モード D を提案してください）。
D · アーティストを追加	新しいアーティストを登録したい	「アーティスト X を追加／オンボード／作成して」「新しいアーティストを設定して」	recoup-create-artist スキル（8 回の呼び出しチェーン）を使用します。

ロスターの確認（モード B・C）

アーティストが入力済みの artists/ ツリーがある open-agents サンドボックスでは、そのファイルシステムを正とし、API の代わりに recoup-artist-workspace スキルを使用してください。それ以外（API キーのインストール、または artists/ ディレクトリがない場合）は、API から一覧を取得します。

BASE="https://api.recoupable.com/api"   # AUTH set per the Authentication section above

# 1. Whose account is this credential? Sanity-check BEFORE trusting the roster.
curl -sS "${AUTH[@]}" "$BASE/accounts/id"            # -> {"accountId":"…"}

# 2. Organizations on the account
curl -sS "${AUTH[@]}" "$BASE/organizations" \
  | jq -r '.organizations[] | [.organization_id, .organization_name] | @tsv'

# 3a. Artists for one org (preferred when you know the org)
curl -sS "${AUTH[@]}" "$BASE/artists?org_id=$ORG_ID" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'

# 3b. …or every artist the account can see (account-wide)
curl -sS "${AUTH[@]}" "$BASE/artists" \
  | jq -r '.artists[] | [.name, .account_id, .id] | @tsv'

確認済みのフィールド形式（2026-06-07 時点の実データ）：各 org 行には organization_id、organization_name、その行自体の id があります。organization_id の値を org_id として渡してください。各 artist 行には name、account_id、その行自体の id があります。両方のアーティスト ID を取得してください。コンテンツエンドポイントと /api/artists/{…}/socials が必要とするのは account_id で、行の id はアーティストの主キーです。

停止ルール — ロスターを絶対に捏造しない

GET /accounts/id が、メールアドレスが agent+…@recoupable.com のアカウントを返す場合（GET /api/accounts/{accountId} で確認してください）、または organizations と artists の両方が空 ([]) の場合、使い捨てのアカウント／エージェント登録用キーである可能性が非常に高く、ユーザーの実際のアカウントではありません。処理を停止して、その旨を伝えてください。 解決された accountId を示し、実際のアカウントに紐づくキーを提供するか、recoup-setup を実行するようユーザーに依頼してください。タスクを進めるためにアーティスト、人物像、EP、ロスターを捏造してはいけません。ロスターが空なのは、埋めるための白紙状態ではなく、明らかにすべき認証情報の問題です。

組織のスコープ設定（RECOUP_ORG_ID）

サンドボックス内で実行している場合、環境変数として RECOUP_ORG_ID も公開されます。これは、サンドボックスが開かれた組織を示します。アクセストークンはアカウント単位のスコープであり（アカウントが所属するすべての組織を対象とします）、スコープを指定しないリストエンドポイント（GET /api/artists など）で使用すると、このサンドボックスが表す組織だけでなく、そのアカウントのすべての組織の結果が返されます。この不一致はアカウントにとって予想外です。

RECOUP_ORG_ID が設定されている場合は、リスト／クエリエンドポイントのスコープをその値に設定します。

# Artists for this sandbox's org only
curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  "https://api.recoupable.com/api/organizations/$RECOUP_ORG_ID/artists"

Recoup CLI では、対応しているコマンドに --org "$RECOUP_ORG_ID" を渡してください。RECOUP_ORG_ID が設定されていない場合は、open-agents サンドボックス内ではありません。通常どおりアカウント単位のスコープで呼び出してください。

インベントリ — まずファイルシステムを確認し、次に API にフォールバック： artists/ ツリーにデータがある open-agents サンドボックス内では、API を呼び出すのではなく、ローカルのツリーを優先して読み取ってください。サンドボックスではファイルシステムが正しい情報源です（recoup-artist-workspace スキルを参照）。ただし、artists/ ディレクトリがない場合（たとえば、サンドボックス外に API キーをインストールしている場合）は、ファイルシステムから情報を取得できないため、上記のロスターの検出にフォールバックしてください。ファイルシステムが空、または存在しないことだけを根拠に「ロスターは空です」と判断しないでください。まず API で確認してください。

ドキュメントマップ

エンドポイントの全範囲は、以下のセクションに分かれています。このマップを使って適切な領域を選び、すべてを取得するのではなく、その領域の詳細なドキュメントだけを取得してください（エンドポイントの検索を参照）。

アカウントと ID

• アカウント — アカウントの作成／取得／更新、アカウントへのアーティストの追加
• 組織 — 組織の作成／一覧表示、組織へのアーティストの追加
• ワークスペース — ワークスペースの作成
• サブスクリプション — サブスクリプションの取得、Stripe のチェックアウトセッションの作成
• エージェント — エージェントの登録、メール認証
• 管理者 — 管理者専用：エージェント登録、コーディングエージェント／コンテンツエージェントの Slack タグ、Resend メール、Privy ログイン、サンドボックス統計、組織リポジトリのコミット統計

アーティストとコンテンツ

• アーティスト — 作成／取得／削除、ソーシャル情報の取得、ピン留め／解除、プロフィールの取得（全プラットフォーム対象）、ソーシャル情報のスクレイピング開始
• 投稿 — 全プラットフォームにわたるアーティストの投稿の取得
• コメント — アーティストまたは特定の投稿へのコメントの取得
• ファン — アーティストのファンのソーシャルプロフィールの取得
• 楽曲 — ISRC による楽曲の作成／取得、カタログの管理（CRUD と楽曲の追加／削除）、オーディオ LM による楽曲分析、分析プリセットの一覧表示
• コンテンツ作成 — パイプラインの開始、動画／画像／キャプションの生成、ffmpeg による編集、動画分析、アップスケール、コスト見積もり、音声文字起こし、テンプレート

リサーチ（Songstats + Web）

音楽業界の検索作業の大部分をカバーするセクションです。Songstats を利用します。エンティティ ID は、数値の Chartmetric ID ではなく、短い英数字の文字列です（例：wjcgfd9i）。

• 検出：検索（type=artists|tracks|labels）、プロフィール、類似アーティスト、人名検索、URL による検索
• カタログ：アルバム、トラック、トラックの詳細、トラックのプレイリスト
• メトリクス：プラットフォームのメトリクス（16 ソース）、オーディエンスの人口統計、キャリアのタイムライン、マイルストーン
• サーフェス：プレイリストへの掲載状況
• インサイト：AI インサイト、ソーシャル URL
• Web：情報の補完、URL の抽出、詳細なリサーチ、Web 検索

Songstats への移行に伴い削除済みです（呼び出すと 404 が返されます）：discover、rank、リスナーの cities、charts、playlist（単数形）、venues、radio、festivals、genres、curator、instagram-posts。地理情報は audience から、検出情報は similar と web から取得できるようになりました。

ソーシャル連携

• ソーシャルメディア — プロフィールからソーシャル投稿を取得し、スクレイピングを実行します
• Instagram 連携 — コメント、プロフィール（一括）
• Spotify 連携 — 検索、アーティスト、アーティストのアルバム、アーティストの人気楽曲、アルバム
• Twitter/X 連携 — ツイートの検索、トレンドの取得
• コネクター — サードパーティの OAuth 連携を一覧表示、認証、切断します
• コネクターのアクション — 共有接続を介して外部操作（Google Docs/Sheets/Drive の編集、Gmail、TikTok、Instagram）を実行します。以下のセクションを参照してください。
• Apify 連携 — スクレイパーの実行結果
• 文字起こし — Whisper による音声の文字起こし

チャットとエージェント

• チャット — チャットの作成／取得／削除、メッセージ、AI による生成／ストリーミング（Vercel AI SDK 互換）、更新、コピー、圧縮
• コンテンツエージェント — Slack ウェブフック＋タスクコールバック（内部用）
• Pulses — パルスの一覧表示／更新
• 通知 — 認証済みアカウントに通知メールを送信します
• タスク — スケジュールされたタスクの作成／取得／更新／削除、タスク実行履歴の取得
• 画像生成 — 単独の AI 画像生成（コンテンツ作成のスコープ内でも利用可能）

開発者向けとインフラストラクチャ

• サンドボックス — サンドボックスの作成／セットアップ／一覧表示／削除、ファイル内容の取得、ファイルのアップロード、スナップショットの更新

ガイド（エンドポイント以外のページ）

認証 · CLI · MCP · クイックスタート。

OpenAPI 仕様

主要セクションの機械可読スキーマ：accounts.json、social.json、releases.json、research.json、content.json（https://developers.recoupable.com/api-reference/openapi/<name>.json で提供）。

エンドポイントを見つける

セクションがわかったら、インデックス全体ではなく、そのセクションのドキュメントだけを取得します。例：

# Find the exact path + params for a specific endpoint
curl -s https://developers.recoupable.com/llms-full.txt | grep -A 30 -i "similar artists"

# Pull the OpenAPI schema for one area
curl -s https://developers.recoupable.com/api-reference/openapi/research.json | jq '.paths | keys'

正確なパス、パラメーター名、レスポンス形式を推測しないでください。まず該当するセクションを取得してください。

リクエストの例

# Get all socials for an artist
curl -sS -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" \
  "https://api.recoupable.com/api/artists/{artistId}/socials" | jq

サンドボックスには jq がプリインストールされています。

複数ステップのワークフロー

特定の順序が必要な複数エンドポイントのシーケンスでは、自分で手順を考案するのではなく、公開されているワークフローガイドに従ってください。ガイドには、各ステップで呼び出すエンドポイント、次のステップのために記録する内容、サンドボックス環境では意図的に省略する手順が記載されています。

ワークフロー	ガイド	実行ツール
新しいアーティストの作成と調査（完全な情報拡充の流れ — POST artist、Spotify マッチング、プロフィール／ソーシャル／ナレッジ、Songstats のプロフィール／キャリア／プレイリストとウェブを使った構造化調査、KB の統合）	https://developers.recoupable.com/workflows/create-artist	recoup-artist-workspace スキル — RECOUP.md チェックリストファイルを作成し、各ステップの完了時にチェックを入れます

ワークフローガイドを読み込むきっかけ： 「新しいアーティストを作成」「X をオンボーディング」「このアーティストを追加」のような表現、または完了に複数のエンドポイントが必要なリクエスト。

create-artist の手順では、最初に recoup-artist-workspace スキルを呼び出してください — このスキルは各ワークフロー手順にチェックボックスを1つずつ設けた artists/{slug}/RECOUP.md を作成し、エージェントはそのファイルに沿って実行します（各ステップの後にチェックを入れ、出力を frontmatter に保存します）。上記のワークフローガイドは各ステップのリクエスト形式を curl ごとに確認するためのリファレンスですが、完了状況の正本はチェックリストです。この手順は8回の連続した呼び出しで構成されており、いずれかを省略するとアーティスト情報が不完全なままになります。

コネクターアクション（Google Docs/Sheets/Drive、Gmail、TikTok、Instagram）

Recoup の外部で読み書きする場合（URL で Google ドキュメントを編集する、サンドボックスのファイルを Drive と同期する、メールを送信する、TikTok に投稿するなど）は、次の 2 つのエンドポイントを使って、プラットフォーム共通のサードパーティ接続を利用します。

• GET /api/connectors/actions — slug、description、parameters JSON Schema、connectorSlug、isConnected を含む、利用可能なすべてのアクションのカタログです。ドキュメントを参照してください。
• POST /api/connectors/actions — スキーマに合った parameters を指定し、actionSlug でアクションを 1 つ実行します。ドキュメントを参照してください。

スラッグは常にUPPERCASE_SNAKE_CASEです（例：GOOGLEDOCS_INSERT_TEXT_ACTION、GMAIL_FETCH_EMAILS）。認証には同じ RECOUP_ACCESS_TOKEN Bearer を使います。実行前に必ずカタログから parameters のスキーマを取得してください。Composio の形式はアクションごとに異なります。

実例：Google ドキュメントとサンドボックスのファイルの同期

ユーザーが docs.google.com/document/d/{ID}/edit の URL を貼り付けた場合は、ID を抽出し、用途に合った Google Docs アクションを選びます。読み取りには GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT、ドキュメント全体の置き換えには GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN、インデックス位置への挿入には GOOGLEDOCS_INSERT_TEXT_ACTION、検索と置換には GOOGLEDOCS_REPLACE_ALL_TEXT を使います。

DOC_ID=$(echo "$DOC_URL" | sed -nE 's|.*/document/d/([^/]+).*|\1|p')
EXEC="https://api.recoupable.com/api/connectors/actions"
AUTH=(-H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" -H "Content-Type: application/json")

# Read the doc into a local file.
curl -sS -X POST "${AUTH[@]}" "$EXEC" \
  -d "$(jq -n --arg id "$DOC_ID" '{actionSlug:"GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT", parameters:{document_id:$id}}')" \
  | jq -r '.result.data.text' > artists/$ARTIST_SLUG/notes.md

# (edit notes.md locally — agent edits, git diff, etc.)

# Push it back, replacing the doc's content.
curl -sS -X POST "${AUTH[@]}" "$EXEC" \
  -d "$(jq -n --arg id "$DOC_ID" --rawfile md artists/$ARTIST_SLUG/notes.md \
        '{actionSlug:"GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN", parameters:{document_id:$id, markdown_content:$md}}')"

Google ドキュメントとローカルファイルは、同じコンテンツを異なる形で表示したものです。ローカルコピーは、アーティストの他のワークスペースファイルと一緒にコミットしてください。

トリガーの目安： 外部 URL（docs.google.com、drive.google.com、sheets.google.com）、または「このドキュメントを編集」「メールを送信」「TikTok に投稿」などのフレーズ。内部の Recoup リソース（アーティスト、ソーシャル、リサーチ）には、上記の Docs Map に記載されている専用エンドポイントを使います。

トラブルシューティング

エラー	意味	対処方法
401	トークンがない、無効、または期限切れです	RECOUP_ACCESS_TOKEN が設定されていることを確認してください。プロンプトを長時間実行している場合は、ユーザーに再送を依頼してください
403	ユーザーにリソースへのアクセス権がありません	問い合わせ対象の組織／アーティストに対する権限がユーザーにあることを確認してください
404	エンドポイントが見つかりません	上記の Docs Map を再確認してください。エンドポイントが移動または改名された可能性があります
5xx	サーバーエラーです	1 回再試行してください。解消しない場合は、ステータスをユーザーに伝えてください

このスキルを使用しない場合

• サンドボックス内のファイルを読み書きする場合は、ファイルシステムツールを使います。
• Songstats、Chartmetric、Spotify などのサードパーティ API を直接呼び出す場合は、上記の Recoup Research エンドポイントを優先してください（認証付きで、現在設定されているリサーチプロバイダーである Songstats を利用します）。専用スキルがある場合は、そちらを使ってください。
• ユーザーの Git リポジトリの内容を読む場合は、すでに作業ディレクトリにマウントされています。