Reporting API v1

Authentication

Create an API key in your console (API access section). The key is shown once — store it in a secret manager, never in client-side code or a repository. Send it as a Bearer token:

curl https://bloccarbon.com/api/v1/campaigns \
  -H "Authorization: Bearer bc_live_..."

Keys can be revoked instantly from the console. A revoked key, a downgraded plan or a suspended organisation all cut access on the next request.

Endpoints

• GET /api/v1/campaigns

  Your campaigns (all statuses): id, slug, title, status, payMode, accessMode, locale, createdAt.

• GET /api/v1/campaigns/{id}/analytics

  The console analytics numbers: funnel, per-participant kg by calculator, settlement position. Optional ?from=YYYY-MM-DD&to=YYYY-MM-DD half-open UTC window.

• GET /api/v1/campaigns/{id}/participants

  Verified participants: id, email, verifiedAt.

• GET /api/v1/campaigns/{id}/submissions

  Submissions with line items — each line pins the emission-factor value and source it was computed with.

• GET /api/v1/certificates

  Certificates for your paid orders (organisation settlements and participant funding): number, fundedKg, issuedAt, public certificate URL.

Pagination

List endpoints return { "data": [...], "nextCursor": "..." | null }. Pass ?cursor= the previous response's nextCursor to fetch the next page; null means you have everything. ?limit= accepts 1–100 (default 50).

Errors & rate limits

Errors are { "error": { "code": "...", "message": "..." } } with conventional status codes: 400 (invalid parameter — bad limit, cursor or from/to date), 401 (bad key), 403 (plan or suspension), 404 (not found — including ids that belong to another organisation), 429 (rate limited). Each key may make 300 requests per minute; failed authentication attempts are separately limited to 30 per minute per IP, so a misconfigured key can 429 before it 401s.

Versioning & data protection

v1 is additive-only: new fields and endpoints may appear, but existing fields are never renamed, retyped or removed. Breaking changes would ship as /api/v2 with notice.

Participant emails appear in participant and analytics responses — they are your organisation's campaign data, and your systems become a processor of them. Handle them under your privacy notice and our privacy policy.