JiriUhlirMeta 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.