{"openapi":"3.1.0","info":{"title":"Mowa API","version":"1.0.0","description":"The Mowa API. Authenticate with a workspace API key as a bearer token. Create one in the dashboard under Developers. One key covers the whole workspace."},"servers":[{"url":"https://mowa.dev/api/v1","description":"Mowa API"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Gateway","description":"OpenAI-compatible model gateway"},{"name":"Traces","description":"Record calls your own SDK made, as OpenTelemetry traces"},{"name":"Prompts"},{"name":"Datasets"},{"name":"Usage"},{"name":"Jobs"}],"paths":{"/chat/completions":{"post":{"tags":["Gateway"],"summary":"Create a chat completion","description":"OpenAI-compatible. We proxy to the real provider using your connected key, return the response, and log the request and response for observability. Set model as provider/model, for example openai/gpt-5.6-luna. Supports stream: true, pass-through image/audio/video/file parts for compatible models, and mowa trace fingerprints.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"},"example":{"model":"openai/gpt-5.6-luna","messages":[{"role":"user","content":"Hello"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"object\":\"chat.completion.chunk\",\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\ndata: [DONE]\n\n"}}}}}},"/traces":{"post":{"tags":["Traces"],"summary":"Record traces (OTLP)","description":"OpenTelemetry OTLP over HTTP, JSON or protobuf. Send the spans your SDK already makes, such as Vercel AI SDK telemetry, GenAI semantic convention spans, or an OpenRouter Broadcast destination. Each call is saved as a trace and steps, with the source telemetry or openrouter. Mowa fields come from span metadata: mowa.prompt, mowa.dataset, mowa.scorers, mowa.user, mowa.fingerprint, and mowa.bundle. For chat agents, set session.id (or gen_ai.conversation.id) to the same conversation id on every turn. Recorded calls are free, are priced from the model price list, and stay out of the spend total on the usage page. The reply is immediate and the work happens after.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceSpans":{"type":"array","items":{"type":"object"}}}}},"application/x-protobuf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Accepted"}}}},"/images/generations":{"post":{"tags":["Gateway"],"summary":"Generate an image","description":"OpenAI-compatible image generation. Uses your connected OpenAI or Google key. model is optional; if omitted we use a connected image provider. Returns base64 image data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"model":{"type":"string","description":"Optional, e.g. openai/gpt-image-2"}}},"example":{"prompt":"a blueprint of a paper airplane"}}}},"responses":{"200":{"description":"Success"}}}},"/audio/transcriptions":{"post":{"tags":["Gateway"],"summary":"Transcribe audio","description":"OpenAI-compatible speech to text on a connected key. Saves the audio and the transcript with word times to the trace.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","description":"Optional, e.g. google/gemini-3.5-transcribe"},"response_format":{"type":"string","enum":["json","text","verbose_json"]},"mowa_agent":{"type":"string"},"mowa_version":{"type":"string"}}}}}},"responses":{"200":{"description":"Success"}}}},"/audio/speech":{"post":{"tags":["Gateway"],"summary":"Turn text into speech","description":"OpenAI-compatible text to speech on a connected key. Returns the audio bytes and saves them to the trace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string"},"model":{"type":"string","description":"Optional, e.g. google/gemini-3.8-flash-tts"},"voice":{"type":"string"},"instructions":{"type":"string"},"response_format":{"type":"string"},"speed":{"type":"number"}}},"example":{"input":"Your order ships today."}}}},"responses":{"200":{"description":"Audio bytes"}}}},"/models":{"get":{"tags":["Gateway"],"summary":"List models for your account","description":"Returns the models available across every provider key connected in the workspace. Each id is ready to pass to /chat/completions.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}}}}}},"/prompts":{"get":{"tags":["Prompts"],"summary":"List prompts","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromptList"}}}}}},"post":{"tags":["Prompts"],"summary":"Create a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrompt"},"example":{"name":"Support triage","content":"Classify the message: {{message}}"}}}},"responses":{"201":{"description":"Created"}}}},"/prompts/{id}":{"get":{"tags":["Prompts"],"summary":"Get a prompt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/prompts/{id}/versions":{"post":{"tags":["Prompts"],"summary":"Create a prompt version","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/versions/{versionId}/publish":{"post":{"tags":["Prompts"],"summary":"Publish a prompt version","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published"}}}},"/datasets":{"get":{"tags":["Datasets"],"summary":"List datasets","responses":{"200":{"description":"Success"}}}},"/datasets/{id}":{"get":{"tags":["Datasets"],"summary":"Get a dataset with rows","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Success"}}}},"/datasets/{id}/rows":{"post":{"tags":["Datasets"],"summary":"Add a dataset row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object"}}}}}},"responses":{"201":{"description":"Created"}}}},"/datasets/{id}/generate":{"post":{"tags":["Datasets"],"summary":"Generate synthetic dataset rows","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["count"],"properties":{"count":{"type":"integer"},"guidance":{"type":"string"}}}}}},"responses":{"202":{"description":"Enqueued"}}}},"/jobs/{jobId}":{"get":{"tags":["Jobs"],"summary":"Get job status","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Get AI usage for the last 30 days","responses":{"200":{"description":"Success"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Mowa workspace API key."}},"schemas":{"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","description":"Optional. provider/model, e.g. openai/gpt-5.6-luna. If omitted we use a connected provider's default."},"mowa":{"type":"object","description":"Mowa extension: reference a stored prompt, capture the result, and attach trace grouping metadata.","properties":{"prompt":{"type":"string","description":"A prompt id or version id from your workspace."},"variables":{"type":"object"},"dataset":{"type":"string","description":"Dataset id to append the result to."},"scorers":{"type":"array","items":{"type":"string"}},"session":{"type":"string","description":"Conversation id. Send the same value on every turn of a chat so Mowa groups the turns into one conversation."},"fingerprint":{"type":"string","description":"Optional app-provided trace grouping id."},"bundle":{"type":"object","description":"Optional behavior bundle used to compute the trace fingerprint."}}},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","description":"Content part. Supports text, image_url, input_audio, input_video, video_url, and file."}}]}}}},"temperature":{"type":"number"},"max_tokens":{"type":"integer"},"top_p":{"type":"number"},"stream":{"type":"boolean","default":false}}},"ChatCompletionResponse":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object"}},"usage":{"type":"object"},"mowa":{"type":"object","properties":{"request_id":{"type":"string"},"trace_fingerprint":{"type":"string"}}}}},"ModelsResponse":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"models":{"type":"array","items":{"type":"object"}}}}}}},"CreatePrompt":{"type":"object","required":["name","content"],"properties":{"name":{"type":"string"},"content":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string"},"color":{"type":"string"}}},"PromptList":{"type":"object","properties":{"prompts":{"type":"array","items":{"type":"object"}}}}}}}