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

# Invite API

> Create, manage, and verify invite tokens for platform access

# Invite API

Create and verify invite tokens for gating access to the Agentbot platform.

<Note>Invite tokens are 64-character hex strings generated from `crypto.randomBytes(32)`. The older 12-character code format is deprecated — see [legacy format](#legacy-invite-format) below.</Note>

## Authentication

| Endpoint                   | Auth required                    |
| -------------------------- | -------------------------------- |
| `POST /api/invite`         | Session (any authenticated user) |
| `POST /api/invites/verify` | None                             |
| `GET /api/admin/invites`   | Session (admin only)             |
| `POST /api/admin/invites`  | Session (admin only)             |

## Create invite

```http theme={"dark"}
POST /api/invite
```

Creates an invite token linked to your account. Requires an authenticated session.

### Request body

| Field  | Type   | Required | Description                                                                  |
| ------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `name` | string | Yes      | Display name for the invite recipient. Validated against injection patterns. |

### Response

```json theme={"dark"}
{
  "success": true,
  "inviteUrl": "https://agentbot.sh/invite?token=abc123...&name=Alice",
  "token": "a1b2c3d4...64 hex characters"
}
```

| Field       | Type    | Description                                         |
| ----------- | ------- | --------------------------------------------------- |
| `success`   | boolean | Whether the invite was created                      |
| `inviteUrl` | string  | Full URL the recipient can use to accept the invite |
| `token`     | string  | 64-character hex token                              |

### Errors

| Code | Description                                    |
| ---- | ---------------------------------------------- |
| 400  | Name is missing or contains invalid characters |
| 401  | Not authenticated                              |
| 404  | User not found                                 |
| 500  | Failed to create invite                        |

## Verify invite

```http theme={"dark"}
POST /api/invites/verify
```

Verifies an invite token and returns invite details. No authentication required. Tokens must be in the 64-character hex format.

### Request body

| Field   | Type   | Required | Description                   |
| ------- | ------ | -------- | ----------------------------- |
| `token` | string | Yes      | 64-character hex invite token |

### Response (valid)

```json theme={"dark"}
{
  "valid": true,
  "plan": "headliner",
  "audience": "headliner",
  "email": "invitee@example.com"
}
```

| Field      | Type                        | Description                                                                                                                                          |
| ---------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `valid`    | boolean                     | Whether the token is valid                                                                                                                           |
| `plan`     | string                      | Plan tier assigned to the invite. Returns `"headliner"` when the invite audience is `headliner`, otherwise `"solo"`.                                 |
| `audience` | string \| undefined         | Invite audience tier: `headliner`, `guest`, or `partner`. Omitted when the invite was verified by token format alone.                                |
| `email`    | string \| null \| undefined | Email associated with the invite, when stored. Omitted when the invite was verified by token format alone.                                           |
| `note`     | string \| undefined         | Present only when the invite was verified by token format alone (database model pending). Omitted when the invite was verified against the database. |

<Note>The branded headliner landing page at `/basefm/headliner` calls this endpoint to confirm the invite before pointing DJs to redemption and the DJ stream panel. It reads `audience` and `email` from the response to display issued-to details.</Note>

### Errors

| Code | Description                                                             |
| ---- | ----------------------------------------------------------------------- |
| 400  | Token is missing, not a string, or not in valid 64-character hex format |
| 404  | Invite not found                                                        |
| 410  | Invite has already been used or has expired                             |
| 500  | Verification failed                                                     |

## List invites (admin)

```http theme={"dark"}
GET /api/admin/invites
```

Returns the most recent invites with summary counts. Requires an authenticated session with an admin email address. Records are persisted in the database, so invites survive process restarts and remain auditable.

### Response

```json theme={"dark"}
{
  "invites": [
    {
      "code": "a1b2c3d4...64 hex characters",
      "email": "invitee@example.com",
      "audience": "headliner",
      "createdAt": "2026-03-25T21:00:00.000Z",
      "expiresAt": "2026-06-25T21:00:00.000Z",
      "status": "active"
    }
  ],
  "total": 1,
  "active": 1
}
```

| Field                 | Type                | Description                                                                                                                 |
| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `invites`             | array               | List of invites, ordered by creation time descending. Up to 200 entries.                                                    |
| `invites[].code`      | string              | 64-character hex invite token                                                                                               |
| `invites[].email`     | string \| null      | Email the invite was created for                                                                                            |
| `invites[].audience`  | string              | Invite audience tier: `headliner`, `guest`, or `partner`                                                                    |
| `invites[].createdAt` | string              | ISO 8601 creation timestamp                                                                                                 |
| `invites[].usedAt`    | string \| undefined | ISO 8601 timestamp when the invite was redeemed                                                                             |
| `invites[].expiresAt` | string \| undefined | ISO 8601 expiration timestamp. Omitted if the invite has no expiry.                                                         |
| `invites[].status`    | string              | One of `active`, `used`, or `expired`. An invite is `expired` when `expiresAt` has passed and the invite has not been used. |
| `total`               | number              | Total number of invites returned                                                                                            |
| `active`              | number              | Number of invites with status `active`                                                                                      |

### Errors

| Code | Description                     |
| ---- | ------------------------------- |
| 403  | Not authorized (requires admin) |
| 500  | Failed to retrieve invites      |

## Create invite (admin)

```http theme={"dark"}
POST /api/admin/invites
```

Creates an invite for a specific email address and persists it to the database. Requires an authenticated session with an admin email address.

### Request body

| Field       | Type   | Required | Description                                                                                    |
| ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| `email`     | string | Yes      | Email address to associate with the invite. Must be a valid email format; lower-cased on save. |
| `audience`  | string | No       | Invite audience tier. One of `headliner`, `guest`, or `partner`. Defaults to `headliner`.      |
| `expiresAt` | string | No       | ISO 8601 timestamp at which the invite expires. Omit for an invite with no expiry.             |

### Response

```json theme={"dark"}
{
  "success": true,
  "invite": {
    "code": "a1b2c3d4...64 hex characters",
    "email": "invitee@example.com",
    "audience": "headliner",
    "createdAt": "2026-03-25T21:00:00.000Z",
    "expiresAt": "2026-06-25T21:00:00.000Z",
    "status": "active"
  },
  "code": "a1b2c3d4...64 hex characters",
  "email": "invitee@example.com",
  "audience": "headliner",
  "inviteUrl": "https://agentbot.sh/invite?token=a1b2c3d4..."
}
```

Returns HTTP `201 Created` on success.

| Field       | Type    | Description                                                                                         |
| ----------- | ------- | --------------------------------------------------------------------------------------------------- |
| `success`   | boolean | Whether the invite was created                                                                      |
| `invite`    | object  | The created invite record. Same shape as items in the [list invites](#list-invites-admin) response. |
| `code`      | string  | 64-character hex invite token (mirrors `invite.code`)                                               |
| `email`     | string  | Email the invite was created for (mirrors `invite.email`)                                           |
| `audience`  | string  | Invite audience tier (mirrors `invite.audience`)                                                    |
| `inviteUrl` | string  | Full URL the recipient can use to accept the invite                                                 |

### Errors

| Code | Description                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | Email is missing, not a valid email address, `audience` is not one of the allowed values, or `expiresAt` is not a valid ISO 8601 date |
| 403  | Not authorized (requires admin)                                                                                                       |
| 500  | Failed to create invite                                                                                                               |

***

## Legacy invite format

<Warning>The previous invite system used 12-character hex codes with `POST /api/invite/generate` and `POST /api/invite/validate`. These endpoints are deprecated. Migrate to the new endpoints above.</Warning>

### Deprecated: generate invite code

```http theme={"dark"}
POST /api/invite/generate
```

Previously generated a 12-character hex invite code. Replaced by `POST /api/invite` (session auth) and `POST /api/admin/invites` (admin session auth).

### Deprecated: validate invite code

```http theme={"dark"}
POST /api/invite/validate
```

Previously validated and consumed a 12-character invite code. Replaced by `POST /api/invites/verify`, which accepts 64-character hex tokens and returns `valid` and `plan` fields.