Make your first API call

Create a read-only API key for your project, then call a capability with curl. This takes about five minutes and needs the Owner, Admin or Agency role on the project.

Create an API key

1. Open your project, go to Settings › Project Settings, and select API Keys.

2. Click Create Key.

3. Enter a Name, for example My first agent.

4. Under Scopes, select Analytics Read. It lets the key read all analytics data in this project and change nothing.

5. Leave Expiration (optional) empty for a key that never expires, or pick a date.

6. Click Create Key, then copy the key. We show it only once.

The key starts with ansehn_. Store it in a password manager or a secret store, never in source control.

List what the key can call

Every request sends the key in the Authorization header as a bearer token.

export ANSEHN_API_KEY="ansehn_..."

curl https://api.ansehn.com/v1/capabilities \
  -H "Authorization: Bearer $ANSEHN_API_KEY"

The response lists every capability this key can call:

{
  "data": [
    {
      "name": "getProjectOverview",
      "description": "...",
      "risk": "read",
      "requiresIdempotencyKey": false
    }
  ]
}

Call a capability

Call a capability with POST /v1/capabilities/{name}. Put its input in the input field, or send an empty body when it takes none.

curl -X POST https://api.ansehn.com/v1/capabilities/getProjectOverview \
  -H "Authorization: Bearer $ANSEHN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": {} }'

A successful call returns 200 with the result in data. The componentHint field tells you the shape of the result, for example overview, table or kpi.

To pass input, for example a date range for your scores:

curl -X POST https://api.ansehn.com/v1/capabilities/getRankings \
  -H "Authorization: Bearer $ANSEHN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "range": { "from": "2026-09-01", "to": "2026-09-30" } } }'

Each capability's input schema is in GET /v1/openapi.json. See the article "Capabilities API reference".

If something goes wrong

• 401 unauthorized: the key is missing, mistyped, revoked or expired, or its creator lost access to the project. Check the Authorization: Bearer header, and create a new key if needed.

• 403 forbidden: the key's scopes do not include this capability. Check the list from GET /v1/capabilities.

• 422 invalid_input: the body or input does not match the capability's schema. The response lists the fields that failed.

All error codes are in the article "Errors, rate limits and idempotency".