# Prixe API — Instructions for AI Agents

You are interacting with the Prixe Stock Data API. Follow these instructions to make successful API calls.

## Quick Start

1. **Get an API key** from [prixe.io](https://prixe.io)
2. **Include it in every request** as a Bearer token:
   ```
   Authorization: Bearer YOUR_API_KEY
   ```
3. **Base URL**: `https://api.prixe.io`
4. **All endpoints** accept and return JSON. Set `Content-Type: application/json` on POST requests.

## How to Read These Docs

- Visit `/mcp/` for the full endpoint index
- Visit `/mcp/<endpoint>` for detailed docs on a specific endpoint (e.g. `/mcp/last_sold`, `/mcp/price`, `/mcp/news`)
- Each endpoint page includes: parameters, response schema, code examples, and error codes

## Available Endpoints

| Slug | Path | Method | Description |
|---|---|---|---|
| `ai_summary` | `/api/news, /api/forms, /api/board_members` | POST | AI Summary |
| `board_members` | `/api/board_members` | POST | Board Members & Company Officers |
| `executive_disclosures` | `/api/politicians/executive_disclosures` | POST | Executive Branch Disclosures |
| `forms_get` | `/api/forms` | GET | Available SEC Forms |
| `forms_post` | `/api/forms` | POST | SEC Form Data |
| `holdings` | `/api/politicians/holdings` | POST | Politician Net Trading Activity |
| `last_sold` | `/api/last_sold` | POST | Last Sold Price |
| `list` | `/api/politicians/list` | POST | Politicians List |
| `news` | `/api/news` | POST | Fetch News |
| `politicians` | `/api/politicians` | POST | Congressional Stock Transactions |
| `price` | `/api/price` | POST | Historical Price |
| `search` | `/api/search` | POST | Search |
| `stats` | `/api/stats` | POST | Market Statistics |
| `ws` | `wss://ws.prixe.io/ws` | WEBSOCKET | Live Price Data (WebSocket) |

## Making Requests

### REST Endpoints (POST)

Most endpoints use POST with a JSON body:

```bash
curl -X POST https://api.prixe.io/api/last_sold \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL"}'
```

### REST Endpoints (GET)

Some endpoints use GET with query parameters:

```bash
curl -X GET "https://api.prixe.io/api/forms?ticker=AAPL&year=2024" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### WebSocket

Connect to `wss://ws.prixe.io/ws?api_key=YOUR_API_KEY` and send JSON messages to subscribe to real-time price data.

## Rate Limits

Rate limits depend on your subscription plan:

| Plan | Hourly | Daily |
|---|---|---|
| Free | 100 | 100 |
| Pro | 1,000 | 10,000 |
| Pro+ | 36,000 | 864,000 |
| Enterprise | Custom | Custom |

To see your current usage, pass `include_limits=true` in any `/api/` request. The response will include a `rate_limit` object.

## Error Handling

All errors return JSON:

```json
{"error": "description of what went wrong"}
```

Common status codes:
- **400** — Bad request (missing/invalid parameters)
- **401** — Unauthorized (missing or invalid API key)
- **429** — Rate limit exceeded (wait and retry)
- **500** — Server error (retry after a moment)

## Tips for AI Agents

- **Always validate ticker symbols** before making calls. Use `/api/search` to verify a ticker exists.
- **Check rate limits** by including `include_limits=true` in your requests.
- **Use callbacks** — most POST endpoints accept a `callback_url` parameter for async webhook delivery.
- **Paginate large results** — `/api/forms` (POST) supports `limit` and `offset` parameters.
- **Date formats** — `/api/price` accepts both Unix timestamps (integer) and `YYYY-MM-DD` strings.
- **Multi-ticker requests** — `/api/price` supports up to 20 tickers at once with the `tickers` array (Pro+ only).
- **AI summaries** — pass `ai_summary=true` on `/api/news`, `/api/forms`, and `/api/board_members` for AI-generated summaries.
- **Interval limits** — 1-minute data is only available for the last ~7 days; hourly for ~2 years; daily has full history.

## Documentation Endpoints

These `/mcp/` routes are unauthenticated and return `text/markdown`:

- `GET /mcp/` — Full endpoint index
- `GET /mcp/instructions` — This page (how to use the API)
- `GET /mcp/<slug>` — Detailed docs for a specific endpoint