API reference - Help Genie

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)

POST /v1/{resource}
{
  "action": "custom-action",
  "id": "optional-id",
  "data": {}
}

Direct invocation (POST body)

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

resource

string

required

API resource name. Example: genies, knowledge-base, integrations, api-keys.

action

string

required

Action for the selected resource (for example list, get, create, update, delete).

string

Optional resource identifier for single-record actions.

data

object

Action-specific parameters (filters, pagination, payload fields).

Response envelope

{
  "success": true,
  "data": {
    // action-specific response data
  }
}

Error (4xx / 5xx):

{
  "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