API Changelog

March 2026 — Router Restructuring & Agent Scrapers

This release restructures the Parsera API into three typed sub-routers and introduces AI-powered agentic scrapers alongside classic code-based scrapers.

New API Structure

The API is now organized into three sub-routers:

Router	Prefix	Purpose
Extractor	`/v1/extractor/`	One-shot extraction (extract, parse, markdown) + classic scraper management
Agent	`/v1/agent/`	AI-powered extraction: one-shot and reusable agentic scrapers
Scrapers	`/v1/scrapers/`	Unified execution: list all scrapers, run sync/async, poll results

New Endpoints

Agent API (`/v1/agent/`)

Method	Path	Description
`POST`	`/v1/agent/extract`	Start a one-shot AI agent extraction (returns 202)
`GET`	`/v1/agent/extract/{task_id}`	Poll one-shot extraction status and results
`POST`	`/v1/agent/new`	Create a new empty agentic scraper
`POST`	`/v1/agent/generate`	Build an agentic scraper from URL + prompt (returns 202)
`GET`	`/v1/agent/{scraper_id}`	Get agentic scraper details and build status
`DELETE`	`/v1/agent/{scraper_id}`	Delete an agentic scraper

Extractor API (`/v1/extractor/`)

Method	Path	Description
`POST`	`/v1/extractor/extract`	Extract structured data from a URL
`POST`	`/v1/extractor/parse`	Parse provided HTML/text content
`POST`	`/v1/extractor/extract_markdown`	Convert a URL to markdown
`POST`	`/v1/extractor/new`	Create a new empty classic scraper
`POST`	`/v1/extractor/generate`	Generate classic scraper code (returns 202)
`GET`	`/v1/extractor/{scraper_id}`	Get classic scraper details and code gen status
`DELETE`	`/v1/extractor/{scraper_id}`	Delete a classic scraper

Scrapers Execution (`/v1/scrapers/`)

Method	Path	Description
`GET`	`/v1/scrapers`	List all scrapers (classic + agentic)
`POST`	`/v1/scrapers/run`	Run any scraper synchronously
`POST`	`/v1/scrapers/run_async`	Run any scraper asynchronously (returns 202)
`GET`	`/v1/scrapers/run_async/{run_id}`	Poll async run status and results

Changed Endpoints

Old Path	New Path	What Changed
`POST /v1/extract`	`POST /v1/extractor/extract`	New canonical path (old still works)
`POST /v1/parse`	`POST /v1/extractor/parse`	New canonical path (old still works)
`POST /v1/extract_markdown`	`POST /v1/extractor/extract_markdown`	New canonical path (old still works)
`GET /v1/scrapers`	`GET /v1/scrapers`	Response now includes `type`, `status`, `url`, `created_at` fields
`POST /v1/scrapers/run`	`POST /v1/scrapers/run`	Now accepts `template_id` (+ `scraper_id` alias). Handles both classic and agentic scrapers
`POST /v1/scrapers/generate`	`POST /v1/extractor/generate`	Now returns 202 with `{ template_id, status }` instead of synchronous `{ message }`
`POST /v1/scrapers/new`	`POST /v1/extractor/new` or `POST /v1/agent/new`	Split by scraper type
`DELETE /v1/scrapers/{id}`	`DELETE /v1/extractor/{id}` or `DELETE /v1/agent/{id}`	Split by scraper type

Deprecated Endpoints

The following endpoints still work but return a _warning field and are hidden from Swagger. They will be removed in a future version.

Deprecated Path	Replacement
`POST /v1/scrapers/new`	`POST /v1/extractor/new` or `POST /v1/agent/new`
`POST /v1/scrapers/generate`	`POST /v1/extractor/generate` or `POST /v1/agent/generate`
`GET /v1/scrapers/{scraper_id}`	`GET /v1/extractor/{id}` or `GET /v1/agent/{id}`
`GET /v1/scrapers/{scraper_id}/runs/{run_id}`	`GET /v1/scrapers/run_async/{run_id}`
`DELETE /v1/scrapers/{scraper_id}`	`DELETE /v1/extractor/{id}` or `DELETE /v1/agent/{id}`

New Concepts

Scraper Types

Scrapers now have two types:

Extractor (type: "extractor") — Classic code-based scrapers. Fast, deterministic, cost-effective. Generated Python code extracts structured data using CSS/XPath selectors.
Agentic (type: "agentic") — AI-powered scrapers. An AI agent browses the website, navigates pages, and extracts structured data. Ideal for complex sites that require interaction.

Asynchronous Execution

A new async execution pattern is available for both scraper types:

Dispatch: POST /v1/scrapers/run_async returns immediately with { run_id, status: "queued" }
Poll: GET /v1/scrapers/run_async/{run_id} returns progress and results
Callback (optional): provide callback_url to receive results via POST when complete

Run statuses: running → completed | completed_partial | failed

One-Shot Agent Extraction

Extract data using an AI agent without creating a reusable scraper:

Start: POST /v1/agent/extract with url and prompt → returns { task_id, status: "pending" }
Poll: GET /v1/agent/extract/{task_id} → returns status and data when complete
Callback (optional): provide callback_url for async delivery

Async Code Generation

Scraper code generation (/v1/extractor/generate and /v1/agent/generate) now returns 202 Accepted with { template_id, status: "generating" } instead of blocking until complete. Poll the scraper details endpoint to check generation status.

Parameter Changes

scraper_id → template_id: Request bodies now use template_id as the primary field. The scraper_id alias is still accepted for backward compatibility.
template_id is optional in generate: If omitted, a new scraper is automatically created.
max_pages: New parameter for agentic async runs to limit pagination depth.
callback_url: Now supported in async runs and agent extraction.
proxy_country / cookies: Not supported for agentic scrapers. If provided, they are ignored and a warning is returned.

Migration Guide

From old `/v1/scrapers/*` CRUD to new typed endpoints

Action	Old	New
Create scraper	`POST /v1/scrapers/new`	`POST /v1/extractor/new` (classic) or `POST /v1/agent/new` (agentic)
Generate scraper	`POST /v1/scrapers/generate`	`POST /v1/extractor/generate` (classic) or `POST /v1/agent/generate` (agentic)
Get scraper details	`GET /v1/scrapers/{id}`	`GET /v1/extractor/{id}` (classic) or `GET /v1/agent/{id}` (agentic)
Delete scraper	`DELETE /v1/scrapers/{id}`	`DELETE /v1/extractor/{id}` (classic) or `DELETE /v1/agent/{id}` (agentic)
List scrapers	`GET /v1/scrapers`	`GET /v1/scrapers` (unchanged, now returns both types)
Run scraper	`POST /v1/scrapers/run`	`POST /v1/scrapers/run` (unchanged, now handles both types)

From Agents API (`agents.parsera.org`)

Old	New
`POST agents.parsera.org/v1/generate`	`POST api.parsera.org/v1/agent/generate`
`POST agents.parsera.org/v1/scrape`	`POST api.parsera.org/v1/scrapers/run`
`GET agents.parsera.org/v1/list`	`GET api.parsera.org/v1/scrapers`
`POST agents.parsera.org/v1/remove`	`DELETE api.parsera.org/v1/agent/{id}`