# Extraction API Reference

> Complete API reference for the Stack0 AI Extraction API.

Complete REST API reference for AI-powered data extraction.

## Base URL

base-urlCopy

```
https://api.stack0.dev/v1
```

## Authentication

All API requests require authentication using your API key:

authenticationCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/extractions \  -H "Authorization: Bearer sk_live_your_api_key" \  -H "Content-Type: application/json" \  -d '{"url": "https://example.com", "mode": "markdown"}'
```

POST`/webdata/extractions`

Create a new AI extraction request.

#### Request Body

| Field | Type | Description |
| --- | --- | --- |
| url | string | URL to extract from (required) |
| mode | string | auto, schema, markdown, or raw |
| schema | object | JSON schema for structured extraction |
| prompt | string | Natural language guidance |
| includeLinks | boolean | Include page links |
| includeImages | boolean | Include image URLs |
| includeMetadata | boolean | Include page metadata |
| waitForSelector | string | Wait for element |
| waitForTimeout | number | Wait time in ms |

create-extractionCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/extractions \  -H "Authorization: Bearer sk_live_xxx" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/product",    "mode": "schema",    "schema": {      "type": "object",      "properties": {        "name": { "type": "string" },        "price": { "type": "number" },        "description": { "type": "string" }      }    },    "includeMetadata": true  }' # Response{  "id": "ext_abc123",  "status": "pending"}
```

GET`/webdata/extractions/:id`

Get an extraction by ID.

get-extractionCopy

```
curl https://api.stack0.dev/v1/webdata/extractions/ext_abc123 \  -H "Authorization: Bearer sk_live_xxx" # Response{  "id": "ext_abc123",  "url": "https://example.com/product",  "mode": "schema",  "status": "completed",  "extractedData": {    "name": "Product Name",    "price": 99.99,    "description": "Product description..."  },  "markdown": null,  "pageMetadata": {    "title": "Product Name - Example Store",    "description": "Buy Product Name...",    "ogImage": "https://example.com/product.jpg"  },  "tokensUsed": 1250,  "processingTimeMs": 3500,  "createdAt": "2024-01-15T10:30:00Z",  "completedAt": "2024-01-15T10:30:03Z"}
```

GET`/webdata/extractions`

List extractions with optional filters.

#### Query Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| status | string | Filter by status |
| url | string | Filter by URL |
| limit | number | Max results (default 20) |
| cursor | string | Pagination cursor |

list-extractionsCopy

```
curl "https://api.stack0.dev/v1/webdata/extractions?status=completed&limit=10" \  -H "Authorization: Bearer sk_live_xxx" # Response{  "items": [...],  "nextCursor": "cursor_xyz"}
```

DELETE`/webdata/extractions/:id`

Delete an extraction.

delete-extractionCopy

```
curl -X DELETE https://api.stack0.dev/v1/webdata/extractions/ext_abc123 \  -H "Authorization: Bearer sk_live_xxx" # Response{ "success": true }
```

## Batch Extractions

POST`/webdata/batch/extractions`

Create a batch extraction job for multiple URLs.

batch-extractionsCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/batch/extractions \  -H "Authorization: Bearer sk_live_xxx" \  -H "Content-Type: application/json" \  -d '{    "urls": [      "https://example.com/article/1",      "https://example.com/article/2"    ],    "config": {      "mode": "markdown",      "includeMetadata": true    }  }' # Response{  "id": "batch_abc123",  "status": "pending",  "totalUrls": 2}
```

GET`/webdata/batch/:id`

Get a batch job by ID.

get-batch-jobCopy

```
curl https://api.stack0.dev/v1/webdata/batch/batch_abc123 \  -H "Authorization: Bearer sk_live_xxx" # Response{  "id": "batch_abc123",  "type": "extraction",  "status": "completed",  "totalUrls": 2,  "processedUrls": 2,  "successfulUrls": 2,  "failedUrls": 0,  "createdAt": "2024-01-15T10:30:00Z",  "completedAt": "2024-01-15T10:31:00Z"}
```

POST`/webdata/batch/:id/cancel`

Cancel a running batch job.

cancel-batch-jobCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/batch/batch_abc123/cancel \  -H "Authorization: Bearer sk_live_xxx" # Response{ "success": true }
```

## Scheduled Extractions

POST`/webdata/schedules`

Create a recurring extraction schedule.

create-scheduleCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/schedules \  -H "Authorization: Bearer sk_live_xxx" \  -H "Content-Type: application/json" \  -d '{    "name": "Daily price monitoring",    "url": "https://competitor.com/pricing",    "type": "extraction",    "frequency": "daily",    "config": {      "mode": "schema",      "schema": {        "type": "object",        "properties": {          "price": { "type": "number" },          "features": { "type": "array" }        }      }    },    "detectChanges": true  }' # Response{ "id": "sch_abc123" }
```

POST`/webdata/schedules/:id/toggle`

Toggle a schedule on or off.

toggle-scheduleCopy

```
curl -X POST https://api.stack0.dev/v1/webdata/schedules/sch_abc123/toggle \  -H "Authorization: Bearer sk_live_xxx" # Response{ "isActive": false }
```

## Extraction Modes

| Mode | Description |
| --- | --- |
| schema | Extract data matching your JSON schema |
| markdown | Convert content to clean markdown |
| auto | AI determines best extraction approach |
| raw | Return raw HTML content |

## Status Values

| Status | Description |
| --- | --- |
| pending | Job queued, waiting to start |
| processing | Job is currently running |
| completed | Job finished successfully |
| failed | Job encountered an error |

### Related

[Extraction SDK](https://www.stack0.dev/docs/sdk/extraction)[Screenshot API](https://www.stack0.dev/docs/api-reference/screenshots)[Error Handling](https://www.stack0.dev/docs/errors)

---

Source: https://www.stack0.dev/docs/api-reference/extraction
llms.txt: https://www.stack0.dev/llms.txt
Sitemap: https://www.stack0.dev/sitemap.xml
Documentation: https://www.stack0.dev/docs
OpenAPI spec: https://www.stack0.dev/openapi.json
MCP server: https://api.stack0.dev/mcp