# Alva API Docs

Alva API docs collect the public developer resources, OpenAPI discovery document, authentication notes, MCP metadata, and integration safety rules that AI agents should read before calling Alva.

## Public discovery URLs

- API docs page: https://alva.ai/api-docs
- API docs markdown: https://alva.ai/api-docs.md
- OpenAPI spec: https://alva.ai/openapi.json
- Developer guide: https://alva.ai/developers
- Developer LLM guide: https://alva.ai/developers/llms.txt
- Agent authentication: https://alva.ai/auth.md
- MCP integration notes: https://alva.ai/mcp.md
- Webhook status: https://alva.ai/webhooks.md

## API origin

- API base origin advertised for agents: https://api-llm.prd.alva.ai
- Representative authenticated API surfaces are documented in `/openapi.json`.
- Private account data, billing, brokerage connections, live execution, and playbook writes require user-scoped authentication.

## Authentication model

- Browser users sign in through the Alva web app.
- API examples use `Authorization: Bearer <user_token_or_api_key>`.
- API keys are created by signed-in users at `/apikey`.
- OAuth 2.0/OIDC discovery metadata is not currently advertised publicly; agents should not assume OAuth dynamic client registration until that metadata exists.

## Agent-safe API workflow

1. Fetch `/llms.txt` and `/llms-full.txt` for product context and constraints.
2. Fetch `/openapi.json` to inspect available request and response schemas.
3. Read `/auth.md` before requesting credentials from a user.
4. Use bounded pagination and batch only independent read requests.
5. Require explicit user confirmation before billing, brokerage, live execution, or playbook write actions.

## Error handling

- 400: correct request shape using `/openapi.json`.
- 401: ask the user to sign in or create an API key at `/apikey`.
- 403: explain the missing permission or account state.
- 429: back off using `Retry-After` or `RateLimit-Reset` when present.
- 5xx: stop after a bounded retry budget and report the failed operation.

## Related resources

- [Agent authentication](https://alva.ai/auth.md)
- [MCP integration notes](https://alva.ai/mcp.md)
- [Webhook status](https://alva.ai/webhooks.md)
- [Automated backtesting guide markdown](https://alva.ai/automated-investment-strategy-backtesting.md)
- [Agent sandbox](https://alva.ai/sandbox.md)
- [Agent status page](https://alva.ai/status)