Skip to content

Cresva API

API documentation

10 REST endpoints over the ad performance data Cresva has already ingested for you: metrics, forecasts, anomalies, attribution, creatives and budget recommendations across Meta, Google and TikTok. Read only, JSON in and JSON out.

Quickstart

Key, first call, first row of data. Start here if you have never called the API.

API reference

All 10 endpoints with their parameters, defaults and response shapes.

Your first request

Every endpoint is authenticated with a bearer token and addressed by brand. /v1/brands takes no parameters and returns the brands a key can reach, which makes it the call to start with: the id it returns is the brand_id everything else takes.

Request
curl "https://api.cresva.ai/v1/brands" \  -H "Authorization: Bearer $CRESVA_API_KEY"

Test keys return simulated data

A key beginning cresva_sk_test_ answers every endpoint with deterministic fake rows and never touches your real data, so you can build against the shapes before connecting an ad account. Every response says which it was in meta.simulated.

What the API gives you

These are the same fetchers, metric catalog, detectors and attribution resolver the product uses internally. The API is a second door onto one implementation rather than a parallel one, which is why the vocabulary matches the dashboard exactly.

  • Performance. Spend, revenue, ROAS, CPA and conversions at account, campaign, adset or ad level, at hourly through monthly granularity.
  • Interpretation. Stored forecasts with confidence intervals, detected anomalies with their z-scores, and attributed performance under the model the brand has configured.
  • Decisions. Budget reallocation fitted to spend-response curves. It recommends and does not act: nothing in this API changes a budget on any platform.
  • Provenance. When each platform last synced and the date its data is fresh through, so you can tell a real zero from a stale one.

How the documentation is built

The parameter tables, defaults, enums, response shapes and rate-limit numbers on these pages are generated from lib/api/v1/schemas.ts, the same object the handler parses every request through. The OpenAPI specification and the TypeScript client are generated from it too.

That is worth saying plainly because the previous version of this page was hand-written beside the API and drifted: it documented seven endpoints while the software had ten, named rate-limit tiers that were not plans, and used a word for a metric that the resolver does not speak. A parameter that is not enforced can no longer be documented, and one that is enforced can no longer be missed.

Where to go next

Authentication

Key formats, scoping a key to one brand, rotation and what a 401 means.

Errors

One envelope, eight codes, and what each one is telling you to do.

Rate limits

Per-minute budgets by plan, the three headers on every response, and backoff.

SDKs

The cresva package on npm, and what to do from Python.

OpenAPI spec

Generate your own client from the same document the server is built from.

openapi.json

The specification itself, served from the API.