Skip to content

API Reference

This page describes the FintraOS HTTP API: authentication, conventions, endpoints, and example requests. It is designed to be stable, explicit, and developer-first.

Base URL, Headers, and Auth

These conventions apply to all endpoints.

  • Base URL (local): http://localhost:8080/
  • Required headers:
  • x-tenant-id: <tenant_id>
  • content-type: application/json
  • Optional header (when enabled):
  • x-api-key: <api_key>

Conventions

  • Timestamps: ISO‑8601 UTC (for example 2026-03-31T18:00:00Z)
  • Money:
  • Minor units in event payloads (*_minor as integers)
  • Read models may return human-readable decimal strings where noted
  • Determinism:
  • Read models are built from events
  • Explanations and metrics include provenance to a stream position (for example a source_event_id and source_version)
  • SSE:
  • For streaming endpoints, include ?tenant_id=<tenant_id> in the URL because browsers cannot set custom headers on EventSource

Errors

All errors return a stable JSON envelope:

{ "error": { "code": "INTERNAL", "message": "failed to ...", "details": null } }

Ingest (Connect)

POST /v1/connect/import/json

Submit an identity-shape JSON payload to stage an import.

  • Body: { accounts[], transactions[], positions?, manual_assets? }
  • Response: { "import_job_id": "<uuid>" }

POST /v1/connect/import/{import_job_id}/approve

Commit staged data to events and enqueue a rebuild pipeline.

  • Response: { "import_job_id": "...", "status": "committed", "committed": true, "source_event_id": "...", "source_version": <int>, "job_id": "<uuid>" }

Views (Read APIs)

  • GET /v1/profile/{profile_id}
  • GET /v1/profile/{profile_id}/transactions?from=&to=&category_l1=&merchant=
  • GET /v1/profile/{profile_id}/intelligence
  • GET /v1/profile/{profile_id}/recurring
  • GET /v1/profile/{profile_id}/patterns
  • GET /v1/profile/{profile_id}/positions
  • GET /v1/profile/{profile_id}/projections
  • GET /v1/profile/{profile_id}/projection/{name}

Pricing Refresh

POST /v1/profile/{profile_id}/pricing/refresh

Fetch live quotes for held symbols, store as events, rebuild projections, and expose pricing_cache for use by UI and AI.

  • Response includes unpriced[] so missing quotes and base-currency conversion issues are visible, not silent.

AI Gateway

POST /v1/ai/query

  • Input: { "profile_id": "...", "question": "...", "persona_id": "...", "detail_level": "concise|normal|deep" }
  • Output: { "answer_summary": "...", "key_numbers": [], "reasoning": [], "sources": [], "actions": [] }

Examples

These examples use environment variables for clarity:

API="http://localhost:8080"
TENANT="org_demo"
PROFILE="fresh_1"

1) Import JSON then approve

curl -sS -X POST "$API/v1/connect/import/json" \
  -H "x-tenant-id: $TENANT" -H "content-type: application/json" \
  -d @testdata/ingest/mock_uk_tax_year_2025_2026.json | jq

curl -sS -X POST "$API/v1/connect/import/<IMPORT_ID>/approve" \
  -H "x-tenant-id: $TENANT" | jq

2) Fetch intelligence

curl -sS "$API/v1/profile/$PROFILE/intelligence" \
  -H "x-tenant-id: $TENANT" | jq

3) Ask the AI a question

curl -sS -X POST "$API/v1/ai/query" \
  -H "x-tenant-id: $TENANT" -H "content-type: application/json" \
  -d '{ "profile_id": "'"$PROFILE"'", "question": "What is my net worth and runway?", "persona_id": "moderate_coach", "detail_level": "normal" }' | jq