Getting Started

Espresso API & MCP

v0.1 Live

Espresso is Cafecito's curated business intelligence product suite. The API exposes the structured data behind Espresso as read-only sips: event digests, derived signals, tags, and relationships that are ready for dashboards, monitoring workflows, and AI agents.

Key features

Business intelligence data - Event and signal records with UUIDs, timestamps, and domain specific structured fields
Semantic search - Natural language search with an adjustable similarity threshold
Tag filtering - Filter events and signals by scalar tags such as topics, domains, regions, or entities
Relationship traversal - Follow same_as and derived_from links between related sips
MCP-friendly responses - Return normal JSON or flat plain text with response_type=text

Authentication

Get API Key

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Espresso gateway endpoints live under the /espresso path prefix.

Code
BASE_URL="https://api.cafecito.tech"
API_KEY="YOUR-API-KEY"

Check out API reference for the complete schema, parameters, and response details.

Data model

A sip is the basic unit of information. Each sip has a UUID, a created timestamp, and a JSON digest. Espresso currently exposes:

Events - Self-contained digests of related actions or developments, such as a policy change and its local fallout
Signals - Larger derived intelligence synthesized from related events and actions, such as a cross-domain market or policy outlook
Tags - Scalar labels that can be used to filter event and signal lists
Relationships - Links between sips, including same_as and derived_from

List endpoints flatten each sip's digest and merge id and created into every returned object. Some records may include additional pipeline-specific keys beyond the stable fields shown in the reference.

Core endpoints

Endpoint	Description
`GET /espresso/health`	Service health check
`GET /espresso/tags`	Paginated list of unique tag strings
`GET /espresso/events`	Event-kind sips, sorted by `created` descending
`GET /espresso/signals`	Signal-kind sips, sorted by `created` descending
`GET /espresso/related/{relationship}`	Sips linked by `same_as` or `derived_from`

Query parameters

Events and signals

Parameter	Type	Description
`ids`	CSV UUIDs	Fetch specific sips by UUID
`tags`	CSV strings	Tag filters, ANDed across supplied tags
`q`	string	Semantic search query, max 1024 characters
`acc`	number (0-1)	Minimum similarity for `q`, default `0.75`
`from`	date	Include sips created on or after `YYYY-MM-DD`
`response_type`	string	`json` or `text`, default `json`
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Parameter	Type	Description
`response_type`	string	`json` returns a string array; `text` returns comma-separated tags
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Parameter	Type	Description
`relationship`	path string	`same_as` or `derived_from`
`ids`	CSV UUIDs	Required source sip UUIDs
`response_type`	string	`json` or `text`, default `json`
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Response formats

Use response_type=json for structured objects and arrays. Use response_type=text when sending results to MCP clients or LLM workflows that do not need JSON syntax.

Code
date: 2026-06-07
briefing: Analysis of upcoming policy and market shifts...
event_type: policy_reform
impact_level: high
actions: Cooperation agreement signed, reevaluation scheduled
related_to: public_policy, market_trends, regulation

MCP Server

Server URL: https://api.cafecito.tech/espresso/mcp

Espresso endpoints are exposed as hosted MCP tools for AI agent integration. See the MCP Integration guide for client setup patterns.

Examples

Below are real-world examples. Replace YOUR-API-KEY with the key you generated in the developer portal.

1. Health check

3. Filter events by tag and date

4. Semantic event search

5. Search signals as plain text

Status codes

200 - Matching data returned
204 - Empty result set
400 - Invalid query parameters or malformed UUID
401 - Missing or invalid API key
429 - Rate limit exceeded
500 - Database or embedder error

Last modified on June 8, 2026

Beans Cortado

Getting Started

Espresso API & MCP

v0.1 Live

Key features

Business intelligence data - Event and signal records with UUIDs, timestamps, and domain specific structured fields
Semantic search - Natural language search with an adjustable similarity threshold
Tag filtering - Filter events and signals by scalar tags such as topics, domains, regions, or entities
Relationship traversal - Follow same_as and derived_from links between related sips
MCP-friendly responses - Return normal JSON or flat plain text with response_type=text

Authentication

Get API Key

Code
Authorization: Bearer YOUR-API-KEY

Base URL

All Espresso gateway endpoints live under the /espresso path prefix.

Code
BASE_URL="https://api.cafecito.tech"
API_KEY="YOUR-API-KEY"

Check out API reference for the complete schema, parameters, and response details.

Data model

A sip is the basic unit of information. Each sip has a UUID, a created timestamp, and a JSON digest. Espresso currently exposes:

