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

# Lincoln AI

> Hand tasks to your workspace's AI agent from code, the same agent as Dashboard → Conversations.

Lincoln AI is the agent behind **Dashboard → Conversations**. You tell it what you want in plain language
and it does the work with your workspace's own tools: phone numbers, voice agents, campaigns, contacts,
automations, knowledge, videos and more. These endpoints let your code (or your own AI agent, over
[MCP](/api-reference/mcp)) talk to it directly.

Conversations you start here are ordinary Lincoln conversations, so they also appear in the dashboard,
and you can pick a thread up from either side.

| Endpoint                             | What it does                                                        | Scope           |
| ------------------------------------ | ------------------------------------------------------------------- | --------------- |
| `POST /v1/lincoln/messages`          | Send Lincoln a message, or answer its pending approvals             | `lincoln:write` |
| `GET /v1/lincoln/conversations/{id}` | Status, latest reply, actions, pending approvals and the transcript | `lincoln:read`  |
| `GET /v1/lincoln/conversations`      | Every conversation in the workspace, newest first                   | `lincoln:read`  |

<Note>
  Lincoln AI must be on the workspace's plan (it comes with the Growth Marketing Manager). Messaging Lincoln
  is free; the actions it takes are billed exactly as they are in the dashboard, and anything that costs money
  waits for your approval first.
</Note>

## 1. Give Lincoln a task

Leave out `conversation_id` to start a new conversation.

```bash theme={null}
curl -X POST "https://api.lumisreach.com/api/v1/lincoln/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Which of my phone numbers got the most calls this week?" }'
```

The request waits for Lincoln to finish (up to `wait_seconds`, default 120, max 240):

```json theme={null}
{
  "data": {
    "conversation_id": "9b0e4c1a-…",
    "title": "Which of my phone numbers got the most calls this week?",
    "status": "idle",
    "run_id": "wrun_…",
    "reply": "Your main line, +1 415 555 0123, took 42 calls this week, more than your other two combined.",
    "actions": [
      {
        "tool_call_id": "toolu_…",
        "tool": "list_phone_numbers",
        "status": "completed",
        "input": {},
        "output": { "numbers": [ … ] },
        "error": null
      }
    ],
    "pending_approvals": [],
    "error": null,
    "updated_at": "2026-09-26T18:04:12.102Z"
  }
}
```

Send the next message with the same `conversation_id` to follow up. Lincoln remembers the whole thread.

## 2. Long tasks: poll

If Lincoln is still working when `wait_seconds` runs out (or you passed `"wait_seconds": 0`), `status` is
`working`. The task keeps running; poll until it settles:

```bash theme={null}
curl "https://api.lumisreach.com/api/v1/lincoln/conversations/9b0e4c1a-…" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

While it works, `reply` holds what Lincoln has said so far. A conversation takes one message at a time:
sending another while it is `working` returns `409 conflict`.

| `status`            | Meaning                                                             |
| ------------------- | ------------------------------------------------------------------- |
| `working`           | Lincoln is mid-task. Poll again in a few seconds.                   |
| `idle`              | Done. `reply` is final; send your next message whenever you like.   |
| `awaiting_approval` | Paused on something that costs money or can't be undone. See below. |
| `failed`            | The task errored; `error` says why. You can send another message.   |

## 3. Approvals

Before anything that spends money or can't be undone (buying a number, placing a call, sending texts,
publishing a video), Lincoln stops and asks. The response comes back as `awaiting_approval`:

```json theme={null}
{
  "data": {
    "status": "awaiting_approval",
    "reply": "I found +1 415 555 0188. Want me to buy it?",
    "pending_approvals": [
      {
        "approval_id": "approval-toolu_…",
        "tool_call_id": "toolu_…",
        "tool": "buy_phone_number",
        "input": { "phoneNumber": "+14155550188" },
        "reason": "Buying a number charges the card on file $5.00 per number, every month."
      }
    ]
  }
}
```

Answer **every** pending approval in one request, with `approvals` instead of `message`:

```bash theme={null}
curl -X POST "https://api.lumisreach.com/api/v1/lincoln/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "9b0e4c1a-…",
    "approvals": [{ "approval_id": "approval-toolu_…", "approved": true }]
  }'
```

Lincoln carries on from where it stopped. Declining (`"approved": false`, optionally with a `reason`)
tells Lincoln not to do it, and it replies accordingly. A new `message` is refused with `409 conflict`
until the pending approvals are answered.

## Over MCP

The same three operations are MCP tools on the [LumisReach MCP server](/api-reference/mcp):
`ask_lincoln`, `get_lincoln_conversation` and `list_lincoln_conversations`. `ask_lincoln` waits 45
seconds by default (so it fits inside most MCP clients' tool timeout) and returns `working` for longer
tasks, which your agent then follows with `get_lincoln_conversation`.