{ "openapi": "3.1.0", "info": { "title": "Bank API", "version": "1.0", "description": "A tiny FinTech sandbox: list accounts, page through transactions with an opaque cursor, and move money with idempotent transfers. Insufficient funds return HTTP 402 Payment Required, frozen accounts 409, and bad amounts 422." }, "servers": [ { "url": "https://funapi.dev/api/bank/v1" } ], "tags": [ { "name": "accounts", "description": "who owns the money" }, { "name": "transactions", "description": "cursor-based pagination" }, { "name": "transfers", "description": "idempotent money movement" }, { "name": "premium", "description": "pay up — 402 on demand" } ], "paths": { "/accounts": { "get": { "tags": [ "accounts" ], "summary": "List accounts", "operationId": "bk-accounts", "responses": { "200": { "description": "Account list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "accounts" ], "summary": "Open a new account", "operationId": "bk-create", "responses": { "201": { "description": "Account opened", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Negative opening deposit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate account.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "string" }, "currency": { "type": "string" }, "deposit": { "type": "integer" } }, "required": [ "owner", "currency", "deposit" ], "additionalProperties": false }, "example": { "owner": "Phoebe Buffay", "currency": "USD", "deposit": 100 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/accounts/{id}": { "get": { "tags": [ "accounts" ], "summary": "Get one account", "operationId": "bk-account", "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id 1–4 (or one you created).", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/accounts/{id}/transactions": { "get": { "tags": [ "transactions" ], "summary": "List transactions (cursor pagination)", "operationId": "bk-txs", "responses": { "200": { "description": "A page of transactions, newest first, plus \"nextCursor\" while more remain", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid cursor or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id. Account 1 has enough history for several pages.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response’s \"nextCursor\". Omit for the first page. An unknown cursor → 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size 1–20, default 3.", "schema": { "type": "integer", "format": "int32" }, "example": 3 } ], "security": [ { "bearerAuth": [] } ] } }, "/transfers": { "post": { "tags": [ "transfers" ], "summary": "Transfer money between accounts", "operationId": "bk-transfer", "responses": { "201": { "description": "Transfer executed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Same account on both sides", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "An account is frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Amount is not a positive number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended for money movement — repeat the same key on retry and the original transfer is replayed instead of double-charging.", "schema": { "type": "string" }, "example": "transfer-2026-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromId": { "type": "integer" }, "toId": { "type": "integer" }, "amount": { "type": "number" }, "note": { "type": "string" } }, "required": [ "fromId", "toId", "amount", "note" ], "additionalProperties": false }, "example": { "fromId": 1, "toId": 2, "amount": 25.5, "note": "pizza night" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/transfers/{id}": { "get": { "tags": [ "transfers" ], "summary": "Look up a transfer", "operationId": "bk-transfer-get", "responses": { "200": { "description": "The transfer", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown transfer id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer id from POST /transfers (5001+).", "schema": { "type": "integer", "format": "int32" }, "example": 5001 } ], "security": [ { "bearerAuth": [] } ] } }, "/accounts/{id}/freeze": { "post": { "tags": [ "accounts" ], "summary": "Freeze an account (admin only)", "operationId": "bk-freeze", "responses": { "200": { "description": "Account frozen", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account to freeze. Account 4 is already frozen → 409.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ], "security": [ { "bearerAuth": [] } ] } }, "/exchange-rates": { "get": { "tags": [ "accounts" ], "summary": "Exchange rates (cacheable, ETag + If-None-Match → 304)", "operationId": "bk-rates", "responses": { "200": { "description": "Rates, with Cache-Control and a stable ETag", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "On the live API: repeat with If-None-Match: \"rates-v1\"", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/premium/statements": { "get": { "tags": [ "premium" ], "summary": "Premium statements — always 402", "operationId": "bk-premium", "responses": { "402": { "description": "Always. Payment Required on demand, like the pizza oven’s 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Cargo demo key: cargo-key-123." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }