Copy page

Build with Cafecito

API Conventions

Use this page to implement a shared HTTP client. Product pages describe resources and filters; this page is the shared transport contract.

Live products: Beans and Espresso. Cortado is a future product and have no public API.

There is no official Cafecito SDK. Integrate with REST or MCP using the patterns on Reusable clients. For limits, see Pricing and limits. For recovery, see Troubleshooting.

Base URL and authentication

Item	Contract
Gateway base URL	https://api.cafecito.tech
Authenticated requests API Key	Authorization: Bearer YOUR-API-KEY
Health	GET /beans/health and GET /espresso/health are public. Do not send a key.
MCP	Same key as REST. Hosted endpoints: https://api.cafecito.tech/beans/mcp and https://api.cafecito.tech/espresso/mcp.

Code
Authorization: Bearer YOUR-API-KEY

One key works across live REST APIs and MCP servers. Store the key in an environment variable or secret manager. Never commit it.

Query validation

Unknown or route-inapplicable query parameters are rejected with HTTP 400 and the ErrorResponse envelope below. Malformed UUIDs, malformed cursors, and out-of-range limit values are rejected with HTTP 400 as well.

Use only the parameters listed for that route in the Beans or Espresso reference.

Pagination

Products paginate collections with limit (default 20, maximum 100) and an opaque cursor. pagination.num_results is the count in this page, not a total match count. When pagination.next_cursor is non-null, send that exact string as the next request cursor on the same route with the same filters. Do not decode, modify, sort, or synthesize tokens.

Empty collections are HTTP 200 with data: []. Missing detail resources are HTTP 404.

Collection envelope

Collections return pagination, meta, and data. Continuation uses only next_cursor → request cursor.

Code
{
  "pagination": {
    "limit": 20,
    "num_results": 20,
    "next_cursor": "OPAQUE_TOKEN_OR_NULL"
  },
  "meta": {
    "as_of": "2026-08-24T20:42:39Z"
  },
  "data": []
}

Detail routes return

Code
{ 
  "data": { ... } 
}

Dates and freshness

Concept	Meaning
Date-only filters (from, to)	Inclusive UTC calendar dates in YYYY-MM-DD.
Beans from / to	Bound article publication time (published_at).
Espresso from / to	Bound record creation time (created_at).
meta.as_of	UTC time this collection snapshot was produced. Show it to users as freshness. Values in examples are captured, not a live dataset.
Bean full_content=true	It does not guarantee a full publisher copy or the most fresh copy if the same article has been updated recently. Handle a missing or partial content value and cite the canonical Article url.

Examples on product pages are not a guaranteed live result set. Re-query when the application needs a current snapshot.

Response formats

JSON is canonical for REST. Espresso is capable of returning YAML or TOON where response_type is documented; those encodings carry the same fields, including opaque cursors and are primarily designed for token optimization for AI Agents. Beans REST and MCP results use JSON.

Errors

Application errors from Beans and Espresso use HTTP status plus:

Code
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation"
  }
}

Missing or invalid public keys are rejected at the gateway with HTTP 401 (engine body). Send Authorization: Bearer <key>.

HTTP status	Typical cause	Retry?
400	Invalid or unknown query, malformed UUID or cursor, unsupported parameter	No. Fix the request.
401	Missing or invalid public API key (gateway)	No. Create or replace the key.
404	Detail resource does not exist	No. Do not treat empty collections as 404.
429	Rate or monthly quota reached	Yes, after backoff. See Pricing.
5xx	Temporary service failure	Yes, with bounded retries.

Successful collections never use 204 for empty results.

Retries and operational recovery

1. Confirm GET /beans/health or GET /espresso/health without a key.
2. Retry 429 and 5xx with exponential backoff and jitter. Honor any Retry-After header when present.
3. Do not retry 400, 401, or 404 with the same request.
4. If a cursor is rejected (400), restart the collection from the first page with the same filters.
5. If a response format is unsupported, fall back to JSON (response_type=json or omit the parameter).
6. Keep identifiers and next_cursor values exactly as returned.

Versioning and support

• Compatible changes are additive: new optional fields, new routes, and new enum values may appear without a URL version bump.
• Breaking changes ship as a new API version, with deprecation notices on this portal before removal.
• Report bugs and request features via Contact (GitHub issue templates).

Product choice

Job	Product
Publisher articles, stories, mentions, available full content	Beans
Market events, signals, evidence	Espresso

MCP tool catalogs and product overviews cover route selection. Shared client wrappers live on Reusable clients.