# Scheme

Source: https://docs.evomi.com/scraping-products-instructions/scraper-api/parameters/extraction/schema/

**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

| Endpoint | Method | Action |
| :--- | :--- | :--- |
| `/account/schemes` | `POST` | Create a new scheme |
| `/account/schemes` | `GET` | List all saved schemes |
| `/account/schemes/{id}` | `GET` | Retrieve specific scheme details |
| `/account/schemes/{id}` | `PUT` | Update an existing scheme |
| `/account/schemes/{id}` | `DELETE` | Remove a scheme |
| `/account/schemes/{id}/status` | `GET` | Check background processing status |

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

---

## Configuration Parameters

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

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | string | **Yes** | A unique nickname for your scheme. |
| `config or config_id` | JSON | **Yes** | See **Config Object Details**  |
| `test` | boolean | No |  Required if `fix` is true; validates the scheme against a URL. |
| `fix` | boolean | No | If `true`, uses AI to repair or generate the scheme. |
| `async` | boolean | No | Processes the request in the background. |
| `extract_prompt` | string | Conditional | Required if `fix` is true; guides the AI on what to extract. |

> **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

| Mode | `test` | `fix` | System Behavior |
| :--- | :--- | :--- | :--- |
| **Create** | `false` | `false` | Saves the scheme config as-is. |
| **Test** | `true` | `false` | Saves if it extracts data on chosen url. |
| **Fix** | `true` | `true` | Fix and save scheme config on chosen url. |

> **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

### Create a scheme
```bash
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
```bash
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
Once saved, you don't need to pass the full config anymore—just the ID.
```bash
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"
  }'
```

---

## 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

## Pages in this section

- [Fix](https://docs.evomi.com/scraping-products-instructions/scraper-api/parameters/extraction/schema/fix/index.md): With test and fix both true, the API writes or repairs an extractscheme from your prompt against the live page, and saves it only if it works.
- [Test](https://docs.evomi.com/scraping-products-instructions/scraper-api/parameters/extraction/schema/test/index.md): test=true validates an extractscheme against a live URL before it is saved, and shows what each selector actually returned.