# Polaris Agent API — Integration Guide

This document describes how to connect an AI agent (Claude, ChatGPT, or any tool that can make HTTP requests) to your Polaris account so it can read your cashflow data — accounts, balances, upcoming income/payments, and 90-day projections.

**If you're an AI agent reading this**: everything you need is below — the base URL, how to authenticate, every available endpoint with example requests and responses, rate limits, and error handling. You can implement this as tool calls / function calling directly from this document.

**If you're a person**: get an API key from the Polaris app first (**Settings → Agent Access → Create API Key**), then hand this whole document plus your key to your AI agent and ask it to help you build whatever you're trying to do (a dashboard, a Slack bot, a daily balance summary, etc.).

---

## 1. Base URL

```
https://us-central1-polaris-cdf95.cloudfunctions.net/agentApi
```

Every endpoint below is relative to this, under `/v1`. For example, the accounts endpoint is:

```
https://us-central1-polaris-cdf95.cloudfunctions.net/agentApi/v1/accounts
```

## 2. Authentication

Every endpoint except `/v1/health` requires an API key, sent as a Bearer token:

```
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Keys are created in the Polaris app (**Settings → Agent Access**) and are shown exactly once at creation — if you lose it, revoke it and create a new one. A key is scoped to:
- **Read or Read & Write** — as of today, **no write endpoints exist yet**, so this doesn't currently change what a key can do. It will matter once writes ship.
- **Specific accounts, or "All accounts"** — a key can never see more than the person who created it can see in the app, even if it's scoped to "all."

A missing, invalid, or revoked key gets a `401`.

## 3. Quick start

```bash
curl -H "Authorization: Bearer pk_live_..." \
  https://us-central1-polaris-cdf95.cloudfunctions.net/agentApi/v1/context
```

That one call returns a complete snapshot — accounts, recent transactions, recurring items, and a 90-day cashflow projection — which is usually all an agent needs to answer questions like *"what's my balance going to look like this month?"* or *"what bills are coming up?"*.

## 4. Endpoints

All responses are JSON. All require the `Authorization` header shown above, except `/v1/health`.

### `GET /v1/health`

No auth required. Confirms the API is up.

```json
{ "ok": true, "version": "v1" }
```

### `GET /v1/me`

Confirms your key works and shows what it's scoped to.

```json
{
  "apiKeyId": "aBcD123",
  "apiKeyName": "Claude Desktop",
  "scope": "read",
  "accountIds": "all"
}
```

### `GET /v1/accounts`

Every account the key can see.

```json
{
  "accounts": [
    {
      "id": "abc123",
      "name": "Main Checking",
      "type": "checking",
      "currentBalance": 4235.10,
      "currency": "USD",
      "institution": "Chase"
    },
    {
      "id": "def456",
      "name": "Amex Platinum",
      "type": "credit_card",
      "currentBalance": -812.44,
      "currency": "USD",
      "institution": "American Express"
    }
  ]
}
```

`type` is one of `checking`, `savings`, `credit_card`.

### `GET /v1/projections`

The 90-day cashflow projection — day-by-day checking balance, plus income/payment events scheduled on each day.

**Query parameters** (both optional):
- `days` — how many days to return, 1–90. Defaults to 90.
- `accountId` — scope the projection to one account instead of everything the key can see. Must be an account the key has access to, or this returns `403`.

```bash
curl -H "Authorization: Bearer pk_live_..." \
  "https://.../agentApi/v1/projections?days=30"
