Espresso API & MCP

Espresso is a market and business intelligence API for discovering market actions, signals, and tracing concrete evidence. Outputs can be incomplete or incorrect; verify material information and do not use them as financial, legal, medical, safety, or other professional advice, or as the sole basis for a consequential decision. All Cafecito products are currently available as free tier. When paid services are introduced, applicable pricing, billing, renewal, cancellation, refund, tax, and additional contract terms will be presented before purchase. Events are concrete developments involving an organization, person, product, market, or region. Signals are higher-level conclusions synthesized from supporting Events. Choose a route by user intent: What happened? Search Events. What does it mean or what is the outlook? Search Signals. What supports a conclusion? Retrieve a Signal, then list its supporting Events. What evidence or source coverage exists? Retrieve an Event, then inspect its evidence. Which exact filter value should I use? Use a discovery route only when the value is not already known. Recommended agent workflow: (1) search the appropriate collection with the smallest useful filter set; (2) select IDs from data; (3) retrieve detail only for selected IDs; (4) traverse evidence, related Signals, or supporting Events only when explanation, provenance, or context is needed. Collections return {data, pagination, meta}. Pagination contains limit, num_results (this page only), and next_cursor. To continue, send pagination.next_cursor unchanged as the next request cursor; never construct or decode cursor tokens. Empty collections return HTTP 200 with data: []. Detail routes return {data}; missing detail resources return HTTP 404. Errors: application failures (400, 404, 500) use { "error": { "code", "message" } }. Gateway authentication and rate-limit failures return HTTP 401 and 429 as RFC 7807 Problem Details. Authentication: REST operations (except /espresso/health) require Authorization: Bearer <api_key>. Filtering: tags use fuzzy text matching. event_types, categories, entities, impact_levels, companies, people, products, and regions use exact matching after snake_case normalization. categories and event_types are separate fields. from and to bound record created_at, not occurrence, publication, lifecycle, or forecast time. Formats: JSON is canonical. YAML and TOON represent the same public payload in token-optimized forms for MCP and AI-agent context. Public payloads never expose embeddings, relation direction, or internal storage objects. Event and Signal fields: Stable core is id, kind, created_at, and tags. Collection records may include summary and other custom fields. Event records may include source. Detail records may also include links and counts.