Scheme

Schemes are reusable extraction Blueprints. Instead of defining your scheme logic with every request, you can save a configuration once and reference it by ID.

Our system also supports AI-assisted schemes, allowing you to automatically generate and fix broken selectors using real page data.

Endpoint Reference Permalink to Endpoint Reference

Authentication: Include your API key in the x-api-key header for all requests.

Configuration Parameters Permalink to Configuration Parameters

When creating or updating a scheme, use the following parameters:

Config Details (config) The config object is a standard scraper api object and is compatible with any scrape parameter, with requirements based on your mode:

• url: Always Required if test or fix is enabled.
• extract_scheme: Required if fix is false.
• Other: View “Test” Tab

Creation Logic Permalink to Creation Logic

Credit Usage: Using the fix feature costs the Scraper Api fee for your configuration + 30 credits for each Ai fix; Up 60 credits in total are possible for multiple Ai fixes. If the AI fails to generate a valid scheme, credits are automatically refunded.

Usage Examples Permalink to Usage Examples

Create a scheme Permalink to Create a scheme

curl -X POST https://scrape.evomi.com/api/v1/account/schemes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Details",
    "config": {
      "extract_scheme": [
        {
          "label": "product_data",
          "selector": "body", 
          "type": "nest",
          "fields": [
            {
              "label": "price",
              "selector": ".p-price",
              "type": "content"
            }
          ]
        }
      ]
    }
  }'

List Your schemes Permalink to List Your schemes

curl -G "https://scrape.evomi.com/api/v1/account/schemes" \
  -d "page=1" \
  -d "per_page=10" \
  -H "x-api-key: YOUR_API_KEY"

Scrape Using a scheme ID Permalink to Scrape Using a scheme ID

Once saved, you don’t need to pass the full config anymore—just the ID.

curl -X POST https://scrape.evomi.com/api/v1/scraper/realtime \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/item-123",
    "scheme_id": "sch_xxxxx"
  }'

Background Processing Permalink to Background Processing

Creating or updating a scheme with async (or when test/fix exceeds the sync timeout) runs the scheme test as a background task. Every response belonging to that task carries the task timing fields, mirrored as X-Task-* headers.

Submit (async), HTTP 202:

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "id": "sch_xxxxx",
  "status": "processing",
  "message": "Schema test submitted for background processing",
  "check_url": "/api/v1/account/schemes/sch_xxxxx/status",
  "credits_reserved": 35,
  "created_at": "2026-09-28T20:31:12.482Z",
  "started_at": null,
  "finished_at": null,
  "elapsed_seconds": 0.1
}

Check status (GET /account/schemes/{scheme_id}/status) — note this endpoint is polled by scheme id, not task id:

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Scheme is still processing",
  "created_at": "2026-09-28T20:31:12.482Z",
  "started_at": "2026-09-28T20:31:13.455Z",
  "finished_at": null,
  "elapsed_seconds": 8.4
}

Once the test finishes, the same endpoint returns the test result with the final timing — finished_at set and elapsed_seconds frozen at its last value. A scheme that has never been tested returns {"status": "not_tested"} with no timing fields, since no task exists for it.

Response Codes Permalink to Response Codes

• 200/201: Success / Created
• 202: Request accepted (Async processing)
• 400: Validation error (check your JSON syntax)
• 402: Insufficient credits
• 404: scheme ID not found
• 500: Internal server error