KosmoKrator

data

OpenAlex Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.openalex.*. Use lua_read_doc("integrations.openalex") 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 OpenAlex workflow without starting an interactive agent session.

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

Workflow file

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

workflow.lua 
local openalex = app.integrations.openalex
local result = openalex.list_works({})

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.openalex, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.openalex.default.* or app.integrations.openalex.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need OpenAlex, 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.

OpenAlex

Namespace: openalex

OpenAlex provides a scholarly graph covering works, authors, sources, institutions, topics, funders, publishers, geographic entities, classifications, and API utilities. The integration uses the current OpenAlex API reference and intentionally excludes deprecated concepts; use topics, domains, fields, and subfields instead.

All tools require an OpenAlex API key. Changefile tools may require a paid OpenAlex plan.

Entity Pattern

Most entities have a list tool and a get tool:

local works = openalex.list_works({
  search = "agentic retrieval",
  filter = {
    publication_year = 2024,
    is_oa = true,
  },
  sort = "cited_by_count:desc",
  per_page = 10,
  select = { "id", "display_name", "doi", "cited_by_count" },
})

local author = openalex.get_author({
  id = "https://orcid.org/0000-0001-6187-6610",
  select = { "id", "display_name", "works_count", "cited_by_count" },
})

List tools support search, filter, sort, per_page, page, cursor, sample, seed, select, and group_by. filter can be a raw OpenAlex filter string or a Lua table; tables are converted to OpenAlex comma-separated field:value syntax. select arrays are sent comma-separated.

Current Entity Coverage

  • works
  • authors
  • sources
  • institutions
  • topics
  • domains
  • fields
  • subfields
  • sdgs
  • countries
  • continents
  • languages
  • keywords
  • publishers
  • funders
  • awards
  • work_types
  • source_types
  • institution_types
  • licenses

Autocomplete

Use openalex.autocomplete for typeahead suggestions. Supported entities are works, authors, sources, institutions, topics, keywords, publishers, and funders.

local suggestions = openalex.autocomplete({
  entity = "authors",
  q = "Ada Lovelace",
})

Utilities

  • openalex.rate_limit checks the current API-key rate-limit status.
  • openalex.list_changefiles lists available changefile dates.
  • openalex.get_changefile gets changefile details for a specific date.
local usage = openalex.rate_limit({})

local changefile = openalex.get_changefile({
  date = "2026-01-01",
})

Return Shape

The integration returns OpenAlex JSON directly, preserving upstream fields. List responses usually include:

  • meta
  • results
  • group_by

Singleton get tools return the entity object. API errors are returned as tool errors with the OpenAlex error message when available.

Raw agent markdown 
# OpenAlex

Namespace: `openalex`

OpenAlex provides a scholarly graph covering works, authors, sources, institutions, topics, funders, publishers, geographic entities, classifications, and API utilities. The integration uses the current OpenAlex API reference and intentionally excludes deprecated `concepts`; use `topics`, `domains`, `fields`, and `subfields` instead.

All tools require an OpenAlex API key. Changefile tools may require a paid OpenAlex plan.

## Entity Pattern

Most entities have a list tool and a get tool:

```lua
local works = openalex.list_works({
  search = "agentic retrieval",
  filter = {
    publication_year = 2024,
    is_oa = true,
  },
  sort = "cited_by_count:desc",
  per_page = 10,
  select = { "id", "display_name", "doi", "cited_by_count" },
})

local author = openalex.get_author({
  id = "https://orcid.org/0000-0001-6187-6610",
  select = { "id", "display_name", "works_count", "cited_by_count" },
})
```

List tools support `search`, `filter`, `sort`, `per_page`, `page`, `cursor`, `sample`, `seed`, `select`, and `group_by`. `filter` can be a raw OpenAlex filter string or a Lua table; tables are converted to OpenAlex comma-separated `field:value` syntax. `select` arrays are sent comma-separated.

## Current Entity Coverage

- `works`
- `authors`
- `sources`
- `institutions`
- `topics`
- `domains`
- `fields`
- `subfields`
- `sdgs`
- `countries`
- `continents`
- `languages`
- `keywords`
- `publishers`
- `funders`
- `awards`
- `work_types`
- `source_types`
- `institution_types`
- `licenses`

## Autocomplete

Use `openalex.autocomplete` for typeahead suggestions. Supported entities are `works`, `authors`, `sources`, `institutions`, `topics`, `keywords`, `publishers`, and `funders`.

```lua
local suggestions = openalex.autocomplete({
  entity = "authors",
  q = "Ada Lovelace",
})
```

## Utilities

- `openalex.rate_limit` checks the current API-key rate-limit status.
- `openalex.list_changefiles` lists available changefile dates.
- `openalex.get_changefile` gets changefile details for a specific date.

```lua
local usage = openalex.rate_limit({})

local changefile = openalex.get_changefile({
  date = "2026-01-01",
})
```

## Return Shape

The integration returns OpenAlex JSON directly, preserving upstream fields. List responses usually include:

