{"openapi":"3.1.0","info":{"title":"Nomiq AI Gateway API","version":"1.0.0","description":"Production-grade, multi-provider AI Gateway API serving the Nomiq iOS mobile client. Dynamically powered by admin panel provider configurations with transparent fallback failover, Supabase JWT verification, paid subscription gatekeeping, rate-limit enforcement, and zero-prompt cost telemetry.","contact":{"name":"Nomiq Platform Engineering","url":"https://nomiq.ai"},"license":{"name":"Proprietary","url":"https://nomiq.ai/terms"}},"servers":[{"url":"/","description":"Current Environment"},{"url":"https://api.nomiq.ai","description":"Production Gateway"}],"tags":[{"name":"AI Gateway","description":"Multi-provider unified AI inference operations for iOS client"}],"paths":{"/api/v1/ai/complete":{"post":{"tags":["AI Gateway"],"summary":"Execute AI task inference","description":"Dispatches consumer AI tasks (OCR receipt extraction, transaction categorization, financial chat, and spending insights) through the active configured provider (DeepSeek, OpenAI, Anthropic) with automatic fallback failover upon provider errors or throttling.","operationId":"completeAITask","security":[{"BearerAuth":[]}],"requestBody":{"description":"Task specification, input payload, and optional model parameters","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayRequest"},"examples":{"ocr":{"summary":"OCR Receipt Scanning","value":{"taskType":"ocr","payload":{"image_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg...","mime_type":"image/jpeg","country_hint":"US"},"options":{"temperature":0.1,"maxTokens":1000}}},"categorization":{"summary":"Transaction Categorization","value":{"taskType":"categorization","payload":{"description":"UBER *TRIP 1234 HELP.UBER.COM CA","amount":24.5,"currency":"USD","available_categories":["Food & Dining","Travel & Commute","Tech & Subscriptions","Housing & Utilities"]},"options":{"temperature":0.2}}},"chat":{"summary":"Financial Chat Assistant","value":{"taskType":"chat","payload":{"messages":[{"role":"user","content":"How much did I spend on dining this month?"}],"user_context":{"currency":"USD","current_month_spend":1250.4,"top_category":"Food & Dining"}},"options":{"temperature":0.5,"maxTokens":1200}}},"insights":{"summary":"Spending Insights & Anomalies","value":{"taskType":"insights","payload":{"timeframe":"last_30_days","total_spend":3420,"currency":"USD","top_categories":[{"name":"Food & Dining","amount":1200},{"name":"Travel & Commute","amount":450}]},"options":{"temperature":0.3}}}}}}},"responses":{"200":{"description":"Normalized successful AI inference response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayResponse"},"examples":{"ocrSuccess":{"summary":"OCR Extraction Response","value":{"success":true,"task_type":"ocr","request_id":"req_a1b2c3d4e5f6","data":{"merchant":"Whole Foods Market","amount":42.85,"currency":"USD","date":"2026-09-13","category_suggestion":"Food & Dining","confidence":0.97,"items":[{"description":"Organic Honeycrisp Apples","price":6.99,"quantity":1},{"description":"Almond Milk 64oz","price":3.99,"quantity":1},{"description":"Artisan Sourdough Loaf","price":5.49,"quantity":1}]},"usage":{"prompt_tokens":380,"completion_tokens":110,"total_tokens":490}}},"categorizationSuccess":{"summary":"Categorization Response","value":{"success":true,"task_type":"categorization","request_id":"req_c4d5e6f7a8b9","data":{"category":"Travel & Commute","confidence":0.98,"is_recurring":false},"usage":{"prompt_tokens":115,"completion_tokens":32,"total_tokens":147}}}}}}},"400":{"description":"Bad Request — Missing or invalid payload structure or unsupported taskType","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"INVALID_PAYLOAD","message":"Missing or malformed required field: payload is mandatory for taskType categorization."}}}}},"401":{"description":"Unauthorized — Caller missing valid Supabase user JWT or session expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"AUTH_REQUIRED","message":"Valid Supabase user session token required in Authorization header."}}}}},"403":{"description":"Forbidden — User does not have an active paid subscription (Pro or Ultra)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionErrorResponse"},"example":{"success":false,"error":{"code":"SUBSCRIPTION_REQUIRED","message":"An active paid subscription (Pro or Ultra) is required to access AI features.","upgrade_url":"nomiq://subscription/upgrade"}}}}},"429":{"description":"Too Many Requests — User or global rate limit / daily spend cap exceeded","headers":{"x-ratelimit-remaining":{"description":"Remaining requests allowed in the current rate limit window","schema":{"type":"integer"}},"retry-after":{"description":"Number of seconds the client must wait before making another request","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"},"example":{"success":false,"error":{"code":"RATE_LIMIT_EXCEEDED","message":"AI request rate limit exceeded. Please wait before retrying.","retry_after_seconds":60}}}}},"502":{"description":"Bad Gateway — All configured AI providers in failover chain failed to respond","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"ALL_PROVIDERS_UNAVAILABLE","message":"All configured AI providers failed to respond. Failover exhausted."}}}}},"503":{"description":"Service Unavailable — AI Gateway temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"ALL_PROVIDERS_UNAVAILABLE","message":"AI inference providers are currently experiencing an outage."}}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase User Auth Bearer Token obtained via mobile client sign-in."}},"schemas":{"GatewayRequest":{"type":"object","required":["taskType","payload"],"properties":{"taskType":{"type":"string","enum":["ocr","categorization","chat","insights"],"description":"The archetype of AI task to execute"},"payload":{"type":"object","description":"Task-specific parameters. See OCRPayload, CategorizationPayload, ChatPayload, InsightsPayload.","oneOf":[{"$ref":"#/components/schemas/OCRPayload"},{"$ref":"#/components/schemas/CategorizationPayload"},{"$ref":"#/components/schemas/ChatPayload"},{"$ref":"#/components/schemas/InsightsPayload"}]},"options":{"type":"object","description":"Optional execution parameters to tune LLM behavior","properties":{"temperature":{"type":"number","minimum":0,"maximum":2,"default":0.2,"description":"Sampling temperature between 0 and 2. Lower values are more deterministic."},"maxTokens":{"type":"integer","minimum":1,"maximum":4096,"default":1000,"description":"Maximum number of tokens to generate in response."}}}}},"OCRPayload":{"type":"object","required":["image_base64"],"properties":{"image_base64":{"type":"string","description":"Base64-encoded image data URL or raw base64 string of receipt or invoice"},"mime_type":{"type":"string","enum":["image/jpeg","image/png","image/heic","image/webp"],"default":"image/jpeg","description":"MIME type of the submitted image"},"country_hint":{"type":"string","default":"US","description":"Two-letter ISO country code to aid currency and tax resolution"}}},"CategorizationPayload":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"Raw merchant name or bank transaction descriptor string","example":"UBER *TRIP 1234 HELP.UBER.COM CA"},"amount":{"type":"number","description":"Transaction amount","example":24.5},"currency":{"type":"string","default":"USD","description":"Three-letter ISO currency code"},"available_categories":{"type":"array","items":{"type":"string"},"description":"List of available user categories to categorize into"}}},"ChatPayload":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","description":"Chat message history","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"user_context":{"type":"object","description":"Optional financial background context for personalization","properties":{"currency":{"type":"string","example":"USD"},"current_month_spend":{"type":"number","example":1250.4},"top_category":{"type":"string","example":"Food & Dining"}}}}},"InsightsPayload":{"type":"object","required":["timeframe"],"properties":{"timeframe":{"type":"string","enum":["last_7_days","last_30_days","current_month","last_month","year_to_date"],"description":"Timeframe for insight aggregation"},"total_spend":{"type":"number","description":"Total expenditure in the timeframe","example":3420},"currency":{"type":"string","default":"USD"},"top_categories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"number"}}}}}},"GatewayResponse":{"type":"object","required":["success","task_type","request_id","data","usage"],"properties":{"success":{"type":"boolean","enum":[true],"description":"Indicates successful execution"},"task_type":{"type":"string","enum":["ocr","categorization","chat","insights"],"description":"Echoes the requested task type"},"request_id":{"type":"string","description":"Unique gateway trace request identifier","example":"req_a1b2c3d4e5f6"},"data":{"type":"object","description":"Task-specific normalized extraction or inference response object"},"usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer","description":"Number of input tokens consumed","example":120},"completion_tokens":{"type":"integer","description":"Number of generated output tokens","example":45},"total_tokens":{"type":"integer","description":"Total token consumption","example":165}}}}},"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","INVALID_SESSION","INVALID_PAYLOAD","ALL_PROVIDERS_UNAVAILABLE"],"description":"Machine-readable error classification code"},"message":{"type":"string","description":"Human-readable explanation of the error"}}}}},"SubscriptionErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message","upgrade_url"],"properties":{"code":{"type":"string","enum":["SUBSCRIPTION_REQUIRED"]},"message":{"type":"string","example":"An active paid subscription (Pro or Ultra) is required to access AI features."},"upgrade_url":{"type":"string","example":"nomiq://subscription/upgrade"}}}}},"RateLimitErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message","retry_after_seconds"],"properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"]},"message":{"type":"string","example":"AI request rate limit exceeded. Please try again later."},"retry_after_seconds":{"type":"integer","example":60}}}}}}}}