Events - Self-contained digests of related actions or developments, such as a policy change and its local fallout
Signals - Larger derived intelligence synthesized from related events and actions, such as a cross-domain market or policy outlook
Tags - Scalar labels that can be used to filter event and signal lists
Relationships - Links between sips, including same_as and derived_from

Core endpoints

Endpoint	Description
`GET /espresso/health`	Service health check
`GET /espresso/tags`	Paginated list of unique tag strings
`GET /espresso/events`	Event-kind sips, sorted by `created` descending
`GET /espresso/signals`	Signal-kind sips, sorted by `created` descending
`GET /espresso/related/{relationship}`	Sips linked by `same_as` or `derived_from`

Query parameters

Events and signals

Parameter	Type	Description
`ids`	CSV UUIDs	Fetch specific sips by UUID
`tags`	CSV strings	Tag filters, ANDed across supplied tags
`q`	string	Semantic search query, max 1024 characters
`acc`	number (0-1)	Minimum similarity for `q`, default `0.75`
`from`	date	Include sips created on or after `YYYY-MM-DD`
`response_type`	string	`json` or `text`, default `json`
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Parameter	Type	Description
`response_type`	string	`json` returns a string array; `text` returns comma-separated tags
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Parameter	Type	Description
`relationship`	path string	`same_as` or `derived_from`
`ids`	CSV UUIDs	Required source sip UUIDs
`response_type`	string	`json` or `text`, default `json`
`limit`	integer (1-128)	Page size, default `16`
`offset`	integer	Pagination offset

Response formats

Use response_type=json for structured objects and arrays. Use response_type=text when sending results to MCP clients or LLM workflows that do not need JSON syntax.

Code
date: 2026-06-07
briefing: Analysis of upcoming policy and market shifts...
event_type: policy_reform
impact_level: high
actions: Cooperation agreement signed, reevaluation scheduled
related_to: public_policy, market_trends, regulation

MCP Server

Server URL: https://api.cafecito.tech/espresso/mcp

Espresso endpoints are exposed as hosted MCP tools for AI agent integration. See the MCP Integration guide for client setup patterns.

Examples

Below are real-world examples. Replace YOUR-API-KEY with the key you generated in the developer portal.

const API_KEY = process.env.CAFECITO_API_KEY;
const BASE_URL = "https://api.cafecito.tech";

1. Health check

const res = await fetch(`${BASE_URL}/espresso/health`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const status = await res.json();
console.log("Service status:", status);

const params = new URLSearchParams({
  limit: "20",
  offset: "0",
});

const res = await fetch(`${BASE_URL}/espresso/tags?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const tags = await res.json();
console.log("Tags:", tags);

3. Filter events by tag and date

const params = new URLSearchParams({
  tags: "supreme_court,gerrymandering",
  from: "2026-05-01",
  limit: "5",
});

const res = await fetch(`${BASE_URL}/espresso/events?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const events = await res.json();
events?.forEach((e) => console.log(e.id, e.briefing));

4. Semantic event search

const params = new URLSearchParams({
  q: "voting rights redistricting",
  acc: "0.8",
  limit: "5",
});

const res = await fetch(`${BASE_URL}/espresso/events?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const events = await res.json();
events?.forEach((e) => console.log(e.id, e.event_type, e.impact_level));

5. Search signals as plain text

const params = new URLSearchParams({
  q: "market volatility",
  acc: "0.75",
  limit: "5",
  response_type: "text",
});

const res = await fetch(`${BASE_URL}/espresso/signals?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const text = await res.text();
console.log(text);

const params = new URLSearchParams({
  ids: "b07049b5-54c0-50b0-a620-d3aea3f8a173",
  limit: "10",
});

const res = await fetch(`${BASE_URL}/espresso/related/derived_from?${params}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const related = await res.json();
related?.forEach((sip) => console.log(sip.id, sip.briefing));

Status codes

200 - Matching data returned
204 - Empty result set
400 - Invalid query parameters or malformed UUID
401 - Missing or invalid API key
429 - Rate limit exceeded
500 - Database or embedder error

Last modified on June 8, 2026

Beans Cortado

Espresso API & MCP

Key features

Authentication

Base URL

Data model

Core endpoints

Query parameters

Events and signals

Tags

Related sips

Response formats

MCP Server

Examples

1. Health check

2. List tags

3. Filter events by tag and date

4. Semantic event search

5. Search signals as plain text

6. Fetch related sips

Status codes

Espresso API & MCP

Key features

Authentication

Base URL

Data model

Core endpoints

Query parameters

Events and signals

Tags

Related sips

Response formats

MCP Server

Examples

1. Health check

2. List tags

3. Filter events by tag and date

4. Semantic event search

5. Search signals as plain text

6. Fetch related sips

Status codes