API リファレンス

エージェントのエンドポイント

クラウドエージェントの /v1/agents エンドポイント一覧：自社ユーザー向けのエージェント作成、設定、起動と停止、API でのタスク実行、ファイルと共有リンク、Web ページのオープン、エージェントトークン、ホワイトラベルのエージェント用ブランディング。

クラウドエージェントの API は https://lovelyrouter.com/v1/agents にあります。コンソールの API キーで Authorization: Bearer $LOVELY_API_KEY として認証するか（認証）、1 つのエージェントについてはエージェントトークンで認証します。エージェントのセッションが自分用に受け取るキーでは、これらのエンドポイントを呼べません。本文は JSON、金額の単位はマイクロドル（1,000,000 = $1）です。エージェントの料金はプリペイド残高から差し引かれます。クラウドエージェントの料金をご覧ください。

手順はクラウドエージェントの概要から始めてください。

エージェントオブジェクト#

属性

idstring

一意の ID。agt_ に 24 文字が続きます。

objectstring

常に agent。

namestring | null

任意のラベル。

userstring | null

このエージェントが担当するユーザーの自社 ID（1〜128 文字：英数字と _ . @ : + -）。一覧の絞り込みに使えます。

metadataobject | null

任意の JSON オブジェクト（最大 4 KB）。

statusstring

stopped、starting、running のいずれか。

sessionobject | null

実行中のセッション：id、status、size、vcpu、mem_gib、started_at、ready_at、これまでの費用 charge_micros（サンドボックスの時間）、llm_micros（モデルとツール）、total_micros。

urlstring

エージェントの Web ページ https://agent.lovelyrouter.com/a/<id>/。オープンまたは ui スコープのトークンでサインインします。

sizeidle_minutes

設定をご覧ください。

settingsobject

model、tools、mcp_servers（ヘッダーの値は •••••••• と表示）、instructions。

budget_microsinteger | null

spend.total_micros がこの値に達すると、エージェントは停止し、起動も実行もできなくなります。

brandingstring | null

ページで使うブランディング（brd_…）。null は標準の見た目です。

white_labelboolean

ブランディングがあると true：サンドボックスはホワイトラベル料金で請求されます。開いている session も自身について同じことを示します。

spendobject

compute_micros（サンドボックスの時間）、llm_micros（そのセッションが使ったモデルとツール）、total_micros。

workspaceobject

保存量 bytes、measured_at。

created_atinteger

エポックからのミリ秒。

エージェントを作成する#

POST/v1/agents

空のワークスペースを持つエージェントを作成し、201 とエージェントオブジェクトを返します。任意の設定を指定でき、"start": true ですぐに起動します。1 アカウントあたり最大 1,000 エージェントです。

Shell

curl https://lovelyrouter.com/v1/agents \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Support bot", "user": "cust-42", "metadata": {"plan": "pro"}, "budget_micros": 5000000}'

エージェントを一覧する#

GET/v1/agents

新しい順です。?user=cust-42 でそのユーザーのエージェントを返します。limit（200 以下、既定 50）、before（created_at の値）で前のページへ。レスポンスの next_before が次のページの値です。

cURL

curl "https://lovelyrouter.com/v1/agents?user=cust-42" -H "Authorization: Bearer $LOVELY_API_KEY"

エージェントの取得・更新・削除#

PATCH/v1/agents/{id}

GET はエージェントを返します。PATCH（または POST）は送った項目を変更します。DELETE は実行中なら停止し、ワークスペースごと完全に削除します。設定は次回の起動から適用されます。

ボディパラメーター

nameuser

エージェントオブジェクトと同じ。null で消去します。

modelstring | null

既定の LLM。GET /v1/models の任意のチャットモデル id。null = claude-haiku-5.5。

toolsbooleanデフォルト true

Lovely Router のデータツールとブラウザエージェントを MCP ツール（mcp__tools__*）として提供。使った分だけ請求されます。

mcp_serversarray

