Skip to Content
Coinio

API

The endpoints meant for use outside the web app.

Coinio's web app talks to its own internal API with a session cookie. Those endpoints can change between versions and are not documented as a public interface. Three endpoints are stable and meant for other tools:

EndpointAuthUsed by
GET /api/healthnoneHealth checks
GET /api/widgetAPI keyThe iPhone widget and your own scripts
POST /mcpAPI key or OAuthMCP clients

API keys

Create keys in Settings › Integrations › API keys and send them as a bearer token:

COINIO_KEY=coi_read_...   # your key
curl -H "Authorization: Bearer $COINIO_KEY" https://coinio.example.com/api/widget
  • Read only keys (coi_read_...) can read. Full access keys (coi_full_...) can also change data through MCP.
  • A key is shown once. Coinio stores only a hash of it, and the list shows each key's prefix and when it was last used.
  • Revoking a key takes effect immediately.

Errors are JSON:

StatusBodyMeaning
401{"error":"unauthorized"}No Authorization header.
401{"error":"invalid_token"}Unknown or revoked key.
403{"error":"insufficient_scope"}The key does not have the access needed.

Health

curl https://coinio.example.com/api/health
{ "ok": true, "version": "0.1.0" }

No authentication. The Docker image's health check calls it.

Widget

GET /api/widget returns a short summary in your main currency: what is left this month, the monthly average and the next six payments (overdue ones first). Any key works.

{
  "base": "USD",
  "leftThisMonthMinor": 9196,
  "monthlyAverageMinor": 14344,
  "ratesStale": false,
  "items": [
    {
      "subscriptionId": 6,
      "name": "Home internet",
      "logoPath": null,
      "dueDate": "2026-11-17",
      "daysLeft": -2,
      "amountMinor": 4499,
      "currency": "USD",
      "baseMinor": 4499,
      "autoPay": false,
      "variableAmount": false,
      "reminderDays": 1
    }
  ],
  "generatedAt": "2026-11-19T22:33:10.000Z"
}
FieldMeaning
baseMain currency.
leftThisMonthMinorOverdue plus still due this month, in the main currency.
monthlyAverageMinorAverage monthly cost of active subscriptions.
ratesStaletrue when exchange rates are more than 4 days old.
items[].daysLeftDays until the due date; negative means overdue.
items[].amountMinor, currencyAmount in the subscription's own currency.
items[].baseMinorThe same in the main currency, or null when there is no exchange rate.
generatedAtWhen the response was made (ISO 8601, UTC).

Amounts ending in Minor are integers in cents: 9196 is 91.96.

MCP

POST /mcp is a stateless MCP server over streamable HTTP. The tools and sign-in options are on the MCP page. A quick test with a key (COINIO_KEY set as above):

curl -X POST https://coinio.example.com/mcp \
  -H "Authorization: Bearer $COINIO_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Edit on GitHub

On this page