{"openapi":"3.0.3","info":{"title":"GeniusPro API","version":"1.0.0","description":"OpenAI-compatible chat, models, files, embeddings, and realtime voice. See https://api.geniuspro.io/ for the lightweight discovery index.","contact":{"name":"GeniusPro","url":"https://platform.geniuspro.io"}},"servers":[{"url":"https://api.geniuspro.io"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"x-security-policy":{"url":"https://geniuspro.io/security","summary":"No training on API traffic; PII scrubbed from GeniusPro logs by default; opt-in edge PII scrubbing via X-GP-Scrub-Prompt header or scrub_pii body flag.","controls":["no_training_on_api_traffic","pii_scrubbed_from_logs","opt_in_edge_pii_scrub","tls_in_transit","encryption_at_rest","hashed_api_keys"],"compliance_covered_today":["SOC 2 Type II","ISO 27001"],"compliance_covered_today_note":"Attested across the GeniusPro stack: managed Postgres database, US cloud hosting for control plane and realtime voice proxy, and every hyperscaler-hosted model route used for compliance-sensitive traffic.","compliance_available_under_baa":["HIPAA"],"compliance_available_under_baa_note":"Enterprise tier wires HIPAA-covered workspaces so every link carries a signed BAA: upstream (hyperscaler-hosted model provider under the matching BAA) and database (HIPAA-eligible tier with a signed BAA). Contact https://geniuspro.io/#invite.","vendor_chain_disclosure":"Specific infrastructure and model-provider names are shared under NDA during onboarding and security-questionnaire review, not on public surfaces."},"x-ai-usage-policy":{"url":"https://geniuspro.io/ai-usage","summary":"AI agents may read, summarize, link, and cite GeniusPro public surfaces with attribution. Verbatim copying, foundation-model training, and PII collection require written permission.","ok":["Read the discovery index, this OpenAPI spec, ai-plugin.json, llms.txt, JSON-LD, and model catalog.","Summarize and link back to canonical URLs.","Cite model slugs from https://api.geniuspro.io/v1/models/catalog as the authoritative source.","Build integrations against https://api.geniuspro.io/v1."],"not_ok":["Copy GeniusPro prose, code samples, or documentation verbatim without attribution.","Use GeniusPro content for foundation-model training, fine-tuning, RLHF, DPO, or distillation without written permission.","Collect, cache, or redistribute any PII that appears on GeniusPro public surfaces.","Misrepresent model slugs, pricing, availability, or capabilities."],"customer_traffic_note":"Data callers send to api.geniuspro.io is governed by the separate security policy at https://geniuspro.io/security, not this AI-usage policy.","permission_contact":"legal@geniuspro.io"},"tags":[{"name":"Discovery"},{"name":"Chat"},{"name":"Models"},{"name":"Files"},{"name":"Embeddings"},{"name":"Realtime"}],"paths":{"/":{"get":{"tags":["Discovery"],"summary":"API discovery index","description":"Lightweight JSON pointing to the OpenAPI spec, plugin manifest, docs, and auth details. No auth required.","security":[],"responses":{"200":{"description":"Discovery index","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/openapi.json":{"get":{"tags":["Discovery"],"summary":"Full OpenAPI 3.0 spec","security":[],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/ai-plugin.json":{"get":{"tags":["Discovery"],"summary":"AI plugin manifest","security":[],"responses":{"200":{"description":"Plugin manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/docs":{"get":{"tags":["Discovery"],"summary":"Human-readable API docs (Redoc)","security":[],"responses":{"200":{"description":"HTML docs page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/health":{"get":{"tags":["Discovery"],"summary":"Health check","security":[],"responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/models":{"get":{"tags":["Models"],"summary":"List available models","description":"Per-key, plan-filtered list — what the authenticated caller can reach right now (includes their CATs). For the unauthenticated universe of publicly callable slugs, use GET /v1/models/catalog.","responses":{"200":{"description":"List of model ids","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/models/catalog":{"get":{"tags":["Models","Discovery"],"summary":"Public catalog of GeniusPro model slugs (four tiers)","description":"Unauthenticated, authoritative list of every publicly callable model slug, grouped into experts (professional-role simon-says-* orchestrators), task orchestrators (simon-says-* auto-routers), benchmarked specialists (simon-says-* single-model per task), and direct raw-provider slugs. User CATs (cat:slug) are per API key and not listed here. Sourced live from the admin catalog with a 5-minute cache; does not leak upstream provider/model mappings or pricing. Use this to answer 'does this model exist?' without an API key.","security":[],"responses":{"200":{"description":"Four-tier model catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelCatalogResponse"}}}}}}},"/v1/chat/completions":{"post":{"tags":["Chat"],"summary":"Create a chat completion","description":"OpenAI-compatible. Set `stream: true` to receive server-sent events. Files attached via `{ type: 'file', file: { file_id } }` content parts must be uploaded first through /v1/files. Send `X-GP-Scrub-Prompt: true` (or `scrub_pii: true` in the body) to mask PII from `messages[].content` before the request is dispatched to the upstream provider; see https://geniuspro.io/security.","parameters":[{"in":"header","name":"X-GP-Scrub-Prompt","required":false,"schema":{"type":"string","enum":["true","1","yes","on"]},"description":"Opt-in edge PII scrubbing. Equivalent to `scrub_pii: true` in the request body. When set, emails, phone numbers, SSNs, credit cards, IP addresses, and API keys are masked from messages[].content BEFORE dispatching to the upstream provider. PII is always scrubbed from GeniusPro's own logs regardless of this flag."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Chat completion response (non-streaming)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/embeddings":{"post":{"tags":["Embeddings"],"summary":"Create text embeddings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}}},"responses":{"200":{"description":"Embedding vectors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/files":{"post":{"tags":["Files"],"summary":"Request a pre-signed upload URL","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileCreateRequest"}}}},"responses":{"200":{"description":"File slot created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileCreateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"get":{"tags":["Files"],"summary":"List uploaded files","responses":{"200":{"description":"File list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/files/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Files"],"summary":"Get file metadata","responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileObject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["Files"],"summary":"Delete an uploaded file","responses":{"200":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}}},"/v1/files/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Files"],"summary":"Confirm upload after PUT to the pre-signed URL","responses":{"200":{"description":"File marked ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileObject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}}},"/v1/realtime":{"get":{"tags":["Realtime"],"summary":"WebSocket upgrade for real-time voice","description":"Connect via `wss://api.geniuspro.io/v1/realtime?api_key=<key>` or send `{ type: 'auth', api_key }` as the first message. Binary frames are audio; JSON frames are control messages.","responses":{"101":{"description":"Switching protocols to WebSocket"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"The account is out of API credits. `error.message` begins with `API_BILLING:`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Request body exceeds 4 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded; back off and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"}},"required":["message"]}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"geniuspro-api"}}},"Model":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"model"},"owned_by":{"type":"string"}}},"ModelList":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"CatalogModel":{"type":"object","properties":{"id":{"type":"string","example":"simon-says-coding-super"},"category":{"type":"string","nullable":true,"description":"Coarse use-case category (chat, coding, reasoning, creative, image, vision, audio, embedding, agents, orchestrator)."},"types":{"type":"array","items":{"type":"string"},"description":"Tags such as 'benchmark'. Used internally to distinguish benchmarked specialists from general orchestrators."}},"required":["id","types"]},"ModelCatalogResponse":{"type":"object","description":"Authoritative public list of GeniusPro model slugs. Four-tier shape (experts / orchestrators / benchmarked / direct) so AI agents can see the product structure at a glance. Does not leak upstream provider/model mappings or pricing. User CATs (cat:slug) are per API key and not listed here.","properties":{"base_url":{"type":"string","example":"https://api.geniuspro.io"},"counts":{"type":"object","properties":{"experts":{"type":"integer"},"orchestrators":{"type":"integer"},"benchmarked":{"type":"integer"},"direct":{"type":"integer"},"total":{"type":"integer"}}},"experts":{"type":"array","description":"Professional-role simon-says-* orchestrators (finance, legal, PM, architecture, etc.). Same wire format as other Simon slugs; domain discipline + expert chassis where configured.","items":{"$ref":"#/components/schemas/CatalogModel"}},"orchestrators":{"type":"array","description":"Task-family simon-says-* slugs that auto-route across upstreams (chat, coding, reasoning, image, voice, etc.). Call one name; GeniusPro picks the best model per request.","items":{"$ref":"#/components/schemas/CatalogModel"}},"benchmarked":{"type":"array","description":"simon-says-* slugs selected per task from continuous benchmarks (math, logic, long-doc, terminal, legal, finance, etc.).","items":{"$ref":"#/components/schemas/CatalogModel"}},"direct":{"type":"array","description":"Raw-provider slugs exposed for callers who want a specific upstream (gpt-5.4, claude-opus-4-7, gemini-3.1-pro, grok-3, llama-4-*, etc.) plus vision (sam3) and image models.","items":{"$ref":"#/components/schemas/CatalogModel"}},"updated_at":{"type":"string","format":"date-time"},"note":{"type":"string"},"links":{"type":"object","properties":{"authoritative_api":{"type":"string"},"human_docs":{"type":"string"},"llms_txt":{"type":"string"},"openapi":{"type":"string"},"discovery":{"type":"string"}}}},"required":["base_url","counts","experts","orchestrators","benchmarked","direct"]},"ChatMessageContentPart":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}},"required":["type","image_url"]},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"file":{"type":"object","properties":{"file_id":{"type":"string"}},"required":["file_id"]}},"required":["type","file"]}]},"ChatMessage":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatMessageContentPart"}}]},"name":{"type":"string"},"tool_call_id":{"type":"string"}},"required":["role"]},"ChatCompletionRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","example":"simon-says"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"max_tokens":{"type":"integer","minimum":1},"stream":{"type":"boolean","default":false},"scrub_pii":{"type":"boolean","default":false,"description":"Opt-in edge PII scrubbing. When true (or when the X-GP-Scrub-Prompt: true header is set), GeniusPro masks emails, phone numbers, SSNs, credit cards, IP addresses, and API keys from messages[].content BEFORE dispatching the request to the upstream provider. OFF by default because many legitimate workflows (resume parsing, customer-email summarization) explicitly need PII to reach the model. PII is always scrubbed from GeniusPro's own logs and stored records regardless of this flag; see https://geniuspro.io/security."},"tools":{"type":"array","items":{"type":"object"}},"tool_choice":{"oneOf":[{"type":"string","enum":["auto","none","required"]},{"type":"object"}]}}},"ChatCompletionChoice":{"type":"object","properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/ChatMessage"},"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter"]}}},"Usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"ChatCompletionResponse":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"chat.completion"},"created":{"type":"integer","format":"int64"},"model":{"type":"string"},"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionChoice"}},"usage":{"$ref":"#/components/schemas/Usage"}}},"EmbeddingRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"Embedding":{"type":"object","properties":{"object":{"type":"string","example":"embedding"},"index":{"type":"integer"},"embedding":{"type":"array","items":{"type":"number"}}}},"EmbeddingResponse":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Embedding"}},"model":{"type":"string"},"usage":{"$ref":"#/components/schemas/Usage"}}},"FileCreateRequest":{"type":"object","required":["filename","mime_type"],"properties":{"filename":{"type":"string"},"mime_type":{"type":"string","enum":["application/pdf","image/png","image/jpeg","image/webp","image/gif","text/plain","text/csv","application/json","text/markdown"]},"purpose":{"type":"string","enum":["assistants","vision","fine-tune","user_upload"]}}},"FileCreateResponse":{"type":"object","properties":{"id":{"type":"string"},"upload_url":{"type":"string","format":"uri"},"expires_at":{"type":"integer","format":"int64"}}},"FileObject":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"},"bytes":{"type":"integer"},"status":{"type":"string","enum":["pending","ready","error"]},"created_at":{"type":"integer","format":"int64"}}},"FileList":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/FileObject"}}}}}}}