REST API リファレンス

ダッシュボードを経由せず、HTTP で直接 Argosvix のデータを操作できる REST API です。任意のフレームワークや curl から利用できます。

ベース URL

https://ingest.argosvix.com

すべてのエンドポイントはこのオリジン配下です。SDK と同じ宛先で、ダッシュボード（dashboard.argosvix.com）とは別オリジンです。CORS は明示的に許可済のオリジンからのみ受理します。

認証

すべてのエンドポイントは、以下のいずれかの方法で認証します。

Bearer トークン — SDK と同じ argk_... API キーを使い、Authorization: Bearer argk_... ヘッダで送信します。サーバー間の用途で標準的に使う方式です。
セッション Cookie — dashboard.argosvix.com にログイン中のブラウザセッションから直接呼ぶ場合に使います。更新系メソッドでは CSRF 対策として Origin / Referer のチェックがかかります。

ステータスコード:

ステータス	意味
200	成功
201	作成成功
204	成功（応答ボディなし、削除など）
400	バリデーション失敗
401	Bearer またはセッションが未指定・無効
402	プラン制限 — 上位プランで利用できる機能（`reason: "plan_required"`）
403	CSRF 拒否、権限不足
404	リソースが存在しない、または他アカウントのため見えない
409	重複 — 同じリソースが既に存在します
429	レート制限
500	サーバー側の一時障害（リトライ可）
503	一時的に利用できません — 少し待って再試行、続く場合はサポートへ

API キーの権限スコープ（最小権限運用）

API キーには権限スコープを付与できます。スコープは 3 種類です。

