API Reference Overview

How to read the Forbidden Finance API reference — the base URL, the response envelope every endpoint shares, what the reference does not repeat, and where the always-current machine-readable spec lives.

Overview

The pages in this section are generated from the Forbidden Finance OpenAPI specification: every endpoint, every parameter, every schema, with a playground you can call from the browser.

The surface is 40 operations — 29 reads and 11 writes — mounted under /v1 at:

https://api.403fin.io

API access is a Premium feature and is currently in limited beta.

Read the guides first

The reference documents each endpoint in isolation. Four behaviors apply to every endpoint and are explained once, in the guides, rather than repeated on forty pages:

Behavior	Where
Authentication, the response envelope, errors, money encoding, pagination, rate limits	Getting Started with the API
Which scope an operation needs, and the two-switch rule that gates writes	Scopes & Permissions
The mandatory `Idempotency-Key`, `expected_version`, and how each write behaves	Writing Data
Why a field may be missing, a row absent, or a write refused	Data Privacy & Redaction

Three things surprise people who go straight to the reference:

Every write returns 200, including the creates. A replayed response has to be byte-identical to the original, and a replay cannot honestly claim to have created anything.
Every write requires an Idempotency-Key header. There is no way to opt out, and a corrected retry needs a fresh key.
Monetary amounts are decimal strings, never floats. Parse them with a decimal library.

The machine-readable spec

The running server publishes its own specification, unauthenticated, at:

https://api.403fin.io/v1/openapi.json

That document is generated by the server, so it is always current. Point your code generator at it rather than at a copy — including the copy that backs these pages, which is vendored and re-synced by hand.

Getting Started with the API

Auth, envelopes, errors, pagination, and limits.

Scopes & Permissions

The 16 scopes and the two-switch rule.

Writing Data

Every write endpoint, with worked examples.

MCP Server Reference

The same surface, as 40 MCP tools.

Need more help? Contact us at [email protected].

Was this page helpful?