> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meter.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Introduction to the Meter REST API

# REST API Overview

The Meter REST API provides direct HTTP access to all Meter features. Use it when the Python SDK isn't available or when you need language-agnostic integration.

## Base URL

```
https://api.meter.sh
```

All API requests should be made to this base URL.

## Authentication

Include your API key in the `Authorization` header using the Bearer scheme:

```bash theme={null}
curl https://api.meter.sh/api/strategies \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json"
```

See [Authentication](/api-reference/rest/authentication) for details.

## Request format

All POST and PATCH requests must include `Content-Type: application/json` and send JSON-encoded request bodies.

**Example:**

```bash theme={null}
curl -X POST https://api.meter.sh/api/strategies/generate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "description": "Extract product names and prices",
    "name": "Product Scraper"
  }'
```

## Response format

All responses are JSON-encoded with appropriate HTTP status codes:

* `200 OK`: Successful request
* `201 Created`: Resource created successfully
* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Invalid or missing API key
* `404 Not Found`: Resource not found
* `500 Internal Server Error`: Server error

**Success response:**

```json theme={null}
{
  "strategy_id": "550e8400-e29b-41d4-a716-446655440000",
  "strategy": {...},
  "preview_data": [...]
}
```

**Error response:**

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

## API endpoints

### Strategies

| Method | Endpoint                      | Description                                |
| ------ | ----------------------------- | ------------------------------------------ |
| POST   | `/api/strategies/generate`    | Generate a new strategy                    |
| POST   | `/api/strategies/{id}/refine` | Refine an existing strategy                |
| GET    | `/api/strategies`             | List all strategies                        |
| GET    | `/api/strategies/{id}`        | Get strategy details                       |
| GET    | `/api/strategies/audit`       | Audit log of strategy create/delete events |
| DELETE | `/api/strategies/{id}`        | Delete a strategy                          |

### Account

| Method | Endpoint             | Description                              |
| ------ | -------------------- | ---------------------------------------- |
| GET    | `/api/account/quota` | Current strategy quota state (read-only) |

### Jobs

| Method | Endpoint                       | Description                |
| ------ | ------------------------------ | -------------------------- |
| POST   | `/api/jobs`                    | Create a new job (async)   |
| POST   | `/api/jobs/execute`            | Execute job (synchronous)  |
| GET    | `/api/jobs/{id}`               | Get job status and results |
| GET    | `/api/jobs`                    | List jobs (with filtering) |
| POST   | `/api/jobs/compare`            | Compare two jobs           |
| GET    | `/api/strategies/{id}/history` | Get strategy job history   |

### Schedules

| Method | Endpoint                      | Description        |
| ------ | ----------------------------- | ------------------ |
| POST   | `/api/schedules`              | Create a schedule  |
| GET    | `/api/schedules`              | List all schedules |
| PATCH  | `/api/schedules/{id}`         | Update a schedule  |
| DELETE | `/api/schedules/{id}`         | Delete a schedule  |
| GET    | `/api/schedules/{id}/changes` | Get unseen changes |

### Watch (Simplified)

| Method | Endpoint     | Description                                      |
| ------ | ------------ | ------------------------------------------------ |
| POST   | `/api/watch` | Create a watch (strategy + schedule in one call) |

### Discovery

| Method | Endpoint                  | Description               |
| ------ | ------------------------- | ------------------------- |
| POST   | `/discover`               | Start URL discovery       |
| GET    | `/discover/{id}`          | Get discovery status      |
| GET    | `/discover/{id}/urls`     | Get discovered URLs       |
| POST   | `/discover/{id}/execute`  | Execute batch scrape      |
| POST   | `/discover/{id}/schedule` | Create recurring schedule |
| GET    | `/discoveries`            | List all discoveries      |
| DELETE | `/discover/{id}`          | Delete a discovery        |

### Strategy Groups

| Method | Endpoint                                     | Description                         |
| ------ | -------------------------------------------- | ----------------------------------- |
| POST   | `/api/strategy-groups`                       | Create a strategy group             |
| GET    | `/api/strategy-groups`                       | List strategy groups                |
| GET    | `/api/strategy-groups/{id}`                  | Get group details with strategies   |
| PATCH  | `/api/strategy-groups/{id}`                  | Update group name/description       |
| DELETE | `/api/strategy-groups/{id}`                  | Delete a group                      |
| POST   | `/api/strategy-groups/{id}/strategies`       | Add strategies to group             |
| DELETE | `/api/strategy-groups/{id}/strategies/{sid}` | Remove strategy from group          |
| POST   | `/api/strategy-groups/{id}/schedule`         | Apply schedule to all group members |
| DELETE | `/api/strategy-groups/{id}/schedule`         | Delete all group schedules          |
| PATCH  | `/api/strategy-groups/{id}/schedule/toggle`  | Enable/disable group schedules      |
| PATCH  | `/api/strategy-groups/{id}/schema`           | Apply output schema to group        |
| GET    | `/api/strategy-groups/{id}/schema/progress`  | Poll schema regeneration progress   |
| POST   | `/api/strategy-groups/{id}/webhook/test`     | Test group webhook                  |

