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

# Discovery API

> REST API for searching, listing, and inspecting paid API proxies on Corbits

The Discovery API provides programmatic access to the Corbits API catalog. Use it to search for proxies, list available endpoints, retrieve OpenAPI specs, and get pricing details.

**Base URL**: `https://api.corbits.dev`

No authentication required.

## Key concepts

### Proxy URLs

Each proxy has a dedicated URL constructed from its name and optional org slug:

* `https://{name}.api.corbits.dev` — standard proxy
* `https://{name}.{org_slug}.api.corbits.dev` — org-scoped proxy

Always use the proxy's `url` field from API responses as the base URL for making calls. Do not use the discovery API URL (`api.corbits.dev`) for API calls.

### Pricing

Prices are stored as **micro-USDC integers**. To convert to USDC, multiply by `1e-6`:

| `price` value | USDC amount |
| ------------- | ----------- |
| `1000`        | \$0.001     |
| `10000`       | \$0.01      |
| `1000000`     | \$1.00      |

### Payment handling

If you're making calls programmatically, use the [`@faremeter/rides`](https://www.npmjs.com/package/@faremeter/rides) SDK — it handles the full x402 challenge/response cycle automatically. See the [Corbits Skill](/discovery/corbits-skill) for a working implementation.

### Path patterns

`path_pattern` values are anchored regular expressions, not literal paths. Examples: `^/v1/messages$`, `^/trenches/curve/[^/]+$`, `^/v1/messages\?beta=true$`. Match callers' request paths against these patterns rather than treating them as URLs.

***

## List your proxy on Discovery

<Note>
  **Find useful solutions and let your solutions be found by others.** Discovery is a two-sided marketplace — you can consume APIs listed by others, and list your own so they're discoverable by developers and AI agents alike. Make sure your Corbits proxy is [registered and active](/marketplace/control-plane/proxies) so it appears in search results.
</Note>

## Endpoints

### Health check

```
GET /health
```

Returns `200 OK` if the service is running.

```bash theme={null}
curl https://api.corbits.dev/health
```

***

### Search proxies and endpoints

```
GET /api/v1/search?q=<query>
```

Full-text search across proxy names, descriptions, tags, and endpoint path patterns. Returns matching proxies and endpoints.

<ParamField query="q" type="string" required>
  Search query. Empty or whitespace-only queries return empty results.
</ParamField>

```bash theme={null}
curl "https://api.corbits.dev/api/v1/search?q=openai"
```

<Expandable title="Example response">
  ```json theme={null}
  {
    "proxies": [
      {
        "id": 61,
        "name": "openai",
        "org_slug": null,
        "url": "https://openai.api.corbits.dev",
        "tags": ["ai", "llm"],
        "default_price": 10000,
        "default_scheme": "exact"
      }
    ],
    "endpoints": [
      {
        "id": 145,
        "proxy_id": 61,
        "proxy_name": "openai",
        "org_slug": null,
        "path_pattern": "^/v1/models$",
        "description": "List available models",
        "price": 1000,
        "scheme": "exact",
        "tags": ["models"]
      }
    ]
  }
  ```
</Expandable>

<Note>
  Search results are returned at the top level (no `data` wrapper). The list and detail endpoints below wrap their payload in a `data` field — match each example exactly.
</Note>

***

### List proxies

```
GET /api/v1/proxies
```

List all active API proxies. Supports cursor-based pagination.

<ParamField query="cursor" type="integer">
  ID of the last item from the previous page. Omit for the first page.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page. Maximum 100.
</ParamField>

```bash theme={null}
curl "https://api.corbits.dev/api/v1/proxies?limit=20"
```

