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 ready for dashboards, monitoring workflows, and AI agents.

All sip identifiers are UUIDs (RFC 4122), for example 339366bc-464d-582f-8132-6875ccc814d2. Pass them as strings in query parameters and path segments.

List endpoints accept an optional response_type query parameter: json (default) or text. Both return the same underlying data; text renders flat plain text without JSON syntax, reducing token cost for MCPs 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:

Actions — micro data such as market performance for a day (domain model; not yet exposed as a list endpoint)
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 for filtering event and signal lists
Relationships — links between sips, including same_as and derived_from

List endpoints flatten each sip's digest and merge id, reported, and site_name into every returned object (reported maps from the persisted created timestamp). Some records may include additional pipeline-specific keys beyond the stable fields shown in the reference.

Core endpoints

Endpoint	Description
`GET /espresso/health`	Check API health (liveness probe)
`GET /espresso/tags`	List tags for filtering events and signals
`GET /espresso/events`	Search events (sorted by created descending)
`GET /espresso/signals`	Search signals (sorted by created descending)
`GET /espresso/related/{relationship}`	Get related sips by relationship

Query parameters

Events and signals

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

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 (default `0`)

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 (default `0`)

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
reported:2026-06-07
related:public_policy|market_trends|regulation
briefing:Analysis of upcoming policy and market shifts...
event_type:policy_reform
impact_level:high
actions:Cooperation agreement signed|reevaluation scheduled
future_outlook:Short-term regulatory scrutiny will intensify...

MCP Server

Server URL: https://api.cafecito.tech/espresso/mcp (v0.1)

Hosted MCP tools (same names as REST operationIds):

Tool	REST path
`searchEvents`	`GET /espresso/events`
`searchSignals`	`GET /espresso/signals`
`listTags`	`GET /espresso/tags`
`getRelatedSips`	`GET /espresso/related/{relationship}`

Use response_type=text on list endpoints for token-efficient agent consumption. 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 (not an error)
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 29, 2026

Beans Cortado

Getting Started

Espresso API & MCP

v0.1 Live

All sip identifiers are UUIDs (RFC 4122), for example 339366bc-464d-582f-8132-6875ccc814d2. Pass them as strings in query parameters and path segments.

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:

Actions — micro data such as market performance for a day (domain model; not yet exposed as a list endpoint)
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 for filtering event and signal lists
Relationships — links between sips, including same_as and derived_from

Core endpoints

Endpoint	Description
`GET /espresso/health`	Check API health (liveness probe)
`GET /espresso/tags`	List tags for filtering events and signals
`GET /espresso/events`	Search events (sorted by created descending)
`GET /espresso/signals`	Search signals (sorted by created descending)
`GET /espresso/related/{relationship}`	Get related sips by relationship

Query parameters

Events and signals

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

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 (default `0`)

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 (default `0`)

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
reported:2026-06-07
related:public_policy|market_trends|regulation
briefing:Analysis of upcoming policy and market shifts...
event_type:policy_reform
impact_level:high
actions:Cooperation agreement signed|reevaluation scheduled
future_outlook:Short-term regulatory scrutiny will intensify...

MCP Server

Server URL: https://api.cafecito.tech/espresso/mcp (v0.1)

Hosted MCP tools (same names as REST operationIds):

Tool	REST path
`searchEvents`	`GET /espresso/events`
`searchSignals`	`GET /espresso/signals`
`listTags`	`GET /espresso/tags`
`getRelatedSips`	`GET /espresso/related/{relationship}`

Use response_type=text on list endpoints for token-efficient agent consumption. 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.reported, e.site_name, 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 (not an error)
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 29, 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