Stories

Story grouping of related publisher Articles.

List Stories

GET

https://api.cafecito.tech

/beans/stories

Returns Stories identified by stable UUIDs. The collection does not include every member Article.

List Stories › query Parameters

q

string · maxLength: 512

Optional relevance query. When supplied, score_threshold may be omitted. score_threshold without q returns HTTP 400. On Sources and label routes, a case-insensitive prefix query.

score_threshold

number · min: 0 · max: 1

Optional relevance threshold used only with q. Rejected when q is absent.

content_type

string · enum

Filterable Article type. post is response-only: content_type=post returns HTTP 400. The other 14 stored types remain filterable. Omit to include every stored type.

Enum values:

blog

contract

earnings_report

enforcement_action

financial_report

lawsuit

news

official_statement

sources

string[] · maxItems: 128 · style: form

Source UUIDs to include (CSV).

exclude_sources

string[] · maxItems: 128 · style: form

Source UUIDs to exclude (CSV).

domains

string[] · maxItems: 100 · style: form

Source domain values to include (CSV).

exclude_domains

string[] · maxItems: 100 · style: form

Source domain values to exclude (CSV).

authors

string[] · maxItems: 100 · style: form

Author text filters. Every supplied value must match (CSV).

categories

string[] · maxItems: 100 · style: form

Category values to include (CSV).

exclude_categories

string[] · maxItems: 100 · style: form

Category values to exclude (CSV).

regions

string[] · maxItems: 100 · style: form

Region values to include (CSV).

entities

string[] · maxItems: 100 · style: form

Entity values to include (CSV).

sentiments

string[] · maxItems: 100 · style: form

Sentiment values to include (CSV).

tags

string[] · maxItems: 100 · style: form

Normalized tag terms. Every supplied term must match (CSV).

languages

string[] · maxItems: 100 · style: form

ISO 639 language codes to include (CSV). Any listed value matches. A stored language matches if it equals a listed code or starts with that code.

min_article_count

integer · min: 2

Minimum number of Articles in a Story.

Default: 2

from

string · date

UTC lower timestamp bound. YYYY-MM-DD means 00:00:00Z.

to

string · date

UTC upper timestamp bound. YYYY-MM-DD means 00:00:00Z.

limit

integer · min: 1 · max: 100

Maximum records in the page.

Default: 20

cursor

string

Opaque continuation token from pagination.next_cursor. Send it unchanged as the next request cursor. Never construct or decode cursor tokens.

List Stories › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List Stories › Responses

Successful response.

StoryCollectionResponse

Pagination · required

ResponseMeta · required

Story[] · required

GET/beans/stories

curl https://api.cafecito.tech/beans/stories \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "pagination": {
    "limit": 1,
    "num_results": 1,
    "next_cursor": "eyJ2IjoxLCJpZCI6IjA2ODYwYWFhLWE0M2MtNTg1Zi05Y2IzLWE2NzEwYTkzYTc0YSIsImMiOiIyMDI2LTA4LTI0VDAyOjAwOjQzWiJ9"
  },
  "meta": {
    "as_of": "2026-08-24T20:42:41.302877043Z"
  },
  "data": [
    {
      "id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
      "title": "UAE AI Programme adds Agentic AI focus",
      "first_published_at": "2026-06-22T02:00:40Z",
      "last_published_at": "2026-08-24T02:00:43Z",
      "article_count": 12,
      "source_count": 1,
      "categories": [
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models",
        "ai_ethics_and_governance",
        "robotics_and_autonomous_systems",
        "media_and_journalism"
      ],
      "regions": [
        "egypt",
        "middle_east",
        "africa",
        "japan",
        "riyadh",
        "saudi_arabia",
        "united_arab_emirates"
      ],
      "entities": [
        "carrington_malin",
        "anghami",
        "airev",
        "daniel_valle",
        "dubai_university",
        "muhammad_khalid",
        "qatar_university",
        "ai",
        "ai_agents",
        "ai_infrastructure"
      ],
      "tags": [
        "carrington_malin",
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models",
        "anghami",
        "ai_ethics_and_governance",
        "egypt",
        "middle_east",
        "airev",
        "daniel_valle",
        "dubai_university"
      ],
      "top_articles": [
        {
          "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
          "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
          "title": "UAE AI Programme adds Agentic AI focus",
          "published_at": "2026-08-24T02:00:43Z",
          "source": null
        },
        {
          "id": "ec2e3641-07cd-5a9c-870f-79256e293481",
          "url": "https://www.middleeastainews.com/p/kuwait-backs-ai-to-boost-smart-meter",
          "title": "Kuwait backs AI to boost smart meter efficiency",
          "published_at": "2026-08-22T02:00:35Z",
          "source": null
        },
        {
          "id": "e3a0e8ed-c10c-58ed-a408-61985f6f58f4",
          "url": "https://www.middleeastainews.com/p/dubai-chambers-nasscom-partner-on",
          "title": "Dubai Chambers, Nasscom partner on Agentic AI",
          "published_at": "2026-08-21T02:00:07Z",
          "source": null
        }
      ]
    }
  ]
}

