Geysera Signal — Developer Guide

How to use Geysera from code: the read API, the webhooks, and the copilot — the endpoint that can both answer questions about a workspace and change it.

Written for two readers who want the same things: an engineer wiring up an integration, and an AI agent operating the platform on someone's behalf. Everything a person can do in the dashboard is reachable here.

For endpoint-by-endpoint detail — paths, parameters, error codes, exact limits — see the API reference, generated from the running service. This page explains how the product behaves; that one is the lookup.

Contents

1. The three surfaces
2. Authentication
3. Conventions
4. The public read API
5. Plan caps, and why your totals may be smaller than reality
6. The copilot: asking questions
7. The copilot: making changes
8. The tool catalogue
9. Webhooks
10. Capability discovery
11. Errors
12. Things that will surprise you

---

1. The three surfaces

Pick the read API when you know what you want and need a stable contract. Pick the copilot when you want the platform to work out how to answer, or when you want to act.

Auth asymmetry, stated up front. The public read API takes an API key. The copilot takes a Clerk session JWT and is not reachable with an sk_sig_ key today. A headless integration can therefore read but not act. If you need programmatic writes, say so — the constraint is the auth wiring, not the design.

---

2. Authentication

API keys (sk_sig_…)

Mint one in the dashboard under Exports & API, or ask the copilot to (create_api_key). Send it as a bearer token:

curl https://app.signal.geysera.com/signal-api/v1/accounts \
  -H "Authorization: Bearer sk_sig_your_key_here"

• The plaintext key is shown exactly once, at creation. Only a SHA-256 hash and a display prefix are stored, so nobody — including support — can recover it. Lose it and you mint a new one.
• A key is scoped to one workspace and is read-only: it reaches the four public GETs and nothing else.
• Maximum 10 active keys per workspace. Revocation is immediate and permanent.

Missing, malformed, unknown or revoked keys all return 401 with the same body. That is deliberate — a distinct "this key existed once" would confirm which keys are real.

Clerk JWT

The dashboard and the copilot use your session token. Browser clients get this automatically; there is no documented way to mint one from a script.

---

3. Conventions — read this before your first call

Base URL. Read it from GET /capabilities (spec_url, servers) rather than hardcoding it. It is configuration on our side and it will move.

Headers

Pagination. page (1-based) and page_size. Responses carry total, page, page_size. total is what you may access, not the raw row count — see §5.

Rate limit. 300 requests per minute per workspace. Over it you get 429. The dashboard itself issues 6+ parallel calls per page load and shares your budget, so leave headroom.

Time. All timestamps are ISO 8601 UTC. days parameters are trailing windows ending today.

---

4. The public read API

Four endpoints. All GET, all paginated where a list is returned.

GET /accounts

Organisations that visited, ranked by intent.

curl "https://app.signal.geysera.com/signal-api/v1/accounts?classification=lead&page_size=10" \
  -H "Authorization: Bearer $GEYSERA_KEY"

{
  "accounts": [
    {
      "company_domain": "acme.com",
      "company_name": "Acme Corp",
      "intent_score": 82,
      "visitor_count": 4,
      "visit_count": 11,
      "classification": "lead",
      "first_seen_at": "2026-07-02T09:14:00Z",
      "last_seen_at": "2026-09-01T16:03:00Z"
    }
  ],
  "total": 137,
  "page": 1,
  "page_size": 10
}

intent_score is 0–100, the same scale the dashboard shows.

Every field, and which can be null. Nullability is not cosmetic here — the identity fields are the ones most likely to be absent, and a client that assumes otherwise breaks on real data rather than on the example above.

company_domain can be the string personal. Consumer mailbox domains — gmail, icloud and the rest — all roll up under that one sentinel, because a consumer address carries no company. On a DTC site that single "account" can be the majority of your visitors. Filter it out of anything B2B.

GET /visitors

Individual identified people.

Fields include resolved_email, resolved_name, resolved_title, employer, and is_locked. When is_locked is true, resolved_email is null and resolved_name is masked — the plan is withholding them. Do not record that person as having no email; see §5.

Every field, and which can be null.

Identification gives you an email reliably. Name, title and employer are enrichment on top of that and are absent more often than they are present — write your templates and your CRM sync to survive nulls in all three.

GET /attribution

Channel and campaign rollup for a window. Takes days (default 30).

Served from a nightly rollup, not computed live, so it is fast and may lag by up to a day. It describes only sessions that carried a campaign context, which on most workspaces is a minority of traffic. Read the percentages as shares of attributed sessions, not of all visitors.

