Build against one reliable API.

Quickstart

Monsoon Gateway accepts OpenAI-compatible chat-completion requests at the global base URL. Start by discovering a callable model, then send a completion with your bearer key.

Access note: API keys are provisioned for the founder-operated private prototype. There is no self-service key creation yet. The identifiers below are explicit placeholders; replace them with callable IDs returned by GET /models.

1. Discover available models

Only models marked available or degraded are callable. Do not copy a model name from this guide into production code without checking the authenticated catalog.

curl https://api.monsoon.sh/v1/models \
  -H "Authorization: Bearer $MONSOON_API_KEY"

2. Send a request with cURL

curl https://api.monsoon.sh/v1/chat/completions \
  -H "Authorization: Bearer $MONSOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "organization/model-primary",
    "messages": [
      {
        "role": "user",
        "content": "Return a short response using only synthetic test data."
      }
    ]
  }'

3. Use the Python OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MONSOON_API_KEY"],
    base_url="https://api.monsoon.sh/v1",
)

completion = client.chat.completions.create(
    model="organization/model-primary",
    messages=[
        {
            "role": "user",
            "content": "Return a short response using only synthetic test data.",
        }
    ],
)

print(completion.choices[0].message.content)
print(completion.model)  # The model actually served.

4. Use the TypeScript OpenAI SDK

import OpenAI from "openai";

const apiKey = process.env.MONSOON_API_KEY;
if (!apiKey) throw new Error("MONSOON_API_KEY is required");

const client = new OpenAI({
  apiKey,
  baseURL: "https://api.monsoon.sh/v1",
});

const completion = await client.chat.completions.create({
  model: "organization/model-primary",
  messages: [
    {
      role: "user",
      content: "Return a short response using only synthetic test data.",
    },
  ],
});

console.log(completion.choices[0]?.message.content);
console.log(completion.model); // The model actually served.

The completion response preserves the standard chat-completion fields. Monsoon adds route metadata without replacing those fields, and the response model is always the model that actually served the request.

Authentication

External clients authenticate every request under /v1 with a bearer API key. Both the global and Vietnam-preview hosts require the same authentication and schema validation before their lane-specific behavior begins.

Authorization: Bearer <MONSOON_API_KEY>

Keep keys in a secret manager or environment variable. Do not place them in browser code, source control, URLs, logs, screenshots, or support messages. A key is shown only when it is provisioned; Monsoon stores a non-secret prefix and hash afterward. Revoked keys stop working, and per-key rate limits apply.

Transport and browser access

• Public API traffic is TLS-only.
• Request bodies are JSON. Non-streaming responses are JSON; streaming responses use server-sent events.
• Browser requests are limited to an explicit set of Monsoon web origins. Credentialed wildcard CORS is not supported.
• The authenticated Playground reaches the same /v1/models and /v1/chat/completions handlers through the founder session. It is not a separate inference API.

Unauthenticated exception

POST https://api.monsoon.sh/early-access is the only unauthenticated public data-writing endpoint. It is a validated, rate-limited application form, not an API-key or account-creation endpoint.

Models and identifiers

Use GET /models on the global base URL to retrieve the authenticated catalog. Public model IDs are author- or family-namespaced strings such as organization/model-name; internal route aliases never appear in public responses.

curl https://api.monsoon.sh/v1/models \
  -H "Authorization: Bearer $MONSOON_API_KEY"

Each catalog entry can include its display name, capabilities, context window, estimated input and output prices in USD, last synchronization time, availability, and whether it is callable. Values that Monsoon cannot establish are returned as unknown or null rather than inferred.

Availability vocabulary

• Available: the authenticated catalog contains the model and at least one enabled eligible route is configured. Callable.
• Degraded: a callable contract state reserved for partial route impairment. The current prototype synchronizer does not derive this state from live health checks.
• Stale: the last successful catalog synchronization is more than 60 minutes old. Not callable.
• Unverified: a catalog entry exists, but no enabled eligible route is configured. Not callable.
• Unavailable: the synchronized catalog no longer reports the model as available. Not callable.

All entries remain visible. Select only entries whose callable value is true.

Request and response model fields

model selects the primary model. The optional models field adds caller-controlled ordered fallbacks. The completion response returns the model actually served in its model field, including after a successful fallback.

