KosmoKrator

data

ClinicalTrials.gov Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local clinicaltrials_gov = app.integrations.clinicaltrials_gov
local result = clinicaltrials_gov.list_studies({})

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

MCP-only Lua

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

ClinicalTrials.gov

Namespace: clinicaltrials-gov

ClinicalTrials.gov exposes a public REST API v2 for clinical study records, metadata, search areas, enum values, statistics, and data version checks. No credentials are required.

Search Studies

Use clinicaltrials_gov_list_studies for /studies.

local page = clinicaltrials_gov.list_studies({
  ["query.cond"] = "lung cancer",
  ["filter.overallStatus"] = { "RECRUITING", "NOT_YET_RECRUITING" },
  fields = { "NCTId", "BriefTitle", "OverallStatus", "HasResults" },
  sort = { "@relevance" },
  countTotal = true,
  pageSize = 25,
})

For JSON paging, pass the returned nextPageToken as pageToken with the same query and filter parameters.

Arrays are encoded as pipe-delimited values, matching the API v2 OpenAPI style.

Fetch One Study

local study = clinicaltrials_gov.fetch_study({
  nctId = "NCT00841061",
  fields = { "ProtocolSection", "ResultsSection" },
})

The format parameter can be json, csv, json.zip, fhir.json, or ris for single-study retrieval. Non-JSON responses are returned as body, content_type, status, and selected pagination headers.

Metadata And Query Building

Use metadata, search areas, and enums before generating precise queries:

local fields = clinicaltrials_gov.metadata({
  includeIndexedOnly = true,
})

local areas = clinicaltrials_gov.search_areas({})
local enums = clinicaltrials_gov.enums({})

The metadata endpoint is the best source for allowed field, piece, and area names used by fields, sort, and advanced Essie expressions.

Statistics

local sizes = clinicaltrials_gov.size_stats({})

local phase_values = clinicaltrials_gov.field_values_stats({
  types = { "ENUM" },
  fields = { "Phase", "OverallStatus" },
})

local list_sizes = clinicaltrials_gov.field_sizes_stats({
  fields = { "Phase", "Condition" },
})

Version

local version = clinicaltrials_gov.version({})

Check dataTimestamp before assuming the weekday ClinicalTrials.gov data refresh has completed.

Raw agent markdown 
# ClinicalTrials.gov

Namespace: `clinicaltrials-gov`

ClinicalTrials.gov exposes a public REST API v2 for clinical study records, metadata, search areas, enum values, statistics, and data version checks. No credentials are required.

## Search Studies

Use `clinicaltrials_gov_list_studies` for `/studies`.

```lua
local page = clinicaltrials_gov.list_studies({
  ["query.cond"] = "lung cancer",
  ["filter.overallStatus"] = { "RECRUITING", "NOT_YET_RECRUITING" },
  fields = { "NCTId", "BriefTitle", "OverallStatus", "HasResults" },
  sort = { "@relevance" },
  countTotal = true,
  pageSize = 25,
})
```

For JSON paging, pass the returned `nextPageToken` as `pageToken` with the same query and filter parameters.

Arrays are encoded as pipe-delimited values, matching the API v2 OpenAPI style.

## Fetch One Study

```lua
local study = clinicaltrials_gov.fetch_study({
  nctId = "NCT00841061",
  fields = { "ProtocolSection", "ResultsSection" },
})
```

The `format` parameter can be `json`, `csv`, `json.zip`, `fhir.json`, or `ris` for single-study retrieval. Non-JSON responses are returned as `body`, `content_type`, `status`, and selected pagination headers.

## Metadata And Query Building

Use metadata, search areas, and enums before generating precise queries:

```lua
local fields = clinicaltrials_gov.metadata({
  includeIndexedOnly = true,
})

local areas = clinicaltrials_gov.search_areas({})
local enums = clinicaltrials_gov.enums({})
```

The metadata endpoint is the best source for allowed field, piece, and area names used by `fields`, `sort`, and advanced Essie expressions.

## Statistics

```lua
local sizes = clinicaltrials_gov.size_stats({})

local phase_values = clinicaltrials_gov.field_values_stats({
  types = { "ENUM" },
  fields = { "Phase", "OverallStatus" },
})

local list_sizes = clinicaltrials_gov.field_sizes_stats({
  fields = { "Phase", "Condition" },
})
```

## Version

```lua
local version = clinicaltrials_gov.version({})
```

Check `dataTimestamp` before assuming the weekday ClinicalTrials.gov data refresh has completed.
Metadata-derived Lua example 
local result = app.integrations.clinicaltrials_gov.list_studies({})
print(result)

Functions

list_studies Read

Search or list ClinicalTrials.gov studies with API v2 query and filter parameters.

Lua path
app.integrations.clinicaltrials_gov.list_studies
Full name
clinicaltrials-gov.clinicaltrials_gov_list_studies
ParameterTypeRequiredDescription
No parameters.
fetch_study Read

Fetch a single study by NCT ID.

Lua path
app.integrations.clinicaltrials_gov.fetch_study
Full name
clinicaltrials-gov.clinicaltrials_gov_fetch_study
ParameterTypeRequiredDescription
No parameters.
metadata Read

Retrieve the study data model field tree.

Lua path
app.integrations.clinicaltrials_gov.metadata
Full name
clinicaltrials-gov.clinicaltrials_gov_metadata
ParameterTypeRequiredDescription
No parameters.
search_areas Read

Retrieve search documents and search areas.

Lua path
app.integrations.clinicaltrials_gov.search_areas
Full name
clinicaltrials-gov.clinicaltrials_gov_search_areas
ParameterTypeRequiredDescription
No parameters.
enums Read

Retrieve enum types and values used in study records.

Lua path
app.integrations.clinicaltrials_gov.enums
Full name
clinicaltrials-gov.clinicaltrials_gov_enums
ParameterTypeRequiredDescription
No parameters.
size_stats Read

Retrieve study JSON size statistics.

Lua path
app.integrations.clinicaltrials_gov.size_stats
Full name
clinicaltrials-gov.clinicaltrials_gov_size_stats
ParameterTypeRequiredDescription
No parameters.
field_values_stats Read

Retrieve value statistics for study leaf fields.

Lua path
app.integrations.clinicaltrials_gov.field_values_stats
Full name
clinicaltrials-gov.clinicaltrials_gov_field_values_stats
ParameterTypeRequiredDescription
No parameters.
field_sizes_stats Read

Retrieve size statistics for list and array fields.

Lua path
app.integrations.clinicaltrials_gov.field_sizes_stats
Full name
clinicaltrials-gov.clinicaltrials_gov_field_sizes_stats
ParameterTypeRequiredDescription
No parameters.
version Read

Retrieve API and data version timestamps.

Lua path
app.integrations.clinicaltrials_gov.version
Full name
clinicaltrials-gov.clinicaltrials_gov_version
ParameterTypeRequiredDescription
No parameters.