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

# Lines API

> How Tuco AI exposes your sending identities through the API. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples in curl.

## Before You Request Lines

The line-request API is for workspaces that already exist in Tuco.

That means the normal first step is still:

1. Sign in to Tuco.
2. Create or join a workspace.
3. Buy a base plan for that workspace.
4. Use your workspace API key to request lines.

If the workspace does not have an active subscription, Tuco returns `subscription_required` and does not create the request.

***

## What the Lines API Does

Lines are the sending identities you use in Tuco, such as phone numbers and email addresses.

Through the API, you can:

* Request a new line.
* Check whether a request is waiting for payment, provisioning, active, failed, or canceled.
* Recover a payment link for a pending request.
* Cancel a pending request you no longer want.
* List the lines already attached to your workspace.

***

## Line Request Flow

The request flow is intentionally simple:

1. Submit the line details once.
2. Tuco checks your active plan and current capacity.
3. If the request is included in your plan, Tuco moves it straight to `provisioning`.
4. If the request requires an add-on, Tuco stores the line request as `awaiting_payment` and returns a hosted invoice link.
5. After payment succeeds, the request moves to `provisioning`.

You do not need to resubmit the same line after payment.

### What happens if the user does not want to pay?

If a line request is in `awaiting_payment`, the user can:

* pay the invoice and let the same request continue
* recover the payment link later
* cancel the request entirely

Canceling the pending request releases the payment block and lets the workspace create a different request.

### What happens if the user loses the payment link?

Use the line-request management endpoint to recover it. If the invoice is still open, Tuco returns the same hosted invoice link. If billing has already been reconciled, the request may already move to `provisioning`.

### What blocks the next request?

Only `awaiting_payment` blocks a new line request.

A request already in `provisioning` does not block the next purchase. This lets a workspace continue buying or requesting lines while earlier ones are still being set up.

***

## Plan Behavior

Tuco checks both the workspace plan and the line type you are requesting.

| Plan    | Phone lines                                         | Email lines                                 |
| ------- | --------------------------------------------------- | ------------------------------------------- |
| Mini    | Not available                                       | First email included, more email lines paid |
| Starter | First phone included, no extra phone lines          | Paid add-ons                                |
| Growth  | First 2 phone lines included, more phone lines paid | Paid add-ons                                |

Workspace-level overrides can still raise limits for specific customers.

***

## Line Request Statuses

| Status             | Meaning                                                                              |
| ------------------ | ------------------------------------------------------------------------------------ |
| `awaiting_payment` | The line request exists, but payment is still required before provisioning can begin |
| `provisioning`     | Tuco accepted the request and provisioning is underway                               |
| `active`           | The line is ready to use                                                             |
| `failed`           | Provisioning did not complete successfully                                           |
| `canceled`         | The request was canceled before completion                                           |

***

## Endpoints

* [Create Line Request](/api-reference/endpoint/create-line-request)
* [Get Line Request](/api-reference/endpoint/get-line-request)
* [Manage Line Request](/api-reference/endpoint/manage-line-request)
* [Get Lines](/api-reference/endpoint/get-lines)

### Recommended integration pattern

For most API clients, the cleanest pattern is:

1. Call `POST /api/line-requests`
2. If the response is `provisioning`, store the returned `line._id`
3. If the response is `awaiting_payment`, store the returned `line._id` and `paymentUrl`
4. Poll `GET /api/line-requests/:id` until the status changes
5. If needed, call `POST /api/line-requests/:id` with `action: "payment_link"` or `action: "cancel"`

***

## Fetch All Lines (API Key)

### Endpoint

* **Method**: `GET`
* **Path**: `/api/lines/by-user`
* **Auth**: Tuco API key or Clerk token (via `authenticateRequest`)

### Behavior

Returns all lines for the authenticated workspace, including:

* current profile details
* provisioning and payment state
* per-day usage
* public health information when available

For request-specific lifecycle management, use the line-request endpoints above.

### Example

```bash theme={null}
GET /api/lines/by-user
Authorization: Bearer tuco_xxx
```

### Response

```json theme={null}
{
  "lines": [
    {
      "_id": "667f1f77bcf86cd799439011",
      "workspaceId": "org_123",
      "firstName": "Sales",
      "lastName": "Team 1",
      "phone": "+12025551234",
      "email": "sales+1@example.com",
      "isActive": true,
      "provisioningStatus": "active",
      "paymentStatus": "paid",
      "requestSource": "api",
      "requestedChannelType": "email",
      "requestedLineType": "purchased",
      "paymentLinkUrl": null,
      "stripeInvoiceId": "in_123",
      "dailyNewConversationsLimit": 20,
      "dailyTotalMessagesLimit": 150,
      "usage": {
        "date": "2025-10-14",
        "newMessages": 3,
        "totalMessages": 42
      },
      "healthCheck": {
        "status": "healthy",
        "lastCheckedAt": "2025-10-14T10:00:00Z"
      }
    }
  ]
}
```

***

## Check Health of a Line

### Endpoint

* **Method**: `GET`
* **Path**: `/api/lines/check-availability?id={lineId}`
* **Auth**: Clerk (Tuco dashboard or trusted backend using Clerk tokens)

This endpoint performs a fresh health check for a specific line (server ping + iMessage availability) and updates the line’s health status.

### Example

```bash theme={null}
GET /api/lines/check-availability?id=667f1f77bcf86cd799439011
Authorization: Bearer <clerk_token>
```

### Response (success)

```json theme={null}
{
  "success": true,
  "lineId": "667f1f77bcf86cd799439011",
  "status": "healthy",
  "failures": [],
  "checkedAt": "2025-10-14T10:30:00Z",
  "shouldNotify": false,
  "notificationSent": false
}
```

If the line is not active or lacks the necessary configuration, you receive a `400` with a descriptive error; on auth failure you receive `401`.