The current inference surface is limited to GET /models and POST /chat/completions. Responses API, embeddings, images, audio, assistants, batches, and fine-tuning are not part of the prototype.

Chat completions

Send POST /chat/completions relative to either /v1 base URL. The global lane performs real inference; the Vietnam-preview lane returns an explicit mock response and makes no inference call.

{
  "model": "organization/model-primary",
  "messages": [
    {
      "role": "system",
      "content": "Respond concisely."
    },
    {
      "role": "user",
      "content": "Summarize this synthetic test input."
    }
  ],
  "temperature": 0.2,
  "stream": false
}

Supported behavior

• OpenAI-compatible message roles and chat-completion request and response shapes for supported fields
• Non-streaming and server-sent-event streaming responses
• Function tool definitions and tool-call messages
• A single completion choice per request
• Common sampling, token-limit, stop, response-format, and penalty fields where included in the generated request reference
• Additive monsoon route metadata, including the request ID and normalized requested model order

Unknown or unsupported request fields fail with a clear client error. They are never silently ignored. The generated request table is sourced from the checked-in OpenAPI snapshot and exposes its top-level fields, types, constraints, and defaults. Named nested schemas describe structured message, tool, and response objects.

The global lane never silently substitutes a different model. Cross-model fallback occurs only when the caller supplies an ordered model list.

Streaming

Set stream: true to receive OpenAI-compatible chat-completion chunks as server-sent events. Successful streams end with data: [DONE].

curl -N https://api.monsoon.sh/v1/chat/completions \
  -H "Authorization: Bearer $MONSOON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "organization/model-primary",
    "messages": [
      {
        "role": "user",
        "content": "Stream a short response using synthetic test data."
      }
    ],
    "stream": true,
    "stream_options": { "include_usage": true }
  }'

Commit point and fallback

The stream commit point is the first non-empty content, refusal, reasoning, or tool-call delta Monsoon forwards to the client. Before that point, an eligible route failure may advance through configured routes or the caller's ordered model list. After that point, the served route is locked permanently. Monsoon never invisibly switches providers or models inside an active response.

Role and control chunks may be buffered until a semantic delta arrives so an eligible pre-commit failure can still fall back safely.

Mid-stream errors

If a route fails after commitment, Monsoon sends one final chat.completion.chunk event with a top-level error and finish_reason: "error", then closes the stream without [DONE].

{
  "id": "<completion-id>",
  "object": "chat.completion.chunk",
  "created": 0,
  "model": "organization/model-primary",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "logprobs": null,
      "finish_reason": "error"
    }
  ],
  "error": {
    "message": "<sanitized-message>",
    "type": "server_error",
    "param": null,
    "code": "<stable-code>",
    "request_id": "<monsoon-request-id>",
    "retryable": true
  }
}

Treat a missing [DONE] plus a final error chunk as a partial-stream failure. Preserve already received output according to your product's policy, record the request ID, and let your client retry policy decide what happens next. A client disconnect is recorded as cancelled rather than retried by Monsoon.

Tool calling

Monsoon forwards OpenAI-compatible function tool definitions and returns tool-call messages on compatible models. Check the authenticated model catalog before selecting a model; tool support is a model capability, not a gateway-wide guarantee.