json

application/json

Get a Story

GET

https://api.cafecito.tech

/beans/stories/{id}

Returns one Story selected by its stable UUID, including a service-relative member-Article path. For the public gateway, request /beans plus links.articles.

Get a Story › path Parameters

id

string · uuid · required

Article or Source UUID.

Get a Story › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get a Story › Responses

Successful response.

StoryDetailResponse

StoryDetail · required

GET/beans/stories/{id}

curl https://api.cafecito.tech/beans/stories/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
    "title": "UAE AI Programme adds Agentic AI focus",
    "first_published_at": "2026-06-22T02:00:40Z",
    "last_published_at": "2026-08-24T02:00:43Z",
    "article_count": 12,
    "source_count": 1,
    "categories": [
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models",
      "ai_ethics_and_governance",
      "robotics_and_autonomous_systems",
      "media_and_journalism"
    ],
    "regions": [
      "egypt",
      "middle_east",
      "africa",
      "japan",
      "riyadh",
      "saudi_arabia",
      "united_arab_emirates"
    ],
    "entities": [
      "carrington_malin",
      "anghami",
      "airev",
      "daniel_valle",
      "dubai_university",
      "muhammad_khalid",
      "qatar_university",
      "ai",
      "ai_agents",
      "ai_infrastructure"
    ],
    "tags": [
      "carrington_malin",
      "artificial_intelligence_and_machine_learning",
      "generative_ai_and_foundation_models",
      "anghami",
      "ai_ethics_and_governance",
      "egypt",
      "middle_east",
      "airev",
      "daniel_valle",
      "dubai_university"
    ],
    "top_articles": [
      {
        "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
        "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
        "title": "UAE AI Programme adds Agentic AI focus",
        "published_at": "2026-08-24T02:00:43Z",
        "source": null
      },
      {
        "id": "ec2e3641-07cd-5a9c-870f-79256e293481",
        "url": "https://www.middleeastainews.com/p/kuwait-backs-ai-to-boost-smart-meter",
        "title": "Kuwait backs AI to boost smart meter efficiency",
        "published_at": "2026-08-22T02:00:35Z",
        "source": null
      },
      {
        "id": "e3a0e8ed-c10c-58ed-a408-61985f6f58f4",
        "url": "https://www.middleeastainews.com/p/dubai-chambers-nasscom-partner-on",
        "title": "Dubai Chambers, Nasscom partner on Agentic AI",
        "published_at": "2026-08-21T02:00:07Z",
        "source": null
      }
    ],
    "links": {
      "articles": "/stories/06860aaa-a43c-585f-9cb3-a6710a93a74a/articles"
    }
  }
}

json

application/json

List Story Articles

GET

https://api.cafecito.tech

/beans/stories/{id}/articles

Returns member Articles for a stable Story UUID. Article filters narrow the returned members.

List Story Articles › path Parameters

id

string · uuid · required

Article or Source UUID.

List Story Articles › query Parameters

content_type

string · enum

Filterable Article type. post is response-only: content_type=post returns HTTP 400. The other 14 stored types remain filterable. Omit to include every stored type.

Enum values:

blog

contract

earnings_report

enforcement_action

financial_report

lawsuit

news

official_statement

sources

string[] · maxItems: 128 · style: form

Source UUIDs to include (CSV).

exclude_sources

string[] · maxItems: 128 · style: form

Source UUIDs to exclude (CSV).

domains

string[] · maxItems: 100 · style: form

