> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/en/api-reference/public-api.md).

# Public API

External API for accessing financial data, stock prices, news, and research reports.

## Authentication

All Public API endpoints require authentication via API key.

### Getting an API Key

1. Log in to your account
2. Navigate to Settings > API Keys
3. Create a new API key with the required scopes
4. Save the key securely (it's only shown once)

### Using the API Key

Include your API key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: ak_your_api_key_here" \
     https://api.alpha-lenz.com/api/public/v1/financial/companies
```

## Available Scopes

| Scope            | Description                   |
| ---------------- | ----------------------------- |
| `read:all`       | Full read access to all APIs  |
| `read:financial` | Access to financial data APIs |
| `read:stock`     | Access to stock price APIs    |
| `read:news`      | Access to news APIs           |

## Rate Limits

Default rate limits: **1,000 requests per hour**

Custom rate limits can be configured per API key.

## Base URL

```
https://api.alpha-lenz.com/api/public/v1
```

## API Endpoints

### Basic Financial API (Twelve Data-style)

Simple and intuitive financial data access:

* `GET /api/v1/financial-v4/time-series` - Historical OHLCV price data
* `GET /api/v1/financial-v4/profile` - Company profile and information
* `GET /api/v1/financial-v4/fundamentals` - Financial ratios and metrics

**Note:** Basic Financial API supports optional authentication (trial mode available)

### Financial Data

* `GET /financial/companies` - List companies
* `GET /financial/companies/{symbol}` - Get company details
* `GET /financial/companies/{symbol}/financials` - Get financial statements

### Stock Prices

* `GET /stock/prices/{symbol}` - Get current prices
* `GET /stock/prices/{symbol}/history` - Get historical prices

### News

* `GET /news/articles` - List news articles
* `GET /news/articles/{id}` - Get article details
* `GET /news/articles/{id}/content` - Get full content

## Error Responses

All errors follow this format:

```json
{
  "detail": "Error message"
}
```

### Common Status Codes

| Code | Description                |
| ---- | -------------------------- |
| 401  | Invalid or missing API key |
| 403  | Insufficient scope         |
| 404  | Resource not found         |
| 429  | Rate limit exceeded        |
| 500  | Server error               |