{
  "model": "organization/model-primary",
  "messages": [
    {
      "role": "user",
      "content": "Look up the synthetic value for test-key."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_test_value",
        "description": "Return a value from a synthetic test fixture.",
        "parameters": {
          "type": "object",
          "properties": {
            "key": { "type": "string" }
          },
          "required": ["key"],
          "additionalProperties": false
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto"
}

Complete the tool loop

1. Send the available tool definitions with the user message.
2. Inspect the assistant message for tool_calls.
3. Validate the function name and arguments in your application.
4. Execute the tool in your own trusted environment. Monsoon does not execute application tools for you.
5. Append the assistant tool-call message and one tool message per result, using the matching tool_call_id.
6. Send the updated messages back to /chat/completions for the final assistant response.

{
  "role": "tool",
  "tool_call_id": "<tool-call-id>",
  "content": "{\"value\":\"synthetic-result\"}"
}

Tool-call deltas count as semantic stream commitment. Once the first tool-call delta reaches the client, Monsoon cannot fall back to another route or model for that stream.

Ordered model fallback

Fallback is explicit and deterministic. model names the primary model. Optional models names an ordered fallback list. If only models is provided, that list is the full priority order. If both are provided, Monsoon tries model first and then each entry in models.

{
  "model": "organization/model-primary",
  "models": [
    "organization/model-fallback",
    "organization/model-last-resort"
  ],
  "messages": [
    {
      "role": "user",
      "content": "Use only this synthetic test request."
    }
  ]
}

The request above normalizes to:

1. organization/model-primary
2. organization/model-fallback
3. organization/model-last-resort

An empty normalized list is a client error. Activity shows the first entry as Requested primary and the remainder as Ordered fallbacks.

Python SDK extension field

Pass the Monsoon-specific models property through the Python SDK's supported extra_body option.

completion = client.chat.completions.create(
    model="organization/model-primary",
    messages=[
        {
            "role": "user",
            "content": "Use only this synthetic test request.",
        }
    ],
    extra_body={
        "models": ["organization/model-fallback"],
    },
)

TypeScript SDK extension field

The TypeScript SDK forwards additional request properties at runtime. Mark the Monsoon extension explicitly so TypeScript does not mistake it for a standard OpenAI field.

const completion = await client.chat.completions.create({
  model: "organization/model-primary",
  messages: [
    {
      role: "user",
      content: "Use only this synthetic test request.",
    },
  ],
  // @ts-expect-error Monsoon extension forwarded in the JSON request body.
  models: ["organization/model-fallback"],
});

When fallback is allowed

Automatic fallback is limited to eligible failures before stream commitment: connection and network failures, pre-commit timeouts, rate limiting or overload, and provider 5xx failures.

Monsoon does not fall back for invalid syntax or parameters, authentication or authorization errors, context-window errors, other caller-caused 4xx errors, or moderation and safety refusals. It also never adds a cross-model fallback that the caller did not request.

Within one model, Monsoon may try another eligible configured provider route before advancing to the next caller-supplied model. Route attempts are fully closed or cancelled before another begins.

Errors and request IDs

Monsoon assigns a request ID before routing begins. Every response includes it in the X-Monsoon-Request-ID header. Error bodies repeat the same value so client logs and Activity can be correlated.

X-Monsoon-Request-ID: <monsoon-request-id>

{
  "error": {
    "message": "<human-readable-message>",
    "type": "invalid_request_error",
    "param": "<related-field-or-null>",
    "code": "invalid_request",
    "request_id": "<monsoon-request-id>",
    "retryable": false
  }
}

Error responses contain a stable machine-readable code, a human-readable message, an appropriate HTTP status, the request ID, and a retryable signal when Monsoon can determine it safely. The param value identifies a related request field when available.

Common categories

• invalid_request — the request does not match the supported schema or field constraints. Correct it before retrying.
• invalid_authentication — the bearer key is missing, invalid, or revoked. Do not retry without fixing credentials.
• rate_limit_exceeded — the request exceeded a configured limit. Respect the HTTP status and Retry-After header.
• catalog_stale — synchronization is overdue, so routing is paused. Wait for synchronization to complete, then retry; escalate to the operator if the condition persists.
• all_routes_failed — every eligible route failed before response commitment. Use retryable and your own retry policy.
• router_unavailable — the private model router is temporarily unavailable.

This list is not the complete generated reference. Client logic should branch on code and retryable, not parse the message text.

Provider credentials, authorization headers, raw provider error bodies, internal route aliases, and secrets are never returned. Monsoon normalizes provider failures and exposes only sanitized diagnostic detail.

Streaming errors

An HTTP error before stream commitment uses the normal error shape above. A failure after commitment arrives as a final chat-completion chunk with a top-level error and finish_reason: "error"; that stream closes without [DONE]. See Streaming for the wire shape.

Global and Vietnam preview

Monsoon separates the real global lane from the future regional API shape with two explicit hosts. Do not infer a processing region from the URL unless the behavior below states it.

Global lane

https://api.monsoon.sh/v1

The global lane performs real upstream inference. It routes across eligible configured routes for the requested model order, records each attempt, and returns the model actually served. Compute-provider identity, residency, cost, or other route facts are shown as unknown when Monsoon cannot verify them independently.

Vietnam-resident preview — Coming soon

https://vn.monsoon.sh/v1

The Vietnam host is an explicit mock preview. It demonstrates a stable future regional endpoint without claiming that Vietnam-resident inference is live.

For an authenticated, schema-valid POST /chat/completions request, it:

• returns HTTP 200 with an OpenAI-compatible chat-completion shape;
• returns exactly “Vietnam-resident routing is coming soon.” as the assistant text;
• returns model: "monsoon/vietnam-preview" because no real model was served;
• includes X-Monsoon-Preview: true;
• adds Monsoon route metadata with preview: true, mocked: true, and the normalized requested_model_order;
• records zero input tokens, zero output tokens, and zero cost;
• creates an Activity record labelled “Preview—no inference performed.”; and
• makes no request to a model provider or global routing dependency.

Streaming and non-streaming callers receive compatible preview behavior. GET https://vn.monsoon.sh/v1/models returns an empty data array with preview metadata because there are no live Vietnam-resident models to list. It never mirrors the global catalog.

Authentication and schema validation still apply on the preview host. Catalog availability is not checked because routing never begins.

What “Vietnam-resident” will require

The preview cannot become live until the complete workload boundary is in Vietnam: TLS termination and gateway processing; prompt and response handling; model inference; request and audit logs; metadata and backups; secrets and keys; and operational access paths.

If a future live Vietnam route fails, cross-border fallback will require explicit customer opt-in. Otherwise the route will fail closed. That policy is next-phase work and is not simulated by this prototype.

Content-logging controls

Monsoon separates request metadata from raw prompt and response content. Metadata needed for Activity, reliability analysis, rate limiting, and cost estimation is retained independently so raw content can expire or be deleted without erasing route provenance.

Reduce logging for one request

Authenticated callers can suppress prompt and response storage on a single request:

X-Monsoon-Log-Content: false

This header can only reduce logging. Any value other than false is rejected, and it cannot enable content logging when the workspace setting is off.

curl https://api.monsoon.sh/v1/chat/completions \
  -H "Authorization: Bearer $MONSOON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Monsoon-Log-Content: false" \
  -d '{
    "model": "organization/model-primary",
    "messages": [
      {
        "role": "user",
        "content": "Use only this synthetic test request."
      }
    ]
  }'

Founder-controlled prototype policy

The seeded demo workspace enables raw prompt and response logging only after explicit founder acknowledgement and uses seven-day retention for release verification. The admin can disable future content capture, select 1-, 7-, or 30-day retention, and delete already stored raw content while preserving non-content audit metadata.

This mode is allowed only for synthetic or test traffic that is non-personal, non-regulated, non-confidential, non-production, and not customer data. Raw content is never used for training, evaluation, model improvement, or unrelated analytics, and operational application logs never contain raw prompt or response bodies.

For any later customer workspace, metadata-only logging is the default. Optional raw-content logging requires explicit workspace-admin opt-in and counsel-confirmed notice, retention, deletion, and access controls.

Current prototype access

Monsoon Gateway is a founder-operated private prototype. The public landing page and these docs can be shared; the dashboard and inference API are not currently offered as self-service products or partner credentials.

What exists now

• One preconfigured founder/demo workspace
• One preconfigured founder/admin account
• At least one provisioned demo API key
• A private dashboard and Playground using the same API handlers as external clients
• Global model routing for the authenticated demo configuration
• A mock-only Vietnam endpoint clearly labelled Coming soon

What does not exist yet

• Public signup, invitations, account creation, or password recovery
• Self-service API-key access for applicants or partners
• Customer billing, payment collection, balances, invoices, or credits
• Public uptime, latency, durability, support-response, or residency SLA
• A production-readiness, compliance, security-certification, customer, or partner claim
• Real Vietnam-resident inference

The early-access form qualifies interest and allows Monsoon to contact applicants. Submitting it does not create an account, issue credentials, subscribe someone to a newsletter, or promise access.

Data restriction

All gateway and Playground traffic in the prototype must use synthetic or test data. Do not send personal, regulated, confidential, production, or customer data. This restriction is separate from the limited applicant data governed by the public early-access privacy notice.

Request early access or review the early-access privacy notice.

Generated API reference

The checked-in request contract.

This reference is rendered from openapi/monsoon.openapi.json, the schema snapshot generated by the API build. Request fields, constraints, and successful response schemas below are limited to the public inference operations; normalized errors are documented separately.