> ## Documentation Index
> Fetch the complete documentation index at: https://hevninc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

> REST endpoints used internally by HEVN CLI.

This section has two API reference layers:

* **Generated API Reference** is powered by the live HEVN OpenAPI schema from `https://api.hevn.finance/openapi.json` and enables Mintlify's endpoint pages, request examples, and interactive API Playground.
* **CLI wrapper notes** live in the CLI tab and document the REST endpoints that the current CLI calls through `src/hevn_cli/api/*`.

## Base URL

The generated OpenAPI reference uses:

```bash theme={null}
https://api.hevn.finance
```

The CLI builds requests from the configured API base URL:

```bash theme={null}
https://api.hevn.finance/api/v1
```

The base URL can be selected through `HEVN_ENV`, saved login config, or `HEVN_BASE_URL`.

```bash theme={null}
export HEVN_ENV=prod
export HEVN_BASE_URL=https://api.hevn.finance/api/v1
```

## API clients

| Client      | Source                       | Auth mode         | Used for                                                                            |
| ----------- | ---------------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| `AppApi`    | `src/hevn_cli/api/app.py`    | HEVN API key      | Account, profile, contacts, invoices, contracts, banks, cards, quotes, transactions |
| `McpApi`    | `src/hevn_cli/api/mcp.py`    | Same HEVN API key | Balance, API-key introspection, and app-scoped transfers                            |
| `PublicApi` | `src/hevn_cli/api/public.py` | Public            | FX rates and public invoices                                                        |

## Request behavior

All requests:

* send `Accept: application/json`,
* send the configured API key for authenticated clients,
* use a 60 second HTTP timeout,
* send query parameters only when their values are not `None`,
* parse non-empty responses as JSON,
* raise a CLI `HevnError` for HTTP status codes `>= 400`.

When `--debug` or `HEVN_DEBUG=1` is enabled, error output can include the generated curl command.

Mutating HTTP methods (`POST`, `PUT`, `PATCH`, `DELETE`) are intercepted by `--dry-run` / `HEVN_DRY_RUN=1` before the network call is made.

## Common response handling

The CLI does not enforce a shared backend response schema across endpoints. It passes backend JSON through to command formatters and wraps `--json` / `--yaml` command output in a CLI envelope.

For integration code, use the endpoint-specific objects returned by the backend and treat fields shown in command output as convenience projections rather than exhaustive schemas.

## Endpoint index

<CardGroup cols={2}>
  <Card title="Authentication" icon="key-round" href="/api-reference/authentication">
    Header modes, login config, and idempotency headers.
  </Card>
</CardGroup>