{"openapi":"3.1.0","info":{"title":"Malakore Enterprise AI Gateway API","version":"1.0.0","description":"API for the Malakore AI Gateway project. Provider adapters, persistence, authentication and operational behavior depend on deployment configuration and have not all been validated against live services. No throughput, latency, availability or concurrency target is established by this specification; validate the selected deployment before production use.","contact":{"name":"Malakore AI Gateway repository","url":"https://github.com/NICRAEL-DEV/Malakore-AI-Gateway"}},"servers":[{"url":"/","description":"Current Malakore Gateway Deployment"}],"security":[{"BearerAuth":[]}],"paths":{"/api/v1/chat/completions":{"post":{"summary":"Create Chat Completion (OpenAI Compatible)","description":"Dispatches chat prompts across upstream model providers with intelligent fallback cascades, rate-limiting enforcement, and automatic latency/cost tracking.","operationId":"createChatCompletion","tags":["Inference"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"Target canonical model ID (e.g. gemini/gemini-2.5-flash, anthropic/claude-3-5-sonnet, openai/gpt-4o, openrouter/auto).","example":"gemini/gemini-2.5-flash"},"messages":{"type":"array","description":"Chronological list of chat messages forming the conversation context.","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"],"description":"Role of the message author."},"content":{"type":"string","description":"Contents of the message."}}}},"temperature":{"type":"number","minimum":0,"maximum":2,"default":0.7,"description":"Sampling temperature for randomness."},"max_tokens":{"type":"integer","minimum":1,"description":"Maximum tokens to generate in response."},"stream":{"type":"boolean","default":false,"description":"Whether to stream responses via Server-Sent Events (SSE)."}}}}}},"responses":{"200":{"description":"Successful completion response (JSON or SSE stream).","headers":{"x-request-id":{"schema":{"type":"string"},"description":"Unique trace ID for observability and debugging."},"x-gateway-provider":{"schema":{"type":"string"},"description":"Upstream provider that serviced the request."},"x-gateway-model":{"schema":{"type":"string"},"description":"Actual routed model ID after fallback evaluation."}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"chat.completion"},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"finish_reason":{"type":"string"}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}}}},"401":{"description":"Unauthorized - invalid or missing Bearer API key."},"429":{"description":"Rate limited (RPM, TPM, or monthly budget exhausted)."},"502":{"description":"Upstream error - all providers in fallback cascade failed."}}}},"/api/v1/models":{"get":{"summary":"List Available Models","description":"Returns the catalog of all configured AI models with context limits, pricing, and health.","tags":["Catalog"],"responses":{"200":{"description":"List of supported models."}}}},"/api/v1/providers":{"get":{"summary":"List Provider Health & Status","description":"Inspect upstream providers (OpenRouter, Gemini, OpenAI, Anthropic, HuggingFace, RapidAPI, Ollama, vLLM).","tags":["Infrastructure"],"responses":{"200":{"description":"Provider list with status and latencies."}}},"post":{"summary":"Trigger Provider Live Health Check","description":"Dispatches real test ping to verify upstream credentials and measure network roundtrip.","tags":["Infrastructure"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["providerId"],"properties":{"providerId":{"type":"string"}}}}}},"responses":{"200":{"description":"Health check result."}}}},"/api/v1/routing":{"get":{"summary":"List Routing Rules","description":"Returns active cascading rules, failover priorities, and latency-budget affinities.","tags":["Routing"],"responses":{"200":{"description":"List of routing rules."}}},"post":{"summary":"Create or Update Routing Rule","tags":["Routing"],"responses":{"200":{"description":"Updated rule definition."}}}},"/api/v1/api-keys":{"get":{"summary":"List API Keys","tags":["Security & Access"],"responses":{"200":{"description":"List of provisioned scoped tokens."}}},"post":{"summary":"Generate Scoped API Key","tags":["Security & Access"],"responses":{"201":{"description":"Provisioned key with one-time visible secret token."}}}},"/api/v1/requests":{"get":{"summary":"Query Request Traces","description":"Inspect trace records available from the configured runtime store, including status codes and routing metadata. Retention and durability depend on deployment configuration.","tags":["Observability"],"responses":{"200":{"description":"Filtered list of traces."}}}},"/api/v1/usage":{"get":{"summary":"Get Usage Metrics & Cost Rollups","description":"Aggregates requests, token throughput, and estimated spend.","tags":["Observability"],"responses":{"200":{"description":"Aggregated usage statistics."}}}},"/api/v1/tactical/morse":{"post":{"summary":"Tactical Morse Code Bridge & Acoustic CW Transceiver","description":"Encodes, decodes, synthesizes 750Hz WAV audio, or transceives Morse code with sovereign models under ITU-R M.1677-1.","tags":["Tactical & Resilient Communications"],"responses":{"200":{"description":"Encoded Morse text, decoded plaintext, or audio/wav stream."}}}},"/api/v1/security/dast":{"get":{"summary":"Execute Dynamic API Security Testing (DAST) Probe","description":"Runs automated OWASP API Top 10 and LLM Top 10 synthetic vulnerability probes compatible with HawkScan.","tags":["Security & Access"],"responses":{"200":{"description":"Complete DAST compliance scan report with reproduction cURLs."}}},"post":{"summary":"Trigger DAST Security Audit with Custom Target","tags":["Security & Access"],"responses":{"200":{"description":"DAST compliance scan report."}}}},"/api/v1/security/watermark":{"post":{"summary":"Embed, Verify, or Issue Provenance Certificate for Text (ZK Watermarking)","description":"Zero-knowledge watermarking verifying model provenance under EU AI Act Art. 50 with Z-score >= 3.0.","tags":["Security & Access"],"responses":{"200":{"description":"Watermarked text, verification score, or digital provenance certificate."}}}},"/api/v1/security/attribution":{"get":{"summary":"Inspect Attribution & Zero-Hallucination Engine Capabilities","tags":["Security & Access"],"responses":{"200":{"description":"Attribution audit engine status and supported verification rules."}}},"post":{"summary":"Execute Factual Attribution & Zero-Hallucination Audit on RAG Output","description":"Decomposes claims, verifies citation indexes, validates critical entities, and issues a cryptographic attestation certificate.","tags":["Security & Access"],"responses":{"200":{"description":"Factual attribution report with faithfulness score, claim analysis, and digital certificate."}}}},"/api/v1/resilience/mesh":{"get":{"summary":"Get Sovereign P2P Mesh Node Status","tags":["Resilience & Mesh"],"responses":{"200":{"description":"Local node identity, peer count, and learned threat IoCs."}}},"post":{"summary":"Ingest or Broadcast Sovereign Gossip Envelope","tags":["Resilience & Mesh"],"responses":{"200":{"description":"Gossip envelope processed and ledger validated."}}}},"/api/v1/mcp/tools":{"get":{"summary":"List MCP Tools Filtered by Clearance Level","tags":["Model Context Protocol (MCP)"],"responses":{"200":{"description":"Authorized tools for current caller clearance."}}},"post":{"summary":"Execute MCP Tool with Zero-Trust Clearance Check","tags":["Model Context Protocol (MCP)"],"responses":{"200":{"description":"Tool execution result and DFIR ledger entry."}}}},"/api/v1/webhooks":{"get":{"summary":"List Webhook Alert Endpoints","tags":["Alerts & Webhooks"],"responses":{"200":{"description":"Registered webhook endpoints."}}},"post":{"summary":"Register or Test Webhook Endpoint","tags":["Alerts & Webhooks"],"responses":{"200":{"description":"Registered webhook endpoint or ping test result."}}}},"/api/metrics":{"get":{"summary":"Prometheus / OpenMetrics Scrape Endpoint","description":"Standard plain-text exposition format for Grafana, Datadog, and Kubernetes Prometheus Operator.","tags":["Observability"],"responses":{"200":{"description":"Prometheus metrics stream.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/health":{"get":{"summary":"Liveness & Readiness Healthcheck","description":"Kubernetes and load-balancer health verification endpoint.","tags":["Infrastructure"],"responses":{"200":{"description":"System healthy and ready to accept traffic."}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mk_live_...","description":"Enterprise Malakore Scoped Token (header format: Authorization: Bearer mk_...)"}}}}