Getting Started with the Corvidae API

The Corvidae API gives you programmatic access to your attribution, channel, audience, journey and incrementality reporting. This page explains how to reach the API and how to sign in to it. The next two pages cover the individual reports and creating an API key.

Base URL

https://api.corvidae.ai/reporting

Format

JSON. Enumerated values are returned as text (for example PaidSearch).

Health check

GET https://api.corvidae.ai/reporting/health returns { "success": true }. No sign-in needed.

Interactive reference

Swagger for API-key endpoints

Every report is for one company and a date range. You can only read data for companies you have access to.

Two ways to sign in

Method

How

Use it for

API key

Send your key in the X-API-Key header.

Scripts, dashboards, data pipelines and the Claude connector. Works on the reports marked "API key" in the Reporting API Reference.

Signed-in user token

Send Authorization: Bearer <token>. The token is issued when a person signs in to Corvidae.

Applications acting on behalf of a signed-in Corvidae user. Gives access to every report, including those not available to API keys.

An API key is limited to the company or companies it was created for. See Creating an API Key for how to make one.

Example request

curl "https://api.corvidae.ai/reporting/api/v2/channels/performance?companyId=123&startDate=2026-10-01&endDate=2026-10-31" \
  -H "X-API-Key: <your key>"

Replace <your key> and 123 with your own key and company ID. Keep your key out of shared documents, tickets, chats and source control.

Common rules

  • Dates. Dates are inclusive. Some reports take yyyy-MM-dd and some take a full date and time (ISO 8601). The reference states which. Today's data is imported the next day, so the latest complete day is yesterday.

  • Filtering. Most reports accept optional filters for conversion type (conversionTypeIds), digital property (digitalPropertyIds) and attribution model (modelId). Repeat a parameter to pass several values: conversionTypeIds=1&conversionTypeIds=2. Leave a filter out to include everything.

  • Currency. Revenue values are in the company's reporting currency, already in normal currency units. Fields starting adTech come from the ad platform and are in that account's currency.

  • Conversion counts are decimals, because credit for one conversion can be shared across several touchpoints.

Errors

Status

Meaning

400

A parameter is missing or invalid. The body lists which.

401

No key or token was sent, or it is not valid (including revoked or expired keys).

403

You do not have access to that company, or an API key was used on a report that does not accept keys.

404

The requested item does not exist.

500

The report could not be produced. Try again.

If there is no data for your query, the API replies 200 with "Success": false and a message saying no data is available, instead of an empty list. Check for this in your code.

Using Claude

You can also ask Claude questions about your Corvidae data without writing any code. See Connect Claude to Corvidae.

Need help? Contact your Corvidae account manager.