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

# API reference

> Complete API conventions: auth, request formats, errors, and core resources

## Base URLs

HelpGenie supports both REST-style routes and direct Supabase function invocation.

```
Primary: https://api.helpgenie.ai/v1
Alternative: https://helpgenie.ai/api/v1
Direct Supabase: POST https://api.helpgenie.ai/v1
```

REST routes follow:

```
{BASE_URL}/{resource}[/{id}]
```

## Authentication

All auth methods use the `Authorization` header.

```
Authorization: Bearer <token>
```

### API key (recommended for external integrations)

```
Authorization: Bearer hg_live_...
```

* Prefix: `hg_live_`
* Rate limit: `60 requests/minute` per key
* Maximum `5` active keys per user

### Session JWT (browser/app context)

```
Authorization: Bearer <supabase_access_token>
```

### Service role key (server-to-server)

```
Authorization: Bearer <SUPABASE_SERVICE_ROLE_KEY>
x-user-id: <user-uuid>
Content-Type: application/json
```

## Request formats

### REST-style (recommended)

```
GET    /v1/{resource}         → action: "all"
GET    /v1/{resource}/list    → action: "list"
GET    /v1/{resource}/{id}    → action: "get"
POST   /v1/{resource}         → action: "create"
PATCH  /v1/{resource}/{id}    → action: "update"
DELETE /v1/{resource}/{id}    → action: "delete"
```

### Custom actions (POST body)

```json theme={null}
POST /v1/{resource}
{
  "action": "custom-action",
  "id": "optional-id",
  "data": {}
}
```

### Direct invocation (POST body)

```json theme={null}
POST https://api.helpgenie.ai/v1
{
  "resource": "genies",
  "action": "list",
  "id": null,
  "data": {}
}
```

<ParamField body="resource" type="string" required>
  API resource name. Example: `genies`, `knowledge-base`, `integrations`, `api-keys`.
</ParamField>

<ParamField body="action" type="string" required>
  Action for the selected resource (for example `list`, `get`, `create`, `update`, `delete`).
</ParamField>

<ParamField body="id" type="string">
  Optional resource identifier for single-record actions.
</ParamField>

<ParamField body="data" type="object">
  Action-specific parameters (filters, pagination, payload fields).
</ParamField>

## Response envelope

```json theme={null}
{
  "success": true,
  "data": {
    // action-specific response data
  }
}
```

**Error (4xx / 5xx):**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "status": 400
  }
}
```

## Error codes

| Code                  | Status | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `UNAUTHORIZED`        | 401    | Missing or invalid Authorization header |
| `INVALID_TOKEN`       | 401    | Token is invalid or expired             |
| `FORBIDDEN`           | 403    | User lacks permission for the resource  |
| `NOT_FOUND`           | 404    | Resource not found                      |
| `AGENT_NOT_FOUND`     | 404    | Genie not found or access denied        |
| `VALIDATION_ERROR`    | 400    | Invalid request format or data          |
| `INVALID_ACTION`      | 400    | Action not supported for the resource   |
| `RATE_LIMIT_EXCEEDED` | 429    | Too many requests                       |
| `INTERNAL_ERROR`      | 500    | Server error                            |

## Access control

Roles determine access scope:

* **internal\_admin** - Full cross-account access.
* **standard\_user** - Access to their own business data.
* **consumer** - Limited read-only/interaction access.

Admin users can pass `adminMode: true` or a `userId` parameter to operate on resources owned by other users.

## Resource map

<CardGroup cols={2}>
  <Card title="Genies" icon="robot" href="/api-reference/genies">
    Create, update, list, and delete voice AI genies
  </Card>

  <Card title="Genie groups" icon="layer-group" href="/api-reference/genie-groups">
    Group and organize genies
  </Card>

  <Card title="Conversations" icon="comments" href="/api-reference/conversations">
    Sync, analyze, and manage conversations
  </Card>

  <Card title="Knowledge base" icon="book" href="/api-reference/knowledge-base">
    Manage documents and attach them to genies
  </Card>

  <Card title="Document folders" icon="folder" href="/api-reference/document-folders">
    Organize knowledge base documents into folders
  </Card>

  <Card title="Voices" icon="microphone" href="/api-reference/voices">
    Manage voice favorites and track usage
  </Card>

  <Card title="Voice collections" icon="music" href="/api-reference/voice-collections">
    Create and manage curated voice collections
  </Card>

  <Card title="Leads" icon="user-plus" href="/api-reference/leads">
    Capture and manage customer leads
  </Card>

  <Card title="Lead notes" icon="sticky-note" href="/api-reference/lead-notes">
    Add and manage notes on leads
  </Card>

  <Card title="Marketplace" icon="store" href="/api-reference/marketplace">
    Browse and publish genie templates
  </Card>

  <Card title="Profiles" icon="user" href="/api-reference/profiles">
    Manage user profiles and settings
  </Card>

  <Card title="Teams" icon="users" href="/api-reference/teams">
    Create teams, invite members, manage roles
  </Card>

  <Card title="Activities" icon="clock" href="/api-reference/activities">
    Track platform activity and audit logs
  </Card>

  <Card title="Goals" icon="target" href="/api-reference/goals">
    Manage agent goals and outcomes
  </Card>

  <Card title="API keys" icon="key" href="/api-reference/api-keys">
    Create, revoke, and delete developer API keys
  </Card>

  <Card title="Phone numbers" icon="phone" href="/api-reference/phone-numbers">
    Provision, release, and manage Twilio phone numbers
  </Card>

  <Card title="QR codes" icon="qrcode" href="/api-reference/qr-code">
    Manage QR code images for genie pages
  </Card>

  <Card title="Worker genies" icon="gears" href="/api-reference/worker-genies">
    Autonomous background AI agents for tasks and integrations
  </Card>

  <Card title="Analytics" icon="chart-line" href="/api-reference/analytics">
    Platform analytics, trends, and genie performance
  </Card>

  <Card title="Billing" icon="credit-card" href="/api-reference/billing">
    Subscriptions, usage, invoices, and checkout
  </Card>

  <Card title="Branding" icon="palette" href="/api-reference/branding">
    Team branding, logos, and style configuration
  </Card>

  <Card title="Portals" icon="window" href="/api-reference/portals">
    Create multi-genie portal pages
  </Card>

  <Card title="Agent pages" icon="browser" href="/api-reference/agent-pages">
    Manage individual genie landing pages
  </Card>

  <Card title="Integrations" icon="plug" href="/api-reference/integrations">
    Connect external services and APIs
  </Card>

  <Card title="Automations" icon="bolt" href="/api-reference/automations">
    Create and manage automated workflows
  </Card>

  <Card title="Playbooks" icon="book-open" href="/api-reference/playbooks">
    Browse and apply pre-built genie playbooks
  </Card>

  <Card title="Capabilities" icon="sparkles" href="/api-reference/capabilities">
    Discover resources and actions at runtime
  </Card>
</CardGroup>