Public ingest & trigger

The public API is how outside systems add contacts and start outreach without a human logging in. Two patterns cover most integrations:

Ingest — append rows to a data table
Trigger — start a published spinner (creates a job)

Both use organization API keys (except the per-table ingest webhook, which uses a table token).

Prerequisites

An organization on a plan that allows API keys
A key with the right scopes (ingest, trigger, or both)
For trigger: a spinner that is published (drafts cannot be triggered)
For useful automation: metadata fields configured on the table

Create keys under user menu → API keys. Copy the secret immediately.

Screenshot needed

API keys page showing scopes for ingest and trigger.

Where: User menu → API keys

Save as: src/assets/screenshots/38-api-key-scopes.png

Base URL examples use production. Locally, replace the host with http://localhost:3000.

Ingest with an organization API key

Add one or more records to a data table you already created in the UI.

POST /api/v1/public/ingest
Authorization: Bearer cxg_your_key_here
Content-Type: application/json

{
  "dataTableId": "00000000-0000-0000-0000-000000000000",
  "records": [
    {
      "name": "Ada Lovelace",
      "phone": "+15551234567",
      "account_id": "A-100"
    }
  ]
}

Rule	Detail
Auth	API key with ingest scope
Batch size	1–500 records per request
Success	`{ "ok": true, "inserted": N }`

Column names should match what your table already uses. Only metadata fields enter spinner pipelines later — set those in the UI before you rely on automation.

Per-table ingest webhook (token in URL)

Each data table can expose its own URL and token. CRMs often prefer this because they only need one URL, not an org-wide key.

POST /api/v1/public/data-tables/ingest/{token}
Content-Type: application/json

{
  "records": [
    {
      "name": "Ada Lovelace",
      "phone": "+15551234567",
      "account_id": "A-100"
    }
  ]
}

Rule	Detail
Auth	Token in the path (treat it like a password)
Schema	Columns must match the existing table structure
Empty table	Import a CSV in the UI first so the table has a schema

Product UI guides for common CRMs live under Data tables → Ingest webhook. See also Ingest webhooks.

Screenshot needed

Ingest webhook panel showing URL and token (token partially masked if possible).

Where: Data tables → Ingest webhook

Save as: src/assets/screenshots/32-ingest-webhook.png

Schema mismatch

If columns do not match, the API returns an error such as SCHEMA_MISMATCH with expected and received field lists. Fix the payload to match the table, or adjust the table in the UI.

Trigger a published spinner

Start a job for a spinner that is already published.

POST /api/v1/public/trigger/{spinnerId}
Authorization: Bearer cxg_your_key_here

Rule	Detail
Auth	API key with trigger scope
Spinner	Must be published and belong to your org
Success	`201` with `{ "ok": true, "jobId": "…", "spinnerId": "…" }`

The runtime service must be running for the job to progress. Creating a job through the API is the same as starting work from the UI — plan limits for jobs and records still apply.

Recommended integration flow

CRM event
  → ingest row(s) into data table
  → trigger published spinner
  → monitor Jobs / Records in CXGear

For nightly batches, prefer a spinner schedule inside CXGear when possible, instead of an external cron that only calls trigger.

Success looks like

Rows appear under Data tables → Show data
Trigger returns a jobId and Jobs shows a new run
Records show metadata and outcomes after the run finishes
Keys stay in a secrets manager, not in chat logs

Common problems

Problem	Likely cause	What to do
401 Invalid API key	Bad or revoked key	Create a new key
403 missing scope	Key lacks ingest/trigger	Recreate with scopes
404 Published spinner not found	Draft spinner or wrong id	Publish first; copy id carefully
SCHEMA_MISMATCH	Column names differ	Align payload with table schema
PLAN_LIMIT	Monthly jobs/records or other cap	See When a limit is hit
Job created but never finishes	Runtime not running	Start runtime; see Troubleshooting