Migration Guide

Listen API (V2) replaces the Legacy API (V1). This page summarizes what changed; the pages below walk you through the migration.

🚧
BETA stage
The new API has moved from tech preview to BETA. The core (projects, mention search, export streams, the Mention model) is stable and safe to build on. No major breaking changes will be introduced at this stage.

What changed

Area	Legacy API (V1)	Listen API (V2)
API keys	Legacy Keys provided by CS Team elivered starting with `COMPANY_NAME_...`	New keys starting with `S1-APIKEY-`, which you create yourself in the Listen app. Legacy keys don't work
Extraction model	Asynchronous endpoints: start a request, poll until the result is ready	Streams: results flow to you over one connection
Naming	Statements	Mentions, as in the Listen app
Data shape	Many flat fields	Structured objects such as `author.name`, `author.id`; see Legacy API Field Mapping
Rate limiting	Server time: 35 minutes of processing per 10-minute window	Number of requests only; see Rate Limiting
Rate-limit buckets	One shared bucket	Separate limits per endpoint bucket
Extraction endpoints	One (`statements/search`)	Two families: latest (mentions published in the last 7 days) and historical (the full archive)
Volume	Unlimited	Monthly mentions cap that depends on your plan

Why migrate

Simpler to use: one streaming request replaces paging and polling.
Faster extraction: mentions arrive as a continuous stream.
Limits that are easy to understand: requests are counted, not server time.
Self-service: you create and manage API keys yourself in the Listen app.
Legacy API is going to be turned off in near future (Sunset date yet to be announced)

Migration steps

Migrating from Legacy API (V1) to Listen API (V2): move a statements/search extraction loop to the latest mentions export stream, step by step.
Legacy API Field Mapping: how the new fields are designed, and how each legacy field maps to them.