KosmoKrator

data

NewsAPI Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the NewsAPI KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.newsapi.*. Use lua_read_doc("integrations.newsapi") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic NewsAPI workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.newsapi.everything({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("newsapi"))' --json
kosmo integrations:lua --eval 'print(docs.read("newsapi.everything"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local newsapi = app.integrations.newsapi
local result = newsapi.everything({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.newsapi, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.newsapi.default.* or app.integrations.newsapi.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need NewsAPI, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

NewsAPI

Namespace: newsapi

Use this integration to search indexed news articles, retrieve live top and breaking headlines, and discover source IDs available for top-headlines calls.

Authentication

NewsAPI requires an API key. The integration sends it in the X-Api-Key header rather than adding it to query strings.

Tools

  • newsapi_everything: search indexed articles with q, source/domain filters, date bounds, language, sorting, and pagination.
  • newsapi_top_headlines: retrieve top headlines by country, category, source, keyword, and pagination.
  • newsapi_sources: list source IDs available for newsapi_top_headlines.

Return Notes

NewsAPI responses keep the upstream field names. Article responses include status, totalResults, and articles. Each article has source, author, title, description, url, urlToImage, publishedAt, and content. The content field is usually truncated by NewsAPI and should not be treated as full article text.

newsapi_everything requires at least one of q, sources, or domains. newsapi_top_headlines does not allow sources to be mixed with country or category, matching NewsAPI’s documented constraint.

Examples

local ai = tools.newsapi_everything({
  q = "\"artificial intelligence\" OR LLM",
  language = "en",
  sort_by = "publishedAt",
  page_size = 20
})

local headlines = tools.newsapi_top_headlines({
  country = "us",
  category = "technology",
  page_size = 10
})

local sources = tools.newsapi_sources({
  language = "en",
  country = "us"
})
Raw agent markdown 
# NewsAPI

Namespace: `newsapi`

Use this integration to search indexed news articles, retrieve live top and
breaking headlines, and discover source IDs available for top-headlines calls.

## Authentication

NewsAPI requires an API key. The integration sends it in the `X-Api-Key`
header rather than adding it to query strings.

## Tools

- `newsapi_everything`: search indexed articles with `q`, source/domain
  filters, date bounds, language, sorting, and pagination.
- `newsapi_top_headlines`: retrieve top headlines by country, category, source,
  keyword, and pagination.
- `newsapi_sources`: list source IDs available for `newsapi_top_headlines`.

## Return Notes

NewsAPI responses keep the upstream field names. Article responses include
`status`, `totalResults`, and `articles`. Each article has `source`, `author`,
`title`, `description`, `url`, `urlToImage`, `publishedAt`, and `content`.
The `content` field is usually truncated by NewsAPI and should not be treated
as full article text.

`newsapi_everything` requires at least one of `q`, `sources`, or `domains`.
`newsapi_top_headlines` does not allow `sources` to be mixed with `country` or
`category`, matching NewsAPI's documented constraint.

## Examples

```lua
local ai = tools.newsapi_everything({
  q = "\"artificial intelligence\" OR LLM",
  language = "en",
  sort_by = "publishedAt",
  page_size = 20
})

local headlines = tools.newsapi_top_headlines({
  country = "us",
  category = "technology",
  page_size = 10
})

local sources = tools.newsapi_sources({
  language = "en",
  country = "us"
})
```
Metadata-derived Lua example 
local result = app.integrations.newsapi.everything({})
print(result)

Functions

everything Read

Search across indexed news articles.

Lua path
app.integrations.newsapi.everything
Full name
newsapi.newsapi_everything
ParameterTypeRequiredDescription
No parameters.
top_headlines Read

Retrieve live top and breaking headlines.

Lua path
app.integrations.newsapi.top_headlines
Full name
newsapi.newsapi_top_headlines
ParameterTypeRequiredDescription
No parameters.
sources Read

List news sources available for top headlines.

Lua path
app.integrations.newsapi.sources
Full name
newsapi.newsapi_sources
ParameterTypeRequiredDescription
No parameters.