Copy page

Beans

Beans API Workflows

Serve Your News App with Beans API

Beans can supply publisher-content data for a news application: current Articles, attention-ranked feeds, topic collections, publisher records, Article detail, related reading, and external mention observations. These are backend data workflows only. They do not prescribe presentation, layout, or interaction design.

Set the shared configuration once:

Code
export API_KEY="YOUR_API_KEY"
export BASE_URL="https://api.cafecito.tech"

Operating rules

Rule	Why it matters
Choose a feed route by intent.	latest is chronological, top-headlines uses a fixed recent attention window, and trending ranks observed attention.
Preserve Article and Source UUIDs.	IDs are the handoff between search, detail, similar, mentions, and Source-filtered Article calls.
Keep collection calls independent.	A temporary failure in one collection does not prevent the others from being served.
Request full_content=true only for selected Article detail.	Collections remain compact. Body content is available only when Beans has it; use url for attribution.
Treat pagination.next_cursor as opaque.	Send it back only as cursor with the same route and filters.
Use discovery only for an unknown value.	Known normalized categories, entities, regions, and sentiments can go directly into Article filters.
Send only documented parameters.	Unknown or route-inapplicable keys, including content_type on top-headlines and from/to on feeds, return HTTP 400.

Request content_type accepts 14 filterable types: blog, contract, earnings_report, enforcement_action, financial_report, lawsuit, news, official_statement, podcast, press_release, research_paper, site, technical_documentation, and whitepaper. post may appear on responses. content_type=post returns HTTP 400. Omit content_type when a collection should include all stored types.

Shared server helper

The JavaScript examples use the built-in fetch in Node.js 18 and later.

Code
const apiKey = process.env.CAFECITO_API_KEY;
const baseUrl = "https://api.cafecito.tech";

