Making requests

Request methods

The HelpGenie API supports two ways to make requests: the ApiService.invoke() pattern (recommended for TypeScript projects) and direct HTTP requests.

ApiService.invoke() (recommended)

The ApiService class handles authentication, request formatting, and response unwrapping automatically:

import { ApiService } from "@/services/api/ApiService";

const genies = await ApiService.invoke({
  resource: "genies",
  action: "all",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "all"
  }'

The invoke method accepts an options object with these fields:

string

required

The API resource to target. Must be one of the 13 supported resources.

string

required

The action to perform. Common actions: all, list, get, create, update, delete.

string | number

The record identifier. Required for get, update, and delete actions.

object

The request payload. Used with create and update actions. Structure varies by resource.

Direct HTTP requests

You can also call the Edge Function directly. The API accepts both a body-based resource/action pattern and standard REST-style HTTP methods.

Body-based (POST)
REST-style

Send the resource, action, and data in the request body:

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "get",
    "id": "abc-123"
  }'

Use HTTP methods and URL paths:

# GET all genies
GET /v1/genies

# GET a single genie
GET /v1/genies/abc-123

# GET list (compact format)
GET /v1/genies/list

# CREATE a genie
POST /v1/genies

# UPDATE a genie
PATCH /v1/genies/abc-123

# DELETE a genie
DELETE /v1/genies/abc-123

Common actions

Most resources support a standard set of actions. Some resources add custom actions specific to their domain.

Action	Description	Requires `id`	Requires `data`
`all`	Fetch all records with full details and relations	No	No
`list`	Fetch a compact list of records (for dropdowns and selectors)	No	No
`get`	Fetch a single record by ID	Yes	No
`create`	Create a new record	No	Yes
`update`	Update an existing record	Yes	Yes
`delete`	Delete a record	Yes	No

`list` vs `all`

The API distinguishes between two fetching actions:

all returns full records with related data (joins, counts, nested objects). Use this when you need complete information.
list returns minimal records with only key fields (typically id and name). Use this for populating dropdowns, selectors, or anywhere you need a lightweight list.

// Full records with all relations — use for detail views
const allGenies = await ApiService.invoke({
  resource: "genies",
  action: "all",
});

// Compact records — use for dropdowns and selectors
const genieList = await ApiService.invoke({
  resource: "genies",
  action: "list",
});

# Full records with all relations
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"resource": "genies", "action": "all"}'

# Compact records for dropdowns
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"resource": "genies", "action": "list"}'

Pagination differs between all and list.

The all action on genies uses cursor-based pagination. The response includes nextCursor and hasMore fields. Pass cursor in the request data to fetch the next page.
Most other resources use offset-based pagination. The response includes count, and you control paging with limit and offset in the request data.

Request examples

Create a resource

