API resource guide
The v1 API organizes publisher research into six resource groups. REST and MCP share the same response schemas. A tool result contains the same data as its corresponding REST operation.
Start with discovery
Use publisher search to find domains. Use provider discovery before a footprint comparison, dataset discovery to identify the currently served data, and list discovery before requesting a list summary. List IDs come from these responses. Clients should not guess them. Dataset IDs describe the current directory; v1 does not accept them as historical selectors.
A publisher domain identifies a web property. It does not identify its legal owner. Provider identifiers belong to their documented source namespace. Neither a shared provider nor a seller declaration establishes common ownership.
Search and pagination
Publisher search supports text, business segment, management status, reported ownership role, supply type, monetization provider, traffic tier, header-bidding presence, headquarters country, technology category and provider name. The API reference lists the accepted values. Unknown query parameters and repeated scalar parameters are rejected.
Offset collections default to 25 records and accept up to 100. Send offset and limit, then use page.total and page.hasMore to continue. Signal events use a fixed page size of 50 and an opaque cursor instead, so follow page.nextCursor.
A market summary accepts repeated domain parameters, or one listId. With neither, it summarizes the admitted publisher population. A provider comparison accepts one or two repeated provider parameters and a category. Array parameters use repeated keys, not comma-separated values.
Read the evidence
A null measurement means unknown. It does not mean zero. An empty result means the successful query found no matching records; a failed source read returns an error.
Observation time records when a source measured something. Retrieval time records when MediaContext obtained it. sourceUpdatedAt records when the provider last updated its record and does not establish an observation time. Publication and dataset dates describe the served collection. These dates are not interchangeable.
Observed technology presence, declared seller relationships and resolved claims are different kinds of evidence. A declaration does not prove a commercial contract. Absence requires an observation with relevant coverage; missing data alone cannot establish absence.
Metrics declare their units in the response schema. Counts need their measured population as a denominator. Coverage describes the records used by that operation, not the whole web or every field from every source.
Build a research flow
- Search publishers using the documented filters.
- Read a returned publisher domain and the evidence relevant to your question.
- Compare provider footprints or summarize a selected market.
- Discover a workspace list and inspect its membership before summarizing it.
- Read signal events to understand which evidenced changes need attention.
All workspace reads use the identity attached to the credential. A request cannot select another workspace by adding an ID.
Compatibility
New integrations use /api/v1 and /api/v1/mcp. Existing unversioned REST routes and /api/mcp retain their existing response shapes and tool behavior. Switching the base path is a migration: read the v1 schema before changing a client.
The repository retains openapi-legacy.json and mcp-legacy.json beside the v1 manifests for existing integrations. The API reference on this site documents v1.