# API

トークンで認証し、シンプルな JSON で検索、レンタル、管理、支払いを行います。

## 基本

- ベース URL は `$ARRAKIS_URL` です。リクエストとレスポンスはすべて JSON です。
- `Authorization: Bearer ark_...` で認証します。どのアカウントとして扱われるかはトークンで決まります。
- エラーは `{"detail": "..."}` の形で、内容に応じたステータスコードとともに返ります：401（トークン）、402（残高または支出上限）、403（スコープ）、404、409、422（入力）、429（リクエストが多すぎる）、503（レンタル受付前）。
- スキーマの全体は [/openapi.json](/openapi.json) にあります。[インタラクティブリファレンス](/docs/reference)で呼び出しを試せます。

## トークンとスコープ

| スコープ | 許可される操作 |
|---|---|
| `read` | マシンの検索、自分のマシン・ボリューム・イメージの読み取り |
| `rent` | マシンのレンタル、再起動、停止 |
| `manage` | トークンの作成と失効、SSH 鍵とイメージの保存 |
| `billing` | 残高、支払い、自動チャージ、緊急停止 |

トークンは **API & agents** か `POST /v1/tokens` で作成します。トークンには `spend_limit_usd`、`max_rental_hours`、`expires_at` を設定できます。トークンが作成できるのは、自分が持つスコープの範囲内で、自分の上限を超えないトークンに限られます。

## トークン不要

```sh
curl $ARRAKIS_URL/v1/market/summary
```

GPU ファミリーごとの最新価格と空き状況を返します。

## マシンをレンタルする

```sh
curl -X POST $ARRAKIS_URL/v1/instances \
  -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \
  -d '{"node_id": "<node>", "name": "eval", "ssh_public_key": "ssh-ed25519 AAAA...",
       "termination_hours": 4, "idempotency_key": "eval-2026-10-14"}'
```

`GET /v1/gpus` で `node_id` を見つけます。その `tier` は `on_demand` か `spot` を示します。残高は最初の 1 時間分をまかなえる必要があり（足りなければ 402）、この 1 時間分はマシンが稼働を始めた時点で請求されます（最低 1 時間）。`max_price_per_gpu_hour` を送ると、確認した価格（`GET /v1/gpus/{node_id}/price`）以下でしかレンタルしません。リアルタイム価格がそれより高ければ何もレンタルされず、409 が返ります。

## 主なルート

| メソッド | パス | 機能 |
|---|---|---|
| GET | `/v1/market/summary` | GPU ファミリーごとの最新価格（公開） |
| GET | `/v1/market/history` | GPU ファミリーごとの 1 時間単位の価格。JSON、または `format=csv` で CSV（公開） |
| GET | `/v1/models/fit?model=owner/name` | Hugging Face のモデルに必要な GPU メモリと、いまそれが収まるいちばん安い GPU（公開） |
| GET | `/v1/gpus` | レンタルできるマシン（安い順） |
| GET | `/v1/gpus/{node_id}/price` | マシンの現在のリアルタイム価格 |
| POST | `/v1/instances` | マシンをレンタルする |
| GET | `/v1/instances`, `/v1/instances/{id}` | 自分のマシンの一覧 |
| POST | `/v1/instances/{id}/terminate` | マシンを停止して削除 |
| POST | `/v1/instances/{id}/schedule-removal` | 自動削除の時刻を設定 |
| GET / POST / DELETE | `/v1/volumes` | あなたのボリューム：保存量、費用、マウント先 |
| GET | `/v1/billing/account` | 残高、1 時間あたりの消費額、残高が尽きる時刻 |
| POST | `/v1/billing/checkout` | カード、Link、Apple Pay での支払いを開始 |
| POST | `/v1/billing/stop` | すべてのマシンを停止し、レンタルを一時停止 |
| GET / POST / DELETE | `/v1/tokens` | トークンの一覧、作成、失効 |
| GET | `/v1/support/cases` | あなたのサポート案件と当社の回答 |
| POST | `/mcp` | エージェント向け MCP |

## 再試行

レンタルを再試行するときは、同じ `idempotency_key` を送ります。2 台目がレンタルされることはなく、同じマシンが返ります。

その他：[すべてのドキュメント](/ja/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/ja/llms.txt)