Extractions
The extractions API lets you extract design tokens from any URL.
Endpoints
Create Extraction
Start a new CSS extraction job.
POST /api/extractions
Request Body:
{
"url": "https://example.com",
"options": {
"wait_for": "networkidle",
"viewport": { "width": 1920, "height": 1080 },
"selectors": ["#header", ".main-content"],
"exclude_selectors": [".ad-banner"]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to extract from |
options.wait_for | string | No | Wait condition: load, domcontentloaded, networkidle |
options.viewport | object | No | Browser viewport size |
options.selectors | array | No | Limit extraction to specific elements |
options.exclude_selectors | array | No | Exclude elements from extraction |
Response:
{
"id": "ext_abc123",
"url": "https://example.com",
"status": "pending",
"created_at": "2024-01-15T10:30:00Z"
}
The extraction runs asynchronously. Poll the status endpoint or use webhooks to know when it’s complete.
List Extractions
Get all extractions for your account.
GET /api/extractions
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Results per page (max 100) |
status | string | — | Filter by status |
Response:
{
"data": [
{
"id": "ext_abc123",
"url": "https://example.com",
"status": "completed",
"created_at": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 42
}
}
Get Extraction
Retrieve a specific extraction with its tokens.
GET /api/extractions/:id
Response:
{
"id": "ext_abc123",
"url": "https://example.com",
"status": "completed",
"tokens": {
"colors": [
{
"name": "primary",
"value": "#3b82f6",
"format": "hex",
"usage": 42
},
{
"name": "background",
"value": "#ffffff",
"format": "hex",
"usage": 156
}
],
"typography": [
{
"family": "Inter",
"weights": ["400", "600", "700"],
"sizes": ["14px", "16px", "24px", "32px"]
}
],
"spacing": [
"4px", "8px", "12px", "16px", "24px", "32px", "48px", "64px"
],
"assets": [
{
"type": "image",
"url": "https://example.com/logo.svg",
"dimensions": { "width": 120, "height": 40 }
}
]
},
"metadata": {
"title": "Example Domain",
"duration_ms": 2340,
"elements_analyzed": 847
},
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:02Z"
}
Extraction Status
| Status | Description |
|---|---|
pending | Extraction queued, waiting to start |
running | Browser is loading the page |
completed | Extraction finished successfully |
failed | Extraction encountered an error |
Token Types
Colors
{
"name": "primary",
"value": "#3b82f6",
"format": "hex",
"usage": 42,
"contexts": ["background-color", "border-color"]
}
Typography
{
"family": "Inter",
"weights": ["400", "600", "700"],
"sizes": ["14px", "16px", "24px"],
"line_heights": ["1.4", "1.5", "1.6"]
}
Spacing
An array of unique spacing values found in margins, paddings, and gaps:
["4px", "8px", "12px", "16px", "24px", "32px"]
Assets
{
"type": "image",
"url": "https://example.com/logo.svg",
"dimensions": { "width": 120, "height": 40 },
"format": "svg"
}
Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | invalid_url | The provided URL is malformed |
| 404 | not_found | Extraction not found |
| 422 | extraction_failed | Browser failed to load the page |
| 429 | rate_limited | Too many requests |
{
"error": {
"code": "extraction_failed",
"message": "Failed to load page: timeout after 30s"
}
}