- `meta`
- `results`
- `group_by`

Singleton get tools return the entity object. API errors are returned as tool errors with the OpenAlex error message when available.
Metadata-derived Lua example 
local result = app.integrations.openalex.list_works({})
print(result)

Functions

list_works Read

List, search, filter, sort, sample, or group works.

Lua path
app.integrations.openalex.list_works
Full name
openalex.openalex_list_works
ParameterTypeRequiredDescription
No parameters.
get_work Read

Get one work by OpenAlex ID, DOI, PMID, or supported external ID.

Lua path
app.integrations.openalex.get_work
Full name
openalex.openalex_get_work
ParameterTypeRequiredDescription
No parameters.
list_authors Read

List, search, filter, sort, sample, or group authors.

Lua path
app.integrations.openalex.list_authors
Full name
openalex.openalex_list_authors
ParameterTypeRequiredDescription
No parameters.
get_author Read

Get one author by OpenAlex ID, ORCID, or supported external ID.

Lua path
app.integrations.openalex.get_author
Full name
openalex.openalex_get_author
ParameterTypeRequiredDescription
No parameters.
list_sources Read

List, search, filter, sort, sample, or group sources.

Lua path
app.integrations.openalex.list_sources
Full name
openalex.openalex_list_sources
ParameterTypeRequiredDescription
No parameters.
get_source Read

Get one source by OpenAlex ID, ISSN, or supported external ID.

Lua path
app.integrations.openalex.get_source
Full name
openalex.openalex_get_source
ParameterTypeRequiredDescription
No parameters.
list_institutions Read

List, search, filter, sort, sample, or group institutions.

Lua path
app.integrations.openalex.list_institutions
Full name
openalex.openalex_list_institutions
ParameterTypeRequiredDescription
No parameters.
get_institution Read

Get one institution by OpenAlex ID, ROR, or supported external ID.

Lua path
app.integrations.openalex.get_institution
Full name
openalex.openalex_get_institution
ParameterTypeRequiredDescription
No parameters.
list_topics Read

List, search, filter, sort, sample, or group topics.

Lua path
app.integrations.openalex.list_topics
Full name
openalex.openalex_list_topics
ParameterTypeRequiredDescription
No parameters.
get_topic Read

Get one topic by OpenAlex ID.

Lua path
app.integrations.openalex.get_topic
Full name
openalex.openalex_get_topic
ParameterTypeRequiredDescription
No parameters.
list_domains Read

List, search, filter, sort, sample, or group domains.

Lua path
app.integrations.openalex.list_domains
Full name
openalex.openalex_list_domains
ParameterTypeRequiredDescription
No parameters.
get_domain Read

Get one domain by OpenAlex ID.

Lua path
app.integrations.openalex.get_domain
Full name
openalex.openalex_get_domain
ParameterTypeRequiredDescription
No parameters.
list_fields Read

List, search, filter, sort, sample, or group fields.

Lua path
app.integrations.openalex.list_fields
Full name
openalex.openalex_list_fields
ParameterTypeRequiredDescription
No parameters.
get_field Read

Get one field by OpenAlex ID.

Lua path
app.integrations.openalex.get_field
Full name
openalex.openalex_get_field
ParameterTypeRequiredDescription
No parameters.
list_subfields Read

List, search, filter, sort, sample, or group subfields.

Lua path
app.integrations.openalex.list_subfields
Full name
openalex.openalex_list_subfields
ParameterTypeRequiredDescription
No parameters.
get_subfield Read

Get one subfield by OpenAlex ID.

Lua path
app.integrations.openalex.get_subfield
Full name
openalex.openalex_get_subfield
ParameterTypeRequiredDescription
No parameters.
list_sdgs Read

List, search, filter, sort, sample, or group Sustainable Development Goals.

Lua path
app.integrations.openalex.list_sdgs
Full name
openalex.openalex_list_sdgs
ParameterTypeRequiredDescription
No parameters.
get_sdg Read

Get one Sustainable Development Goal by OpenAlex ID.

Lua path
app.integrations.openalex.get_sdg
Full name
openalex.openalex_get_sdg
ParameterTypeRequiredDescription
No parameters.
list_countries Read

List, search, filter, sort, sample, or group countries.

Lua path
app.integrations.openalex.list_countries
Full name
openalex.openalex_list_countries
ParameterTypeRequiredDescription
No parameters.
get_country Read

Get one country by OpenAlex ID.

Lua path
app.integrations.openalex.get_country
Full name
openalex.openalex_get_country
ParameterTypeRequiredDescription
No parameters.
list_continents Read

List, search, filter, sort, sample, or group continents.

Lua path
app.integrations.openalex.list_continents
Full name
openalex.openalex_list_continents
ParameterTypeRequiredDescription
No parameters.
get_continent Read

Get one continent by OpenAlex ID.

Lua path
app.integrations.openalex.get_continent
Full name
openalex.openalex_get_continent
ParameterTypeRequiredDescription
No parameters.
list_languages Read

