Agentic API のアクションを呼び出す

OAuth アクセストークンを発行し、公開カタログでアクションを探して POST /api/v1/actions/<id> で呼び出します。

4ステップcurlHTTP

利用場面

作業内容

エージェントやスクリプトなどの機械的な呼び出し元から、Trustvice の機能をひとつ使いたい場合です。どの機能も、固定の ID、型付きの入力、共通のレスポンスエンベロープを持つ登録済みアクションなので、ひとつのリクエスト形式ですべてに対応できます。

事前の準備

始める前の準備

アカウント: Trustvice のワークスペース
認証情報: OAuth アクセストークン
ほかに必要なもの: ワークスペースに登録済みの OAuth クライアント（tvc_… の ID とそのシークレット）
curl

コードはシークレットを環境変数から読み込みます。シェルかシークレットストアに保管し、コミットするファイルには決して書かないでください。アクションの呼び出しでは X-Workspace-Id も送ります。

手順の流れ

手順

アクセストークンを発行する
OAuth クライアントの ID とシークレットを client_credentials でアクセストークンに交換します。トークンの有効期間は 1 時間（expires_in: 3600）で、クライアントの権限スコープを持ちます。TRUSTVICE_TOKEN としてエクスポートしてください。
```
curl -sS -X POST https://api.trustvice.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"tvc_…\",\"client_secret\":\"$TRUSTVICE_CLIENT_SECRET\"}"
```
```
POST /api/v1/oauth/token
{ "grant_type": "client_credentials",
  "client_id": "tvc_…", "client_secret": "…" }
```
アクションを探す
登録済みアクションの公開カタログは GET /api/v1/actions で、認証なしで取得できます。アクション ID は <domain>.<noun>.<verb> の階層形式です。各アクションの入力スキーマと権限は API リファレンスに載っています。
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```
呼び出す
アクションの入力を JSON で POST /api/v1/actions/<action-id> に送ります。アクセストークンとワークスペース ID を付けてください。ワークスペース API キーはここでは意図的に拒否されます。API キーが与えるのはワークスペースへのアクセスであって、エージェントの意図ではないためです。
```
curl -sS -X POST https://api.trustvice.com/api/v1/actions/<action-id> \
  -H "Authorization: Bearer $TRUSTVICE_TOKEN" \
  -H "X-Workspace-Id: ws_…" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```
```
POST /api/v1/actions/<action-id>
Authorization: Bearer <oauth-access-token>
X-Workspace-Id: ws_…
Content-Type: application/json

{ …input fields… }
```
エンベロープを読む
まず ok を確認します。成功時の出力は data に、失敗時は error に機械可読な code と人が読める文が入ります。ドメインの 404 や 422 は製品としての回答であり、通信エラーではありません。

転載元の資料: /docs/actions

出力サンプル

返される内容

どのアクションも同じエンベロープで応答します。ok: true と data、または ok: false と error のコードとメッセージです。

JSON

{ "ok": true, "data": { …action output… } }

{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }

証明内容

頼りにできること

誤った、または欠けた認証情報には明確な 401 unauthenticated が返り、中途半端に認証されたリクエストにはなりません。
権限が足りない場合は 403 permission_denied が返り、必要だった権限が正確に示されます。
アクションは REST、MCP、エージェントスキルのいずれのトランスポートでも同じように動きます。

前提にしてはいけないこと

再試行が安全であること。Idempotency-Key ヘッダーを受け付けるのは、冪等とされたアクションだけです。
どのアクションも 1 回目の呼び出しで実行されること。破壊的なアクションと課金に関わるアクションは、まず 412 confirmation_required を返します。

上記の内容はすべて、このページからリンクしている Trustvice のドキュメントに基づいています。ドキュメントのほうが詳しい場合は、そちらが基準です。

次に進む

次の手順

破壊的なアクションを確認する

412 confirmation_required に対応します。確認トークンを発行し、X-Trustvice-Confirmation を付けて呼び出しをやり直します。

4ステップcurl · HTTP

MCPアプリ

MCP クライアントをつなぐ

https://mcp.trustvice.com/mcp の Trustvice MCP サーバーを Claude Code、Cursor、VS Code に追加します。

2ステップClaude Code · Cursor · VS Code

レシートを検証

ブラウザーでレシートを検証する

Trustvice の署名付きレシートを /verify に貼り付け、Ed25519 署名をご自身のブラウザーで確認します。

3ステップ

メール配信

レシピ新着情報

新しいレシピをメールで

レシピ集にレシピを追加したときだけ、短いメールを1通。ほかのメールは送らず、どのメールからも配信停止できます。

Agentic API から始めましょう。

登録済みアクションごとに POST エンドポイントがひとつあり、REST でも MCP でも同じように動きます。ドキュメントには各アクションの入力と権限が載っています。

アクションのドキュメントを読む API リファレンスを開くレシートを検証 →