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

# Introduction

> Overview of the Vings External API — base URL, surfaces, and OpenAPI.

The **Vings External API** is the developer surface of the Vings financial intelligence platform—a readonly service. Authenticated clients can read their own financial data through versioned REST endpoints and a Model Context Protocol (MCP) server.

## Base URL

All API routes use the `/api` prefix:

```
https://external.vin.gs/api
```

Examples:

* `GET https://external.vin.gs/api/v1/me`
* `POST https://external.vin.gs/api/mcp`

## What you can build

| Surface                | Purpose                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **REST (`/api/v1/*`)** | Direct JSON for agents, scripts, and integrations                                        |
| **MCP (`/api/mcp`)**   | JSON-RPC tools for ChatGPT, Claude, and other MCP clients                                |
| **OpenAPI**            | Machine-readable spec at [`/api/openapi.json`](https://external.vin.gs/api/openapi.json) |

Every `/api/v1` route and the MCP endpoint require a bearer token. See [Authentication](/external/docs/authentication).

## Readonly by design

V1 exposes **read** operations only. There are no mutations, sync jobs, or privileged admin paths on this host. Financial responses use `Cache-Control: no-store`.

## Health and metadata

| Endpoint                | Description                           |
| ----------------------- | ------------------------------------- |
| `GET /api/health`       | Liveness                              |
| `GET /api/ready`        | Readiness (environment configuration) |
| `GET /api/openapi.json` | OpenAPI 3.1 document                  |

Use the **API Reference** tab for interactive docs and the playground generated from that OpenAPI document.

## REST overview

Versioned routes under `/api/v1`:

* `GET /v1/me` — current user and API capabilities
* `GET /v1/transactions` — cursor-paginated transaction search
* `GET /v1/cashflow/summary`, `/v1/spending/summary`, `/v1/spending/categories`, `/v1/spending/merchants/top`
* `GET /v1/recurring-payments`
* `GET /v1/budgets/categories`, `/v1/budgets/summary`
* `GET /v1/banks/status`
* `GET /v1/portfolio`, `/v1/portfolio/history`
* `GET /v1/preferences`

`GET /v1/transactions` is the single search endpoint (advanced filters; `showInternalTransfers` defaults to `false`).

## MCP overview

The MCP server lives at `POST /api/mcp` with JSON-RPC 2.0. Transport methods (`initialize`, `tools/list`, `tools/call`, etc.) are documented in OpenAPI; per-tool **input** and **output** JSON Schemas come from `tools/list`, not from OpenAPI. See [MCP](/external/docs/mcp).

## Next steps

1. [Authenticate](/external/docs/authentication) your requests.
2. Explore endpoints in **API Reference** or try `GET /v1/me` in the playground.
3. Building in v0, Lovable, or your own app? See [Personal dashboards](/external/docs/personal-dashboards).
4. For MCP clients, follow [MCP](/external/docs/mcp).