API reference

Agent endpoints

Every /v1/agents endpoint for cloud agents: create agents for your users, settings, start and stop, run tasks over the API, files and share links, open the web page, agent tokens, and brandings for white-labeled agents.

The cloud agents API lives under https://lovelyrouter.com/v1/agents. Authenticate with an API key from the console as Authorization: Bearer $LOVELY_API_KEY (Authentication), or, for one agent, with an agent token. The keys an agent session gets for itself can't call these endpoints. Bodies are JSON; money is in micro-dollars (1,000,000 = $1). Agents are billed from your prepaid balance; see Cloud agent pricing.

For a walkthrough, start with the cloud agents overview.

The agent object#

Attributes

idstring

Unique id, agt_ followed by 24 characters.

objectstring

Always agent.

namestring | null

Your label.

userstring | null

Your own id for the user this agent serves (1–128 characters: letters, digits, _ . @ : + -). Filter the list by it.

metadataobject | null

Your JSON object, up to 4 KB.

statusstring

stopped, starting or running.

sessionobject | null

The open session: id, status, size, vcpu, mem_gib, started_at, ready_at, and what it has cost so far: charge_micros (sandbox time), llm_micros (models and tools) and total_micros.

urlstring

The agent's web page, https://agent.lovelyrouter.com/a/<id>/. Sign in with Open or a ui token.

sizeidle_minutes

See settings.

settingsobject

model, tools, mcp_servers (header values shown as ••••••••), instructions.

budget_microsinteger | null

The agent stops, and won't start or run, once spend.total_micros reaches it.

brandingstring | null

The branding its page wears (brd_…), or null for the standard look.

white_labelboolean

true when it has a branding: its sandbox is billed at the white-label rates. The open session says the same of itself.

spendobject

compute_micros (sandbox time), llm_micros (models and tools its sessions used), total_micros.

workspaceobject

bytes stored, measured_at.

created_atinteger

Milliseconds since the epoch.

Create an agent#

POST/v1/agents

Creates an agent with its own empty workspace and returns 201 with the agent object. Accepts every setting, plus "start": true to start it at once. Up to 1,000 agents per account.

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}'

List agents#

GET/v1/agents

Newest first. ?user=cust-42 returns that user's agents; limit (≤ 200, default 50); before (a created_at) pages back, and next_before in the response is the value for the next page.

cURL

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

Get, update or delete an agent#

PATCH/v1/agents/{id}

GET returns the agent; PATCH (or POST) changes the fields you send; DELETE stops it if it runs and deletes it with its workspace, for good. Settings apply from the next start.

Body parameters

nameuser

As in the agent object; null clears them.

modelstring | null

The default LLM, any chat model id from GET /v1/models. null = claude-haiku-5.5.

toolsbooleanDefault true

Lovely Router's data tools and browser agent as MCP tools (mcp__tools__*), billed per use.

mcp_serversarray

Up to 8 remote MCP servers (streamable HTTP): {"name", "url", "headers"}. name is 1–32 characters of a-z 0-9 _ - starting with a letter (tools is taken), url a public https:// URL, headers up to 10. Header values are stored encrypted and never returned; sending •••••••• back keeps the stored value.

instructionsstring | null

Added to every session, up to 4,000 characters.

sizestring

small, medium or large (sizes).

idle_minutesinteger

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

max_hoursinteger

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

auto_startbooleanDefault true

Wake up when called: a stopped agent starts by itself for a run, an open, or a visit to its page. Applies at once.

brandingstring | null

A branding of yours: the agent becomes white-labeled from its next start, billed at the white-label rates. null = the standard look and rates.

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."}'

Start and stop#

POST/v1/agents/{id}/start