最大 8 つのリモート MCP サーバー（Streamable HTTP）：{"name", "url", "headers"}。name は英字で始まる a-z 0-9 _ - の 1〜32 文字（tools は使用済み）、url は公開の https:// URL、headers は最大 10 個。ヘッダーの値は暗号化して保存され、返されることはありません。•••••••• を送り返すと保存済みの値が保たれます。

instructionsstring | null

すべてのセッションに追加されるテキスト（最大 4,000 文字）。

sizestring

small、medium、large（サイズ）。

idle_minutesinteger

5, 15, 30, 60, 120, 240, 480 or 1440.

max_hoursinteger

1, 2, 4, 8, 12 or 24.

auto_startboolean、既定 `true

呼び出されたら自動で起動：停止中のエージェントが実行、オープン、Web ページへのアクセスで自動的に起動します。すぐに反映されます。

brandingstring | null

あなたのブランディングの 1 つ：次回の起動からエージェントはホワイトラベルになり、ホワイトラベル料金で請求されます。null は標準の見た目と料金です。

cURL

curl -X PATCH https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5", "instructions": "Reply in the user'"'"'s language."}'

起動と停止#

POST/v1/agents/{id}/start

エージェントを起動します。数秒後に running になります（新しいエージェントの初回起動はもう少しかかることがあります）。POST /v1/agents/{id}/stop で停止し、最終的な charge_micros を含むセッションを返します。起動にはそのサイズの 15 分間分（最低 $0.25）の残高が必要で、1 アカウントで同時に動かせるのは 20 エージェントまでです。実行は停止中のエージェントを自動で起動します。

cURL

curl -X POST https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/start -H "Authorization: Bearer $LOVELY_API_KEY"

タスクを実行する#

POST/v1/agents/{id}/runs

エージェント API です。エージェントにタスクを 1 つ送り、実行（run）を返します。エージェントは Web ページと同じく、サンドボックス内で自分のツールと設定を使って作業します。各実行のセッションは保存され、Web ページにも表示されます。エージェントの auto_start がオン（既定）なら、停止中のエージェントはまず起動され、実行で起動したか、もともと動いていたかにかかわらず、最後の実行が終わってから約 5 秒後に停止します（そのセッションで Web ページが使われた場合は、アイドル時に停止します）。実行の合間も動かしておくには、stop_when_done: false を付けてください。API キー、または api スコープのエージェントトークンで使えます。

Body parameters

inputstring必須

タスク（最大 100,000 文字）。

session_idstring

このセッションを続けます（以前の実行の session_id）。省略すると新しいセッションです。

waitinteger

実行の完了まで、リクエストを最大この秒数（300 以下）待機します。

streamboolean

代わりに実行のイベントを Server-Sent Events で返します：run、session、status（ターンとステップ、トークン使用量付き）、tool_call、tool_result、text、final、最後に完了した実行を含む end。

stop_when_doneboolean

実行が終わってから約 5 秒後にエージェントを停止します。既定：true（このセッションでエージェントの Web ページが使われた場合を除く）。false にするとエージェントは動き続け（その後はアイドル時に停止）、true にすると以前に Web ページが使われていてもこの実行の後に停止します（その間に誰かがページを使った場合を除く）。

startboolean、既定：エージェントの `auto_start

停止中ならエージェントを起動します。エージェントトークンでは auto_start だけで決まり、オフのエージェントを true で起動することはできません。

実行には、その中でエージェントが納品したファイルが files として一覧されます：path（エージェントのホームフォルダからの相対パス）、description、bytes、そしてファイルでダウンロードできる url。ホームフォルダの外に保存されたファイルは保持されず、url は null です。API キーを持たない人に見せるには、共有リンクを作ってください。

GET /v1/agents/{id}/runs はエージェントの前回起動以降の実行を一覧し、GET /v1/agents/{id}/runs/{run_id}?wait=30 は 1 件を返し、GET …/events でストリームし、POST …/cancel で停止します。実行の記録はエージェントの実行中だけ保持され、セッションはワークスペースに残ります。エージェントあたり同時に最大 4 件（セッションごとに 1 件）まで実行できます。

