API reference

The Argus Grape read API lets you pull your tracking data — campaigns, affiliates, clicks, conversions, commissions and stats — programmatically. It is authenticated with a Bearer API key and returns JSON or CSV.

Base URL

Every endpoint lives under the /v1 prefix of your API host. The host is configured by NEXT_PUBLIC_ARGUS_API_URL (default http://localhost:3001), so the base URL is {API_URL}/v1.

Authentication

Create an API key in the dashboard under Settings → API keys. The secret is shown once, at creation time — copy it then, because it is stored hashed and can never be retrieved again. Each key looks like agk_live_…; the dashboard lists the non-secret prefix so you can recognise a key without exposing it.

Send the key on every request in the Authorization header as a Bearer token. Keys can be revoked from the same screen at any time — a revoked key immediately returns 401 Unauthorized.

header

Authorization: Bearer agk_live_a1b2c3d4e5f6...

Response format

Responses are JSON by default. Append ?format=csv to any endpoint to download the same data as a CSV file — handy for spreadsheets and ad-hoc analysis. When both a query filter and the format are present, combine them with & (e.g. ?status=approved&format=csv).

The dashboard exposes the same export: every table has a one-click Export CSV button that downloads the rows currently in view.

Campaigns

Method	Path	Notes
GET	`/v1/campaigns`	List your campaigns with status, commission_bps and level_split.

Affiliates

Method	Path	Notes
GET	`/v1/affiliates`	List affiliates with their ltree path and depth. Query: campaign_id to scope to one campaign.

Activity

Method	Path	Notes
GET	`/v1/clicks`	Recent clicks. Query: status=valid\|shadow_banned, limit.
GET	`/v1/conversions`	Recent conversions with rejection reasons. Query: status=pending\|approved\|rejected, limit.
GET	`/v1/commissions`	Commission lines per affiliate and level. Query: limit.

Rankings & stats

Method	Path	Notes
GET	`/v1/leaderboard`	Contest ranking: valid clicks, points and commission per affiliate. Query: campaign_id (required).
GET	`/v1/stats/overview`	Workspace totals: clicks, shadow-banned clicks, approved conversions, revenue, commissions, affiliates.

Examples

Pull recent approved conversions as JSON:

curl — json

curl http://localhost:3001/v1/conversions?status=approved&limit=50 \
  -H "Authorization: Bearer agk_live_a1b2c3d4e5f6..."

Download the campaign leaderboard as a CSV file:

curl — csv

curl "http://localhost:3001/v1/leaderboard?campaign_id=camp_123&format=csv" \
  -H "Authorization: Bearer agk_live_a1b2c3d4e5f6..." \
  -o leaderboard.csv

Read-only

The /v1 API is read-only. Write operations — creating campaigns and affiliates, inviting your team, ingesting conversions — are managed in the dashboard and via signed webhooks.