Developer

API Reference

Pull your Adsteer dashboards, trends, and AI diagnosis programmatically. All endpoints are read-only reporting APIs over your own data.

Quickstart

1. Get your API key. Connect your account via self-serve onboarding (paste your Meta token) or managed setup. Your API key is shown once on success — save it.

2. Call the API. Send your key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/products

Base URL: https://adsteer-api.fly.dev
Auth: every /api/* endpoint requires the X-API-Key header. Invalid key → 401. Requesting a product your account isn't authorised for → 403. If your trial has expired without an active subscription, /api/* returns 402 with a checkout_url in the body.

Account

GET/api/products

List the products your account can access.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/products

# → { "tenant_id": "t-...", "products": ["drama", "mindramas"] }

GET/api/me

Your account info, including Meta token days remaining (60-day cycle).

curl -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/me

# → { "tenant_id": "t-...", "products": ["drama"],
#     "token_created_at": "2026-06-01T...", "token_days_remaining": 21 }

Reporting

GET/api/snapshot/{product}

The standard KPI snapshot (envelope) for a product on a given day.

Query param	Description
`anchor`	Date `YYYY-MM-DD`. Defaults to today (account timezone).
`force_refresh`	`true` to bypass cache and re-pull.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://adsteer-api.fly.dev/api/snapshot/drama?anchor=2026-07-10"

# → { "status": "ok", "snapshot": { ... }, "cache": "hit", "data_age_seconds": 42 }

GET/api/trend/{product}

KPI time series for the last N days (for trend charts). Max 30 days.

Query param	Description
`days`	Number of days, 1–30. Default `7`.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://adsteer-api.fly.dev/api/trend/drama?days=14"

# → { "status": "ok", "product": "drama", "days": 14,
#     "trend": [ { "date": "2026-06-27", "kpi": { "spend": ..., "roas_meta": ... } }, ... ] }

GET/api/advice/{product}

AI diagnosis for the day's snapshot, keyed by domain (overview / funnel / plans / series / retention / reconcile). Falls back to a heuristic when the agent result isn't cached.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/advice/drama

# → { "status": "ok", "advice": { "overview": {...}, "funnel": {...}, ... } }

Advice review

POST/api/advice/review

Record your decision on an advice card. Scoped to your tenant + product.

Body field	Description
`product`	Product the card belongs to (must be in your scope).
`card_id`	The advice card identifier.
`decision`	One of `adopt` / `ignore` / `executed`.
`ignore_reason`	Optional note when ignoring.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"drama","card_id":"c-123","decision":"adopt"}' \
  https://adsteer-api.fly.dev/api/advice/review

# → { "status": "ok", "card_id": "c-123", "decision": "adopt" }

GET/api/advice/reviews/{product}

Read back your saved review state per card (for badges on the dashboard).

curl -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/advice/reviews/drama

# → { "status": "ok", "reviews": { "c-123": { "decision": "adopted", "ts": "..." } } }

Token & billing

POST/api/token/refresh

Rotate your Meta access token. Your API key and tenant ID stay the same.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"access_token":"EAAG...new-long-lived-token..."}' \
  https://adsteer-api.fly.dev/api/token/refresh

# → { "status": "ok", "message": "Token updated. Your API key remains the same." }

POST/api/billing/checkout

Create a Stripe Checkout session and get a URL to start/continue your subscription.

curl -X POST -H "X-API-Key: YOUR_API_KEY" \
  https://adsteer-api.fly.dev/api/billing/checkout

# → { "status": "ok", "checkout_url": "https://checkout.stripe.com/..." }

Need higher limits, an integration, or something not covered here? Email zhengchenkai0307@gmail.com.