Getting Started

This guide takes you from zero to your first authenticated request in a few minutes: create an API key in the Evinor app, then call GET /v1/sensors.

• Base URL: https://api.evinor.ai
• Transport: HTTPS only — plain HTTP is not served.
• Authentication: every request carries an API key as a bearer token.

1. Create an API key

API keys are managed from the Evinor web app, under Settings → API keys:

1. Sign in to the Evinor app and open Settings.
2. Select the API keys section.
3. Click Create API key.
4. Give the key a descriptive name (so you can recognize it later) and choose its scopes:
   • Sensors: read (SENSORS_READ) — list and read sensors.
   • Sensors: write (SENSORS_WRITE) — create, update, enable, disable, delete, and rotate the signing secret of sensors.
5. Click Create.

A key's scopes are fixed at creation and cannot be edited afterward — to change scopes, create a new key and revoke the old one. You can hold up to 10 active keys at a time.

One-time reveal

The raw key is shown exactly once, immediately after creation. Copy it and store it somewhere safe (a secrets manager or an environment variable) before you dismiss the dialog — Evinor stores only a hash of the key and can never show it to you again. If you lose it, revoke the key and create a new one.

2. Make your first request

Every request sends the key in the Authorization header as a bearer token. List the sensors on your account:

curl https://api.evinor.ai/v1/sensors \
  -H "Authorization: Bearer evnr_live_your_key_here"

A successful response is a cursor-paginated envelope:

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "object": "sensor",
      "name": "Series B fundraising in fintech",
      "description": null,
      "enabled": true,
      "created_at": "2026-07-01T09:12:33.000Z",
      "updated_at": "2026-07-01T09:12:33.000Z",
      "filter": {
        "event_type_id": "…",
        "involved_entity_ids": [],
        "involved_entity_list_ids": [],
        "required_source_news_outlet_ids": [],
        "report_source_kind": "ANY",
        "represented_entity_ids": [],
        "represented_entity_list_ids": [],
        "min_reports": 1
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

If the account has no sensors yet, data is an empty array. See Pagination for how to page through larger result sets.

The sensor filter

A sensor's filter decides which events fire it. The same field names are used by POST /v1/events/search, so a search you like can become a sensor without renaming anything.

Field	Type	Notes
event_type_id	uuid | null	Restrict to one event type, or null for every type.
involved_entity_ids	string[]	Canonical entity ids that must be involved.
involved_entity_list_ids	string[]	Entity lists whose members count as involved.
required_source_news_outlet_ids	string[]	Only count reports from these outlets.
report_source_kind	string	Which reports may fire the sensor: ANY (default), ARTICLES_ONLY, USER_REPORTS_ONLY, or REPRESENTED_ONLY.
represented_entity_ids	string[]	With REPRESENTED_ONLY: only reports submitted on behalf of one of these entities. Empty = on behalf of any entity.
represented_entity_list_ids	string[]	With REPRESENTED_ONLY: only reports submitted on behalf of a member of one of these entity lists.
min_reports	integer	Minimum distinct outlets reporting the event. Defaults to 1.

ARTICLES_ONLY fires only on news-article reports; USER_REPORTS_ONLY only on reports submitted by users; REPRESENTED_ONLY only on user reports submitted on behalf of an entity. "On behalf of" is the reporter's own statement of whom they represent — Evinor does not present it as verified. The two represented_* lists are accepted only with REPRESENTED_ONLY; sending them with any other kind is rejected.

Updating a filter with PATCH /v1/sensors/{id}

A PATCH without filter keeps the whole filter as it is. A PATCH with filter treats the keys differently:

• Missing event_type_id, involved_entity_ids, involved_entity_list_ids, required_source_news_outlet_ids, or min_reports reset to their defaults (null, [], or 1). Send the full set of these you want to keep.
• Missing report_source_kind, represented_entity_ids, or represented_entity_list_ids keep their stored values. A client that predates these fields can update a sensor without clearing its report-source setting.
• Setting report_source_kind to anything other than REPRESENTED_ONLY without the two lists clears them to []. For example, PATCH { "filter": { "report_source_kind": "ANY" } } on a REPRESENTED_ONLY sensor stores ANY with both lists empty.

3. Explore the full API

The complete, interactive endpoint reference — every operation, its parameters, request and response schemas, and per-language code samples — lives at API Reference.

Next steps

• Authentication — key format, header usage, and rotation.
• Errors — the RFC 9457 problem format every error uses.
• Rate limits — the per-key request budget and its headers.
• Receiving webhooks — verify and consume signed sensor deliveries.