GET /recommendations

Open recommended actions. No parameters.

Read-only in v1: status changes carry an optimistic-locking contract that was deliberately not bolted onto a read API. Use the copilot (set_recommendation_status) or the dashboard to act on one.

---

5. Plan caps, and why your totals may be smaller than reality

Every workspace has a monthly resolution cap:

New workspaces get 7 days at pro_plus limits.

Beyond the cap, records are withheld. The three surfaces express that differently, and you need to know which one you are reading:

The practical consequence: on the public API, total is not "how many accounts exist", it is "how many you may see". Do not compute conversion rates against it and do not treat a locked visitor's null email as "this person has no email". Both are the plan talking, not the data.

---

6. The copilot: asking questions

POST /signal/copilot/ask      one JSON response
POST /signal/copilot/stream   the same thing, as SSE

/ask is complete on its own. The stream exists because humans want progress feedback; a script never needs it.

curl -X POST https://app.signal.geysera.com/agent-api/signal/copilot/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Which companies visited pricing last week and have not bought?"}'

Request

Response

{
  "answer": "Four companies viewed pricing…",
  "refusal": null,
  "clarification": null,
  "question_kind": "descriptive",
  "plan": { "reasoning": "…", "calls": ["search_accounts", "page_funnel"] },
  "disclosures": ["…"],
  "limits": ["…"],
  "warnings": [],
  "pending_confirmation": null,
  "trace": [ { "tool": "…", "sql": "…", "coverage": {…}, "caveats": [], "window": {…}, "data": {…} } ],
  "thread_id": "…",
  "message_id": "…"
}

Exactly one of answer, refusal or clarification is set.

• refusal is the product working, not an error. It means the data cannot support the claim you asked for. Do not retry it.
• clarification is a question back. Answer it on the same thread_id.
• trace is the audit trail: every tool that ran, the SQL it executed, its coverage, and the window it covered. data holds the rows — parse those rather than the prose if you want structure.
• limits and disclosures are the constraints the answer was written under. If you are re-publishing the answer, carry them.

Every number in answer is guaranteed to appear in trace. A numeric guard truncates the answer rather than let a figure through that no tool produced. So prose and trace cannot disagree.

---

7. The copilot: making changes

The copilot can change things. Nothing changes without a round trip.

Ask. If the request would change something, nothing runs and you get:

{
  "answer": null,
  "pending_confirmation": {
    "actions": [
      {
        "tool": "run_sync_rule",
        "arguments": { "rule_id": "b3f1…" },
        "effect": "Push this rule's matching contacts to the connected ESP NOW. Contacts that arrive there cannot be recalled.",
        "irreversible": true
      }
    ],
    "irreversible": true,
    "approve_with": { "question_kind": "action", "calls": [ … ] }
  }
}

Approve. Re-send the same question with approve_with copied verbatim into approved_plan:

curl -X POST .../copilot/ask -H "Content-Type: application/json" -d '{
  "question": "push that rule now",
  "thread_id": "t-42",
  "approved_plan": { "question_kind": "action", "calls": [ … ] }
}'

Why it is the plan and not a boolean

The planner is a sampled model. Approving a flag would authorise whatever it decides on the second pass, which need not be what you were shown. Sending the plan back makes the approved actions and the executed actions the same object — and an approved plan is replayed verbatim, with the planner skipped entirely.

Rules worth knowing

• Approval is good for one request. It is not stored, not remembered, and does not persist on a thread. The next turn re-gates.
• A mixed plan runs none of it. A read bundled with a write waits for the same yes.
• irreversible: true means the product cannot undo it: credits spent with a vendor, contacts pushed to an ESP, a secret shown once, a row hard-deleted.
• Show effect to your user, not tool. It is written to be consented to.
• A malformed approved_plan returns 422, not a silent no-op.

If you are automating this

Be honest with yourself about what the gate is doing for you. In the dashboard it is a human reading a sentence and clicking. In a script, echoing approve_with back is three lines, and the gate becomes an intent check and an audit record rather than human oversight. If your agent is choosing its own actions, put your own review in front of the irreversible ones — particularly run_enrichment_pipeline (spends vendor credits across the workspace), run_sync_rule (pushes contacts you cannot recall) and the credential tools.

---

8. The tool catalogue

68 tools. You do not call them directly — you ask a question and the planner chooses — but knowing what exists tells you what is answerable.

