Skip to content

Getting started

Quickstart

Four steps: create a key, list your brands, read a month of performance, and check the data is fresh enough to trust.

1. Create an API key

Keys are created at Settings, API keys. A key is shown once at creation and stored hashed, so it cannot be retrieved afterwards. If you lose one, revoke it and create another.

  • cresva_sk_live_... reads your real, ingested data.
  • cresva_sk_test_ returns deterministic simulated data and never touches a real record, which makes it the right key for CI.

Keys are server side

A key carries read access to your whole account's performance data. Keep it in an environment variable and call the API from your own backend. A key shipped in client-side JavaScript is a key you have published.

2. List your brands

Every other endpoint is addressed by brand, so this is the first call an integration makes. It takes no parameters: the key already knows what it can reach.

Request
curl "https://api.cresva.ai/v1/brands" \  -H "Authorization: Bearer $CRESVA_API_KEY"
200
{  "data": [    {      "id": "brd_8Kq2mR4xVn",      "name": "Bearaby",      "currency": "USD",      "timezone": "America/New_York",      "status": "active",      "platforms": ["meta", "google"]    }  ],  "meta": { "request_id": "req_01JQ8Z3M6WT4", "simulated": false }}

Illustrative values, real shape.

A brand with no connected ad account comes back with an empty platforms array. That is the signal that the answer to every other question for that brand will be empty too, and why it is worth checking here rather than being surprised later.

3. Read performance

/v1/metrics is the endpoint most integrations spend their time in. Two dates are required; everything else has a default.

Request
curl "https://api.cresva.ai/v1/metrics?\date_from=2026-07-01&date_to=2026-07-31&\level=campaign&brand_id=brd_8Kq2mR4xVn" \  -H "Authorization: Bearer $CRESVA_API_KEY"

Illustrative dates and ids.

The TypeScript tab uses the generated client. Install it with npm install cresva. There is no Python client, so the Python tab is raw HTTP; the SDKs page explains why in detail.

4. Check the data is fresh

A number from this API is only as good as the last sync behind it. /v1/sync reports when each platform last succeeded and the date its data is fresh through, which is how you tell a real zero from a stale one.

Build this into your integration, not your checklist

Reading data_fresh_as_of before you act on a number costs one call and removes a whole class of quiet failure: a pipeline that broke on Tuesday and a dashboard that has been confidently reporting Monday ever since.

What to read next