Source domain values to include (CSV).

exclude_domains

string[] · maxItems: 100 · style: form

Source domain values to exclude (CSV).

authors

string[] · maxItems: 100 · style: form

Author text filters. Every supplied value must match (CSV).

categories

string[] · maxItems: 100 · style: form

Category values to include (CSV).

exclude_categories

string[] · maxItems: 100 · style: form

Category values to exclude (CSV).

regions

string[] · maxItems: 100 · style: form

Region values to include (CSV).

entities

string[] · maxItems: 100 · style: form

Entity values to include (CSV).

sentiments

string[] · maxItems: 100 · style: form

Sentiment values to include (CSV).

tags

string[] · maxItems: 100 · style: form

Normalized tag terms. Every supplied term must match (CSV).

languages

string[] · maxItems: 100 · style: form

ISO 639 language codes to include (CSV). Any listed value matches. A stored language matches if it equals a listed code or starts with that code.

from

string · date

UTC lower timestamp bound. YYYY-MM-DD means 00:00:00Z.

to

string · date

UTC upper timestamp bound. YYYY-MM-DD means 00:00:00Z.

full_content

boolean

Request available body content. Availability is not a grant of republication, redistribution, archival, training, or other downstream rights. Handle a missing content value, preserve the canonical url, and follow https://cafecito.tech/docs/third-party-content-policy/.

Default: false

limit

integer · min: 1 · max: 100

Maximum records in the page.

Default: 20

cursor

string

Opaque continuation token from pagination.next_cursor. Send it unchanged as the next request cursor. Never construct or decode cursor tokens.

List Story Articles › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List Story Articles › Responses

Successful response.

StoryArticleCollectionResponse

Pagination · required

StoryArticleMeta · required

Article[] · required

GET/beans/stories/{id}/articles

curl https://api.cafecito.tech/beans/stories/:id/articles \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "pagination": {
    "limit": 1,
    "num_results": 1,
    "next_cursor": "eyJ2IjoxLCJpZCI6IjNhNDc5ZTNjLWE4N2QtNTkxZS1iYjZjLTVjODNjMDNiNmE0MCIsImMiOiIyMDI2LTA4LTI0VDAyOjAwOjQzWiJ9"
  },
  "meta": {
    "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
    "as_of": "2026-08-24T20:42:41.566851796Z"
  },
  "data": [
    {
      "id": "3a479e3c-a87d-591e-bb6c-5c83c03b6a40",
      "url": "https://www.middleeastainews.com/p/uae-ai-programme-adds-agentic-ai",
      "content_type": "news",
      "published_at": "2026-08-24T02:00:43Z",
      "author": "Carrington Malin",
      "image_url": null,
      "title": "UAE AI Programme adds Agentic AI focus",
      "summary": "Listen now | Middle East AI News Minute - 24-Aug-26",
      "categories": [
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models"
      ],
      "regions": null,
      "entities": [
        "carrington_malin"
      ],
      "sentiments": [
        "disturbed",
        "anxious"
      ],
      "ideology": "center",
      "tags": [
        "artificial_intelligence_and_machine_learning",
        "generative_ai_and_foundation_models",
        "carrington_malin"
      ],
      "story_id": "06860aaa-a43c-585f-9cb3-a6710a93a74a",
      "source": null
    }
  ]
}

json

application/json

Discovery Health

List Stories

GET

https://api.cafecito.tech

/beans/stories

Returns Stories identified by stable UUIDs. The collection does not include every member Article.

List Stories › query Parameters

q

string · maxLength: 512

Optional relevance query. When supplied, score_threshold may be omitted. score_threshold without q returns HTTP 400. On Sources and label routes, a case-insensitive prefix query.

score_threshold

number · min: 0 · max: 1

Optional relevance threshold used only with q. Rejected when q is absent.

content_type

string · enum

Filterable Article type. post is response-only: content_type=post returns HTTP 400. The other 14 stored types remain filterable. Omit to include every stored type.

Enum values:

blog

contract

earnings_report

enforcement_action

financial_report

lawsuit

news

official_statement

sources

string[] · maxItems: 128 · style: form

Source UUIDs to include (CSV).

exclude_sources

string[] · maxItems: 128 · style: form

Source UUIDs to exclude (CSV).

domains

string[] · maxItems: 100 · style: form