Commerce analytics (11)

data_coverage · revenue_and_aov · aov_decomposition · product_performance · customer_counts · price_history · page_funnel · page_to_product_attribution · membership_conversion_paths · visiting_accounts · causal_impact

causal_impact is the only one that can support a claim about cause — a Bayesian interrupted time series that returns "inconclusive" when the data cannot carry the claim. Everything else measures association.

The product (22 reads)

search_accounts · get_account · search_visitors · visitor_journey · journey_paths · attribution_overview · open_recommendations · workspace_setup · intent_pages · enrichment_config · sync_rules · dry_run_sync_rule · list_api_keys · list_webhooks · list_alert_destinations · identification_status · list_conversations · get_conversation · list_team · subscription · esp_connection · recall_facts

recall_facts and forget_fact are the assistant's memory. It keeps short facts about your workspace and feeds them into the planner on later turns, so a wrong one shapes answers you have not asked yet. recall_facts lists them; forget_fact stops one being used. Ask "what have you remembered about us" if an answer keeps coming out wrong in the same way.

dry_run_sync_rule is the one to reach for before any push: it reports exactly which contacts a rule WOULD send, and changes nothing. It reads like a write and is not one.

Start with workspace_setup when data looks wrong or missing — it returns store connection, onboarding progress, pixel status, identification health and plan usage in one call, and distinguishes "nothing happened" from "we are not collecting".

Changes (35)

Access and money need the workspace to opt in

Six tools grant workspace access or change what is billed: invite_team_member, update_team_member, remove_team_member, cancel_invitation, start_checkout, open_billing_portal.

They are off unless the workspace turns them on (guardrails.copilot_privileged_actions_enabled, default false). Nothing in the copilot can set that column — it is enabled deliberately, out of band, by someone who has decided an agent holding a session may act on their behalf.

Why these and not the rest: everything else the assistant changes is workspace data, where wrong is recoverable. These decide who can reach the workspace and what it costs, and the confirmation gate does not protect them the way it protects the rest — for a script, approving is echoing the plan back (§7). So three further checks apply, all failing closed:

And some targets are refused whatever your role, because they are the changes that let one compromised session lock everyone else out:

• you cannot act on yourself;
• an owner cannot be removed or demoted;
• nobody can be promoted to owner.

Those remain dashboard-only, on purpose.

start_checkout and open_billing_portal return their links under checkout_url and portal_url in the response's secrets field, not in the answer text — a live payment link does not belong in a conversation that is replayed into later prompts and can be exported.

One plan cannot look things up for itself

The calls in a plan run concurrently with static arguments — no call reads another's output. A tool cannot be handed an id that a different call in the same plan was meant to fetch.

Tools are therefore addressed by the identifier you already have, never by an opaque id:

That is not a style preference: when classify_account took a UUID, "classify acme.com as a competitor" came back as an answer about acme.com's current classification, having changed nothing, because the planner could not resolve the id and fell back to a read.

update_sync_rule takes both rule (which one) and name (rename it to).

Matching is exact, ignoring case and surrounding whitespace only. Account domains are unique per workspace and always resolve. Rule, destination and key names are not unique — nothing in the schema prevents two rules sharing a name — so if a name matches nothing you get a refusal listing what does exist, and if it matches more than one you get a refusal saying it is ambiguous. Neither case changes anything. There is no fuzzy matching: the approved plan carries the name and re-resolves it at execution, so a loose match could act on a different object than the one whose effect you approved.

set_visitor_contacted and set_recommendation_status take the visitor's email address and the recommendation's subject respectively — the thing a person would actually type, not a row id.

If you need two steps, take two turns: run the read, then send a second question using what it returned.

---

9. Webhooks

Register an endpoint (dashboard, or create_webhook) and Geysera posts to it when a visitor is identified. Max 5 per workspace.

Delivery carries a Stripe-style signature:

X-Signal-Timestamp: 1756742400
X-Signal-Signature: t=1756742400,v1=<hex hmac-sha256>

The signed payload is "{timestamp}.{raw_body}", keyed by your whsec_… secret. Verify against the raw body, before any JSON parsing — re-serialising changes the bytes and the signature will not match.

import hashlib, hmac, time

