Three steps: get a key, try a request right here in the browser, then copy the code into your app. No database access, no setup — if you can make an HTTP request, you can use this API.

Response will appear here.

Everything else here is read-only. A few routes add data, each behind its own write scope. A write key is issued separately from read keys, and only by a named few. Nothing here can ever delete a row — every write login was never granted DELETE.

Events: POST /v1/attr_events

Needs a key scoped attr_events_write, issued separately from read scopes and to far fewer people.

It can add an event. It cannot change or delete one. That is enforced by the database permission rather than by application code — the login behind this route was never granted UPDATE or DELETE, so a bug here cannot rewrite history.

source_event_id is required, and it is the one that matters

Every write carries a source_event_id: a stable id for the thing that happened. Send the same one twice and the second request does nothing and returns created: false with the row that already exists. That is what makes a retry safe.

Derive it from the event, never from the request that reported it, and never generate a fresh one inside a retry loop — that identifies the attempt rather than the event, and removes the protection entirely. Our own ingesters show the convention: Stripe uses the payment-intent id, so the live webhook and the catch-up poller produce the same key for one payment; Whop uses whop:<id>. For a new consumer, <your-system>:<your stable row id>.

Reusing an id with a different payload is a 409, not a silent no-op — otherwise you would get the first event’s result back for a request that never happened.

curl -X POST "$BASE/v1/attr_events" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_event_id": "onboarding:enr_123",
    "event_type":      "purchase",
    "source_system":   "onboarding",
    "event_timestamp": "2026-09-19T12:00:00Z",
    "amount":          "4500.00",
    "close_lead_id":   "lead_abc123"
  }'

Of the attribution data, only attr_events accepts writes, and that is not a temporary limit. Every other attribution dataset is derived — the per-lead figures are a rollup, the attribution credit is model output — so writing into one would either be recomputed away on the next run, or would make the numbers stop agreeing with the events they came from. The other writable tables below are not attribution figures: they are records other apps keep, and each has a scope of its own.

The Nest Briefer: coach engagement and team notes

The Nest reads and writes the two tables the Coaching Briefer shares with the CX CRM. Two write scopes, each reaching one table: coach_engagement_write and team_notes_write. Behind them is a login of their own that the database lets reach those two tables and nothing else. Read them back with coach_engagement_pii and team_notes_pii.

curl -X PUT "$BASE/v1/coach_engagement/01K8ZQ5V3N2M4P6R8T0W2Y4A6C" \
  -H "Authorization: Bearer <your-write-key>" \
  -H "Content-Type: application/json" \
  -d '{"status": "green", "set_by": "coach@egelloc.com", "reason": "Engaged on every call"}'

curl -X POST "$BASE/v1/team_notes" \
  -H "Authorization: Bearer <your-write-key>" \
  -H "Content-Type: application/json" \
  -d '{"student_id": "01K8ZQ5V3N2M4P6R8T0W2Y4A6C", "author_email": "coach@egelloc.com", "body": "Called the family today."}'

curl -X DELETE "$BASE/v1/team_notes/901?author_email=coach@egelloc.com" \
  -H "Authorization: Bearer <your-write-key>"

Testing safely: ?dry_run=true

These routes write to the real tables, and there is no sandbox copy. So each of the three accepts ?dry_run=true: the call does everything for real — your key, its scope, every rule above and the actual database write — then always undoes it. The answer is exactly what a real call would return, plus "dry_run": true. Nothing is saved.

curl -X POST "$BASE/v1/team_notes?dry_run=true" \
  -H "Authorization: Bearer <your-write-key>" \
  -H "Content-Type: application/json" \
  -d '{"student_id": "01K8ZQ5V3N2M4P6R8T0W2Y4A6C", "author_email": "coach@egelloc.com", "body": "Testing."}'

Two things to know. Dry runs don’t see each other: a note “added” in one is gone at once, so to try a removal, dry-run it on a real note. And a dry-run note’s id is real but never used, so real ids skip it.

The advisor’s sales notes reach the Nest through attr_advisor_notes_pii, with every amount blanked ([amount]) — pricing stays off staff-facing profiles. On a Sales Won activity the same rows also carry the deal’s sales_notes, interested_products, special_requests_for_coach and red_flags_or_parent_dynamic, as plain text, amounts blanked the same way.

