The REST API serves the same data as the MCP server as plain JSON over HTTPS — ideal for scripts, backends, and dashboards. Every endpoint lives under `https://api.equibles.com/v1`.

## Base URL & authentication

All requests go to `https://api.equibles.com/v1` and must include your API key as a `Bearer` token (or an `?api_key=` query parameter — see [Authentication](/docs/authentication)).

```bash
curl "https://api.equibles.com/v1/stocks/AAPL/prices?startDate=2024-01-01" \
  -H "Authorization: Bearer eq_your_api_key"
```

## Pagination

List endpoints accept `limit` and `offset` query parameters and wrap the rows in a `data` array alongside a `meta` object. Use `meta.hasMore` to decide whether to fetch the next page (increase `offset` by `limit`). The maximum `limit` is 500.

```json
{
  "data": [ /* rows */ ],
  "meta": { "limit": 50, "offset": 0, "count": 50, "hasMore": true }
}
```

To pull an entire list, page until `hasMore` is `false`. Each page is one request against your [daily limit](/docs/rate-limits), so a 10,000-row read at `limit=500` costs 20 requests:

```python
import requests

def fetch_all(url, key, page=500):
    rows, offset = [], 0
    while True:
        r = requests.get(url, params={"limit": page, "offset": offset},
                         headers={"Authorization": f"Bearer {key}"})
        r.raise_for_status()
        body = r.json()
        rows += body["data"]
        if not body["meta"]["hasMore"]:
            return rows
        offset += page
```

## Response format

- All responses are JSON with **camelCase** field names.
- Dates are ISO `yyyy-MM-dd` strings.
- Successful reads return `200`; see [Rate limits & errors](/docs/rate-limits) for non-2xx.
- `v1` is stable — breaking changes ship under a future version, never inside `v1`.

## A worked example

Fetch the short-squeeze board for names above a $1B market cap. Note that ratio fields come over the wire as **fractions** (`0.112` = 11.2%), even though the MCP tool formats them as percentages:

```bash
curl "https://api.equibles.com/v1/short-squeeze-scores?minMarketCap=1000000000&maxResults=3" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
r = requests.get(
    "https://api.equibles.com/v1/short-squeeze-scores",
    params={"minMarketCap": 1_000_000_000, "maxResults": 3},
    headers={"Authorization": "Bearer eq_your_api_key"},
)
for s in r.json()["data"]:
    print(s["ticker"], s["score"])
```

```javascript
const url =
  "https://api.equibles.com/v1/short-squeeze-scores?minMarketCap=1000000000&maxResults=3";
const res = await fetch(url, {
  headers: { Authorization: "Bearer eq_your_api_key" },
});
const { data } = await res.json();
data.forEach((s) => console.log(s.ticker, s.score));
```

```json
{
  "settlementDate": "2026-06-30",
  "data": [
    {
      "ticker": "TRAX",
      "score": 97,
      "shortInterestPercentOfShares": 0.112,
      "daysToCover": 4.8,
      "shortVolumeShareTrend": -0.010,
      "shortInterestChangePercent": 0.332,
      "failsToDeliverPercentOfShares": 0.0,
      "priceAboveVwap": 0.725,
      "hasPriceSpikeCatalyst": true,
      "hasVolumeSurgeCatalyst": true,
      "hasEarningsProximityCatalyst": false,
      "marketCapitalization": 1260000000,
      "averageDailyDollarVolume": 29650000
    }
  ]
}
```

Every endpoint's exact parameters and response schema are in the [interactive docs](https://api.equibles.com/docs).

## Errors & rate limits

Non-2xx responses return a consistent error envelope, and requests count against a shared daily limit across MCP and REST. Full details are on [Rate limits & errors](/docs/rate-limits).

```json
{ "error": { "code": "not_found", "message": "Stock not found.", "status": 404 } }
```

## Client libraries

There's no official SDK — the API is plain HTTPS + JSON, so any HTTP client works (the examples here use `curl`, `requests`, and `fetch`). For a typed client, generate one from the [OpenAPI spec](https://api.equibles.com/openapi/v1.json) with a tool like `openapi-generator` or `openapi-typescript`.

## Reference

- [Endpoint reference](/docs/api/endpoints) — all endpoints, grouped by domain.
- [Interactive docs](https://api.equibles.com/docs) — try endpoints live in Swagger UI.
- [OpenAPI spec](https://api.equibles.com/openapi/v1.json) — generate a client from `v1.json`.