async function beansGet(path, query = {}) {
  const url = new URL(path, baseUrl);
  for (const [key, value] of Object.entries(query)) {
    if (value !== undefined && value !== null && value !== "") {
      url.searchParams.set(key, String(value));
    }
  }

  const response = await fetch(url, {
    headers: { Authorization: "Bearer " + apiKey },
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  return response.json();
}

Scenario 1: Serve independent home-feed collections

Use when: A request needs current publication, a fixed headline set, and attention-ranked coverage.

Call sequence: 3 independent calls

1. GET /beans/articles/latest for chronological publication.
2. GET /beans/news/top-headlines for the fixed recent attention window (news only; no content_type or dates).
3. GET /beans/articles/trending for attention-ranked coverage (no from or to).

Code
const settled = await Promise.allSettled([
  beansGet("/beans/articles/latest", {
    content_type: "news",
    limit: 24,
  }),
  beansGet("/beans/news/top-headlines", {
    limit: 12,
  }),
  beansGet("/beans/articles/trending", {
    content_type: "news",
    limit: 12,
  }),
]);

function collection(result) {
  if (result.status === "fulfilled") {
    return { ...result.value, error: null };
  }
  return {
    data: [],
    pagination: { next_cursor: null },
    meta: {},
    error: "collection unavailable",
  };
}

const [latest, headlines, trending] = settled.map(collection);

const payload = {
  latest: latest.data,
  headlines: headlines.data,
  trending: trending.data,
  cursors: {
    latest: latest.pagination.next_cursor,
    headlines: headlines.pagination.next_cursor,
    trending: trending.pagination.next_cursor,
  },
  asOf: {
    latest: latest.meta.as_of,
    headlines: headlines.meta.as_of,
    trending: trending.meta.as_of,
  },
  errors: {
    latest: latest.error,
    headlines: headlines.error,
    trending: trending.error,
  },
};

Code
curl -s --get "$BASE_URL/beans/articles/latest" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=news" \
  --data-urlencode "limit=24"

curl -s --get "$BASE_URL/beans/news/top-headlines" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "limit=12"

curl -s --get "$BASE_URL/beans/articles/trending" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=news" \
  --data-urlencode "limit=12"

Serving rule: Preserve each route as a separate collection. top-headlines and trending are different rankings; do not merge them into one ordered list or substitute one when the other is empty.

Scenario 2: Resolve a topic, then serve filtered Articles

Use when: A request contains a human topic label and needs an accepted Beans filter before Article retrieval.

Call sequence: 2 calls

1. GET /beans/categories?q={term} to discover an accepted category value when it is unknown.
2. GET /beans/articles/search with the selected category and optional natural-language query.

Code
const categoryPage = await beansGet("/beans/categories", {
  q: "climate",
  limit: 20,
});
const category = categoryPage.data.at(0)?.value;

const articlePage = category
  ? await beansGet("/beans/articles/search", {
      q: "climate policy",
      categories: category,
      content_type: "news",
      from: "2026-08-01",
      limit: 20,
    })
  : { data: [], pagination: { next_cursor: null }, meta: {} };

const payload = {
  resolvedCategory: category ?? null,
  articles: articlePage.data,
  nextCursor: articlePage.pagination.next_cursor,
  asOf: articlePage.meta.as_of,
};

Code
# Skip discovery when the normalized category is already known.
curl -s --get "$BASE_URL/beans/categories" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "q=climate" \
  --data-urlencode "limit=20"

curl -s --get "$BASE_URL/beans/articles/search" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "q=climate policy" \
  --data-urlencode "categories=CATEGORY_VALUE" \
  --data-urlencode "content_type=news" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "limit=20"

Serving rule: Return the selected normalized filter value with the Article collection so later requests can reuse it. Different filter fields combine with AND; multiple values within one include field use OR.

Scenario 3: Resolve a publisher, then serve its Articles

Use when: A request starts with a publisher or domain and needs current coverage from that publisher.

Call sequence: 3 calls

1. GET /beans/sources to resolve a Source UUID from domain, name, or URL metadata.
2. GET /beans/sources/{id} for one Source record.
3. GET /beans/articles/search?sources={id} for the Source Article collection.

Code
const sourcePage = await beansGet("/beans/sources", {
  q: "publisher.example",
  domains: "publisher.example",
  limit: 10,
});
const source = sourcePage.data.at(0);

const payload = source
  ? await Promise.all([
      beansGet("/beans/sources/" + source.id),
      beansGet("/beans/articles/search", {
        sources: source.id,
        from: "2026-08-01",
        limit: 20,
      }),
    ]).then(([sourceDetail, articlePage]) => ({
      source: sourceDetail.data,
      articles: articlePage.data,
      nextCursor: articlePage.pagination.next_cursor,
    }))
  : { source: null, articles: [], nextCursor: null };

Code
curl -s --get "$BASE_URL/beans/sources" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "q=publisher.example" \
  --data-urlencode "domains=publisher.example" \
  --data-urlencode "limit=10"

curl -s "$BASE_URL/beans/sources/SOURCE_UUID" \
  -H "Authorization: Bearer $API_KEY"

curl -s --get "$BASE_URL/beans/articles/search" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "sources=SOURCE_UUID" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "limit=20"

Serving rule: A Source describes a publisher. Use its UUID for sources; do not send a domain value to the sources filter.

Scenario 4: Enrich one selected Article

Use when: A known Article needs its available body, related publisher coverage, and external observations.

Call sequence: 3 calls

1. GET /beans/articles/{id}?full_content=true for the selected Article.
2. GET /beans/articles/{id}/similar for related publisher reading.
3. GET /beans/articles/{id}/mentions for external social or forum observations.

Code
const articleId = "ARTICLE_UUID";

const [article, similar, mentions] = await Promise.all([
  beansGet("/beans/articles/" + articleId, { full_content: true }),
  beansGet("/beans/articles/" + articleId + "/similar", { limit: 10 }),
  beansGet("/beans/articles/" + articleId + "/mentions", { limit: 20 }),
]);

const payload = {
  article: article.data,
  similarArticles: similar.data,
  mentions: mentions.data,
  cursors: {
    similar: similar.pagination.next_cursor,
    mentions: mentions.pagination.next_cursor,
  },
};

Code
curl -s --get "$BASE_URL/beans/articles/ARTICLE_UUID" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "full_content=true"

curl -s "$BASE_URL/beans/articles/ARTICLE_UUID/similar?limit=10" \
  -H "Authorization: Bearer $API_KEY"

curl -s "$BASE_URL/beans/articles/ARTICLE_UUID/mentions?limit=20" \
  -H "Authorization: Bearer $API_KEY"

Serving rule: similar returns related reading, not guaranteed Story membership. mentions returns external observations, not replacement publisher Articles. content can be null even when full_content=true if a body is unavailable.

Scenario 5: Continue a collection without offset pagination

Use when: A server needs the next bounded batch from an existing route and filter set.

Call sequence: 2 or more calls

1. Request the first collection page without cursor.
2. Return pagination.next_cursor with the collection data.
3. Reissue the exact route and filters with that token as cursor only when it is non-null.

Code
async function latestArticles(cursor = null) {
  const page = await beansGet("/beans/articles/latest", {
    content_type: "news",
    limit: 20,
    cursor,
  });

  return {
    articles: page.data,
    nextCursor: page.pagination.next_cursor,
    asOf: page.meta.as_of,
  };
}

const firstPage = await latestArticles();
const secondPage = firstPage.nextCursor
  ? await latestArticles(firstPage.nextCursor)
  : null;

Code
curl -s --get "$BASE_URL/beans/articles/latest" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=news" \
  --data-urlencode "limit=20"

curl -s --get "$BASE_URL/beans/articles/latest" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=news" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=NEXT_CURSOR_FROM_FIRST_RESPONSE"

Serving rule: Keep the route and all filters identical while continuing. Do not use offset, page, pageSize, or a cursor from another collection. Stop when next_cursor is null.

Data-serving checklist

1. Select the feed route from the requested data intent rather than applying local ordering to a generic search.
2. Return API data items without inventing Article, Source, trend, or mention fields.
3. Keep selected Article and Source UUIDs as opaque values for follow-up calls.
4. Preserve separate collection cursors and freshness metadata.
5. Treat empty data: [] as a successful result and HTTP 404 as a missing Article, Source, or Story.
6. Use Beans migration for provider parameter mapping and the Beans API reference for request and response schemas.

Scenario 6: Resolve a Story, then serve its member Articles

Use when: A news request needs a related-coverage group and the publisher Articles that belong to it.

Call sequence: 3 calls

1. GET /beans/stories selects a stable Story UUID.
2. GET /beans/stories/{id} returns Story detail.
3. GET /beans/stories/{id}/articles returns the first member-Article page. The detail and member calls can run in parallel after selection.

Code
const storyPage = await beansGet("/beans/stories", {
  q: "technology",
  min_article_count: 2,
  limit: 1,
});
const storyId = storyPage.data.at(0)?.id;

const payload = storyId
  ? await Promise.all([
      beansGet("/beans/stories/" + storyId),
      beansGet("/beans/stories/" + storyId + "/articles", {
        content_type: "news",
        limit: 20,
      }),
    ]).then(([story, articles]) => ({
      story: story.data,
      articles: articles.data,
      nextCursor: articles.pagination.next_cursor,
      asOf: articles.meta.as_of,
    }))
  : { story: null, articles: [], nextCursor: null, asOf: storyPage.meta.as_of };

The detail response carries the same stable UUID and a service-relative links.articles path. For a gateway request, call GET /beans followed by that path. The member-Article envelope repeats the requested Story UUID in meta.story_id; Article story_id is present for members assigned to a Story.

Scenario 7: Monitor earnings or litigation coverage

Use when: The application watches publisher financial reports or lawsuits rather than general news.

Call sequence: 1 call (repeat with cursor as needed)

GET /beans/articles/search with a filterable content_type. Do not send content_type=post.

Code
const earnings = await beansGet("/beans/articles/search", {
  content_type: "earnings_report",
  from: "2026-08-01",
  limit: 20,
});

const litigation = await beansGet("/beans/articles/search", {
  content_type: "lawsuit",
  entities: "openai",
  limit: 20,
});

Code
curl -s --get "$BASE_URL/beans/articles/search" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=earnings_report" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "limit=20"

curl -s --get "$BASE_URL/beans/articles/search" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "content_type=official_statement" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "limit=20"

Serving rule: These types are publisher documents. For structured impact or outlook, continue in Espresso after selecting identifiers here.