def verify(secret: str, header: str, timestamp: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(
        secret.encode(), f"{timestamp}.{raw_body.decode()}".encode(), hashlib.sha256
    ).hexdigest()
    # Constant-time: a fast-failing comparison leaks the signature a byte at a time.
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        return False
    # Reject stale timestamps, or a captured delivery can be replayed forever.
    return abs(time.time() - int(timestamp)) < 300

{
  "type": "signal.visitor_identified",
  "created": 1756742400,
  "data": { "…": "…" }
}

Notes:

• The signing secret is shown once, at registration. Rotating issues a new one and invalidates the old.
• Endpoints receive every event type — there is no per-endpoint subscription filter. Branch on type.
• Return 2xx quickly. Deliveries retry.
• signal.test arrives from the "send test ping" action.

---

10. Capability discovery

curl https://app.signal.geysera.com/agent-api/capabilities

Unauthenticated, and enough to bootstrap without reading this document: the public route list, the auth model, rate limits, pagination and error conventions, and spec_url pointing at the OpenAPI 3.1 spec.

curl https://app.signal.geysera.com/signal-api/v1/openapi.json

The spec is derived from the live application, not hand-maintained, so it cannot drift from what the endpoints do.

Two deliberate omissions, so you do not go looking:

• The internal schema (~326 paths, including /admin and /observability) is not published. Serving it unauthenticated would hand out a map of the attack surface. /capabilities describes the public surface only, by allowlist, so a new internal route is invisible here until someone deliberately publishes it.
• There is no checked-in spec. One used to sit in public/openapi.json, describing nine paths of which six had been deleted, served publicly at /openapi.json — it is gone, and a test stops another appearing. The spec you want is generated from the live routes at /signal-api/v1/openapi.json.

---

11. Errors

Every error has the same shape:

{
  "error_code": "RATE_LIMITED",
  "message": "Too many requests for this workspace.",
  "correlation_id": "3f2c…",
  "details": null
}

Retry 429 and 5xx with exponential backoff. Do not retry 4xx — send an X-Idempotency-Key on writes so a network-level retry is safe.

When the fix is somewhere in the dashboard

Some failures cannot be fixed by changing the request. Pushing to an ESP you have not connected, or using a key that was never granted a scope, needs a person in the dashboard. Those errors carry the address:

{
  "error_code": "CONFLICT",
  "message": "Connect Klaviyo on Auto-sync Rules first.",
  "details": {
    "code": "klaviyo_not_connected",
    "fix_url": "/rules",
    "fix_label": "Auto-sync Rules"
  }
}

fix_url is relative to your dashboard origin (https://app.signal.geysera.com). fix_label is the wording that appears in the dashboard's own navigation, so telling someone to open "Auto-sync Rules" matches what they will see.

This exists because an agent cannot look around. Before these fields, the same errors said "Settings → Integrations" — a tab that has never existed — and the only way to discover that was to follow the instruction and find nothing.

---

12. Things that will surprise you

Collected because each one has already produced a wrong conclusion.

total is not a row count. It is capped at what your plan may access. Never use it as a denominator.

A masked record is not an empty one. is_locked: true means the plan is withholding the name and email. Recording "no email on record" is wrong, and it is wrong about a real person.

A refusal is a real answer. The copilot refuses when the data cannot support the claim. Retrying the same question gets the same refusal.

Attribution covers a minority of traffic. Only sessions carrying a campaign context. On some workspaces that is a few percent. The response says so; read the caveats.

Intent scores can be meaningless. They rank visitors by which "intent pages" a workspace has configured. If those rules match little of the real traffic, every visitor scores alike and the ranking is close to arbitrary. intent_pages reports the coverage — check it before trusting a ranking.

replace_intent_pages replaces. Pages absent from your list are deleted, and any score_weight you omit resets to 1. Read the current set, modify it, send it all back.

Empty page_patterns matches nobody. In update_enrichment_config, an empty list is not "no restriction" — it switches enrichment off in practice.

run_enrichment_pipeline is not one visitor. It takes no arguments, because it acts on the whole workspace: every eligible abandoner is bought from a data provider, one credit each. It used to take a visitor's email, which bounded nothing — the route checked that visitor's ownership and then ran the same workspace-wide job. There is no single-visitor enrichment.

Bot traffic is filtered, historically imperfectly. Some older rows have an unset bot flag. If a visitor count looks implausibly large for the number of distinct people, that is why.

The attribution rollup can lag a day. It is nightly. attribution_overview reads the same cached rows the dashboard does, so the two agree — with each other, and with yesterday.

---

Questions, or you need programmatic write access with an API key? Include the correlation_id from a recent response — it is the fastest way for us to see exactly what you saw.