Shell

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "Summarize README.md in three bullets.", "wait": 120}'

Response

{
  "id": "run_k3f9a1c7mf0x2",
  "object": "agent_run",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "status": "completed",
  "session_id": "session-631cba7f-3095-4f66-b2cb-6786ff1f951c",
  "input": "Summarize README.md in three bullets.",
  "output": "- …",
  "error": null,
  "usage": { "input_tokens": 1240, "output_tokens": 96, "cache_read_tokens": 15703, "cache_write_tokens": 0 },
  "steps": 2,
  "tool_calls": 1,
  "files": [
    {
      "path": "deepseek-harness/api-requests/summary.md",
      "description": "README summary",
      "bytes": 412,
      "in_home": true,
      "url": "https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md"
    }
  ],
  "started_at": 1792363795275,
  "finished_at": 1792363805502
}

ファイル#

GET/v1/agents/{id}/files/{path}

エージェントのホームフォルダ内のフォルダを一覧するか、ファイルをダウンロードします。path はホームフォルダからの相対パスで、省略するとホームフォルダ自体です。API の実行は deepseek-harness/api-requests で作業します（そのセッションはエージェントの Web ページで API Requests にまとめられます）。Web ページで始めたセッションは、別のフォルダを開かない限り deepseek-harness/default-workspace で作業します。エージェントの実行中はライブの内容（"live": true）を、停止中は最後に停止したときに保存された内容を読み取ります。読み取りのためにエージェントを起動することはありません。API キー、または api スコープのエージェントトークンで使えます。

フォルダは {"object": "list", "path", "live", "data", "truncated"} を返します。最大 1,000 件、フォルダが先で、それぞれ name、path、type（file または dir）、bytes、modified_at、url を持ちます。ファイルは、その内容を対応するコンテンツタイプの添付ファイルとして返します。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/default-workspace \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl -O https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md \
  -H "Authorization: Bearer $LOVELY_API_KEY"

共有リンク#

POST/v1/agents/{id}/shares

リンクを持っている人なら誰でもサインインなしで、ファイルを開いたり、フォルダを Web サイトとして開いたりできるリンクを作ります。リンクはエージェントの停止中も使えます。フォルダのリンクはその index.html（ない場合はファイル一覧）を開き、ページはフォルダ内の他のファイルを相対パスで読み込みます。ファイルのリンクはファイル名で終わります。201 と {"object": "agent_share", "agent_id", "path", "type", "url", "expires_at"} を返します。

ボディパラメータ

pathstring、必須

エージェントのホームフォルダ内のファイルまたはフォルダ。ファイルと同じ書き方です。