read — 読み取りのみ（GET 系と /v1/query/*）
write:records — 記録の取り込み（/v1/ingest、/v1/traces など records 系の書き込み）
write — それ以外の操作系（アラート・プロンプト・評価・ゲートの作成/変更など）

npx @argosvix/cli init が発行するキーは既定で read + write:records の最小権限です（アプリに埋めるキーが漏れても、アラート設定の変更や削除系の操作はできません）。操作系まで必要な場合（MCP からの運用など）はダッシュボードでスコープを広げたキーを別途発行してください。スコープ指定のない既存キーは従来どおり全権として扱われます。

クォータと保持期間:

記録クォータは Free 50,000 件/月、Pro / Team 1,000,000 件/月（Team は seat ごと）。超過すると取り込みは翌月の初めまで 429 を返します（Retry-After ヘッダつき）。読み取り系エンドポイントは超過後も使えます。
保持期間は Free 30 日、Pro / Team 90 日。期間を過ぎた記録は自動削除されます。
個別のレート制限があるエンドポイント（webhook テスト、提案系）は各節に記載しています。

記録の取り込み

`POST /v1/ingest` — 呼び出し記録を送信する

SDK を使わずに、HTTP で直接 LLM 呼び出しの記録を送信します。SDK 未対応の言語（Go / Ruby / Rust など）からの計測はこのエンドポイントを使ってください。1 リクエストに最大 100 件、ボディは最大 1 MiB（超過は 413）。

必須フィールド: id（呼び出しごとに一意。重複 id は上書きされず拒否されます）、provider（openai / anthropic / gemini / mistral）、model、timestamp（ISO 8601）、promptTokens / completionTokens / totalTokens / costUsd / latencyMs（非負の数値）。

任意フィールド: tags（Record<string, string>）、error、errorDetails、traceId / spanId / parentSpanId（トレース連結用）、sessionId。

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/ingest \
  -d '{
    "records": [{
      "id": "call_20260706_0001",
      "provider": "openai",
      "model": "gpt-4o-mini",
      "timestamp": "2026-07-06T00:00:00.000Z",
      "promptTokens": 42,
      "completionTokens": 18,
      "totalTokens": 60,
      "costUsd": 0.0012,
      "latencyMs": 234,
      "tags": {"service": "checkout"}
    }]
  }'

レスポンスは部分成功です。バリデーションに落ちた記録だけが rejected に理由つきで返り、残りは取り込まれます:

{"accepted": 1, "rejected": [{"id": "call_x", "reason": "missing id"}]}

OpenTelemetry トレース取り込み（OTLP/HTTP）

`POST /v1/traces` — OTLP/HTTP の span を取り込む

OpenTelemetry の OTLP/HTTP（JSON エンコーディング）でトレースを送ると、生成 AI 用のセマンティック規約（GenAI semantic conventions）に沿った span を Argosvix の呼び出し記録に取り込みます。LangGraph・OpenLLMetry・Traceloop などの OTel 計装を、コードを書き直さずにそのまま向けられます。

認証は他のエンドポイントと同じ Bearer API キーです。エンコーディングは http/json と http/protobuf の両方に対応しているので、エクスポーターは既定設定のままで使えます。

エクスポーター側の設定例:

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.argosvix.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20argk_xxx

span のマッピング

LLM 呼び出しを表す span（gen_ai.* 属性を持つもの）だけを取り込みます。新旧どちらの属性名にも対応します。

取り込む値	参照する属性（先に見つかった方を採用）
プロバイダー	`gen_ai.provider.name` または `gen_ai.system`
モデル	`gen_ai.request.model` または `gen_ai.response.model`
入力トークン	`gen_ai.usage.input_tokens` または `gen_ai.usage.prompt_tokens`
出力トークン	`gen_ai.usage.output_tokens` または `gen_ai.usage.completion_tokens`
コスト	`gen_ai.usage.cost`（無ければモデル別単価から自動算出）

プロバイダーは openai / anthropic / gemini / mistral のいずれかに正規化します。これらに該当しない span や、gen_ai.* 属性を持たない span（HTTP・DB など）は取り込まず、拒否件数に計上します。traceId と spanId はそのまま保持するので、取り込み後にトレース詳細画面で実行の入れ子をたどれます。同じ span を再送しても traceId-spanId で重複を判定して二重計上しません。

レスポンス契約

OTel エクスポーターは 2xx 以外を受け取るとリトライするため、業務的な拒否も HTTP 200 で表現します。

状況	ステータス	ボディ
全 span を受理	200	`{}`
一部を拒否	200	`{"partialSuccess":{"rejectedSpans":"2","errorMessage":"..."}}`
月次クォータ超過	200	全 span を `rejectedSpans` に計上（翌月まで取り込まれません）
protobuf が壊れている	400	—
JSON が壊れている	400	—
ボディが大きすぎる（1 MiB 超）	413	—

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/traces \
  -d '{
    "resourceSpans": [{
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8aa5a2d2c872e8321cf37308d69df2",
          "spanId": "051581bf3cb55c13",
          "name": "chat",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000002400000000",
          "attributes": [
            {"key": "gen_ai.system", "value": {"stringValue": "openai"}},
            {"key": "gen_ai.request.model", "value": {"stringValue": "gpt-5.5"}},
            {"key": "gen_ai.usage.input_tokens", "value": {"intValue": "100"}},
            {"key": "gen_ai.usage.output_tokens", "value": {"intValue": "50"}}
          ]
        }]
      }]
    }]
  }'

観測（呼び出し記録の検索）

`POST /v1/query/calls` — 呼び出し記録の検索

期間 / プロバイダー / モデル / 件数で絞り込んだ呼び出し記録を返します。

リクエストボディ:

フィールド	型	説明
`startTime`	ISO 8601	期間開始 (UTC)
`endTime`	ISO 8601	期間終了 (UTC)
`provider`	string	`openai` / `anthropic` / `gemini` / `mistral`
`model`	string	モデル名（部分一致）
`limit`	number	件数（1〜200、既定 50）
`sortBy`	string	`timestamp` / `provider` / `model` / `total_tokens` / `cost_usd` / `latency_ms` / `error`
`sortOrder`	string	`asc` / `desc`（既定 `desc`）

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/query/calls \
  -d '{"provider":"anthropic","limit":10}'

レスポンス（records 配列。フィールドは全記録で同じ形、値が無いものは null）:

{
  "records": [{
    "id": "call_20260706_0001",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "promptTokens": 42,
    "completionTokens": 18,
    "totalTokens": 60,
    "costUsd": 0.0012,
    "latencyMs": 234,
    "timestamp": "2026-07-06T00:00:00.000Z",
    "tags": {"service": "checkout"},
    "error": null,
    "errorDetails": null,
    "traceId": null,
    "spanId": null,
    "parentSpanId": null,
    "sessionId": null,
    "toolCalls": null,
    "piiRedacted": false,
    "redactionMetadata": null,
    "requestMeta": null
  }]
}

limit の上限は 200 です。それ以上を取得する場合は startTime / endTime で時間窓を区切って繰り返すか、MCP の export_calls（CSV / JSON エクスポート）を使ってください。

`POST /v1/query/aggregate` — 集計

provider / model / day / tag でグループ別の cost / latency / tokens / count を返します。

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/query/aggregate \
  -d '{"groupBy":"model","metric":"cost","startTime":"2026-06-01T00:00:00Z"}'

レスポンス:

{
  "groups": [
    {"key": "gpt-4o", "value": 1.7031, "count": 68, "lastSeen": "2026-07-02T04:45:16.000Z"},
    {"key": "gpt-4o-mini", "value": 0.0214, "count": 312, "lastSeen": "2026-07-05T22:10:03.000Z"}
  ],
  "total": {"value": 1.7245, "count": 380}
}

`POST /v1/query/percentiles` — パーセンタイル

latency または cost の p50 / p95 / p99 を 1 回で取得できます。

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/query/percentiles \
  -d '{"metric":"latency"}'

レスポンス:

{"metric": "latency", "p50": 950, "p95": 2400, "p99": 4200, "p999": 6005, "max": 6005, "count": 246}

`GET /v1/query/calls/:id` — 単一呼び出し記録

call id を指定して 1 件の詳細を取得します。他アカウントの id は 404 で構造的に分離します。

`GET /v1/query/trace/:id` — トレース詳細

trace id を指定して、関連する全 span を取得します（最大 50 件）。errorDetails や requestMeta は構造的に除外されます。

アカウントと予算

`GET /v1/account` — 識別情報

プラン名、月の利用量、保持期間など、機微でない識別情報のスナップショットを返します。サブスクリプションの詳細は含みません。Bearer 認証のみ受理します。

curl -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  https://ingest.argosvix.com/v1/account

`GET /v1/account/llm-feature-budget` — LLM 機能予算の状況

今月の予算、利用額、残額、月の境界（YYYY-MM 形式）を返します。Free / Pro+ ともに読み取り可能です。

{
  "budgetUsd": 5,
  "spentUsd": 0.42,
  "remainingUsd": 4.58,
  "periodStart": "2026-06",
  "defaultBudgetUsd": 5,
  "minBudgetUsd": 5,
  "maxBudgetUsd": 500
}

`PATCH /v1/account/llm-feature-budget` — 予算の変更（Pro+）

月額予算を $5 から $500 の範囲、$0.01 単位で変更します。

curl -X PATCH \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/account/llm-feature-budget \
  -d '{"budgetUsd":30}'

アラート

`GET /v1/alerts` — 一覧

設定済アラートを返します。

`POST /v1/alerts` — 新規作成

{
  "name": "monthly cost",
  "alertType": "monthly_budget",
  "thresholdValue": 100,
  "windowMinutes": 1440,
  "channelKinds": ["webhook"],
  "channelTargets": { "webhook": { "url": "https://..." } },
  "enabled": true
}

alertType は cost_threshold / monthly_budget / error_rate / latency_degradation / anomaly_cost / anomaly_latency / anomaly_error_rate / eval_score（品質 SLO。evalCriterionId 必須）/ guardian_findings（受信箱の新しい発見を外部チャネルへ通知。しきい値と評価窓は使わないので 0 と 60 を渡します）のいずれか。

`GET /v1/alerts/:id` — 単一取得

アラートの設定と直近の発火履歴を返します。

`PATCH /v1/alerts/:id` — 部分更新

name / thresholdValue / windowMinutes / channelKinds / channelTargets などを更新できます。alertType は変更不可です（変えたい場合は削除して作り直してください）。

`DELETE /v1/alerts/:id` — 削除

関連する発火履歴も一緒に削除されます。

`POST /v1/alerts/test-webhook` — webhook 試験送信（Pro+）

webhook URL の登録前に、受信できるかを試送できます。送信先は HTTPS のみ受理し、private / loopback / cloud metadata IP は拒否します。レート制限は 5 件 / 分です。

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/alerts/test-webhook \
  -d '{"url":"https://example.com/hook","alertName":"test"}'

応答:

{
  "ok": true,
  "delivered": true,
  "message": "test webhook delivered (= 2xx response within 5s)"
}

`GET /v1/alerts/events` — 発火履歴の一覧

アカウント全体のアラート発火イベントを新しい順で返します。alertId で単一アラートに絞り込めます。

クエリパラメータ	説明
`limit`	1〜100(既定 20)
`alertId`	指定すると該当アラートの発火のみ
`beforeTriggeredAt` + `beforeId`	keyset cursor。前ページ最後のイベントの `triggeredAt` と `id` を渡すと続きを返します(必ず両方同時指定、片方のみは 400)

各イベントには発火時点の条件スナップショット(thresholdValue / windowMinutes / alertType)が含まれます。スナップショット機能の導入より前に発火した古いイベントは現在のルール値で補完され、thresholdIsSnapshot: false で区別できます。

{
  "events": [
    {
      "id": "6f30f1b2-...",
      "alertId": "71845ee2-...",
      "alertName": "コスト超過",
      "alertType": "cost_threshold",
      "triggeredAt": "2026-06-12T02:15:01.683Z",
      "observedValue": 0.005,
      "thresholdValue": 0.000001,
      "thresholdIsSnapshot": true,
      "windowMinutes": 60,
      "channelsSent": ["email"],
      "acknowledgedAt": null,
      "acknowledgedBy": null
    }
  ]
}

`POST /v1/alerts/events/:eventId/acknowledge` — 発火イベントの確認

個別の発火イベントを「対応済」「確認済」とマークします。ミュート（silence）とは独立した操作で、何度呼んでも結果は変わりません。

プロンプト管理

`GET /v1/prompts` — 一覧

登録済プロンプトを返します。クエリパラメータで label や name による絞り込みができます。

`POST /v1/prompts` — 新規作成（Pro+）

{
  "name": "customer_support",
  "version": "v1",
  "template": "Hello {{user}}",
  "variables": { "user": "world" },
  "labels": ["production"],
  "description": "primary cs prompt"
}

プロンプトの name + version はアカウント内で一意である必要があります。重複は 409 を返します。

`GET /v1/prompts/:id` — 単一取得

`PATCH /v1/prompts/:id` — 部分更新（Pro+）

template / variables / labels / description を部分更新できます。name と version は変更できません（変えたい場合は POST /v1/prompts/:id/rename を使ってください）。

`POST /v1/prompts/:id/rename` — 改名（Pro+）

name と version を変更します。誤字の修正などに使います。

curl -X POST \
  -H "Authorization: Bearer $ARGOSVIX_API_KEY" \
  -H "Content-Type: application/json" \
  https://ingest.argosvix.com/v1/prompts/7/rename \
  -d '{"name":"customer_support","version":"v2"}'

`DELETE /v1/prompts/:id` — 削除（Pro+）

⚠ バージョンを削除すると、そのプロンプトが過去の評価ランから切り離され、それらのランは「どのプロンプトで実行したか」の来歴を失います。論理的に sunset したいだけなら PATCH で labels を sunset に変える方が安全です。

評価基準

`GET /v1/eval-criteria` — 一覧

Argosvix 標準の基準と、自アカウント固有のカスタム基準を返します。

`POST /v1/eval-criteria` — 作成（Pro+）

{
  "name": "helpfulness",
  "rubric": "Score how helpful the answer is to the user.",
  "scaleMin": 1,
  "scaleMax": 5,
  "scope": "call"
}

任意の scope: call（既定。呼び出しごとに 1 採点）/ trajectory（同一 trace_id の呼び出しを 1 つのトランスクリプトにまとめ、複数ターンのエージェント実行を 1 単位として採点します。llm_judge 型専用）。軌跡の採点結果は GET /v1/eval-runs/:id の trajectoryScores で返ります。

`PATCH /v1/eval-criteria/:id` — 全置換更新（Pro+）

name / rubric / scaleMin / scaleMax の 4 項目すべてが必須です。scope は省略時に既存値を引き継ぎます。標準基準は変更不可で 404 を返します。

`DELETE /v1/eval-criteria/:id` — 削除（Pro+）

⚠ その基準で記録された過去のスコアもすべて削除され、過去のスコア比較ができなくなります。改名したいだけなら PATCH で全項目を上書き更新してください。

`POST /v1/eval-criteria/propose` — LLM ジャッジによる評価基準の候補生成（Pro+）

LLM ジャッジ（gpt-4o-mini）に useCaseHint と任意の sampleCallIds を渡して、自社のユースケースに合った評価基準の候補を提案させます。提案のみで、自動では登録されません（採用するかは利用者が別途 POST /v1/eval-criteria で登録します）。サンプルの復号に失敗した場合は partialFailures に記録されます。

{
  "useCaseHint": "Customer support bot for e-commerce (returns + refund policy)",
  "sampleCallIds": ["call_abc123", "call_xyz789"],
  "maxCriteria": 5
}

useCaseHint: 必須、1〜500 文字
sampleCallIds: 任意、最大 5 件、自アカウントの呼び出しのみ指定可能
maxCriteria: 任意、1〜10（既定 5）
レート制限: 60 秒あたり 30 リクエスト（固定ウィンドウ。超過時は 429 と Retry-After ヘッダを返します。アカウント単位で適用します）

返却:

{
  "criteria": [
    {
      "name": "tone_appropriateness",
      "rubric": "Is the bot's tone polite and professional?",
      "scaleMin": 1,
      "scaleMax": 5,
      "reasoning": "Tone is critical in customer support."
    }
  ],
  "partialFailures": [],
  "budgetSpentUsd": 0.002,
  "proposedRawCount": 5,
  "droppedCount": 0
}

監査: eval.propose_criteria を監査ログに記録します。

評価ラン

`GET /v1/eval-runs` — 一覧

評価ランの履歴を、サマリ（scoredCount / failedCount / 平均スコア）付きで返します。

`GET /v1/eval-runs/:id` — 単一取得

実行内容と、各（基準 × 呼び出し）ごとのスコアを返します。

`POST /v1/eval-runs` — 新規実行（Pro+）

{
  "name": "weekly review",
  "recentCount": 50,
  "label": "production",
  "promptRegistryId": 7,
  "idempotencyKey": "uuid-1234-..."
}

idempotencyKey を渡すと、60 分以内の同キーでの再実行は既存のランを返します（重複実行の防止）。

アノテーション

`GET /v1/annotations` — 一覧

?callId=xxx で単一の呼び出しのアノテーション、?label=xxx でラベル横断検索ができます。

`POST /v1/annotations` — 作成

{
  "callId": "call-xyz",
  "annotationText": "good response",
  "label": "approved",
  "qualityScore": 5
}

annotationText / label / qualityScore のうち少なくとも 1 つが必要です。

`GET /v1/annotations/:id` — 単一取得

`PATCH /v1/annotations/:id` — 部分更新

annotationText / label / qualityScore を部分更新できます。callId は変更できません。

`DELETE /v1/annotations/:id` — 削除

安全分類

`GET /v1/safety-assessments` — 一覧

?call_id=xxx でその呼び出しの全分類器の結果を、省略するとアカウント全体の最新を返します。

`POST /v1/safety-assessments/scan-batch` — オンデマンドの一括安全分類（Pro+）

15 分ごとに自動実行されるバックグラウンドスキャンを「今すぐ」補完するためのエンドポイントです。自アカウントの未分類の呼び出しを最大 100 件まとめて OpenAI Moderation で分類します。結果はオンデマンド実行として記録され（定期処理由来と区別できます）、重複登録は自動的に防止されます。

{
  "maxRecords": 50
}

maxRecords: 任意、1〜100（既定 50）、整数
レート制限: 60 秒あたり 30 リクエスト（固定ウィンドウ。超過時は 429 と Retry-After ヘッダを返します。アカウント単位で適用します）
OpenAI Moderation を利用します（コストはほぼ $0）。プランと予算の上限はバックエンド側で適用します。

返却:

{
  "scanned": 50,
  "assessed": 48,
  "flagged": 2,
  "failures": 0,
  "skipped": 2
}

監査: safety.scan_batch_run を監査ログに記録します。

`GET /v1/safety-assessments/:id` — 単一取得

ラベル、スコア、根拠、分類器 ID、ソースを返します。

エラー応答

{
  "error": "invalid model (length 1-128 required)"
}

403 / 409 / 503 などのエラーでは、応答ボディの error フィールドに具体的な原因が記述されます。クライアントはステータスコードと error 文字列で分岐してください。

SDK と MCP サーバー

REST API を直接呼び出す代わりに、言語別の SDK や MCP サーバーも利用できます。

SDK Reference — @argosvix/sdk で wrap するだけで呼び出しが自動記録されます。
MCP Server — Claude Desktop / Cursor / Codex CLI から会話で操作できます。

サポート

hello@argosvix.com まで連絡ください。

最終更新: 2026-07-09

REST API リファレンス

ベース URL

認証

API キーの権限スコープ（最小権限運用）

記録の取り込み

POST /v1/ingest — 呼び出し記録を送信する

OpenTelemetry トレース取り込み（OTLP/HTTP）

POST /v1/traces — OTLP/HTTP の span を取り込む

span のマッピング

レスポンス契約

観測（呼び出し記録の検索）

POST /v1/query/calls — 呼び出し記録の検索

POST /v1/query/aggregate — 集計

POST /v1/query/percentiles — パーセンタイル

GET /v1/query/calls/:id — 単一呼び出し記録

GET /v1/query/trace/:id — トレース詳細

アカウントと予算

GET /v1/account — 識別情報

GET /v1/account/llm-feature-budget — LLM 機能予算の状況

PATCH /v1/account/llm-feature-budget — 予算の変更（Pro+）

アラート

GET /v1/alerts — 一覧

POST /v1/alerts — 新規作成

GET /v1/alerts/:id — 単一取得

PATCH /v1/alerts/:id — 部分更新

DELETE /v1/alerts/:id — 削除

POST /v1/alerts/test-webhook — webhook 試験送信（Pro+）

GET /v1/alerts/events — 発火履歴の一覧

POST /v1/alerts/events/:eventId/acknowledge — 発火イベントの確認

プロンプト管理

GET /v1/prompts — 一覧

POST /v1/prompts — 新規作成（Pro+）

GET /v1/prompts/:id — 単一取得

PATCH /v1/prompts/:id — 部分更新（Pro+）

POST /v1/prompts/:id/rename — 改名（Pro+）

DELETE /v1/prompts/:id — 削除（Pro+）