Every dataset route is a read-only GET returning JSON over HTTPS. Base URL /v1. A few routes write, each behind its own write scope — see Writing — and none can delete a row.

Authentication

Send a bearer key on every data route (this catalog and /v1/health need none). Keys are scoped per dataset — the scope name equals the dataset name (e.g. attr_activity, attr_leads).

Authorization: Bearer <your-api-key>

Scopes, PII & money

Scoping is the only access mechanism. It gates two sensitive things independently — who someone is, and what a deal is worth:

• Scoped — every dataset is its own scope. A key reads only the datasets it was granted; anything else is a 403.
• PII-gated — customer/staff PII (names, emails, phones, raw notes) lives only in the separate *_pii datasets. A key without a *_pii scope never sees PII — and the non-PII view doesn't even contain those columns.
• Money-gated — deal amounts live only in the *_fin datasets (the Money group). attr_leads carries no total_revenue and attr_activity no program total, initial payment, instalment amounts or purchase amount. What stays is the shape of a deal — payment type, how many instalments, their dates, product, purchase date — which is what funnel work needs and reveals no figure. Join attr_leads_fin on close_lead_id and attr_activity_fin on id.

Identity and money are independent grants, not a ladder: a key can have names without amounts, amounts without names, or neither. One exception worth knowing — attr_activity_pii returns the raw custom_data blob, which still contains the amounts, so it is not a revenue-free dataset.

So an app that doesn't need PII is granted only the plain scopes and cannot retrieve it. Example — a sales-performance dashboard:

Pagination & filtering

Every filter is ANDed, including repeats of the same column — that is what makes a two-sided range work: ?date_created__gte=2026-07-01&date_created__lte=2026-07-31 is one closed interval. It also means a repeated equality (?id=a&id=b) matches nothing rather than quietly picking one. For equality use the bare ?column=value; there is no __eq.

__in replaces N requests with one — ?activity_type_name__in=AC%20Booked,AC%20Completed,AC%20Not%20Completed instead of three calls or pulling everything and filtering locally. It works on the aggregate endpoint too. Two caveats: since every filter is ANDed, repeating __in on the same column is an intersection, not a union; and a value that itself contains a comma cannot be expressed — there is no escape character. An empty list (?col__in=) is a 400, not an empty page, because a blank variable is a far likelier explanation than a deliberate request for no rows.

Careful with dates on timestamp columns. A bare date parses as midnight, so __lte=2026-07-31 means <= 2026-07-31 00:00:00 and silently drops almost all of the 31st. For a whole month use a half-open interval — ?date_created__gte=2026-07-01&date_created__lt=2026-08-01 returns 58,332 rows where the __lte version returns 55,917.

Range filters are how you pull a large dataset affordably. Walking all of attr_activity is ~799 pages; one month is ~58. The first request for a new range pays for its total (~8 s on attr_activity), then it's cached for 5 minutes; pass after and the count is skipped entirely. A value the column's type can't parse returns 400 with Postgres' own explanation (e.g. invalid input syntax for type timestamp: "notadate"), and a range on a type that has no such operator (like a jsonb column) also returns 400.

List responses are enveloped: { items, limit, offset, total, next_after, total_cache_ttl_seconds }. Single-record routes (/v1/{dataset}/{id}) return the row object directly.

total is cached; the rows are not. Counting is the slowest part of a list request, so the figure is cached per dataset + filter set and may be up to total_cache_ttl_seconds old — 300 by default. If you walk a dataset and your own tally disagrees with total by a little, that is this, plus anything the ingest wrote while you were walking. It is not drift. total and the TTL are both null on cursor pages (?after=), where the count is not recomputed at all.

total counts the rows matching your filters, ignoring paging. Counting a large table is genuinely expensive, so the number is cached for up to 5 minutes — treat it as an accurate size for paging and progress, not as a live figure to reconcile against. items is never cached and is always read fresh.

Ordering — read this before paging

Every dataset returns rows in a fixed order, so walking offset=0,100,200… visits each row exactly once. Most sort on a unique id; some have a composite grain and sort on several columns instead. Each dataset's full sort key is published in /v1/catalog as order_by, in order of precedence.

Cursors are opaque. For a single-column sort key next_after is just that column's value; for a composite one it is an encoded token covering every column in the key. Pass it back exactly as you received it and don't parse, build, or reuse one across datasets — a cursor from the wrong dataset is a 400, not a silently wrong page.

