Listaro API reference
Use a scoped API key in the Authorization header. Each resource belongs to one workspace. Inspect result completeness and evidence, and retain request keys after uncertain outcomes.
The account and API gateway are deployed. Capture execution requires the separately configured engine. An unavailable engine returns an explicit error and no captured data.
list_extraction_presets
List the six source-observed extraction presets and their field schemas.
POST https://listaro.vercel.app/api/v1/operations/list_extraction_presetsRequired key scope: list_extraction_presets. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}crawl_site
Queue an exact-origin durable crawl with bounded budgets, robots policies, recovery and source evidence.
POST https://listaro.vercel.app/api/v1/operations/crawl_siteRequired key scope: crawl_site. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"seedUrl": "https://example.org",
"maxPages": 5,
"maxDepth": 1,
"renderMode": "never",
"useSitemaps": true
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sync": {
"type": "object",
"properties": {
"baselineCrawlId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"mode": {
"default": "full",
"type": "string",
"enum": [
"full",
"incremental"
]
},
"emitUnchanged": {
"default": false,
"type": "boolean"
}
},
"additionalProperties": false
},
"dataset": {
"type": "object",
"properties": {
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"recordSelector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"primaryKeyFields": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
}
},
"onInvalid": {
"default": "retain_with_errors",
"type": "string",
"enum": [
"retain_with_errors",
"reject_record"
]
},
"dedupe": {
"default": "none",
"type": "string",
"enum": [
"none",
"primary_key"
]
}
},
"additionalProperties": false
},
"rag": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"chunkStrategy": {
"default": "section",
"type": "string",
"enum": [
"section",
"fixed"
]
},
"maxTokensPerChunk": {
"default": 512,
"type": "integer",
"minimum": 16,
"maximum": 8192
},
"overlapTokens": {
"default": 32,
"type": "integer",
"minimum": 0,
"maximum": 1024
},
"includeBoilerplate": {
"default": false,
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"seedUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"maxPages": {
"default": 5,
"type": "integer",
"minimum": 1,
"maximum": 30000
},
"maxDepth": {
"default": 1,
"type": "integer",
"minimum": 0,
"maximum": 20
},
"maxBytesPerPage": {
"default": 1000000,
"type": "integer",
"minimum": 1024,
"maximum": 5000000
},
"timeoutMs": {
"type": "integer",
"minimum": 500,
"maximum": 30000
},
"renderMode": {
"default": "never",
"type": "string",
"enum": [
"never",
"auto",
"always",
"guarded"
]
},
"preset": {
"type": "string",
"enum": [
"general",
"product",
"business",
"article",
"event",
"job"
]
},
"useSitemaps": {
"default": false,
"type": "boolean"
},
"fieldSpecs": {
"default": [],
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
},
"includePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"excludePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"crawlDelayMs": {
"type": "integer",
"minimum": 0,
"maximum": 60000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1000,
"maximum": 3600000
},
"maxTotalBytes": {
"type": "integer",
"minimum": 1024,
"maximum": 2000000000
},
"maxConcurrency": {
"type": "integer",
"minimum": 1,
"maximum": 16
},
"maxSitemapDocuments": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"seedUrl"
],
"additionalProperties": false
}get_job
Get durable lifecycle, attempts, cancellation, progress counts and result references.
POST https://listaro.vercel.app/api/v1/operations/get_jobRequired key scope: get_job. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"jobId": "11111111-1111-4111-8111-111111111111"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"jobId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"includeRecentEvents": {
"type": "boolean"
},
"eventCursor": {
"type": "string",
"maxLength": 1024
},
"eventLimit": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
},
"batchCursor": {
"type": "string",
"maxLength": 1024
},
"batchLimit": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 50
}
},
"required": [
"jobId"
],
"additionalProperties": false
}get_crawl
Read source-backed crawl pages with stable cursor pagination and verified artifacts.
POST https://listaro.vercel.app/api/v1/operations/get_crawlRequired key scope: get_crawl. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"crawlId": "11111111-1111-4111-8111-111111111111",
"limit": 20
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"crawlId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"changeFilter": {
"minItems": 1,
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"added",
"updated",
"unchanged",
"unavailable",
"excluded",
"unknown",
"deleted_confirmed"
]
}
},
"limit": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"maxLength": 1024
}
},
"required": [
"crawlId"
],
"additionalProperties": false
}create_watch
Save a watch definition with automatic scheduling OFF.
POST https://listaro.vercel.app/api/v1/operations/create_watchRequired key scope: create_watch. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"seedUrl": "https://example.org",
"maxPages": 5,
"maxDepth": 1,
"renderMode": "never",
"useSitemaps": true,
"intervalMinutes": 1440
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sync": {
"type": "object",
"properties": {
"mode": {
"default": "full",
"type": "string",
"enum": [
"full",
"incremental"
]
},
"baselineCrawlId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"emitUnchanged": {
"default": false,
"type": "boolean"
}
},
"additionalProperties": false
},
"dataset": {
"type": "object",
"properties": {
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"recordSelector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"primaryKeyFields": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
}
},
"onInvalid": {
"default": "retain_with_errors",
"type": "string",
"enum": [
"retain_with_errors",
"reject_record"
]
},
"dedupe": {
"default": "none",
"type": "string",
"enum": [
"none",
"primary_key"
]
}
},
"additionalProperties": false
},
"rag": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"chunkStrategy": {
"default": "section",
"type": "string",
"enum": [
"section",
"fixed"
]
},
"maxTokensPerChunk": {
"default": 512,
"type": "integer",
"minimum": 16,
"maximum": 8192
},
"overlapTokens": {
"default": 32,
"type": "integer",
"minimum": 0,
"maximum": 1024
},
"includeBoilerplate": {
"default": false,
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"seedUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"maxPages": {
"default": 5,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"maxDepth": {
"default": 1,
"type": "integer",
"minimum": 0,
"maximum": 20
},
"maxBytesPerPage": {
"default": 1000000,
"type": "integer",
"minimum": 1024,
"maximum": 5000000
},
"timeoutMs": {
"type": "integer",
"minimum": 500,
"maximum": 30000
},
"renderMode": {
"default": "never",
"type": "string",
"enum": [
"never",
"auto",
"always",
"guarded"
]
},
"preset": {
"type": "string",
"enum": [
"general",
"product",
"business",
"article",
"event",
"job"
]
},
"useSitemaps": {
"default": false,
"type": "boolean"
},
"fieldSpecs": {
"default": [],
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
},
"includePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"excludePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"crawlDelayMs": {
"type": "integer",
"minimum": 0,
"maximum": 60000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1000,
"maximum": 3600000
},
"maxTotalBytes": {
"type": "integer",
"minimum": 1024,
"maximum": 2000000000
},
"maxConcurrency": {
"type": "integer",
"minimum": 1,
"maximum": 16
},
"maxSitemapDocuments": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"label": {
"type": "string",
"maxLength": 120
},
"intervalMinutes": {
"default": 360,
"type": "integer",
"minimum": 60,
"maximum": 10080
}
},
"required": [
"seedUrl"
],
"additionalProperties": false
}check_watch
Coalesce and queue a manual baseline or change check.
POST https://listaro.vercel.app/api/v1/operations/check_watchRequired key scope: check_watch. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"watchId": "11111111-1111-4111-8111-111111111111"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"watchId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"watchId"
],
"additionalProperties": false
}set_watch_schedule
Explicitly enable or disable a persisted watch schedule.
POST https://listaro.vercel.app/api/v1/operations/set_watch_scheduleRequired key scope: set_watch_schedule. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"watchId": "11111111-1111-4111-8111-111111111111",
"enabled": false,
"intervalMinutes": 1440
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"watchId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"enabled": {
"type": "boolean"
},
"intervalMinutes": {
"type": "integer",
"minimum": 60,
"maximum": 10080
}
},
"required": [
"watchId",
"enabled"
],
"additionalProperties": false
}list_watches
List saved watches with bounded pagination.
POST https://listaro.vercel.app/api/v1/operations/list_watchesRequired key scope: list_watches. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"limit": 20
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"maxLength": 1024
}
},
"additionalProperties": false
}compare_crawls
Compare all observed pages from same-origin snapshots; missing observations never assert deletion.
POST https://listaro.vercel.app/api/v1/operations/compare_crawlsRequired key scope: compare_crawls. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"beforeRunId": "11111111-1111-4111-8111-111111111111",
"afterRunId": "22222222-2222-4222-8222-222222222222"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"beforeRunId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"afterRunId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"beforeRunId",
"afterRunId"
],
"additionalProperties": false
}get_change_report
Read a saved source-backed watch comparison with pagination.
POST https://listaro.vercel.app/api/v1/operations/get_change_reportRequired key scope: get_change_report. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"reportId": "11111111-1111-4111-8111-111111111111",
"limit": 20
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"reportId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"changeFilter": {
"minItems": 1,
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"added",
"updated",
"unchanged",
"unavailable",
"excluded",
"unknown",
"deleted_confirmed"
]
}
},
"limit": {
"default": 40,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"maxLength": 1024
}
},
"required": [
"reportId"
],
"additionalProperties": false
}scrape_page
Acquire a page once and return Markdown, HTML, JSON, links, metadata, images or screenshot artifacts.
POST https://listaro.vercel.app/api/v1/operations/scrape_pageRequired key scope: scrape_page. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"url": "https://example.org",
"formats": [
"markdown",
"metadata",
"images"
],
"renderMode": "never"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"dataset": {
"type": "object",
"properties": {
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"recordSelector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"primaryKeyFields": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
}
},
"onInvalid": {
"default": "retain_with_errors",
"type": "string",
"enum": [
"retain_with_errors",
"reject_record"
]
},
"dedupe": {
"default": "none",
"type": "string",
"enum": [
"none",
"primary_key"
]
}
},
"additionalProperties": false
},
"rag": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"chunkStrategy": {
"default": "section",
"type": "string",
"enum": [
"section",
"fixed"
]
},
"maxTokensPerChunk": {
"default": 512,
"type": "integer",
"minimum": 16,
"maximum": 8192
},
"overlapTokens": {
"default": 32,
"type": "integer",
"minimum": 0,
"maximum": 1024
},
"includeBoilerplate": {
"default": false,
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"formats": {
"default": [
"markdown",
"metadata"
],
"minItems": 1,
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"enum": [
"markdown",
"html",
"rawHtml",
"json",
"links",
"metadata",
"images",
"screenshot"
]
}
},
"renderMode": {
"default": "auto",
"type": "string",
"enum": [
"never",
"auto",
"always"
]
},
"waitFor": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"timeoutMs": {
"type": "integer",
"minimum": 1,
"maximum": 10000
}
},
"additionalProperties": false
},
"extract": {
"type": "object",
"properties": {
"fields": {
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
},
"preset": {
"type": "string",
"enum": [
"general",
"product",
"business",
"article",
"event",
"job"
]
},
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"records": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"fields": {
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
}
},
"required": [
"selector",
"fields"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"timeoutMs": {
"type": "integer",
"minimum": 500,
"maximum": 30000
},
"maxBytes": {
"type": "integer",
"minimum": 1024,
"maximum": 5000000
}
},
"required": [
"url"
],
"additionalProperties": false
}map_site
Discover exact-scope URLs from sitemaps and a bounded link sample; discovered URLs are not verified page fetches.
POST https://listaro.vercel.app/api/v1/operations/map_siteRequired key scope: map_site. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"url": "https://example.org",
"maxUrls": 20,
"maxDepth": 2,
"useSitemaps": true
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"maxUrls": {
"default": 1000,
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"maxSitemapDocuments": {
"default": 100,
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"maxDepth": {
"default": 2,
"type": "integer",
"minimum": 0,
"maximum": 20
},
"includeSubdomains": {
"default": false,
"type": "boolean"
},
"includePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"excludePatterns": {
"maxItems": 40,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"useSitemaps": {
"default": true,
"type": "boolean"
}
},
"required": [
"url"
],
"additionalProperties": false
}scrape_batch
Queue 1–1000 input-order page results with isolated failures, retries and cancellation.
POST https://listaro.vercel.app/api/v1/operations/scrape_batchRequired key scope: scrape_batch. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"urls": [
"https://example.org"
],
"formats": [
"markdown",
"metadata"
],
"renderMode": "never",
"maxConcurrency": 2
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"dataset": {
"type": "object",
"properties": {
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"recordSelector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"primaryKeyFields": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
}
},
"onInvalid": {
"default": "retain_with_errors",
"type": "string",
"enum": [
"retain_with_errors",
"reject_record"
]
},
"dedupe": {
"default": "none",
"type": "string",
"enum": [
"none",
"primary_key"
]
}
},
"additionalProperties": false
},
"rag": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"chunkStrategy": {
"default": "section",
"type": "string",
"enum": [
"section",
"fixed"
]
},
"maxTokensPerChunk": {
"default": 512,
"type": "integer",
"minimum": 16,
"maximum": 8192
},
"overlapTokens": {
"default": 32,
"type": "integer",
"minimum": 0,
"maximum": 1024
},
"includeBoilerplate": {
"default": false,
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"urls": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"maxLength": 2048,
"format": "uri"
}
},
"formats": {
"default": [
"markdown",
"metadata"
],
"minItems": 1,
"maxItems": 8,
"type": "array",
"items": {
"type": "string",
"enum": [
"markdown",
"html",
"rawHtml",
"json",
"links",
"metadata",
"images",
"screenshot"
]
}
},
"renderMode": {
"default": "auto",
"type": "string",
"enum": [
"never",
"auto",
"always"
]
},
"extract": {
"type": "object",
"properties": {
"fields": {
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
},
"preset": {
"type": "string",
"enum": [
"general",
"product",
"business",
"article",
"event",
"job"
]
},
"schema": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"records": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"fields": {
"maxItems": 40,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,63}$"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"attribute": {
"type": "string",
"pattern": "^[a-z][a-z0-9:_-]{0,63}$"
},
"multiple": {
"type": "boolean"
}
},
"required": [
"name",
"selector"
],
"additionalProperties": false
}
}
},
"required": [
"selector",
"fields"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"maxConcurrency": {
"default": 4,
"type": "integer",
"minimum": 1,
"maximum": 16
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"urls"
],
"additionalProperties": false
}get_artifact
Read a checksum-verified workspace artifact with bounded UTF-8 or base64 ranges.
POST https://listaro.vercel.app/api/v1/operations/get_artifactRequired key scope: get_artifact. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"artifactId": "a_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"offset": 0,
"limitBytes": 32768
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"pattern": "^a_[0-9a-f]{64}$"
},
"offset": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limitBytes": {
"default": 32768,
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"encoding": {
"type": "string",
"enum": [
"utf8",
"base64"
]
}
},
"required": [
"artifactId"
],
"additionalProperties": false
}cancel_job
Idempotently cancel a queued or running workspace job while preserving completed evidence.
POST https://listaro.vercel.app/api/v1/operations/cancel_jobRequired key scope: cancel_job. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"jobId": "11111111-1111-4111-8111-111111111111"
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"jobId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"reason": {
"type": "string",
"maxLength": 500
}
},
"required": [
"jobId"
],
"additionalProperties": false
}parse_document
Parse PDF, DOCX, XLSX, HTML or TXT with source evidence, page/sheet metadata and resource limits.
POST https://listaro.vercel.app/api/v1/operations/parse_documentRequired key scope: parse_document. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"url": "https://example.org/example.pdf",
"formats": [
"markdown",
"text"
],
"maxBytes": 1000000
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"rag": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"chunkStrategy": {
"default": "section",
"type": "string",
"enum": [
"section",
"fixed"
]
},
"maxTokensPerChunk": {
"default": 512,
"type": "integer",
"minimum": 16,
"maximum": 8192
},
"overlapTokens": {
"default": 32,
"type": "integer",
"minimum": 0,
"maximum": 1024
},
"includeBoilerplate": {
"default": false,
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
},
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"artifactId": {
"type": "string",
"pattern": "^a_[0-9a-f]{64}$"
},
"formats": {
"default": [
"text",
"markdown"
],
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"text",
"markdown",
"json",
"tables"
]
}
},
"maxBytes": {
"default": 10000000,
"type": "integer",
"minimum": 1,
"maximum": 20000000
}
},
"additionalProperties": false
}browser_session
Create, inspect or close an ephemeral browser context with TTL and resource limits.
POST https://listaro.vercel.app/api/v1/operations/browser_sessionRequired key scope: browser_session. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"action": "create",
"initialUrl": "https://example.org",
"ttlSeconds": 120
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"action": {
"type": "string",
"enum": [
"create",
"get",
"close"
]
},
"sessionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"initialUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"ttlSeconds": {
"default": 120,
"type": "integer",
"minimum": 1,
"maximum": 600
}
},
"required": [
"action"
],
"additionalProperties": false
}browser_action
Navigate, click, fill, scroll, wait, snapshot or screenshot in an authorized guarded browser session.
POST https://listaro.vercel.app/api/v1/operations/browser_actionRequired key scope: browser_action. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"sessionId": "11111111-1111-4111-8111-111111111111",
"action": "snapshot",
"timeoutMs": 3000
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"sessionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"action": {
"type": "string",
"enum": [
"navigate",
"click",
"fill",
"scroll",
"wait_for",
"snapshot",
"screenshot"
]
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"text": {
"type": "string",
"maxLength": 4000
},
"direction": {
"type": "string",
"enum": [
"up",
"down"
]
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"timeoutMs": {
"default": 3000,
"type": "integer",
"minimum": 1,
"maximum": 10000
}
},
"required": [
"sessionId",
"action"
],
"additionalProperties": false
}search_web
Discover ranked public-web URLs through private, keyless metasearch by default. Results are discovered, not fetched or independently verified; optional legacy providers have different coverage.
POST https://listaro.vercel.app/api/v1/operations/search_webRequired key scope: search_web. Supply Content-Type: application/json. Execution calls use an Idempotency-Key header.
Example body
{
"query": "Open-source crawling tools",
"limit": 5
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"maxPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxRequests": {
"type": "integer",
"minimum": 0,
"maximum": 200000
},
"maxFetchedBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxRenderedPages": {
"type": "integer",
"minimum": 0,
"maximum": 30000
},
"maxDurationMs": {
"type": "integer",
"minimum": 1,
"maximum": 3600000
},
"maxArtifactsBytes": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"maxProviderUnits": {
"type": "integer",
"minimum": 0,
"maximum": 1000
}
},
"additionalProperties": false
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"limit": {
"default": 5,
"type": "integer",
"minimum": 1,
"maximum": 10
},
"provider": {
"type": "string",
"maxLength": 40
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}(-[A-Z]{2})?$"
},
"region": {
"type": "string",
"pattern": "^[a-zA-Z]{2}$"
}
},
"required": [
"query"
],
"additionalProperties": false
}