API リファレンス

API の概要

Hane の公開 API に共通する決まり（認証・冪等性・楽観ロック・エラー・ページ送り）と、エンドポイントの一覧の読み方。

Hane の機能は、すべて公開 API（HTTP と JSON）で使えます。コンソール・参照アプリ・hanectl も、同じ API を TypeScript の SDK（@hane/sdk）から呼んでいます。このページでは、どのエンドポイントにも共通する決まりを説明します。各エンドポイントの詳細は左の「エンドポイント」から開いてください。

ベース URL と組織の決まり方

API は組織ごとの Hane の入口（https://<your-hane-endpoint>）の /v1/ の下にあります。組織・プロジェクト・環境は URL に入れません。 どの組織のどの環境を操作するかは、要求に付けた資格情報から決まります。

認証

すべての要求に Authorization: Bearer <token> を付けます。<token> は次のどちらかです。

資格情報	使う場面
API キー（`hane_<環境>_...`）	サービスアカウントとしてサーバーから呼ぶとき。組織・プロジェクト・環境とスコープがキーに結び付いています
アクセストークン	利用者の代わりに呼ぶとき。アプリの BFF が利用者の id_token と API キーを `POST /v1/auth/token` で交換して得ます

詳しくは認証とトークン交換を見てください。

冪等性（Idempotency-Key）

副作用のある POST には Idempotency-Key ヘッダーが必要です。同じキーで送り直した要求は、一度だけ処理されます。キーがないと IDEMPOTENCY_KEY_REQUIRED、同じキーで中身の違う要求を送ると IDEMPOTENCY_CONFLICT になります。SDK は、呼ぶ側が付けなければ自動で付けます。

楽観ロック（If-Match）

更新系の一部は、取得したときのバージョンを If-Match で渡す必要があります。ほかの人が先に更新していれば PRECONDITION_FAILED になるので、取り直してからやり直します。SDK の ifMatch(version) で値を作れます。

import { createHaneClient, ifMatch, unwrap } from "@hane/sdk";

const record = await unwrap(hane.GET("/v1/data/records/{id}", { params: { path: { id } } }));
await unwrap(
  hane.PATCH("/v1/data/records/{id}", {
    params: { path: { id }, header: { "If-Match": ifMatch(record.version) } },
    body: { values: { status: { value: "returned" } } },
  }),
);

エラー

失敗した要求は、HTTP の状態コードと次の形の JSON（Problem）を返します。code で判断し、retryable が true なら時間をおいて送り直せます。request_id は問い合わせのときに伝えてください。

{
  "type": "about:blank",
  "title": "Precondition failed",
  "status": 412,
  "code": "PRECONDITION_FAILED",
  "detail": "...",
  "request_id": "...",
  "retryable": false
}

code	意味
`VALIDATION_FAILED`	入力がスキーマや定義に合わない。`errors` に項目ごとの理由が入る
`UNAUTHENTICATED` / `FORBIDDEN`	資格情報がない・無効 / スコープや権限が足りない
`NOT_FOUND` / `CONFLICT`	対象がない / 今の状態ではできない
`IDEMPOTENCY_KEY_REQUIRED` / `IDEMPOTENCY_CONFLICT`	冪等性のキーがない / 同じキーで違う要求
`PRECONDITION_REQUIRED` / `PRECONDITION_FAILED`	`If-Match` がない / バージョンが古い
`RATE_LIMITED` / `BUDGET_EXCEEDED`	呼出しの上限 / 使用量の予算を超えた。`Retry-After` を見て待つ
`TENANT_SUSPENDED`	組織が緊急停止されている
`NOT_SUPPORTED`	この環境では提供していない機能
`BAD_GATEWAY` / `GATEWAY_TIMEOUT`	転送先（顧客の API など）の失敗・時間切れ
`INTERNAL`	Hane の内部の失敗

SDK の unwrap() は、失敗したときに HaneError（status・code・problem・retryAfterSeconds）を投げます。

ページ送り

一覧の API は limit と cursor を受け取り、items と next_cursor を返します。next_cursor が null になるまで、その値を次の cursor に渡します。

let cursor: string | undefined;
do {
  const page = await unwrap(
    hane.GET("/v1/data/records", { params: { query: { type: "LeaseContract", limit: 100, cursor } } }),
  );
  for (const record of page.items) console.log(record.id);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

進行の受信（SSE）

組み込みチャットの会話の進み具合（応答の生成、ツールの開始と終了、承認待ちなど）は、GET /v1/agents/conversations/{id}/events から Server-Sent Events で受け取れます。切れたときは同じエンドポイントにつなぎ直すと、履歴と今の状態から続きを受け取れます。1 つの AgentRun の状態は、GET /v1/agents/runs/{id} で取り直すか、webhook で受け取ります（Agent を組み込む）。

次に読む

TypeScript SDK型の付いたクライアントで API を呼ぶ

認証とトークン交換API キーとアクセストークンの使い分け