{
  "openapi": "3.0.3",
  "info": {
    "title": "IBANgen API",
    "version": "2026-08-18",
    "description": "API-key authenticated synthetic IBAN, bank intelligence, dataset, and bank-statement QA endpoints. All generated identities are synthetic."
  },
  "servers": [{"url": "https://ibangen.com/api/v1"}],
  "security": [{"ApiKeyAuth": []}],
  "components": {
    "securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key"}},
    "schemas": {
      "Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "string"}, "message": {"type": "string"}, "request_id": {"type": "string"}}},
      "GenerateRequest": {"type": "object", "required": ["country"], "properties": {"country": {"type": "string", "example": "Germany"}, "quantity": {"type": "integer", "minimum": 1, "maximum": 100, "default": 1}, "seed": {"type": "string"}, "include_bank_details": {"type": "boolean"}, "targeting": {"type": "object", "properties": {"city": {"type": "string"}, "bank": {"type": "string"}, "bic": {"type": "string"}}}}},
      "ValidateRequest": {"type": "object", "required": ["ibans"], "properties": {"ibans": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "string"}}}},
      "ProfileRequest": {"type": "object", "properties": {"country": {"type": "string", "default": "Random", "example": "Germany"}, "iban": {"type": "string"}, "additional_info": {"type": "object", "additionalProperties": true}}},
      "TestCasesRequest": {"type": "object", "required": ["country"], "properties": {"country": {"type": "string", "example": "Germany"}, "quantity": {"type": "integer", "minimum": 1, "maximum": 25, "default": 20}, "seed": {"type": "string", "maxLength": 80}, "output": {"type": "string", "enum": ["json", "csv"], "default": "json"}}},
      "StatementReview": {"type": "object", "required": ["success", "status", "review_id"], "properties": {"success": {"type": "boolean"}, "status": {"type": "string", "enum": ["pending_analysis", "completed", "analysis_failed"]}, "review_id": {"type": "string"}, "review_step": {"type": "string"}, "retention": {"type": "object"}, "score": {"type": "integer"}, "risk_level": {"type": "string"}}},
      "BulkDatasetRequest": {"type": "object", "required": ["country"], "properties": {"country": {"type": "string", "example": "Germany"}, "quantity": {"type": "integer", "minimum": 1, "default": 10}, "seed": {"type": "string", "maxLength": 80}, "output": {"type": "string", "enum": ["json", "csv"], "default": "json"}, "include_bank_details": {"type": "boolean", "default": true}, "include_profiles": {"type": "boolean", "default": false}}},
      "BulkDatasetResponse": {"type": "object", "required": ["success", "rows"], "properties": {"success": {"type": "boolean"}, "rows": {"type": "array", "items": {"type": "object"}}, "limit": {"type": "integer"}}},
      "BankIdentifier": {"type": "object", "required": ["value"], "properties": {"value": {"type": "string", "maxLength": 128, "example": "DEUTDEFF"}, "type": {"type": "string", "maxLength": 40, "example": "bic"}}},
      "BankIntelligenceLookupRequest": {"type": "object", "properties": {"value": {"type": "string", "description": "Single identifier shortcut."}, "type": {"type": "string"}, "identifiers": {"type": "array", "maxItems": 1000, "items": {"$ref": "#/components/schemas/BankIdentifier"}}}},
      "BankIntelligenceSearchRequest": {"type": "object", "required": ["query"], "properties": {"query": {"type": "string", "minLength": 2, "maxLength": 120, "example": "Sparkasse"}, "country_code": {"type": "string", "minLength": 2, "maxLength": 2, "example": "DE"}, "source_id": {"type": "string"}, "record_type": {"type": "string"}, "status": {"type": "string"}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 25}}},
    "BankIntelligenceResponse": {"type": "object", "properties": {"success": {"type": "boolean"}, "results": {"type": "array", "items": {"type": "object"}}, "record": {"type": "object"}, "count": {"type": "integer"}, "registry_generated_at": {"type": "string", "format": "date-time"}, "charged_api_credits": {"type": "integer"}}},
      "FixtureManifestRequest": {"type": "object", "required": ["fixtures"], "properties": {"fixture_id": {"type": "string"}, "seed": {"type": "string"}, "registry_snapshot": {"type": "string"}, "fixtures": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"type": "object"}}, "sources": {"type": "array", "items": {"type": "object"}}, "schemas": {"type": "array", "items": {"type": "object"}}, "expected_outcomes": {"type": "array", "items": {"type": "string"}}}},
      "FixtureManifestResponse": {"type": "object", "required": ["success", "manifest", "verification"], "properties": {"success": {"type": "boolean"}, "manifest": {"type": "object", "description": "May include an Ed25519 signature when protected signing configuration is enabled."}, "verification": {"type": "object", "properties": {"valid": {"type": "boolean"}, "signed": {"type": "boolean"}, "signature_key_id": {"type": "string"}}}}},
      "PaymentScenarioRequest": {"type": "object", "properties": {"scenario": {"type": "string"}, "country": {"type": "string", "example": "DE"}, "bank_target": {"type": "string"}, "amount": {"type": "string", "example": "1250.00"}, "currency": {"type": "string", "example": "EUR"}, "payment_path": {"type": "string", "example": "sepa_credit_transfer"}, "vop_outcome": {"type": "string", "enum": ["MATCH", "CLOSE_MATCH", "NO_MATCH", "NOAP", "REJECTED"]}, "seed": {"type": "string"}}},
      "PaymentScenarioResponse": {"type": "object", "required": ["success", "scenario"], "properties": {"success": {"type": "boolean"}, "scenario": {"type": "object"}}}
    }
  },
  "paths": {
    "/generate": {"post": {"summary": "Generate synthetic IBANs", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerateRequest"}}}}, "responses": {"200": {"description": "Generated rows"}, "400": {"description": "Stable validation error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Invalid API key"}, "429": {"description": "Quota exhausted"}}}},
    "/validate": {"post": {"summary": "Validate IBANs", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ValidateRequest"}}}}, "responses": {"200": {"description": "Validation rows"}, "400": {"description": "Invalid request"}, "401": {"description": "Invalid API key"}, "429": {"description": "Quota exhausted"}}}},
    "/bank-intelligence/lookup": {"post": {"summary": "Resolve bank identifiers", "description": "Look up BIC, domestic identifiers or other supported registry values. Send one value/type pair or an identifiers array; plan limits and provenance fields are applied server-side.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceLookupRequest"}}}}, "responses": {"200": {"description": "Matched registry records", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceResponse"}}}}, "400": {"description": "Invalid identifier list or plan limit"}, "401": {"description": "Invalid API key"}, "429": {"description": "API credits exhausted"}}}},
    "/bank-intelligence/search": {"post": {"summary": "Search the bank intelligence registry", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceSearchRequest"}}}}, "responses": {"200": {"description": "Matching registry records", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceResponse"}}}}, "400": {"description": "Invalid query or limit"}, "401": {"description": "Invalid API key"}, "429": {"description": "API credits exhausted"}}}},
    "/bank-intelligence/record/{record_id}": {"parameters": [{"name": "record_id", "in": "path", "required": true, "schema": {"type": "integer", "minimum": 1}}], "get": {"summary": "Read one bank intelligence record", "responses": {"200": {"description": "Registry record", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceResponse"}}}}, "401": {"description": "Invalid API key"}, "404": {"description": "Record not found"}, "429": {"description": "API credits exhausted"}}}},
    "/bank-intelligence/export": {"post": {"summary": "Export bank intelligence matches as CSV", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceLookupRequest"}}}}, "responses": {"200": {"description": "CSV export", "content": {"text/csv": {"schema": {"type": "string", "format": "binary"}}}}, "400": {"description": "Invalid identifier list"}, "401": {"description": "Invalid API key"}, "402": {"description": "Export access required"}, "429": {"description": "API or export credits exhausted"}}}},
    "/bank-intelligence/sources": {"get": {"summary": "List registry sources and snapshots", "responses": {"200": {"description": "Source provenance rows", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceResponse"}}}}, "401": {"description": "Invalid API key"}, "403": {"description": "Provenance access required"}, "429": {"description": "API credits exhausted"}}}},
    "/bank-intelligence/changes": {"get": {"summary": "List monitored registry changes", "parameters": [{"name": "source_id", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100}}], "responses": {"200": {"description": "Snapshot changes", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BankIntelligenceResponse"}}}}, "401": {"description": "Invalid API key"}, "403": {"description": "Snapshot-diff access required"}, "429": {"description": "API credits exhausted"}}}},
    "/fixture-manifest/spec": {"get": {"summary": "Read the fixture manifest specification", "security": [], "responses": {"200": {"description": "Manifest schema and verification rules"}}}},
    "/fixture-manifest/compile": {"post": {"summary": "Compile a deterministic synthetic fixture manifest", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FixtureManifestRequest"}}}}, "responses": {"200": {"description": "Manifest and verification result", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FixtureManifestResponse"}}}}, "401": {"description": "Invalid API key"}, "402": {"description": "Pro access required"}, "400": {"description": "Invalid fixture list"}, "429": {"description": "API credits exhausted"}}}},
    "/payment-scenarios/catalog": {"get": {"summary": "List supported payment scenario schemas", "security": [], "responses": {"200": {"description": "Scenario catalog"}}}},
    "/payment-scenarios/compile": {"post": {"summary": "Compile a stateful synthetic payment scenario", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaymentScenarioRequest"}}}}, "responses": {"200": {"description": "Structured scenario artifact", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PaymentScenarioResponse"}}}}, "401": {"description": "Invalid API key"}, "402": {"description": "Business access required"}, "400": {"description": "Invalid scenario"}, "429": {"description": "API credits exhausted"}}}},
    "/statement-validator/analyze": {"post": {"summary": "Queue one bank statement review", "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["statement_file"], "properties": {"statement_file": {"type": "string", "format": "binary"}, "expected_bank": {"type": "string"}, "expected_bank_slug": {"type": "string"}}}}}}, "responses": {"202": {"description": "Queued review", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StatementReview"}}}}, "400": {"description": "Invalid file"}, "401": {"description": "Invalid API key"}, "429": {"description": "Statement quota exhausted"}}}},
    "/statement-validator/review/{review_id}": {"parameters": [{"name": "review_id", "in": "path", "required": true, "schema": {"type": "string"}}], "get": {"summary": "Poll a statement review", "responses": {"202": {"description": "Still processing"}, "200": {"description": "Completed report", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StatementReview"}}}}, "404": {"description": "Review not owned by API key"}}}, "delete": {"summary": "Delete a statement review and upload", "responses": {"200": {"description": "Deleted"}, "404": {"description": "Review not found"}}}},
    "/profile": {"post": {"summary": "Generate a synthetic QA profile", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProfileRequest"}}}}, "responses": {"200": {"description": "Profile"}, "401": {"description": "Invalid API key"}, "403": {"description": "Manual Enterprise review required"}, "429": {"description": "Quota exhausted"}, "503": {"description": "Profile provider unavailable"}}}},
    "/bulk-dataset": {"post": {"summary": "Build a QA dataset", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkDatasetRequest"}}}}, "responses": {"200": {"description": "Dataset", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkDatasetResponse"}}}}, "402": {"description": "Paid access required"}, "429": {"description": "Quota exhausted"}}}},
    "/test-cases": {"post": {"summary": "Build IBAN edge-case fixtures", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TestCasesRequest"}}}}, "responses": {"200": {"description": "Test cases"}, "400": {"description": "Invalid country or output"}, "401": {"description": "Invalid API key"}, "429": {"description": "Quota exhausted"}}}}
  }
}