```

```json
{
  "days": 30,
  "summary": {
    "currentBalance": 4235.10,
    "endingBalance": 3902.55,
    "lowestBalance": 1204.30,
    "lowestBalanceDate": "2026-10-14",
    "totalIncome": 6200.00,
    "totalExpenses": 6532.55,
    "netCashflow": -332.55
  },
  "timeline": [
    {
      "date": "2026-09-27",
      "checkingBalance": 4235.10,
      "projectedIncome": 0,
      "projectedExpenses": 0,
      "events": []
    },
    {
      "date": "2026-10-01",
      "checkingBalance": 3235.10,
      "projectedIncome": 0,
      "projectedExpenses": 1200,
      "events": [
        { "type": "expense", "description": "Rent", "amount": 1200, "accountName": "Main Checking" }
      ]
    }
  ]
}
```

`events[].type` is one of `income`, `expense`, `credit_card_payment`, `investment`.

Note: for credit card accounts, this assumes the full current balance is already reflected in the next statement unless Polaris has separately learned your card's actual statement balance from a linked bank connection — day-to-day accuracy for manually-tracked cards may be approximate.

### `GET /v1/context`

Everything at once: accounts, recent transactions, recurring items, and the projection — the same shape the in-app AI assistant uses.

```json
{
  "accounts": [ { "id": "...", "name": "...", "type": "checking", "balance": 4235.10, "currency": "USD", "institution": "Chase" } ],
  "recentTransactions": [
    { "id": "...", "date": "2026-09-20", "description": "Whole Foods", "amount": -84.21, "category": "Food & Dining", "accountName": "Main Checking" }
  ],
  "recurringItems": [
    { "id": "...", "type": "income", "description": "Salary", "amount": 3200, "frequency": "biweekly", "accountName": "Main Checking", "enabled": true }
  ],
  "projectionSummary": { "currentBalance": 4235.10, "endingBalance": 3902.55, "totalIncome": 6200, "totalExpenses": 6532.55, "netCashflow": -332.55 },
  "projectionTimeline": [ { "date": "2026-09-27", "checkingBalance": 4235.10, "projectedIncome": 0, "projectedExpenses": 0, "events": [] } ],
  "currentDate": "2026-09-27",
  "currentDateTime": "2026-09-27T14:32:00.000Z",
  "timezone": "UTC",
  "snapshot": {
    "accounts": { "totalBalance": 3422.66, "totalCheckingBalance": 4235.10, "totalSavingsBalance": 0, "totalCreditCardBalance": -812.44, "accountCountByType": { "checking": 1, "savings": 0, "credit_card": 1 } },
    "transactions": { "count": 50, "dateRangeStart": "2026-08-10", "dateRangeEnd": "2026-09-20", "totalIncome": 3200, "totalExpenses": 1450.30, "netFlow": 1749.70, "topExpenseCategories": [ { "category": "Food & Dining", "amount": 420.10 } ] },
    "recurring": { "totalCount": 6, "enabledCount": 5, "estimatedMonthlyIncome": 6400, "estimatedMonthlyExpenses": 5100, "estimatedMonthlyNet": 1300 },
    "projections": { "days": 90, "startDate": "2026-09-27", "endDate": "2026-12-25" }
  }
}
```

`timezone` is currently always `"UTC"` (there's no per-request timezone to read server-side) — `currentDate`/`currentDateTime` are still correct, just not localized. `projectionTimeline` here is capped at 60 days; use `/v1/projections` directly if you need the full 90.

## 5. Rate limits

Per API key, two tiers:
- **Burst**: 30 requests/minute
- **Daily**: 2,000 requests/day for reads (writes, once they exist, will be capped tighter)

Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers. Going over either limit returns `429` with a `Retry-After` header (seconds to wait) — back off and retry rather than hammering it.

## 6. Errors

Non-2xx responses look like:

```json
{ "error": { "code": "unauthorized", "message": "Invalid API key." } }
```

| Status | Meaning |
|---|---|
| 401 | Missing, invalid, or revoked API key |
| 403 | The key doesn't have access to the account you asked about |
| 404 | Not found |
| 429 | Rate limited — see `Retry-After` |
| 500 | Something went wrong on our end |

## 7. What this can't do yet

Being upfront about current limits, since an agent (or the person directing it) might otherwise assume more is possible:
- **Read-only.** There's no way to add/edit transactions or recurring items through this API yet, regardless of a key's "Read & Write" setting.
- **No per-account transaction history endpoint.** `/v1/context` includes your 50 most recent transactions across all accounts the key can see, but there's no way to page further back or filter by a single account yet.
- **No recurring-items-only endpoint.** They're included in `/v1/context`, but there's no standalone list.

## 8. Suggested agent tools

If you're an AI agent (or building one) and want to expose this as discrete tools rather than raw HTTP calls, here's a reasonable mapping:

| Tool name | Maps to | Use for |
|---|---|---|
| `get_accounts` | `GET /v1/accounts` | "What accounts do I have / what are my balances?" |
| `get_cashflow_projection` | `GET /v1/projections?days=&accountId=` | "What will my balance be on [date]?" / "Do I have enough for X?" |
| `get_financial_context` | `GET /v1/context` | Anything broader — spending patterns, recurring bills, general "how am I doing" questions |
| `check_agent_connection` | `GET /v1/me` | Verifying a key works before doing anything else |

For each, pass the API key as a fixed `Authorization` header rather than asking the model to supply it per-call.