Starts the agent; it is running a few seconds later (a new agent's first start can take longer). POST /v1/agents/{id}/stop stops it and returns the session with its final charge_micros. Starting needs a balance that covers 15 minutes of its size (at least $0.25); up to 20 agents run at once per account. Runs start a stopped agent by themselves.

cURL

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

Run a task#

POST/v1/agents/{id}/runs

The agent API: sends one task to the agent and returns a run. The agent works in its sandbox with its tools and settings, exactly as in its web page; each run's session is saved and shows up there too. A stopped agent is started first when its auto_start is on (the default), and the agent stops about 5 seconds after its last run ends, whether the run woke it or it was already running, unless its page was used in that session (it then stops when idle). To keep it running between runs, send stop_when_done: false. Works with an API key or an agent token with the api scope.

Body parameters

inputstringRequired

The task, up to 100,000 characters.

session_idstring

Continue this session (from an earlier run's session_id). Omitted: a new session.

waitinteger

Hold the request up to this many seconds (≤ 300) for the run to finish.

streamboolean

Return the run's events as server-sent events instead: run, session, status (turns and steps, with token usage), tool_call, tool_result, text, final, then end with the finished run.

stop_when_doneboolean

Stop the agent about 5 seconds after its runs are done. Default: true, unless the agent's page was used in this session. false keeps the agent running (it then stops when idle); true stops it after this run even if its page was used before, unless someone uses its page meanwhile.

startbooleanDefault the agent's `auto_start

Start the agent if it is stopped. With an agent token, only auto_start decides: true can't start an agent that has it off.

A run lists the files the agent handed over in it as files: path (relative to the agent's home folder), description, bytes and url, where Files downloads it. A file saved outside the home folder isn't kept and has url: null. To show one to someone without an API key, make a share link.

GET /v1/agents/{id}/runs lists the runs since the agent last started, GET /v1/agents/{id}/runs/{run_id}?wait=30 returns one, GET …/events streams it, POST …/cancel stops it. Runs are kept while the agent runs; their sessions stay in the workspace. Up to 4 runs work at once per agent, one per session.

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
}

Files#

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

Lists a folder, or downloads a file, of the agent's home folder. path is relative to it; leave it out for the home folder itself. API runs work in deepseek-harness/api-requests (their sessions are grouped as API Requests in the agent's web page); sessions started in the web page work in deepseek-harness/default-workspace unless you open another folder. While the agent runs, files are read live ("live": true); while it is stopped they are as saved at its last stop, and reading them doesn't start it. Works with an API key or an agent token with the api scope.

A folder returns {"object": "list", "path", "live", "data", "truncated"}: up to 1,000 entries, folders first, each with name, path, type (file or dir), bytes, modified_at and url. A file returns its bytes as an attachment with its content type.

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"

Share links#

POST/v1/agents/{id}/shares

Makes a link that opens a file, or a folder as a website, for anyone who has it, with no sign-in. The link keeps working while the agent is stopped. A folder's link opens its index.html (or a list of its files when it has none), and the page loads the folder's other files by relative path. A file's link ends with its name. Returns 201 with {"object": "agent_share", "agent_id", "path", "type", "url", "expires_at"}.

Body parameters

pathstringRequired

A file or folder in the agent's home folder, as in Files.

expires_inintegerDefault 604800

Seconds the link works: 60 to 31,536,000 (a year). Default: a week.

POST /v1/agents/{id}/shares/revoke turns off every link of the agent at once. A link also ends when its agent is deleted, or when the API key or agent token that made it is revoked: an agent token with the api scope can make links too, and they end with the token. Only the account can turn links off.

Shared pages run sandboxed: scripts, forms and resources from other sites work, cookies and browser storage don't, and the page can't reach Lovely Router or other agents.

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
}

Open the web page#

POST/v1/agents/{id}/open

Returns url, a link valid for 60 seconds that opens the running agent's web page, signed in. The sign-in lasts 7 days, or until the key is revoked. A stopped agent with auto_start on is started first (its page shows Starting… until it is ready); otherwise 409.

Agent tokens for your users#

POST/v1/agents/{id}/tokens

Creates a token for one agent, to give to your own user, so they never see your API key. scopes: api lets the token use this agent's runs and files, make share links, and read its status; ui makes url, a link that opens the agent's web page (reusable until the token expires). Give api only to users who should not see the web page. expires_in: 60 seconds to 30 days (default 3,600). The token stops working when it expires, when you revoke the agent's tokens, when you delete the agent, or when you revoke the API key that created it.