Source domain values to include (CSV).

exclude_domains

string[] · maxItems: 100 · style: form

Source domain values to exclude (CSV).

authors

string[] · maxItems: 100 · style: form

Author text filters. Every supplied value must match (CSV).

categories

string[] · maxItems: 100 · style: form

Category values to include (CSV).

exclude_categories

string[] · maxItems: 100 · style: form

Category values to exclude (CSV).

regions

string[] · maxItems: 100 · style: form

Region values to include (CSV).

entities

string[] · maxItems: 100 · style: form

Entity values to include (CSV).

sentiments

string[] · maxItems: 100 · style: form

Sentiment values to include (CSV).

tags

string[] · maxItems: 100 · style: form

Normalized tag terms. Every supplied term must match (CSV).

languages

string[] · maxItems: 100 · style: form

ISO 639 language codes to include (CSV). Any listed value matches. A stored language matches if it equals a listed code or starts with that code.

min_article_count

integer · min: 2

Minimum number of Articles in a Story.

Default: 2

from

string · date

UTC lower timestamp bound. YYYY-MM-DD means 00:00:00Z.

to

string · date

UTC upper timestamp bound. YYYY-MM-DD means 00:00:00Z.

limit

integer · min: 1 · max: 100

Maximum records in the page.

Default: 20

cursor

string

Opaque continuation token from pagination.next_cursor. Send it unchanged as the next request cursor. Never construct or decode cursor tokens.

List Stories › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List Stories › Responses

Successful response.

StoryCollectionResponse

Pagination · required

ResponseMeta · required

Story[] · required

Get a Story

GET

https://api.cafecito.tech

/beans/stories/{id}

Returns one Story selected by its stable UUID, including a service-relative member-Article path. For the public gateway, request /beans plus links.articles.

Get a Story › path Parameters

id

string · uuid · required

Article or Source UUID.

Get a Story › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get a Story › Responses

Successful response.

StoryDetailResponse

StoryDetail · required

List Story Articles

GET

https://api.cafecito.tech

/beans/stories/{id}/articles

Returns member Articles for a stable Story UUID. Article filters narrow the returned members.

List Story Articles › path Parameters

id

string · uuid · required

Article or Source UUID.

List Story Articles › query Parameters

content_type

string · enum

Filterable Article type. post is response-only: content_type=post returns HTTP 400. The other 14 stored types remain filterable. Omit to include every stored type.

Enum values:

blog

contract

earnings_report

enforcement_action

financial_report

lawsuit

news

official_statement

sources

string[] · maxItems: 128 · style: form

Source UUIDs to include (CSV).

exclude_sources

string[] · maxItems: 128 · style: form

Source UUIDs to exclude (CSV).

domains

string[] · maxItems: 100 · style: form

Source domain values to include (CSV).

exclude_domains

string[] · maxItems: 100 · style: form

Source domain values to exclude (CSV).

authors

string[] · maxItems: 100 · style: form

Author text filters. Every supplied value must match (CSV).

categories

string[] · maxItems: 100 · style: form

Category values to include (CSV).

exclude_categories

string[] · maxItems: 100 · style: form

Category values to exclude (CSV).

regions

string[] · maxItems: 100 · style: form

Region values to include (CSV).

entities

string[] · maxItems: 100 · style: form

Entity values to include (CSV).

sentiments

string[] · maxItems: 100 · style: form

Sentiment values to include (CSV).

tags

string[] · maxItems: 100 · style: form

Normalized tag terms. Every supplied term must match (CSV).

languages

string[] · maxItems: 100 · style: form

ISO 639 language codes to include (CSV). Any listed value matches. A stored language matches if it equals a listed code or starts with that code.

from

string · date

UTC lower timestamp bound. YYYY-MM-DD means 00:00:00Z.

to

string · date

UTC upper timestamp bound. YYYY-MM-DD means 00:00:00Z.

full_content

boolean

Default: false

limit

integer · min: 1 · max: 100

Maximum records in the page.

Default: 20

cursor

string

Opaque continuation token from pagination.next_cursor. Send it unchanged as the next request cursor. Never construct or decode cursor tokens.

List Story Articles › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List Story Articles › Responses

Successful response.

StoryArticleCollectionResponse

Pagination · required

StoryArticleMeta · required

Article[] · required