List, search, filter, sort, sample, or group languages.

Lua path
app.integrations.openalex.list_languages
Full name
openalex.openalex_list_languages
ParameterTypeRequiredDescription
No parameters.
get_language Read

Get one language by OpenAlex ID.

Lua path
app.integrations.openalex.get_language
Full name
openalex.openalex_get_language
ParameterTypeRequiredDescription
No parameters.
list_keywords Read

List, search, filter, sort, sample, or group keywords.

Lua path
app.integrations.openalex.list_keywords
Full name
openalex.openalex_list_keywords
ParameterTypeRequiredDescription
No parameters.
get_keyword Read

Get one keyword by OpenAlex ID.

Lua path
app.integrations.openalex.get_keyword
Full name
openalex.openalex_get_keyword
ParameterTypeRequiredDescription
No parameters.
list_publishers Read

List, search, filter, sort, sample, or group publishers.

Lua path
app.integrations.openalex.list_publishers
Full name
openalex.openalex_list_publishers
ParameterTypeRequiredDescription
No parameters.
get_publisher Read

Get one publisher by OpenAlex ID, Wikidata ID, or supported external ID.

Lua path
app.integrations.openalex.get_publisher
Full name
openalex.openalex_get_publisher
ParameterTypeRequiredDescription
No parameters.
list_funders Read

List, search, filter, sort, sample, or group funders.

Lua path
app.integrations.openalex.list_funders
Full name
openalex.openalex_list_funders
ParameterTypeRequiredDescription
No parameters.
get_funder Read

Get one funder by OpenAlex ID.

Lua path
app.integrations.openalex.get_funder
Full name
openalex.openalex_get_funder
ParameterTypeRequiredDescription
No parameters.
list_awards Read

List, search, filter, sort, sample, or group awards.

Lua path
app.integrations.openalex.list_awards
Full name
openalex.openalex_list_awards
ParameterTypeRequiredDescription
No parameters.
get_award Read

Get one award by OpenAlex ID.

Lua path
app.integrations.openalex.get_award
Full name
openalex.openalex_get_award
ParameterTypeRequiredDescription
No parameters.
list_work_types Read

List OpenAlex work type enumerations.

Lua path
app.integrations.openalex.list_work_types
Full name
openalex.openalex_list_work_types
ParameterTypeRequiredDescription
No parameters.
get_work_type Read

Get one work type by OpenAlex ID.

Lua path
app.integrations.openalex.get_work_type
Full name
openalex.openalex_get_work_type
ParameterTypeRequiredDescription
No parameters.
list_source_types Read

List OpenAlex source type enumerations.

Lua path
app.integrations.openalex.list_source_types
Full name
openalex.openalex_list_source_types
ParameterTypeRequiredDescription
No parameters.
get_source_type Read

Get one source type by OpenAlex ID.

Lua path
app.integrations.openalex.get_source_type
Full name
openalex.openalex_get_source_type
ParameterTypeRequiredDescription
No parameters.
list_institution_types Read

List OpenAlex institution type enumerations.

Lua path
app.integrations.openalex.list_institution_types
Full name
openalex.openalex_list_institution_types
ParameterTypeRequiredDescription
No parameters.
get_institution_type Read

Get one institution type by OpenAlex ID.

Lua path
app.integrations.openalex.get_institution_type
Full name
openalex.openalex_get_institution_type
ParameterTypeRequiredDescription
No parameters.
list_licenses Read

List OpenAlex license enumerations.

Lua path
app.integrations.openalex.list_licenses
Full name
openalex.openalex_list_licenses
ParameterTypeRequiredDescription
No parameters.
get_license Read

Get one license by OpenAlex ID.

Lua path
app.integrations.openalex.get_license
Full name
openalex.openalex_get_license
ParameterTypeRequiredDescription
No parameters.
autocomplete Read

Search OpenAlex autocomplete suggestions for works, authors, sources, institutions, topics, keywords, publishers, or funders.

Lua path
app.integrations.openalex.autocomplete
Full name
openalex.openalex_autocomplete
ParameterTypeRequiredDescription
No parameters.
rate_limit Read

Check the current OpenAlex API key rate-limit status and remaining allowance.

Lua path
app.integrations.openalex.rate_limit
Full name
openalex.openalex_rate_limit
ParameterTypeRequiredDescription
No parameters.
list_changefiles Read

List available OpenAlex changefile dates. Changefile access may require a paid OpenAlex plan.

Lua path
app.integrations.openalex.list_changefiles
Full name
openalex.openalex_list_changefiles
ParameterTypeRequiredDescription
No parameters.
get_changefile Read

Get OpenAlex changefile details and download links for a specific date. Changefile access may require a paid OpenAlex plan.

Lua path
app.integrations.openalex.get_changefile
Full name
openalex.openalex_get_changefile
ParameterTypeRequiredDescription
date string yes Changefile date in YYYY-MM-DD format.