<Expandable title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": 1,
        "name": "helius",
        "org_slug": null,
        "url": "https://helius.api.corbits.dev",
        "tags": [],
        "default_price": 10000,
        "default_scheme": "exact"
      }
    ],
    "pagination": {
      "nextCursor": "1",
      "hasMore": true
    }
  }
  ```
</Expandable>

To paginate, pass `pagination.nextCursor` from the previous response as the `cursor` query param. Stop when `hasMore` is `false`.

```bash theme={null}
curl "https://api.corbits.dev/api/v1/proxies?cursor=61&limit=20"
```

***

### Get proxy details

```
GET /api/v1/proxies/{id}
```

Returns a single proxy with its `endpoint_count`.

<ParamField path="id" type="integer" required>
  Proxy ID.
</ParamField>

```bash theme={null}
curl https://api.corbits.dev/api/v1/proxies/61
```

<Expandable title="Example response">
  ```json theme={null}
  {
    "data": {
      "id": 61,
      "name": "openai",
      "org_slug": null,
      "url": "https://openai.api.corbits.dev",
      "tags": [],
      "default_price": 10000,
      "default_scheme": "exact",
      "endpoint_count": 99
    }
  }
  ```
</Expandable>

**Errors**: `400` invalid ID, `404` not found or inactive.

***

### Get OpenAPI spec

```
GET /api/v1/proxies/{id}/openapi
```

Returns the proxy's full OpenAPI specification, including endpoint schemas and parameters. On Corbits-instrumented specs, payment metadata is carried in the per-operation `x-payment-info` extension and the top-level `x-discovery` extension. See [OpenAPI extensions](#openapi-extensions) below.

<ParamField path="id" type="integer" required>
  Proxy ID.
</ParamField>

```bash theme={null}
curl https://api.corbits.dev/api/v1/proxies/61/openapi
```

<Expandable title="Example response">
  ```json theme={null}
  {
    "data": {
      "id": 61,
      "name": "openai",
      "spec": {
        "openapi": "3.1.0",
        "info": { "title": "OpenAI API", "version": "2.3.0" },
        "servers": [{ "url": "https://api.openai.com/v1" }],
        "paths": { ... }
      }
    }
  }
  ```
</Expandable>

<Note>
  The `servers[0].url` field contains the upstream base path. When constructing call URLs, combine the proxy URL with this base path and the spec path: `https://openai.api.corbits.dev/v1/models`.
</Note>

**Errors**: `400` invalid ID, `404` not found or no spec available.

***

### List proxy endpoints

```
GET /api/v1/proxies/{id}/endpoints
```

List all endpoints for a proxy with pricing details. Supports cursor-based pagination.

<ParamField path="id" type="integer" required>
  Proxy ID.
</ParamField>

<ParamField query="cursor" type="integer">
  ID of the last item from the previous page.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page. Maximum 100.
</ParamField>

```bash theme={null}
curl https://api.corbits.dev/api/v1/proxies/61/endpoints
```

<Expandable title="Example response">
  ```json theme={null}
  {
    "data": [
      {
        "id": 145,
        "path_pattern": "^/v1/models$",
        "description": "List available models",
        "price": 1000,
        "scheme": "exact",
        "tags": ["models"]
      }
    ],
    "pagination": {
      "nextCursor": "145",
      "hasMore": true
    }
  }
  ```
</Expandable>

Paginate by passing `pagination.nextCursor` as the `cursor` query param until `hasMore` is `false`.

<Note>
  Some passthrough proxies have `endpoint_count: 0` and return an empty `data` array even when the proxy itself is live (Helius is one example). If Discovery has no endpoints for a proxy, fall back to its OpenAPI spec via `GET /api/v1/proxies/{id}/openapi` or the upstream provider's documentation.
</Note>

**Errors**: `404` proxy not found or inactive.

***

### Get endpoint details

```
GET /api/v1/proxies/{id}/endpoints/{endpointId}
```

Returns a single endpoint's details including pricing and description.

<ParamField path="id" type="integer" required>
  Proxy ID.
</ParamField>

<ParamField path="endpointId" type="integer" required>
  Endpoint ID.
</ParamField>

```bash theme={null}
curl https://api.corbits.dev/api/v1/proxies/61/endpoints/145
```

**Errors**: `400` invalid ID, `404` not found.

***

## OpenAPI extensions

Corbits-instrumented OpenAPI specs carry payment metadata in two places:

**Top level** — `x-discovery` describes proxy-wide discovery metadata:

```json theme={null}
{
  "x-discovery": {
    "ownershipProofs": []
  }
}
```

**Per operation** — `x-payment-info` describes pricing and accepted payment protocols:

```json theme={null}
{
  "x-payment-info": {
    "price": { "mode": "fixed", "amount": "0.025000", "currency": "USD" },
    "protocols": [
      { "x402": { "network": "solana", "facilitator": "https://facilitator.corbits.dev" } },
      { "mpp":  { "intent": "charge", "method": "solana", "currency": "USDC" } }
    ]
  }
}
```

Corbits operates a public x402 facilitator at `https://facilitator.corbits.dev` covering Solana, Base, Polygon, Monad, SKALE, and additional networks. Listings may point at a different facilitator if the operator chose to run their own.

Some specs additionally carry `x-payment-protocols` and `x-guidance` per operation.

Passthrough proxies that mirror an upstream provider's spec (OpenAI, Anthropic, Brave, Exa, etc.) do not carry Corbits extensions — they expose only the upstream provider's `x-*` keys. For those proxies, use the proxy's `default_price` and per-endpoint `price` from the Discovery API instead.