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 and verify invite tokens for gating access to the Agentbot platform.
Invite tokens are 64-character hex strings generated from
crypto.randomBytes(32). The older 12-character code format is deprecated — see
legacy format below.
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
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
{
"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
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)
{
"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. |
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.
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)
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
{
"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)
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
{
"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..."
}
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 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 |
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.
Deprecated: generate invite code
POST /api/invite/generate
POST /api/invite (session auth) and POST /api/admin/invites (admin session auth).
Deprecated: validate invite code
POST /api/invite/validate
POST /api/invites/verify, which accepts 64-character hex tokens and returns valid and plan fields.
