Meta services

Stateless API proxy over the Meta Marketing API (Facebook / Instagram advertising), running in AppFactory at https://services.csbot.cz/apps/meta.

The service stores no secrets: every credential is supplied per request in an X- header and used only to call the Graph API. Structure mirrors the sibling analytics service.

Phase 1 is read-only — every endpoint issues a GET upstream, so the service cannot spend money. Campaign management is phase 2.

Quick start

GET https://services.csbot.cz/apps/meta/health
GET https://services.csbot.cz/apps/meta/docs      ← Swagger, "Try it out"

curl "https://services.csbot.cz/apps/meta/ads/me/adaccounts" \
  -H "X-Meta-Access-Token: EAAG..." \
  -H "X-Meta-App-Secret: <APP_SECRET>"

Credentials

Header	Required	Meaning
`X-Meta-Access-Token`	one of these	Access token; a Business Manager System User token is recommended.
`Authorization: Bearer <token>`	one of these	Equivalent alternative (the X- header wins if both are sent).
`X-Meta-App-Secret`	no, recommended	App secret → the proxy derives `appsecret_proof`. Required if the app enforces app-secret proof.
`X-Meta-Api-Version`	no	Graph version override, e.g. `v25.0`.

Permissions needed for this phase: ads_read, business_management.

Endpoints

Group	Paths
Infra	`/health`, `/version`
Structure	`/ads/me/adaccounts`, `/ads/me/businesses`, `/ads/businesses/{id}/adaccounts`, `/ads/accounts/{id}` (+ `/campaigns`, `/adsets`, `/ads`, `/adcreatives`), `/ads/campaigns/{id}` (+ `/adsets`, `/ads`), `/ads/adsets/{id}` (+ `/ads`), `/ads/ads/{id}`, `/ads/adcreatives/{id}`
Insights	`/ads/insights/{object_id}`, `/ads/insights/{object_id}/jobs`, `/ads/insights/{object_id}/run`, `/ads/insights/jobs/{report_run_id}`, `/ads/insights/jobs/{report_run_id}/results`
Generic read	`/graph/{path}`

Large reports must go through the async endpoints — see documentation/meta-ads.md.

Configuration

Non-secret settings come from environment variables; see the table in documentation/overview.md. The most relevant one is META_API_VERSION (default v25.0), which callers can override per request.

Local development

python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
.venv/Scripts/uvicorn app.main:app --reload --port 8000
# http://127.0.0.1:8000/docs

Documentation

documentation/overview.md — architecture, config, design decisions, what is deliberately not wired.
documentation/meta-ads.md — endpoints, insight fields and levels, pagination, errors, curl examples.

2.7 KiB Raw Blame History