# Annualreports — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for and access thousands of international company annual reports in PDF and HTML formats, while filtering by ticker, exchange, industry, sector, company size, and location. Browse company profiles and financial documents across different markets and industries to find the information you need.

**Category:** Finance & Markets | **Website:** [annualreports.com/](https://annualreports.com/) | **Docs:** [parse.bot/marketplace/669d01dd-0233-49c4-9777-38755abc915b/annualreports-com-api](https://parse.bot/marketplace/669d01dd-0233-49c4-9777-38755abc915b/annualreports-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Browse exchanges

List all stock exchanges available for filtering companies. Returns exchange name, full name, numeric ID, and logo URL. Use the returned IDs with search_companies exchange_id parameter.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/browse-exchanges \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Browse industries

List all industries grouped by sector. Each sector contains an array of industries with their IDs for use in search_companies filtering. Returns the complete taxonomy of sectors and industries.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/browse-industries \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get companies by program

Retrieve companies in a featured index program. Returns all companies belonging to the specified program with their name, slug, industry, and sector. Known programs: 9 (REIT), 14 (Russell 1000), 15 (Russell 2000), 16 (Russell Microcap).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `program_id` | string | Yes | Program ID: 9 (REIT), 14 (Russell 1000), 15 (Russell 2000), or 16 (Russell Microcap) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/get-companies-by-program \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"program_id":"<string>"}'
```

### Get company profile

Retrieve a full company profile including metadata (ticker, exchange, industry, sector, employees, headquarters, description, website, rating) and all available annual reports with PDF and HTML links. The slug identifier comes from search_companies results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Company slug from search_companies results (e.g. 'apple-inc') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/get-company-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Search companies

Search for companies by name, ticker, or using filters for exchange, industry, sector, or first letter. Returns matching companies with basic metadata including name, slug, industry, sector, and premium status. At least one filter parameter should be provided. Results are not paginated — the full matching set is returned.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alpha` | string | No | First letter of company name (A-Z or # for numeric) |
| `exchange_id` | string | No | Exchange ID for filtering (use browse_exchanges to get available IDs) |
| `industry_id` | string | No | Industry ID for filtering (use browse_industries to get available IDs, e.g. 'i1') |
| `query` | string | No | Search keyword (company name or ticker symbol) |
| `sector_id` | string | No | Sector ID for filtering |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/annualreports/search-companies \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"alpha":"<string>","exchange_id":"<string>","industry_id":"<string>","query":"<string>","sector_id":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.