Every dataset now reports stable_order: true. attr_leads_utm used to be the exception — it has no natural unique column — and it now sorts on row_key, an opaque per-row id. Treat row_key as a cursor and a row identity, nothing more: it is a salted hash, it carries no meaning, and it does not join to anything else. Use close_lead_id to join that dataset to the rest.

Pulling a whole dataset — use the cursor

offset makes the database walk and throw away every row it skips, so it collapses with depth. On attr_activity, offset=50000 already fails with a 504 at the gateway — this is not something you can wait out. Pass after instead and the index turns the same page into a seek: ~1 second, flat at any depth.

Every response carries next_after. Feed it back as ?after=… and keep going until it comes back null, which means you've reached the end:

# walk an entire dataset, constant time per page
cursor = None
while True:
    url = f"/v1/attr_activity?limit=1000"
    if cursor: url += f"&after={cursor}"
    page = requests.get(url, headers=hdrs).json()
    handle(page["items"])
    cursor = page["next_after"]
    if not cursor: break

Works on every dataset, attr_leads_utm included (it pages on row_key; all 116,406 rows walk in ~2 minutes).

total is null on cursor pages. Counting the rows is the slowest part of a request (~2 s on the largest dataset, against ~350 ms for the data itself) and the answer never changes as you walk — so you get it on the first page and it isn't recomputed on the rest. Read total from your first response and keep it.

Errors

Every failure returns the same JSON shape, with the reason in detail. Nothing else is added, so you can branch on the status code and log detail verbatim.

HTTP 403
{ "detail": "API key lacks required scope 'attr_leads'" }

A 403 names the scope you're missing — hand that string to whoever issues your key and they know exactly what to grant.

Limits

How fresh is the data?

This API reads the warehouse directly, so it is exactly as current as the last sync — there is no caching layer of its own. Sync cadence, all times UTC:

Treat the cadence as a guide and the data as the source of truth. For an authoritative answer, read the row's own timestamp — last_updated on the lead aggregates, date_updated on Close records, computed_at on attribution results, updated_at on UTM. A daily job that failed will show up there and nowhere else.

Summarising without pulling every row

Every dataset also has an /aggregate endpoint, so you can ask for a total or a breakdown instead of downloading the rows and adding them up yourself:

curl -H "Authorization: Bearer $KEY" \
  "https://attribution-data-api.egelloc.com/v1/attr_activity/aggregate?group_by=activity_type_name&metrics=count&date_created__gte=2026-07-01&date_created__lte=2026-07-31"

group_by takes up to three columns (omit it for a grand total). A date or timestamp column can carry a time bucket — group_by=date_created:week — which is how you get a trend rather than one group per distinct instant. Units: hour, day, week, month, quarter, year. The bucketed key comes back as date_created_week, so it is never confused with the raw column, and groups are ordered chronologically.

metrics takes any of:

Money is mostly text. Amounts pulled out of custom_data are stored as text, so sum on them returns a 400 telling you so. The typed revenue columns live on the _fin datasets — sum:total_revenue on attr_leads_fin works.

Filter it, or it may time out. The same filters as the list endpoint apply, and they matter more here: an aggregate reads every matching row. Unfiltered it scans the whole dataset, and you may get a 504 asking you to narrow it — a date range is the usual fix. Figures may be up to 5 minutes old (the response tells you, in cache_ttl_seconds), and truncated: true means there were more groups than the limit returned.

Test leads are excluded — figures match the dashboards

Internal test and staff leads are filtered out server-side, using the same rule the marketing and sales dashboards apply. A figure you pull here should tie out with the same figure on a dashboard. A lead is excluded if any of these hold:

This affects attr_activity (and its _pii / _fin twins) and crm_leads (and _pii) — about 120 leads and 790 activities, roughly 0.1%. There is no way to opt back in; if you need to see test leads, ask the API owner. Datasets built on the attribution pipeline's own tables are unaffected, since no dashboard reads those.

Getting help

For a key, a new scope, or a 403 you think is wrong, go to whoever issued your key — keys are managed by egelloC admins in the incubator panel, and the issuer can see and change your scopes. For data that looks wrong or stale, quote the row's timestamp column and the dataset name.

Health & docs

curl -s /v1/health     → {"status":"ok"}
curl -s /v1/health/db  → {"status":"ok","db":"ok"}

Interactive OpenAPI docs: /docs · /redoc · /openapi.json.