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

# Gateway Routes API: Create and Manage Payment Routes

> Create, list, update, and delete x402 payment routes that proxy USDC-paid agent requests to your upstream HTTP services on Meterlane.

Routes are the core configuration objects in the Meterlane Agent Gateway. Each route binds a public URL path to an upstream HTTP service and sets the USDC price that agents must pay per request. You manage routes through the `/api/routes` endpoints using your Bearer API key. Changes take effect immediately — no redeployment required.

***

## POST /api/routes

Creates a new payment route under your organisation.

```http theme={null}
POST https://gateway.meterlane.app/api/routes
Authorization: Bearer bp_live_…
Content-Type: application/json
```

### Request body

<ParamField body="path" type="string" required>
  The route path segment appended after your org slug, e.g. `weather/forecast`. Must be unique within your organisation.
</ParamField>

<ParamField body="priceUSD" type="number" required>
  The per-request price in USD charged to the caller, e.g. `0.01`. Settled as USDC on-chain.
</ParamField>

<ParamField body="targetUrl" type="string" required>
  The full upstream URL that the gateway proxies paid requests to, e.g. `https://api.example.com/forecast`.
</ParamField>

<ParamField body="network" type="string" required>
  The blockchain network used for settlement. Accepted values: `base`, `base-sepolia`.
</ParamField>

<ParamField body="active" type="boolean">
  Whether the route accepts requests. Defaults to `true`. Set to `false` to pause the route without deleting it.
</ParamField>

<ParamField body="streaming" type="boolean">
  Whether the gateway streams the upstream response body. Defaults to `false`. Enable for SSE or chunked-transfer upstreams.
</ParamField>

<ParamField body="discoverable" type="boolean">
  Whether the route appears in your public route listing. Defaults to `false`.
</ParamField>

<ParamField body="description" type="string">
  A human-readable description shown in the dashboard and MCP manifest.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://gateway.meterlane.app/api/routes \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "weather/forecast",
    "priceUSD": 0.01,
    "targetUrl": "https://api.example.com/forecast",
    "network": "base",
    "active": true,
    "streaming": false,
    "discoverable": true,
    "description": "Real-time weather forecast endpoint"
  }'
```

### Response `201 Created`

<ResponseField name="id" type="string">
  Unique identifier for the route, e.g. `route_01hx9z2k3m4n5p6q`.
</ResponseField>

<ResponseField name="orgId" type="string">
  The organisation this route belongs to.
</ResponseField>

<ResponseField name="path" type="string">
  The route path as stored.
</ResponseField>

<ResponseField name="priceUSD" type="number">
  Per-request price in USD.
</ResponseField>

<ResponseField name="targetUrl" type="string">
  The upstream URL this route proxies to.
</ResponseField>

<ResponseField name="network" type="string">
  Blockchain network used for settlement.
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the route is currently accepting requests.
</ResponseField>

<ResponseField name="streaming" type="boolean">
  Whether response streaming is enabled.
</ResponseField>

<ResponseField name="discoverable" type="boolean">
  Whether the route appears in the public listing.
</ResponseField>

```json theme={null}
{
  "id": "route_01hx9z2k3m4n5p6q",
  "orgId": "org_01hx9abcdefg",
  "path": "weather/forecast",
  "priceUSD": 0.01,
  "targetUrl": "https://api.example.com/forecast",
  "network": "base",
  "active": true,
  "streaming": false,
  "discoverable": true,
  "description": "Real-time weather forecast endpoint"
}
```

***

## GET /api/routes

Returns all routes belonging to your organisation.

```http theme={null}
GET https://gateway.meterlane.app/api/routes
Authorization: Bearer bp_live_…
```

### Example request

```bash theme={null}
curl https://gateway.meterlane.app/api/routes \
  -H "Authorization: Bearer bp_live_…"
```

### Response `200 OK`

```json theme={null}
[
  {
    "id": "route_01hx9z2k3m4n5p6q",
    "orgId": "org_01hx9abcdefg",
    "path": "weather/forecast",
    "priceUSD": 0.01,
    "targetUrl": "https://api.example.com/forecast",
    "network": "base",
    "active": true,
    "streaming": false,
    "discoverable": true,
    "description": "Real-time weather forecast endpoint"
  },
  {
    "id": "route_01hx9z2k3m4n5p6r",
    "orgId": "org_01hx9abcdefg",
    "path": "news/headlines",
    "priceUSD": 0.005,
    "targetUrl": "https://api.example.com/headlines",
    "network": "base",
    "active": true,
    "streaming": false,
    "discoverable": false,
    "description": "Latest news headlines"
  }
]
```

***

## PATCH /api/routes/:id

Updates one or more fields on an existing route. Only fields you include in the request body are changed.

```http theme={null}
PATCH https://gateway.meterlane.app/api/routes/:id
Authorization: Bearer bp_live_…
Content-Type: application/json
```

### Path parameters

<ParamField path="id" type="string" required>
  The route ID returned when the route was created, e.g. `route_01hx9z2k3m4n5p6q`.
</ParamField>

### Request body (all fields optional)

<ParamField body="path" type="string">
  New route path segment. Must remain unique within your organisation.
</ParamField>

<ParamField body="priceUSD" type="number">
  Updated per-request price in USD.
</ParamField>

<ParamField body="targetUrl" type="string">
  Updated upstream URL.
</ParamField>

<ParamField body="network" type="string">
  Updated settlement network. Accepted values: `base`, `base-sepolia`.
</ParamField>

<ParamField body="active" type="boolean">
  Pass `false` to pause the route or `true` to resume it.
</ParamField>

<ParamField body="streaming" type="boolean">
  Enable or disable response streaming.
</ParamField>

<ParamField body="discoverable" type="boolean">
  Show or hide the route in the public listing.
</ParamField>

<ParamField body="description" type="string">
  Updated human-readable description.
</ParamField>

### Example request

```bash theme={null}
curl -X PATCH https://gateway.meterlane.app/api/routes/route_01hx9z2k3m4n5p6q \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "priceUSD": 0.02,
    "active": false
  }'
```

### Response `200 OK`

Returns the full updated route object in the same shape as the `POST` response.

***

## DELETE /api/routes/:id

Permanently deletes a route. Agents calling the deleted route URL will receive a `404 ROUTE_NOT_FOUND` error immediately after deletion.

```http theme={null}
DELETE https://gateway.meterlane.app/api/routes/:id
Authorization: Bearer bp_live_…
```

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the route to delete.
</ParamField>

### Example request

```bash theme={null}
curl -X DELETE https://gateway.meterlane.app/api/routes/route_01hx9z2k3m4n5p6q \
  -H "Authorization: Bearer bp_live_…"
```

### Response `204 No Content`

A successful deletion returns `204` with an empty body.

<Warning>
  Deletion is permanent. If you want to stop a route from accepting requests without losing its configuration, set `active` to `false` using `PATCH` instead.
</Warning>