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_presets

Required 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_site

Required 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_job

Required 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_crawl

Required 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_watch

Required 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_watch

Required 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_schedule

Required 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_watches

Required 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_crawls

Required 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_report

Required 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_page

Required 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_site

Required 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_batch

Required 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_artifact

Required 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_job

Required 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_document

Required 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_session

Required 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_action

Required 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_web

Required 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
}