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

# Customer API preview

> Selected workspace API operations, actual permissions and current limits.

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](./openapi.json). 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`.

| Permission | Current use |
| - | - |
| `read:signals` | Workspace identity, observations, rule results, source projections and job/delivery inspection. |
| `write:signals` | Create/stage rules, queue retrospective previews and publish a reviewed version. |
| `write:workflows` | Enable an existing reviewed workflow or pause it. |
| `ingest:events` | Submit authenticated producer events. |
| `admin:tenant` | Account/source binding, receipt replay, provider controls and optional website configuration. |

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.

```bash theme={null}
curl 'https://workspace.example.com/v1/observations?page_size=20&identity=resolved' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

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.

| Method | Path | Authorization |
| - | - | - |
| POST | `/v1/account-mappings` | `admin:tenant` |
| GET | `/v1/accounts` | `read:signals` |
| POST | `/v1/accounts` | `admin:tenant` |
| POST | `/v1/backtests/{identifier}` | `write:signals` |
| GET | `/v1/builder/catalog` | `read:signals` |
| GET | `/v1/builder/companies` | `read:signals` |
| GET | `/v1/builder/previews/{identifier}` | `read:signals` |
| PUT | `/v1/builder/signal-sets/{identifier}/draft` | `write:signals` |
| POST | `/v1/builder/signal-sets/{identifier}/publish` | `write:signals` |
| GET | `/v1/builder/signal-sets/{identifier}/versions` | `read:signals` |
| POST | `/v1/builder/workflows/{identifier}/enable` | `write:workflows` |
| POST | `/v1/data/bind` | `admin:tenant` |
| GET | `/v1/data/connections` | `read:signals` |
| PATCH | `/v1/data/connections/{identifier}` | `admin:tenant` |
| GET | `/v1/data/objects` | `read:signals` |
| GET | `/v1/data/objects/history` | `read:signals` |
| POST | `/v1/events` | `ingest:events` |
| GET | `/v1/health` | `read:signals` |
| GET | `/v1/integrations` | `read:signals` |
| POST | `/v1/integrations/hubspot/connect` | `admin:tenant` |
| POST | `/v1/integrations/hubspot/sync` | `admin:tenant` |
| POST | `/v1/integrations/hubspot/writeback/enable` | `admin:tenant` |
| POST | `/v1/integrations/hubspot/writeback/request` | `admin:tenant` |
| POST | `/v1/integrations/hubspot/writeback/retry` | `admin:tenant` |
| GET | `/v1/jobs` | `read:signals` |
| GET | `/v1/jobs/{identifier}` | `read:signals` |
| GET | `/v1/me` | `read:signals` |
| GET | `/v1/observations` | `read:signals` |
| GET | `/v1/observations/catalog` | `read:signals` |
| POST | `/v1/receipts/{identifier}/replay` | `admin:tenant` |
| GET | `/v1/signal-sets` | `read:signals` |
| POST | `/v1/signal-sets` | `write:signals` |
| GET | `/v1/signals` | `read:signals` |
| GET | `/v1/website/networks` | `read:signals` |
| POST | `/v1/website/networks` | `admin:tenant` |
| DELETE | `/v1/website/networks/{identifier}` | `admin:tenant` |
| PATCH | `/v1/website/pages/{identifier}` | `admin:tenant` |
| GET | `/v1/website/pages/{identifier}/versions` | `read:signals` |
| GET | `/v1/website/sites` | `read:signals` |
| POST | `/v1/website/sites` | `admin:tenant` |
| PATCH | `/v1/website/sites/{identifier}` | `admin:tenant` |
| POST | `/v1/website/sites/{identifier}/analyze` | `admin:tenant` |
| GET | `/v1/website/sites/{identifier}/pages` | `read:signals` |
| POST | `/v1/website/sites/{identifier}/rotate` | `admin:tenant` |
| GET | `/v1/website/visits` | `read:signals` |
| GET | `/v1/workflow-runs` | `read:signals` |
| GET | `/v1/workflows` | `read:signals` |
| POST | `/v1/workflows/{identifier}/pause` | `write:workflows` |
| GET | `/v1/writebacks` | `read:signals` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.