# Getting started

> Welcome to the Bavest API. Get a key, make your first v2 request and find the data or AI integration you need.

Use the Bavest v2 API to build with financial data: equities, ETFs, funds, corporate actions, news and portfolio analytics. Browse the reference without signing in; requests need your API key and count against its plan.

Start with a connectivity check, then open the reference for the data your application needs. Examples here use v2 exclusively.

## 1. Get your API key

[Create an account](https://dashboard.bavest.co/sign-up) to get a key, or [sign in](https://dashboard.bavest.co/sign-in) to use your existing account. Keep the key on your server in the `BAVEST_API_KEY` environment variable.

Every request uses the `x-api-key` header. The [authentication guide](https://docs.bavest.co/docs/authentication) covers trial access, quotas, errors and key rotation.

## 2. Make your first request

Call [API Status](https://docs.bavest.co/docs/v2_account_status) to check connectivity. The example JSON below comes from the shared API specification; timestamps and processing times in a real response can differ.

Example response:

```json
{
  "data": {
    "status": "active",
    "version": "v2"
  }
}
```

Send the request:

```bash
curl 'https://api.bavest.co/v2/account/status' \
  -H "x-api-key: $BAVEST_API_KEY"
```

Base URL: `https://api.bavest.co/v2`. Most data endpoints return JSON with a `data` field. Logo and document downloads return images or PDF; MCP uses JSON-RPC. Each reference page documents its response type.

## 3. Find your data

- [Equities](https://docs.bavest.co/docs#group-equities): company profiles, metrics and financial statements
- [ETFs and funds](https://docs.bavest.co/docs#group-etfs): profiles, holdings, exposure and risk; use ISINs to identify share classes
- [Earnings transcripts](https://docs.bavest.co/docs/v2_corporate_actions_earnings_transcript): response JSON, request examples and a transcript reader
- [Portfolio analytics](https://docs.bavest.co/docs#group-bavest-quantos): allocation, returns and risk
- [All API routes](https://docs.bavest.co/docs): parameters, response fields, examples and plan availability

Use the identifier and reporting period documented for each endpoint. Where a route requires one of `symbol` and `isin`, send exactly one. Read field-level coverage and data-quality notes before using a value in calculations.

## 4. Try a route and handle errors

On a reference page, paste your own key to send a request, or sign in to use your account's key in the dashboard. Keep keys out of shared URLs, source code and screenshots.

- `401` or `403`: check the key and its access. Repeating the same refused request will not fix it.
- `429` with `Limit Exceeded`: your monthly quota is used up. Other `429` responses can indicate throttling or a route outside your plan; check access and respect `Retry-After` when provided.
- Check remaining usage with [Usage Quota](https://docs.bavest.co/docs/v2_account_quota).

## AI clients and resources

- [Connect an AI client with MCP](https://docs.bavest.co/docs/mcp): Claude, Codex, Windsurf, Cursor and OpenClaw examples
- [Changelog](https://docs.bavest.co/changelog): API changes and migration guidance
- [Markdown index](https://docs.bavest.co/llms.txt): links to current machine-readable documentation
- [Full documentation](https://docs.bavest.co/llms-full.txt): the current reference in one text file
- [OpenAPI JSON](https://docs.bavest.co/openapi.json): for integrations and schema tooling
- [OpenAPI YAML](https://docs.bavest.co/openapi.yaml): the same public schema

Use explicit `.md` links for Markdown downloads. The static Docs host serves HTML at page URLs and Markdown at their `.md` twins.

---

HTML version: https://docs.bavest.co/docs/getting-started. Docs index for agents: https://docs.bavest.co/llms.txt. OpenAPI: https://docs.bavest.co/openapi.json.
