KosmoKrator

data

urlscan.io Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.urlscan.submit({body = "example_body"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("urlscan"))' --json
kosmo integrations:lua --eval 'print(docs.read("urlscan.submit"))' --json

Workflow file

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

workflow.lua 
local urlscan = app.integrations.urlscan
local result = urlscan.submit({body = "example_body"})

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

MCP-only Lua

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

urlscan.io Integration

Use the urlscan integration to submit URLs to the urlscan.io sandbox, search scan results, retrieve artifacts, and operate urlscan Pro resources such as live scans, saved searches, subscriptions, channels, incidents, and data dumps.

All tools are generated from the official urlscan.io OpenAPI bundle at https://docs.urlscan.io/_bundle/apis/urlscan-openapi.json?download. The API uses the api-key request header, so configure an API key before calling tools.

Common Tools

  • urlscan_submit_scan submits a URL scan. Pass a body object such as { url = "https://example.test", visibility = "unlisted" }.
  • urlscan_search_datasource searches urlscan data. Use q for the Elasticsearch query string and optional datasource, size, search_after, and collapse parameters.
  • urlscan_get_result, urlscan_get_screenshot, and urlscan_get_dom retrieve scan artifacts by scan_id.
  • urlscan_get_quotas checks the authenticated account’s quotas.
  • Pro-oriented tools cover live scanning, saved searches, subscriptions, channels, incidents, malicious observable lookup, brands, hostnames, and data dumps.

Return Shape

JSON responses are returned as decoded arrays/objects from urlscan.io. Binary or text artifact endpoints, such as screenshots, DOM exports, response files, and downloads, return { body, status, content_type } because those endpoints do not always return JSON.

Examples

local submitted = app.integrations.urlscan.submit_scan({
  body = {
    url = "https://example.test",
    visibility = "unlisted",
    tags = { "triage" }
  }
})

local results = app.integrations.urlscan.search_datasource({
  q = "page.domain:example.test",
  datasource = "scans",
  size = 10
})

local quotas = app.integrations.urlscan.get_quotas({})

Use fake domains such as example.test in tests and examples. Some endpoints are only available to urlscan Pro accounts; if a host account lacks access, urlscan.io will return the upstream authorization or plan error.

Raw agent markdown 
# urlscan.io Integration

Use the `urlscan` integration to submit URLs to the urlscan.io sandbox, search scan results, retrieve artifacts, and operate urlscan Pro resources such as live scans, saved searches, subscriptions, channels, incidents, and data dumps.

All tools are generated from the official urlscan.io OpenAPI bundle at `https://docs.urlscan.io/_bundle/apis/urlscan-openapi.json?download`. The API uses the `api-key` request header, so configure an API key before calling tools.

## Common Tools

- `urlscan_submit_scan` submits a URL scan. Pass a `body` object such as `{ url = "https://example.test", visibility = "unlisted" }`.
- `urlscan_search_datasource` searches urlscan data. Use `q` for the Elasticsearch query string and optional `datasource`, `size`, `search_after`, and `collapse` parameters.
- `urlscan_get_result`, `urlscan_get_screenshot`, and `urlscan_get_dom` retrieve scan artifacts by `scan_id`.
- `urlscan_get_quotas` checks the authenticated account's quotas.
- Pro-oriented tools cover live scanning, saved searches, subscriptions, channels, incidents, malicious observable lookup, brands, hostnames, and data dumps.

## Return Shape

JSON responses are returned as decoded arrays/objects from urlscan.io. Binary or text artifact endpoints, such as screenshots, DOM exports, response files, and downloads, return `{ body, status, content_type }` because those endpoints do not always return JSON.

## Examples

```lua
local submitted = app.integrations.urlscan.submit_scan({
  body = {
    url = "https://example.test",
    visibility = "unlisted",
    tags = { "triage" }
  }
})

local results = app.integrations.urlscan.search_datasource({
  q = "page.domain:example.test",
  datasource = "scans",
  size = 10
})

local quotas = app.integrations.urlscan.get_quotas({})
```

Use fake domains such as `example.test` in tests and examples. Some endpoints are only available to urlscan Pro accounts; if a host account lacks access, urlscan.io will return the upstream authorization or plan error.
Metadata-derived Lua example 
local result = app.integrations.urlscan.submit({body = "example_body"})
print(result)

Functions

submit Write

Scan Official urlscan.io endpoint: POST /api/v1/scan.

Lua path
app.integrations.urlscan.submit
Full name
urlscan.urlscan_submit_scan
ParameterTypeRequiredDescription
body object yes JSON request body matching the official urlscan.io OpenAPI schema.
search_datasource Read

Search Official urlscan.io endpoint: GET /api/v1/search.

Lua path
app.integrations.urlscan.search_datasource
Full name
urlscan.urlscan_search_datasource
ParameterTypeRequiredDescription
q string no Search Query (Elasticsearch Query String)
size number no Number of results to return
search_after string no For retrieving the next batch of results, send the value of the `sort` attribute of the last (oldest) result you received (comma-separated) from the previous call.
datasource string no Datasources to search: scans (urlscan.io), hostnames, incidents, notifications, certificates (urlscan Pro)
collapse string no Field to collapse results on. Only works on current page of results.
get_result Read

Result Official urlscan.io endpoint: GET /api/v1/result/{scanId}/.

Lua path
app.integrations.urlscan.get_result
Full name
urlscan.urlscan_get_result
ParameterTypeRequiredDescription
scan_id string yes UUID of scan result
get_screenshot Read

Screenshot Official urlscan.io endpoint: GET /screenshots/{scanId}.png.

Lua path
app.integrations.urlscan.get_screenshot
Full name
urlscan.urlscan_get_screenshot
ParameterTypeRequiredDescription
scan_id string yes UUID of scan result
get_dom Read

DOM Official urlscan.io endpoint: GET /dom/{scanId}/.

Lua path
app.integrations.urlscan.get_dom
Full name
urlscan.urlscan_get_dom
ParameterTypeRequiredDescription
scan_id string yes UUID of scan result
get_response Read

Response Official urlscan.io endpoint: GET /responses/{fileHash}/.

Lua path
app.integrations.urlscan.get_response
Full name
urlscan.urlscan_get_response
ParameterTypeRequiredDescription
file_hash string yes SHA256 hash of response
update_result_visibility Write

Update Result Visibility Official urlscan.io endpoint: PUT /api/v1/result/{scanId}/visibility/.

Lua path
app.integrations.urlscan.update_result_visibility
Full name
urlscan.urlscan_update_result_visibility
ParameterTypeRequiredDescription
scan_id string yes UUID of scan result
body object yes JSON request body matching the official urlscan.io OpenAPI schema.
delete_result_visibility Write

Reset to original visibility Official urlscan.io endpoint: DELETE /api/v1/result/{scanId}/visibility/.

Lua path
app.integrations.urlscan.delete_result_visibility
Full name
urlscan.urlscan_delete_result_visibility
ParameterTypeRequiredDescription
scan_id string yes UUID of scan result
get_available_countries Read

Available Countries Official urlscan.io endpoint: GET /api/v1/availableCountries.

Lua path
app.integrations.urlscan.get_available_countries
Full name
urlscan.urlscan_get_available_countries
ParameterTypeRequiredDescription
No parameters.
get_user_agents Read

Available User Agents Official urlscan.io endpoint: GET /api/v1/userAgents.

Lua path
app.integrations.urlscan.get_user_agents
Full name
urlscan.urlscan_get_user_agents
ParameterTypeRequiredDescription
No parameters.
get_quotas Read

API Quotas Official urlscan.io endpoint: GET /api/v1/quotas.

Lua path
app.integrations.urlscan.get_quotas
Full name
urlscan.urlscan_get_quotas
ParameterTypeRequiredDescription
No parameters.
get_available_brands Read

Available Brands Official urlscan.io endpoint: GET /api/v1/pro/availableBrands.

Lua path
app.integrations.urlscan.get_available_brands
Full name
urlscan.urlscan_get_available_brands
ParameterTypeRequiredDescription
No parameters.
get_brand_summary Read

Brands Official urlscan.io endpoint: GET /api/v1/pro/brands.

Lua path
app.integrations.urlscan.get_brand_summary
Full name
urlscan.urlscan_get_brand_summary
ParameterTypeRequiredDescription
No parameters.
get_phishfeed Read

Phishfeed Official urlscan.io endpoint: GET /api/v1/pro/phishfeed.

Lua path
app.integrations.urlscan.get_phishfeed
Full name
urlscan.urlscan_get_phishfeed
ParameterTypeRequiredDescription
q string no q
limit number no How many results to return
format string no Can be one of csv, tsv, or json
get_livescan_scanners Read

Live Scanners Official urlscan.io endpoint: GET /api/v1/livescan/scanners/.

Lua path
app.integrations.urlscan.get_livescan_scanners
Full name
urlscan.urlscan_get_livescan_scanners
ParameterTypeRequiredDescription
No parameters.
create_livescan_task Write

Non-Blocking Trigger Live Scan Official urlscan.io endpoint: POST /api/v1/livescan/{scannerId}/task/.

Lua path
app.integrations.urlscan.create_livescan_task
Full name
urlscan.urlscan_create_livescan_task
ParameterTypeRequiredDescription
scanner_id string yes scannerId
body object no JSON request body matching the official urlscan.io OpenAPI schema.
create_livescan Write

Trigger Live Scan Official urlscan.io endpoint: POST /api/v1/livescan/{scannerId}/scan/.

Lua path
app.integrations.urlscan.create_livescan
Full name
urlscan.urlscan_create_livescan_scan
ParameterTypeRequiredDescription
scanner_id string yes scannerId
body object no JSON request body matching the official urlscan.io OpenAPI schema.
get_livescan_resource Read

Live Scan Get Resource Official urlscan.io endpoint: GET /api/v1/livescan/{scannerId}/{resourceType}/{resourceId}.

Lua path
app.integrations.urlscan.get_livescan_resource
Full name
urlscan.urlscan_get_livescan_resource
ParameterTypeRequiredDescription
scanner_id string yes scannerId
resource_type string yes resourceType
resource_id string yes * For result, screenshot, dom: UUID of the scan * For response, download: The SHA256 of the resource
store_livescan_result Read

Store Live Scan Result Official urlscan.io endpoint: PUT /api/v1/livescan/{scannerId}/{scanId}/.

Lua path
app.integrations.urlscan.store_livescan_result
Full name
urlscan.urlscan_store_livescan_result
ParameterTypeRequiredDescription
scanner_id string yes scannerId
scan_id string yes scanId
body object no JSON request body matching the official urlscan.io OpenAPI schema.
discard_livescan_result Read

Purge Live Scan Result Official urlscan.io endpoint: DELETE /api/v1/livescan/{scannerId}/{scanId}/.

Lua path
app.integrations.urlscan.discard_livescan_result
Full name
urlscan.urlscan_discard_livescan_result
ParameterTypeRequiredDescription
scanner_id string yes scannerId
scan_id string yes scanId
get_hostname_history Read

Hostname History Official urlscan.io endpoint: GET /api/v1/hostname/{hostname}.

Lua path
app.integrations.urlscan.get_hostname_history
Full name
urlscan.urlscan_get_hostname_history
ParameterTypeRequiredDescription
hostname string yes The hostname to query
limit number no Return at most this many results. Minimum 10 Maximum 10000 Default 1000
page_state string no Returns additional results starting from this page state from the previous API call.
get_pro_username Read

User Information Official urlscan.io endpoint: GET /api/v1/pro/username.

Lua path
app.integrations.urlscan.get_pro_username
Full name
urlscan.urlscan_get_pro_username
ParameterTypeRequiredDescription
No parameters.
get_similar_results Read

Structure Search Official urlscan.io endpoint: GET /api/v1/pro/result/{scanId}/similar/.

Lua path
app.integrations.urlscan.get_similar_results
Full name
urlscan.urlscan_get_similar_results
ParameterTypeRequiredDescription
q string no Additional query filter
size number no Maximum results per call
search_after string no Parameter to iterate over older results
scan_id string yes The original scan to compare to
list_saved_searches Read

Saved Searches Official urlscan.io endpoint: GET /api/v1/user/searches/.

Lua path
app.integrations.urlscan.list_saved_searches
Full name
urlscan.urlscan_list_saved_searches
ParameterTypeRequiredDescription
No parameters.
get_saved_search_results Read

Saved Search Search Results Official urlscan.io endpoint: GET /api/v1/user/searches/{searchId}/results/.

Lua path
app.integrations.urlscan.get_saved_search_results
Full name
urlscan.urlscan_get_saved_search_results
ParameterTypeRequiredDescription
search_id string yes searchId
list_subscriptions Read

Subscriptions Official urlscan.io endpoint: GET /api/v1/user/subscriptions/.

Lua path
app.integrations.urlscan.list_subscriptions
Full name
urlscan.urlscan_list_subscriptions
ParameterTypeRequiredDescription
No parameters.
create_subscription Write

Create Subscription Official urlscan.io endpoint: POST /api/v1/user/subscriptions/.

Lua path
app.integrations.urlscan.create_subscription
Full name
urlscan.urlscan_create_subscription
ParameterTypeRequiredDescription
body object no JSON request body matching the official urlscan.io OpenAPI schema.
update_subscription Write

Update Subscription Official urlscan.io endpoint: PUT /api/v1/user/subscriptions/{subscriptionId}/.

Lua path
app.integrations.urlscan.update_subscription
Full name
urlscan.urlscan_update_subscription
ParameterTypeRequiredDescription
subscription_id string yes subscriptionId
body object no JSON request body matching the official urlscan.io OpenAPI schema.
delete_subscription Write

Delete Subscription Official urlscan.io endpoint: DELETE /api/v1/user/subscriptions/{subscriptionId}/.

Lua path
app.integrations.urlscan.delete_subscription
Full name
urlscan.urlscan_delete_subscription
ParameterTypeRequiredDescription
subscription_id string yes subscriptionId
get_subscription_results Read

Subscription Search Results Official urlscan.io endpoint: GET /api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/.

Lua path
app.integrations.urlscan.get_subscription_results
Full name
urlscan.urlscan_get_subscription_results
ParameterTypeRequiredDescription
subscription_id string yes subscriptionId
datasource string yes datasource
list_channels Read

Channels Official urlscan.io endpoint: GET /api/v1/user/channels/.

Lua path
app.integrations.urlscan.list_channels
Full name
urlscan.urlscan_list_channels
ParameterTypeRequiredDescription
No parameters.
create_channel Write

Create Channel Official urlscan.io endpoint: POST /api/v1/user/channels/.

Lua path
app.integrations.urlscan.create_channel
Full name
urlscan.urlscan_create_channel
ParameterTypeRequiredDescription
body object no JSON request body matching the official urlscan.io OpenAPI schema.
get_channel Read

Channel Search Results Official urlscan.io endpoint: GET /api/v1/user/channels/{channelId}.

Lua path
app.integrations.urlscan.get_channel
Full name
urlscan.urlscan_get_channel
ParameterTypeRequiredDescription
channel_id string yes channelId
update_channel Write

Update Channel Official urlscan.io endpoint: PUT /api/v1/user/channels/{channelId}.

Lua path
app.integrations.urlscan.update_channel
Full name
urlscan.urlscan_update_channel
ParameterTypeRequiredDescription
channel_id string yes channelId
body object no JSON request body matching the official urlscan.io OpenAPI schema.
create_incident Write

Create Incident Official urlscan.io endpoint: POST /api/v1/user/incidents.

Lua path
app.integrations.urlscan.create_incident
Full name
urlscan.urlscan_create_incident
ParameterTypeRequiredDescription
body object no JSON request body matching the official urlscan.io OpenAPI schema.
get_incident Read

Get Incident Official urlscan.io endpoint: GET /api/v1/user/incidents/{incidentId}.

Lua path
app.integrations.urlscan.get_incident
Full name
urlscan.urlscan_get_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
update_incident Write

Update Incident options Official urlscan.io endpoint: PUT /api/v1/user/incidents/{incidentId}.

Lua path
app.integrations.urlscan.update_incident
Full name
urlscan.urlscan_update_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
body object no JSON request body matching the official urlscan.io OpenAPI schema.
close_incident Read

Close Incident Official urlscan.io endpoint: PUT /api/v1/user/incidents/{incidentId}/close.

Lua path
app.integrations.urlscan.close_incident
Full name
urlscan.urlscan_close_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
body object no JSON request body matching the official urlscan.io OpenAPI schema.
restart_incident Read

Restart Incident Official urlscan.io endpoint: PUT /api/v1/user/incidents/{incidentId}/restart.

Lua path
app.integrations.urlscan.restart_incident
Full name
urlscan.urlscan_restart_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
body object no JSON request body matching the official urlscan.io OpenAPI schema.
copy_incident Read

Copy Incident Official urlscan.io endpoint: POST /api/v1/user/incidents/{incidentId}/copy.

Lua path
app.integrations.urlscan.copy_incident
Full name
urlscan.urlscan_copy_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
body object no JSON request body matching the official urlscan.io OpenAPI schema.
fork_incident Read

Fork Incident Official urlscan.io endpoint: POST /api/v1/user/incidents/{incidentId}/fork.

Lua path
app.integrations.urlscan.fork_incident
Full name
urlscan.urlscan_fork_incident
ParameterTypeRequiredDescription
incident_id string yes ID of incident
body object no JSON request body matching the official urlscan.io OpenAPI schema.
get_watchable_attributes Read

Get Watchable Attributes Official urlscan.io endpoint: GET /api/v1/user/watchableAttributes.

Lua path
app.integrations.urlscan.get_watchable_attributes
Full name
urlscan.urlscan_get_watchable_attributes
ParameterTypeRequiredDescription
No parameters.
get_incident_states Read

Get Incident States Official urlscan.io endpoint: GET /api/v1/user/incidentstates/{incidentId}/.

Lua path
app.integrations.urlscan.get_incident_states
Full name
urlscan.urlscan_get_incident_states
ParameterTypeRequiredDescription
incident_id string yes ID of incident
list_datadumps Read

List Data Dump Files Official urlscan.io endpoint: GET /api/v1/datadump/list/{timeWindow}/{fileType}/{date}.

Lua path
app.integrations.urlscan.list_datadumps
Full name
urlscan.urlscan_list_datadumps
ParameterTypeRequiredDescription
time_window string yes Time window of the data dump
file_type string yes Type of data dump file
date string yes Date of the data dump in YYYYMMDD format
download_file Read

Download a file Official urlscan.io endpoint: GET /downloads/{fileHash}.

Lua path
app.integrations.urlscan.download_file
Full name
urlscan.urlscan_download_file
ParameterTypeRequiredDescription
file_hash string yes SHA256 hash of file
password string no The password to use to encrypt the ZIP file. Using a password is mandatory, the default password is urlscan!
filename string no Specify the name of the ZIP file that should be downloaded. This does not change the name of files within the ZIP archive. The default filename is $fileHash.zip
lookup_malicious_observable Read

Malicious observable lookup Official urlscan.io endpoint: GET /api/v1/malicious/{type}/{value}.

Lua path
app.integrations.urlscan.lookup_malicious_observable
Full name
urlscan.urlscan_lookup_malicious_observable
ParameterTypeRequiredDescription
type string yes The type of observable to look up.
value string yes The observable value. Format depends on `type`: - `ip`: an IP address (e.g. `192.0.2.1`) - `hostname`: a fully qualified hostname (e.g. `www.example.com`) - `domain`: an apex/registered domain (e.g. `example.com`) - `url`: a URL-encoded URL (e.g. `https%3A%2F%