Skip to main content
The customer API is a preview, available only where workspace access and the relevant integration have been enabled. This reference describes selected current operations; it does not announce general availability, public API credential issuance or external OAuth client registration. Ask your workspace administrator about enabled access. Do not use provider OAuth tokens as Gather API tokens. Download the OpenAPI schema. Request bodies, query parameters and validation limits are generated from the implementation. Many successful responses do not yet have declared response models; an empty response schema means untyped output, not a stable generated-SDK guarantee. All hosts and values in examples are placeholders.

​
Workspace authentication

Send an organization-bound Auth0 API access token for the workspace’s configured audience using Authorization: Bearer YOUR_ACCESS_TOKEN. An ID token or a token for another organization/audience will not work. The workspace hostname routes the request; caller-supplied tenant IDs cannot select a different database. Browser sessions can use the production __Host-signal_session cookie. Read csrf_token from GET /v1/me using that browser session; browser mutations must send X-CSRF-Token and an Origin exactly matching the workspace. Bearer-only mutations do not require session CSRF. HubSpot OAuth initiation additionally requires a browser session; omit the Authorization header for that flow. Authorization takes precedence over cookies, and a bearer-authenticated /v1/me response has csrf_token: null. Permissions are checked per request and constrained by current user access. Provider grants, source purpose/expiry, tenant lifecycle and delivery policy apply separately. Access to one operation does not authorize every operation.

​
Review and publish a rule

  1. Create a draft with POST /v1/signal-sets or stage a revision through PUT /v1/builder/signal-sets/{identifier}/draft using expected_version.
  2. Queue POST /v1/backtests/{identifier} for that version and a timezone-aware cutoff. Poll GET /v1/jobs/{identifier} until it completes.
  3. Inspect GET /v1/builder/previews/{identifier} for named matches and evidence. These retrospective previews send no actions and use current account mappings and latest source revisions, rather than complete point-in-time history.
  4. Publish using POST /v1/builder/signal-sets/{identifier}/publish with the same expected version and preview_job_id. A successful preview must be less than one hour old. A stale/concurrent version needs another test.
  5. Create a paused workflow through the workspace UI. Customer API workflow creation is not published in this preview. Enable the existing workflow using POST /v1/builder/workflows/{identifier}/enable after reviewing its applicable signal version. Publication can cause already enabled workflows to execute.
HubSpot delivery is restricted to four owned company properties and requires separate provider consent, existing compatible property schemas and explicit writeback activation. The enable endpoint validates those properties; it does not create them. Inspect desired/delivered revisions and remote readback under GET /v1/writebacks. A queued job is not proof of delivery. Pausing a workflow can clear managed values when no other rule qualifies. Stopping provider writeback retains existing remote values; it is a different action.

​
Ingest and inspect observations

POST /v1/events requires a 1–160 character Idempotency-Key. Retrying the same key requires the same body; changed content returns 409. Batches hold 1–1,000 events, require timezone-aware occurrence times and cannot supply a tenant or canonical account directly. The src_ namespace is reserved for governed sources. A 202 response acknowledges durable input and a job, not completed processing. GET /v1/observations is the governed raw feed; GET /v1/signals contains scored rule matches. Neither automatically creates an opportunity or CRM deal. Observation pagination uses next_cursor bound to its filters and initial cutoff. Follow a non-null cursor even after a short page. Current withdrawal, expiry or mapping corrections can change visible results between pages.
The source-object APIs return current governed projections and bounded revision history. They do not provide arbitrary archive downloads or private-body access. Canonical linking requires review; it does not infer a person’s employer.

​
Limits and failures

The global request body limit is 4 MiB. Several lists remain bounded rather than paginated: accounts 1,000; signal sets, rule matches, workflows and workflow runs 100; recent jobs 50. Builder company search/previews and source records provide their documented pagination. Rule evaluation refuses oversized cohorts rather than silently truncating; the current evaluation budget is 10,000 company or account/type groups. These are implementation bounds, not a measured capacity SLA. Expect 401 for invalid authentication, 403 for permission/CSRF/browser requirements, 409 for conflicts or unmet review/provider prerequisites, 422 for validation, 423 for unavailable workspace lifecycle state and 503 for unavailable dependencies. Some operations also return 400, 404, 413 or 429 as applicable. Do not blindly retry CRM actions or ambiguous provider outcomes; inspect the current job/output. Website operations are an optional preview requiring configured source/model access. Only reviewed company-network mappings bind visits automatically; network candidates do not prove employer identity. Website evidence remains analytics-only for CRM delivery. Install the generated snippet through the workspace flow after applicable consent; this API schema excludes its public collection wire protocol.

​
Published operations

Internal administration, agents, credentials/app-registration setup, callbacks, unqualified native/LinkedIn connectors, MCP, compatibility mutation paths and workflow creation are outside this published preview.