POST /v1/agents/{id}/tokens/revoke revokes every token of the agent issued so far (links already opened stop within a minute).

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
}

Sessions#

GET/v1/agents/{id}/sessions

The agent's last 50 sandbox sessions, the open one included, with what each cost: charge_micros (sandbox time), llm_micros (the models and tools its key used) and total_micros. A session's stop_reason is user, idle, done (the run that woke it ended), balance, budget, max_time, exited, error, deleted or admin.

Brandings#

POST/v1/agents/brandings

Saved looks for white-labeled agents. POST creates one (201); GET /v1/agents/brandings lists yours (newest first, up to 50); GET, PATCH (or POST) and DELETE /v1/agents/brandings/{id} read, change and delete one. A PATCH changes the fields you send; agents that use the branding pick the change up at their next start. Deleting a branding that agents use returns 409. Agent tokens can't call these endpoints.

Body parameters

agent_namestringRequired

The name your users see on the page and the agent uses for itself: 1–40 letters, digits, spaces and . _ -, starting with a letter or digit.

namestring

Your label, up to 60 characters. Default: agent_name.

logostring | null

A PNG, JPEG, WebP or SVG image as a base64 data: URI, up to 64 KB. null = a monogram: the first letter of agent_name on the accent.

schemestringDefault dark

dark or light.

colorsobject

#rrggbb values: accent, bg (background), and optionally accentSoft (links), onAccent (text on the accent), surface, surface2, surface3 (panels, raised areas, borders), ink, ink2, ink3 (text, secondary, muted). Colors you leave out are derived from scheme, accent and bg. A PATCH that changes only scheme derives a new palette from the accent.

fontstring | null

Text font: 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 or Lora. null = the page's own.

mono_fontstring | null

Code font: JetBrains Mono, Geist Mono, IBM Plex Mono, Fira Code, Source Code Pro, Roboto Mono, DM Mono or Space Mono.

welcomestring | null

The headline over the first message box, up to 80 characters. null = What can I do for you?

The branding object has these fields with every color filled in, plus id (brd_ and 24 characters), object (agent_branding), agents (how many agents use it; in lists and reads), created_at and 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
}

Custom domain#

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

Connects your own domain to a branding (how it works); 201 with the domain object. GET reads it (add ?check=1 to ask for the latest status now), DELETE disconnects it. One domain per branding. Connecting needs a balance of at least one day's price; the domain costs $0.50 per day while connected, starting the day it is connected, with no refund for a day already started. The branding object carries the same object as domain (or null).

Body parameters

hostnamestringRequired

A domain you own, such as agents.yourcompany.com (a pasted URL is fine).

The domain object

hostnamestring

In lower case.

statusstring

pending (waiting for your DNS record or the certificate), active (serving your agents), or error (see errors).

recordsarray

The DNS records to add: {"type", "name", "value", "purpose"}. purpose route is the CNAME that sends the domain to us (required); ownership and certificate are TXT records that let the certificate be issued before the domain points at us (optional).

cname_targetstring

Where the CNAME points.

errorsarray

What is still missing, while pending.

price_day_microsinteger

The price per day.

created_atactive_at

Milliseconds since the epoch.

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"}'

Errors#

Errors use the shape of the rest of the API: {"error": {"type", "message"}}.

Status	Type	When
400	`invalid_request_error`	A field is invalid (the message says which)
401	`authentication_error`	Missing, invalid, revoked or expired key or token
402	`insufficient_quota`	The balance doesn't cover 15 minutes of the size, or the agent's budget is used up
403	`permission_error`	A token without the scope, a token used for something other than its agent's runs and files, or an agent's own key
404	`not_found`	No such agent, run, file or folder
409	`conflict`	Already running (start), stopped with `auto_start` off (open, a run) or a run with `"start": false`, a run already working in that session, or deleting a branding that agents use
429	`rate_limit_exceeded`	20 agents already running, or 4 runs already working on this agent
502	`api_error`	The sandbox couldn't start; you are not charged. Try again
503	`service_unavailable`	Cloud agents are not available right now, or the agent is still starting