Create an agent

An agent is a persistent assistant with a name, a model, a history, and at most one phone. You send it tasks as turns, and it remembers earlier turns.

Create one

curl https://api.lusor.ai/v1/agents \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shopping assistant",
    "description": "Checks orders and prices in shopping apps.",
    "devices": [{ "device_id": "<device id>" }]
  }'

import os, requests

r = requests.post(
    "https://api.lusor.ai/v1/agents",
    headers={"X-Api-Key": os.environ["LUSOR_API_KEY"]},
    json={
        "name": "Shopping assistant",
        "description": "Checks orders and prices in shopping apps.",
        "devices": [{"device_id": "<device id>"}],
    },
)
agent = r.json()["data"]
print(agent["id"], agent["workspaceId"])

const res = await fetch("https://api.lusor.ai/v1/agents", {
  method: "POST",
  headers: { "X-Api-Key": process.env.LUSOR_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Shopping assistant",
    description: "Checks orders and prices in shopping apps.",
    devices: [{ device_id: "<device id>" }],
  }),
});
const { data: agent } = await res.json();
console.log(agent.id, agent.workspaceId);

The call returns 201 with the agent in data. Keep data.id, the agent id.

Field	Required	Notes
`name`	Yes	Up to 255 characters.
`description`	No	Up to 4,096 characters.
`model`	No	The model the agent uses. Leave it out for the default. See Choose a model.
`devices`	No	The agent’s phone, as a list with at most one entry: `[{ "device_id": "<device id>" }]`. A second entry is rejected with `400`.
`color`, `avatar`	No	How the agent looks in the Lusor app. `avatar` is an id such as `emojis/rocket`. Leave it out for a random emoji.

Find device ids with GET /v1/devices. See Phones.

POST /v1/agents/primary returns your workspace’s primary agent, and creates it if there is none. Calling it again returns the same agent.

Give it a phone, or move it

An agent uses at most one phone. To attach one, or to move the agent to another phone, send the new phone:

curl -X PATCH https://api.lusor.ai/v1/agents/<agent id> \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "devices": [{ "device_id": "<new device id>" }] }'

The swap is atomic. The agent’s next turn uses the new phone. Send "devices": [] to detach the phone. The same call changes name, description, model, color or avatar. Send only the fields you want to change.

Manage agents

Action	Endpoint
List agents	`GET /v1/agents`
Read an agent and its newest turns	`GET /v1/agents/{id}`
Read older turns	`GET /v1/agents/{id}/turns?cursor=…`
Change an agent	`PATCH /v1/agents/{id}`
Archive an agent	`DELETE /v1/agents/{id}`
List archived agents	`GET /v1/agents/trash`
Restore an archived agent	`POST /v1/agents/{id}/restore`

GET /v1/agents returns every active agent. Add limit (1 to 100) or cursor to read one page at a time, most recently active first. The response then carries nextCursor and hasMore. GET /v1/agents/{id} returns the agent’s newest 20 turns in turns, oldest first. Pass turnsCursor as cursor to GET /v1/agents/{id}/turns to walk back through older history.

Archive and restore

Archiving hides the agent. Its sessions and recordings stay. You can restore it for 30 days: purgeAfter says until when. After that, restore returns 410.

Get started

Agents & sessions

Phones

Billing and limits

Create an agent

Create one

Give it a phone, or move it

Manage agents

Archive and restore

​Create one

​Give it a phone, or move it

​Manage agents

​Archive and restore

Create one

Give it a phone, or move it

Manage agents

Archive and restore