### Workflows

| Method | Endpoint                                 | Description              |
| ------ | ---------------------------------------- | ------------------------ |
| POST   | `/api/workflows`                         | Create a workflow        |
| GET    | `/api/workflows`                         | List workflows           |
| GET    | `/api/workflows/{id}`                    | Get workflow details     |
| PUT    | `/api/workflows/{id}`                    | Update workflow metadata |
| DELETE | `/api/workflows/{id}`                    | Delete a workflow        |
| POST   | `/api/workflows/{id}/nodes`              | Add a node               |
| PUT    | `/api/workflows/{id}/nodes/{nid}`        | Update a node            |
| DELETE | `/api/workflows/{id}/nodes/{nid}`        | Delete a node            |
| POST   | `/api/workflows/{id}/edges`              | Add an edge              |
| DELETE | `/api/workflows/{id}/edges/{eid}`        | Delete an edge           |
| POST   | `/api/workflows/{id}/run`                | Run a workflow           |
| GET    | `/api/workflows/{id}/runs/{rid}`         | Get run details          |
| GET    | `/api/workflows/{id}/runs`               | List runs                |
| GET    | `/api/workflows/{id}/runs/latest/output` | Get latest output        |
| POST   | `/api/workflows/{id}/runs/{rid}/cancel`  | Cancel a run             |
| POST   | `/api/workflows/{id}/schedules`          | Create workflow schedule |
| GET    | `/api/workflows/{id}/schedules`          | List workflow schedules  |
| PATCH  | `/api/workflows/{id}/schedules/{sid}`    | Update workflow schedule |
| DELETE | `/api/workflows/{id}/schedules/{sid}`    | Delete workflow schedule |

### Webhooks

| Method | Endpoint             | Description           |
| ------ | -------------------- | --------------------- |
| POST   | `/api/webhooks/test` | Test webhook delivery |

See detailed endpoint documentation:

* [Strategy endpoints](/api-reference/rest/strategies)
* [Job endpoints](/api-reference/rest/jobs)
* [Schedule endpoints](/api-reference/rest/schedules)
* [Strategy group endpoints](/api-reference/rest/strategy-groups)
* [Workflow endpoints](/api-reference/rest/workflows)
* [Watch endpoint](/api-reference/rest/watch)
* [Discovery endpoints](/api-reference/rest/discovery)
* [Webhooks](/api-reference/rest/webhooks)

## Rate limiting

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

## Pagination

List endpoints support pagination with `limit` and `offset` query parameters:

```bash theme={null}
# Get first 20 results
curl "https://api.meter.sh/api/strategies?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_..."

# Get next 20 results
curl "https://api.meter.sh/api/strategies?limit=20&offset=20" \
  -H "Authorization: Bearer sk_live_..."
```

## Idempotency

Strategy generation supports an optional `Idempotency-Key` request header.
Retries with the same key within 24 hours replay the original response
without re-running the LLM or consuming additional quota. See
[Strategy generation idempotency](/api-reference/rest/strategies#idempotency)
for the full semantics and examples.

Other POST endpoints do not currently support `Idempotency-Key` — calling
them twice will create two resources.

## CORS

The API does not currently support CORS. For browser-based applications, proxy requests through your backend.

## Webhooks

Configure webhooks when creating schedules to receive real-time notifications:

```bash theme={null}
curl -X POST https://api.meter.sh/api/schedules \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/products",
    "interval_seconds": 3600,
    "webhook_url": "https://your-app.com/webhooks/meter"
  }'
```

See the [Webhooks Guide](/guides/webhooks) for implementation details.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/rest/authentication">
    Learn about API key authentication
  </Card>

  <Card title="Strategy Endpoints" icon="brain" href="/api-reference/rest/strategies">
    Explore strategy API endpoints
  </Card>

  <Card title="Account" icon="user" href="/api-reference/rest/account">
    Read live quota and plan tier
  </Card>

  <Card title="Job Endpoints" icon="gears" href="/api-reference/rest/jobs">
    Explore job API endpoints
  </Card>

  <Card title="Schedule Endpoints" icon="clock" href="/api-reference/rest/schedules">
    Explore schedule API endpoints
  </Card>

  <Card title="Watch Endpoint" icon="eye" href="/api-reference/rest/watch">
    One-step URL monitoring setup
  </Card>

  <Card title="Discovery Endpoints" icon="magnifying-glass" href="/api-reference/rest/discovery">
    Site crawling and URL discovery
  </Card>

  <Card title="Strategy Groups" icon="layer-group" href="/api-reference/rest/strategy-groups">
    Manage strategy groups
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/rest/webhooks">
    Test webhook delivery
  </Card>
</CardGroup>

## Need help?

Email me at [mckinnon@meter.sh](mailto:mckinnon@meter.sh)