API リファレンス
予測可能なリソース、標準的な HTTP メソッド、カーソルページネーション。以下のレート制限は、サーバーが実際に強制している値であり、努力目標の数字ではありません。
Bearer トークンを使用し、スコープはワークスペース単位です。トークンは作成者のロールを継承します。editor のトークンは、どのエンドポイントを呼んでも承認を実行できません。この制御はクライアントではなく、サーバー側で強制されます。
curl https://api.untactit.com/v1/assets \ -H "Authorization: Bearer $TOKEN"
サインイン自体は SSO のみ(SAML または OIDC)です。パスワードは一切保持しないため、パスワード用のエンドポイントは存在せず、漏えいするものもありません。
オフセットではなくカーソル方式です。前のレスポンスの cursor を、 has_more が false になるまで渡します。1 ページあたり最大 100 件です。
{
"data": [ /* up to 100 items */ ],
"has_more": true,
"next_cursor": "cur_01H8X..."
}
リソースは 6 種類です。ロール要件はサーバー側で強制され、権限が足りない場合は、必要なロールがエラー内に明示されます。
| リソース | 対象範囲 | 最小ロール |
|---|---|---|
assets |
一覧・取得・作成・更新。アセットごとに全バージョン履歴を保持。 | viewer / editor |
approvals |
提案・承認・却下。ワークスペースの承認ポリシーに従います。 | editor / approver |
deployments |
計画・実行・ドライラン、およびドリフトを含む配信状態の読み取り。 | 承認者 |
targets |
接続済みのプラットフォームと、そのスコープ。 | admin |
members |
ワークスペースのメンバーとロールの割り当て。 | admin |
audit |
実行者・アクション・時刻でフィルタリングできる監査ログ。CSV エクスポート対応。 | admin |
エラー
エラーには、分岐処理に使える安定した code が含まれます。権限が問題の場合は、本来必要だったロールがレスポンスに明示されるため、推測に頼らず修正できます。
403 insufficient role — 必要なロールと実際のロールを含む413 ペイロードが 4 MB を超過429 レート制限超過409 conflict — 取得後に別の更新でバージョンが変わった{
"error": {
"code": "insufficient_role",
"message": "Approving requires the approver role.",
"required_role": "approver",
"actual_role": "editor",
"request_id": "req_01H8X..."
}
}
サポートメールに request_id を記載していただければ、再現をお願いすることなく、該当の呼び出しを正確に特定できます。
ワークスペースごとのトークンバケットを、パスグループ単位で適用します。持続レートは継続的に補充されます。バーストは、アイドル後に一度に消費できる量です。
読み取りと、アセットへの書き込み。 バーストは 50。インベントリ全体を継続的に同期し、編集中の保存を意識せず行うのに十分な量です。
構造的な変更。 バーストは 5。ロールの変更、ワークスペース設定など、「誰が何をできるか」を変えるすべての操作が対象です。
配信、実行、外部呼び出し。 制限値は処理の重さに応じて設定しています。配信は、届く先のマシンが何台であっても 1 回の呼び出しです。
4 MB を超えるリクエストは 413 で拒否されます。具体的な利用パターンを持つ Enterprise ワークスペースでは、上限の引き上げが可能です。ワークロードの内容をお知らせください。根拠のない数字を示すのではなく、実態に合わせてサイジングします。
公に確約できる日付はありません。エンジンは今日すでに稼働しており、残っているのは安定した契約と、その非推奨化の保証です。API アクセスが評価の必須要件である場合はお知らせください。優先順位を引き上げる材料になります。
専用の環境は用意していません。無料プランで 2 つ目のワークスペースを作成し、テスト環境として使ってください。挙動は同一で、本番データを危険にさらすこともありません。
パスに含めます。破壊的変更は新しいバージョンとして提供し、旧バージョンは 12 か月間並行して維持します。フィールドの追加は予告なく行われるため、未知のフィールドを許容する防御的なパースをしてください。
はい。実装と同じソースから生成するため、実際の挙動から乖離しようがありません。手作業でメンテナンスされる仕様書は、いずれ嘘をつくドキュメントになります。