> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lusor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From an API key to your first agent turn in a few minutes.

This guide sends a task to an agent on one of your phones and reads back the result.

**You need:** a Lusor workspace with at least one phone: a Lusor Phone, or your own iPhone ([connect your iPhone](https://docs.lusor.ai/help/connect-your-iphone.md)) or Android phone ([connect your Android phone](https://docs.lusor.ai/help/connect-your-android.md)). See [Phones](https://docs.lusor.ai/phones/overview.md).

**1. Create an API key**

In the [Lusor app](https://app.lusor.ai), open **Settings → API Keys** and create a key. Copy it now: it is shown once.

```bash theme={null}
export LUSOR_API_KEY="lusor_..."
```

See [Authentication](https://docs.lusor.ai/authentication.md) for how keys work.

**2. Find your phone**

List the phones in the key's workspace:

```bash theme={null}
curl https://api.lusor.ai/v1/devices \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "8e2c…",
      "name": "Pixel",
      "tier": "cloud_managed",
      "planId": "virtual",
      "connected": true,
      "pairedAt": "2026-10-01T12:00:00Z"
    }
  ]
}
```

Note the `id` of a phone with `"connected": true`.

**3. Create an agent on that phone**

```bash theme={null}
curl https://api.lusor.ai/v1/agents \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart agent",
    "devices": [{ "device_id": "<device id>" }]
  }'
```

The response is the agent. Keep `data.id`, the agent id. `data.workspaceId` is your workspace id, which you will need for [direct phone control](https://docs.lusor.ai/phones/direct-control.md).

> [!TIP]
>
> Your workspace may already have agents. `GET /v1/agents` lists them, so you can reuse one instead of creating one.

**4. Send a task**

```bash theme={null}
curl https://api.lusor.ai/v1/agents/<agent id>/turns \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -d '{ "prompt": "Open Settings and tell me which software version this phone runs." }'
```

```json Response (202) theme={null}
{
  "data": {
    "id": "4f1d…",
    "sessionId": "mobile_use_9c2e…",
    "status": "queued",
    "queued": false,
    "needsDevice": false,
    "deviceId": "8e2c…",
    "recording": true
  }
}
```

The agent starts working in the background. `sessionId` identifies the session that records its work. The `Idempotency-Key` header makes the request safe to retry: sending the same key again returns this turn instead of starting a second one.

**5. Wait for it to finish**

Poll the session's status every few seconds:

```bash theme={null}
curl https://api.lusor.ai/v1/sessions/<sessionId>/status \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

The session is finished when `status` is `completed` (or `complete`), `failed`, or `cancelled`. If it is `awaiting_human`, the agent has asked you a question. Answer it with `POST /v1/sessions/<sessionId>/hitl` and it carries on. See [Answer the agent](https://docs.lusor.ai/agents/answer-the-agent.md).

**6. Read the result**

The agent's reply is the turn's `summary`. Read the agent to see its newest turns:

```bash theme={null}
curl https://api.lusor.ai/v1/agents/<agent id> \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

Each entry in `data.turns` has the turn's `sessionId`, `status` and `summary`. For the session itself, read `GET /v1/sessions/<sessionId>`: `error` explains a failure, and `output` holds data the agent collected, if any. To see each step the agent took, read `GET /v1/sessions/<sessionId>/events`.

## A complete script

The same flow in one script. It stops waiting if the agent asks you a question.

```python Python theme={null}
import os, time, uuid, requests

API = "https://api.lusor.ai/v1"
H = {"X-Api-Key": os.environ["LUSOR_API_KEY"]}
DONE = {"completed", "complete", "failed", "cancelled"}

agent_id = "<agent id>"
turn = requests.post(
    f"{API}/agents/{agent_id}/turns",
    headers={**H, "Idempotency-Key": str(uuid.uuid4())},
    json={"prompt": "Open Settings and tell me which software version this phone runs."},
).json()["data"]

session_id = turn["sessionId"]
while True:
    status = requests.get(f"{API}/sessions/{session_id}/status", headers=H).json()
    if status["status"] in DONE:
        break
    if status["status"] == "awaiting_human":
        print("The agent asked a question. See /agents/answer-the-agent.")
        break
    time.sleep(3)

agent = requests.get(f"{API}/agents/{agent_id}", headers=H).json()["data"]
reply = next((t for t in agent["turns"] if t["sessionId"] == session_id), {})
print(status["status"], reply.get("summary"), status.get("error"))
```

```javascript Node.js theme={null}
const API = "https://api.lusor.ai/v1";
const H = { "X-Api-Key": process.env.LUSOR_API_KEY };
const DONE = new Set(["completed", "complete", "failed", "cancelled"]);

const agentId = "<agent id>";
const res = await fetch(`${API}/agents/${agentId}/turns`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ prompt: "Open Settings and tell me which software version this phone runs." }),
});
const { data: turn } = await res.json();

let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = await (await fetch(`${API}/sessions/${turn.sessionId}/status`, { headers: H })).json();
} while (!DONE.has(status.status) && status.status !== "awaiting_human");

const { data: agent } = await (await fetch(`${API}/agents/${agentId}`, { headers: H })).json();
const reply = agent.turns.find((t) => t.sessionId === turn.sessionId);
console.log(status.status, reply?.summary, status.error);
```

## Next steps

> [card] [Send a turn](https://docs.lusor.ai/agents/send-a-turn.md)
>
> Queueing, safe retries, and sessions without an agent.

> [card] [Follow a session](https://docs.lusor.ai/agents/follow-a-session.md)
>
> Statuses, events, artifacts and the session list.

> [card] [Answer the agent](https://docs.lusor.ai/agents/answer-the-agent.md)
>
> Reply when the agent asks you a question.

> [card] [Direct phone control](https://docs.lusor.ai/phones/direct-control.md)
>
> Drive the phone yourself, action by action.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.