# Attribura Data API — LLM guide

> Paste this whole file into your AI assistant (Claude, ChatGPT, …) and ask it to
> pull and analyze your Attribura data. It is complete and self-contained.

## What this is

Attribura measures which content drives real revenue. This read API lets you (or an
agent) pull that data for your account: revenue attributed to each post, itemized
purchases, tracked-link clicks, and self-reported ("how did you hear about us?")
attribution. Everything is directional and confidence-scored — never sold as
deterministic.

Base URL: https://api.attribura.com

## Auth — a read-only token

Create one in the dashboard: Brand → Connect to Claude → "Read-only (data)". You get an
`atb_…` token that can ONLY read (any write is refused with 403), so it is safe to drop
in a script or hand to an agent. Send it as a Bearer header:

    Authorization: Bearer atb_your_token

Every response is scoped to that token's project. A read-only token is the recommended
credential here; a normal "full" token also works but can write, so don't share it.

## Endpoints (all GET, all JSON)

### GET /v1/overview
Headline revenue for the project.
    curl -s https://api.attribura.com/v1/overview -H "Authorization: Bearer atb_…"
→ { revenue_cents_30d, events_30d, revenue_cents_all, events_all,
    by_source: [{ source, revenue_cents, events }] }
`source` is superwall | shopify | stripe | asc.

### GET /v1/distributions/performance
The money-per-post table — every post ranked by the revenue it drove. THE core view.
→ [{ distribution_id, channel, hook, campaign_token, clicks, installs,
     conversions, revenue_cents, proceeds_cents, subscriptions }]  (top 200 by revenue)

### GET /v1/revenue/events?since=&limit=
Itemized revenue — each purchase/renewal joined back to the post that drove it.
`since` = RFC-3339 timestamp (optional). `limit` = 1..500 (default 100). Newest first.
→ [{ id, source, kind, amount_cents, currency, occurred_at, external_user_id,
     method, distribution_id, channel, hook }]
`kind` is purchase | renewal | refund | trial_start. `method` is how it was attributed
(campaign_token | code | self_report | self_report_verified | dark_social | …).

### GET /v1/self-reports/summary
Self-report attribution rollup.
→ { reports_30d, reports_all, verified_share, dark_social_share,
    self_report_revenue_cents_30d, by_channel: [{ channel, reports, revenue_cents }] }
`verified_share` (0..1) = pinned to an exact recent post. `dark_social_share` (0..1) =
traffic no link could see (a friend, a podcast, App Store search).

### GET /v1/self-reports?since=&limit=
Itemized "how did you hear about us?" answers. Newest first.
→ [{ id, channel, raw_answer, prompt, method, confidence, distribution_id,
     external_user_id, occurred_at }]

### GET /v1/content?source=&account=&include_hidden=
Imported posts with their latest engagement stats + ready-to-share links.
`source` = instagram | youtube | threads (optional). `account` = an external account id.
→ { items: [{ distribution_id, channel, source, source_post_id, title, hook,
     external_url, posted_at, views, likes, comments_count, campaign_token,
     campaign_url, store_url, hidden }] }

### GET /v1/content/:distribution_id/comments
The imported comments for one post.
→ { items: [{ id, author, text, like_count, published_at }] }

### GET /v1/distributions
Raw posts logged for attribution (no stats).
→ [{ id, channel, kind, campaign_token, link_slug, external_url, hook, posted_at }]

### GET /v1/links
Tracked short links with their total click counts.
→ [{ slug, short_url, destination_url, distribution_id, clicks, created_at }]

### GET /v1/clicks?since=&limit=
Individual short-link click events with the raw request signals. Newest first.
→ [{ occurred_at, slug, distribution_id, ip, ua, referer }]

## Prefer tools? Use the MCP

The same data is available as MCP tools over the hosted server, so an agent can call them
directly instead of curling. Connect once:

    claude mcp add --transport http attribura https://api.attribura.com/mcp \
      -H "Authorization: Bearer atb_your_read_token"

Read tools: get_overview, get_performance, get_revenue_events, get_self_report_summary,
list_self_reports, list_content, list_distributions, list_links, list_clicks.

## How to read the numbers

- All money is in CENTS (integer). `revenue_cents` is gross; `proceeds_cents` is
  after-store-cut where known (App Store).
- Attribution is confidence-scored. Deterministic signals (campaign token, discount
  code) are high-confidence; self-report is directional (≤ 0.6) and never overrides a
  token/code. Treat per-post revenue as "the best signal available", not gospel.
- `dark_social_share` is the traffic that no link or code can see — a healthy number
  means word-of-mouth is working, but it can't be pinned to one post.

## Analysis recipes

- "Which content makes the most money?" → GET /v1/distributions/performance, sort by
  revenue_cents. Look at the hooks/channels of the top rows; make more like them.
- "What's my dark-social share?" → GET /v1/self-reports/summary → dark_social_share.
- "Which channel converts best?" → join performance rows by channel, compare
  revenue_cents ÷ clicks.
- "Show me this month's revenue feed" → GET /v1/revenue/events?since=2026-07-01.
- "Are my links getting clicked?" → GET /v1/links (totals) or /v1/clicks (detail).