const newGenie = await ApiService.invoke({
  resource: "genies",
  action: "create",
  data: {
    genieName: "Support Agent",
    voiceId: "voice-abc-123",
    firstMessage: "Hi, how can I help you today?",
  },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "create",
    "data": {
      "genieName": "Support Agent",
      "voiceId": "voice-abc-123",
      "firstMessage": "Hi, how can I help you today?"
    }
  }'

Get a single resource

const genie = await ApiService.invoke({
  resource: "genies",
  action: "get",
  id: "abc-123",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "get",
    "id": "abc-123"
  }'

Update a resource

const updated = await ApiService.invoke({
  resource: "genies",
  action: "update",
  id: "abc-123",
  data: {
    genieName: "Updated Agent Name",
  },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "update",
    "id": "abc-123",
    "data": {
      "genieName": "Updated Agent Name"
    }
  }'

Delete a resource

await ApiService.invoke({
  resource: "genies",
  action: "delete",
  id: "abc-123",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "delete",
    "id": "abc-123"
  }'

Response structure

All responses use a consistent envelope:

Success response

{
  "success": true,
  "data": {
    "id": "abc-123",
    "genieName": "Support Agent",
    "voiceId": "voice-abc-123",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

For list and all actions, data is an array:

{
  "success": true,
  "data": [
    { "id": "abc-123", "genieName": "Support Agent" },
    { "id": "def-456", "genieName": "Sales Agent" }
  ]
}

When using ApiService.invoke(), the response is automatically unwrapped. You receive the data value directly, not the full envelope.

Error response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404
  }
}

See Error handling for all error codes.

Warnings

A response can include a warnings array of strings next to data. A warning doesn’t mean the request failed. It points out something you should check.

Undocumented fields and strict mode

On create and update actions, the API compares the top-level keys in data with the fields documented for that action. You can get those fields from capabilities/schema. If you send a field that isn’t documented, it was most likely ignored. The request still runs, and the response includes a warning that names the field:

{
  "success": true,
  "data": { "agent": { "id": "abc-123" } },
  "warnings": [
    "Unrecognized field(s) for genies/update: prompt. They are not in the documented schema and were most likely ignored. Call capabilities/schema for the accepted fields, or send \"strict\": true next to \"resource\" to have such a request rejected."
  ]
}

To have such a request rejected instead, send "strict": true at the top level of the body, next to resource. Nothing is changed, and the request fails with UNKNOWN_FIELDS (HTTP 400), listing the unknown and accepted fields in error.details:

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "update",
    "id": "abc-123",
    "strict": true,
    "data": { "prompt": "Be friendly." }
  }'

{
  "success": false,
  "error": {
    "code": "UNKNOWN_FIELDS",
    "message": "Unrecognized field(s) for genies/update: prompt. They are not in the documented schema, so nothing was changed. Call capabilities/schema for the accepted fields and nested paths, then retry.",
    "status": 400,
    "details": {
      "unknown_fields": ["prompt"],
      "allowed_fields": ["name", "genieName", "description", "…"]
    }
  }
}

The check covers top-level data keys only, on create and update. Some keys are never flagged: adminMode and impersonatedUserId, the envelope keys of a body sent without a data wrapper, and the fields of actions that pass extra fields through, such as knowledge-base/create. Public (unauthenticated) requests aren’t checked.

Admin mode and impersonation

Users with the internal_admin role can operate on behalf of other users by including an impersonatedUserId in the request data. This is used for provisioning trial agents, bulk operations, and testing.

const trialGenie = await ApiService.invoke({
  resource: "genies",
  action: "create",
  data: {
    genieName: "Trial Genie",
    voiceId: "voice-123",
    impersonatedUserId: "user-456",
  },
});

Impersonation is only available to internal_admin users. Non-admin requests that include impersonatedUserId will be ignored or rejected.

Query parameters

When using REST-style HTTP requests, query parameters are automatically extracted and passed to handlers:

GET /v1/genies?limit=30&cursor=abc123

When using the body-based approach, include pagination and filter parameters in the data object:

const genies = await ApiService.invoke({
  resource: "genies",
  action: "all",
  data: {
    limit: 30,
    cursor: "abc123",
  },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "all",
    "data": {
      "limit": 30,
      "cursor": "abc123"
    }
  }'

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Request methods

ApiService.invoke() (recommended)

Direct HTTP requests

Common actions

`list` vs `all`

Request examples

Create a resource

Get a single resource

Update a resource

Delete a resource

Response structure

Success response

Error response

Warnings

Undocumented fields and strict mode

Admin mode and impersonation

Query parameters

​Request methods

​ApiService.invoke() (recommended)

​Direct HTTP requests

​Common actions

​list vs all

​Request examples

​Create a resource

​Get a single resource

​Update a resource

​Delete a resource

​Response structure

​Success response

​Error response

​Warnings

​Undocumented fields and strict mode

​Admin mode and impersonation

​Query parameters

Request methods

ApiService.invoke() (recommended)

Direct HTTP requests

Common actions

`list` vs `all`

Request examples

Create a resource

Get a single resource

Update a resource

Delete a resource

Response structure

Success response

Error response

Warnings

Undocumented fields and strict mode

Admin mode and impersonation

Query parameters