expires_ininteger、既定 `604800

リンクが使える秒数：60〜31,536,000（1 年）。既定は 1 週間です。

POST /v1/agents/{id}/shares/revoke は、エージェントのすべてのリンクをまとめて無効にします。エージェントを削除するか、リンクを作った API キーまたはエージェントトークンを失効させても、リンクは無効になります。api スコープのエージェントトークンでもリンクを作れ、そのリンクはトークンとともに無効になります。リンクを無効にできるのはアカウントのみです。

共有ページはサンドボックスで動きます。スクリプト、フォーム、他サイトのリソースは使えますが、Cookie とブラウザのストレージは使えず、ページから Lovely Router や他のエージェントにはアクセスできません。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/shares \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"path": "deepseek-harness/default-workspace/site", "expires_in": 86400}'

Response

{
  "object": "agent_share",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "path": "deepseek-harness/default-workspace/site",
  "type": "dir",
  "url": "https://agent.lovelyrouter.com/s/eyJrIjoic2hyIiwi…/",
  "expires_at": 1792450195275
}

Web ページを開く#

POST/v1/agents/{id}/open

url を返します。60 秒間有効なリンクで、実行中のエージェントの Web ページをサインイン済みで開きます。サインインは 7 日間、またはキーが失効するまで続きます。auto_start がオンなら停止中のエージェントをまず起動します（準備ができるまでページには「Starting…」と表示されます）。オフなら 409 です。

自社ユーザー向けのエージェントトークン#

POST/v1/agents/{id}/tokens

1 つのエージェント用のトークンを作成します。自社のユーザーに渡せば、あなたの API キーを見せずに済みます。scopes：api はこのエージェントの実行とファイルの利用、共有リンクの作成、状態の参照を許可し、ui はエージェントの Web ページを開くリンク url を作ります（トークンの期限まで再利用可）。Web ページを見せたくないユーザーには api だけを渡してください。expires_in：60 秒〜30 日（既定 3,600）。トークンは、期限切れ、エージェントのトークンの失効、エージェントの削除、または作成した API キーの失効で使えなくなります。

POST /v1/agents/{id}/tokens/revoke は、これまでに発行したエージェントのトークンをすべて失効させます（開いているリンクも 1 分以内に使えなくなります）。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/tokens \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scopes": ["api"], "expires_in": 3600}'

Response

{
  "object": "agent_token",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "scopes": ["api"],
  "token": "agtok_eyJrIjoiYWd0Iiwi…",
  "expires_at": 1792367395275,
  "url": null
}

セッション#

GET/v1/agents/{id}/sessions

エージェントの直近 50 件のサンドボックスセッション（実行中のものを含む）とそれぞれの費用：charge_micros（サンドボックスの時間）、llm_micros（そのキーが使ったモデルとツール）、total_micros。セッションの stop_reason は user、idle、done（起動のきっかけになった実行が終了）、balance、budget、max_time、exited、error、deleted、admin のいずれかです。

ブランディング#

POST/v1/agents/brandings

ホワイトラベルのエージェント用に保存する見た目です。POST で作成（201）、GET /v1/agents/brandings で一覧（新しい順、最大 50 個）、GET・PATCH（または POST）・DELETE /v1/agents/brandings/{id} で 1 つを取得・変更・削除します。PATCH は送ったフィールドだけを変更し、そのブランディングを使うエージェントは次回の起動で変更を反映します。エージェントが使用中のブランディングを削除すると 409 になります。エージェントトークンではこれらのエンドポイントを呼べません。

リクエストボディのパラメーター

agent_namestring必須

ユーザーがページで目にし、エージェントが名乗る名前：英字か数字で始まる 1〜40 文字の英字・数字・スペースと . _ -。

namestring

あなた用のラベル。最大 60 文字。既定：agent_name。

logostring | null

PNG、JPEG、WebP または SVG 画像の base64 data: URI。最大 64 KB。null は頭文字アイコン（agent_name の頭文字をアクセント色で表示）。

schemestringデフォルト dark

dark または light。

colorsobject

#rrggbb の値：accent、bg（背景）と、任意で accentSoft（リンク）、onAccent（アクセント上のテキスト）、surface・surface2・surface3（パネル、浮き上がった部分、枠線）、ink・ink2・ink3（テキスト、補助、控えめ）。省いた色は scheme・accent・bg から生成されます。scheme だけを変える PATCH は、アクセントから配色全体を生成し直します。

fontstring | null

本文フォント：Inter、Geist、Roboto、Open Sans、Lato、Poppins、Montserrat、Nunito、DM Sans、Manrope、Plus Jakarta Sans、Space Grotesk、Work Sans、IBM Plex Sans、Source Sans 3、Noto Sans、Outfit、Figtree、Rubik、Lora。null はページ標準のフォント。

mono_fontstring | null

コードフォント：JetBrains Mono、Geist Mono、IBM Plex Mono、Fira Code、Source Code Pro、Roboto Mono、DM Mono、Space Mono。

welcomestring | null

最初のメッセージ入力欄の上の見出し。最大 80 文字。null は何をお手伝いしましょうか？

ブランディングオブジェクトは、すべての色を埋めたこれらのフィールドに加え、id（brd_ と 24 文字）、object（agent_branding）、agents（使用中のエージェント数。一覧と取得で返ります）、created_at、updated_at を持ちます。

cURL

curl https://lovelyrouter.com/v1/agents/brandings \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"agent_name": "Nova Assistant", "scheme": "light", "colors": {"accent": "#0d9488"}, "font": "Inter", "welcome": "How can Nova help today?"}'

Response

{
  "id": "brd_6c1f0a9e3b7d2c4e8f5a1b0d",
  "object": "agent_branding",
  "name": "Nova Assistant",
  "agent_name": "Nova Assistant",
  "logo": null,
  "scheme": "light",
  "colors": {
    "accent": "#0d9488", "accentSoft": "#0b7f75", "onAccent": "#ffffff",
    "bg": "#f7f8fa", "surface": "#ffffff", "surface2": "#f0f1f3", "surface3": "#e6e8ea",
    "ink": "#14161b", "ink2": "#5d5e62", "ink3": "#86878b"
  },
  "font": "Inter",
  "mono_font": null,
  "welcome": "How can Nova help today?",
  "agents": 0,
  "created_at": 1792367395275,
  "updated_at": 1792367395275
}

独自ドメイン#

PUT/v1/agents/brandings/{id}/domain

自社のドメインをブランディングに接続します（仕組み）。ドメインオブジェクトとともに 201 を返します。GET で取得（?check=1 を付けると最新のステータスをすぐに確認）、DELETE で接続を解除します。ドメインはブランディングごとに 1 つです。接続には 1 日分以上の残高が必要です。ドメインは接続中 1 日 $0.50 で、接続した日から課金され、開始済みの日は返金されません。ブランディングオブジェクトの domain も同じオブジェクト（または null）です。

リクエストボディのパラメーター

hostnamestring必須

所有しているドメイン（例：agents.yourcompany.com。URL を貼り付けても構いません）。

ドメインオブジェクト

hostnamestring

小文字。

statusstring

pending（DNS レコードまたは証明書を待っている）、active（エージェントを提供中）、error（errors を参照）。

recordsarray

追加する DNS レコード：{"type", "name", "value", "purpose"}。purpose が route のものはドメインを当社に向ける CNAME（必須）、ownership と certificate はドメインを向ける前に証明書を発行できる TXT レコード（任意）です。

cname_targetstring

CNAME の向け先。

errorsarray

待機中に不足しているもの。

price_day_microsinteger

1 日あたりの料金。

created_at、`active_at`、`checked_at` integer | null

エポックからのミリ秒。

cURL

curl -X PUT https://lovelyrouter.com/v1/agents/brandings/brd_6c1f0a9e3b7d2c4e8f5a1b0d/domain \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hostname": "agents.yourcompany.com"}'

エラー#

エラーは他の API と同じ形式です：{"error": {"type", "message"}}。

ステータス	タイプ	条件
400	`invalid_request_error`	項目が無効（どの項目かはメッセージに記載）
401	`authentication_error`	キーまたはトークンがない、無効、失効済み、期限切れ
402	`insufficient_quota`	残高がサイズの 15 分間分に足りない、またはエージェントの予算を使い切った
403	`permission_error`	スコープのないトークン、エージェントの実行とファイル以外に使われたトークン、またはエージェント自身のキー
404	`not_found`	そのエージェント、実行、ファイル、またはフォルダがない
409	`conflict`	すでに実行中（起動）、`auto_start` がオフで停止中（オープン、実行）または `"start": false` の実行、そのセッションで実行が進行中、またはエージェントが使用中のブランディングの削除
429	`rate_limit_exceeded`	すでに 20 エージェントが実行中、またはこのエージェントで 4 件の実行が進行中
502	`api_error`	サンドボックスを起動できなかった（請求なし）。再試行してください
503	`service_unavailable`	クラウドエージェントが現在利用できない、またはエージェントがまだ起動中