OpenAI-compatible API

Base URL and authentication

Use ForgeRouter as an OpenAI-compatible base URL and send an active API key with Bearer authentication. Store secrets in environment variables and manage keys from API keys.

The snippets on this page are illustrative and are not executed against a live provider in CI. CI verifies their routes, authentication variables and documented contract fields; run a smoke call only with a non-sensitive test key and prompt.

export FORGEROUTER_BASE_URL="https://router.forgesoftware.fr"
export FORGEROUTER_API_KEY="your_key_from_the_dashboard"

GET /v1/models

The response is OpenAI-compatible with an additional forgerouter object per model. The default balanced policy lists published non-Community deployments only; Community deployments require economy-community policy and consent.

curl "$FORGEROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $FORGEROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "provider-a/hermes-observed",
      "object": "model",
      "owned_by": "provider-a",
      "forgerouter": {
        "deployment_id": 42,
        "canonical_model": "nousresearch/hermes-3-llama-3.1-8b",
        "provider": "provider-a",
        "trust_tier": "observed",
        "publication_status": "observed",
        "country": "FR",
        "country_evidence": "declared",
        "pricing_version": "price_2026_06_001"
      }
    }
  ]
}

POST /v1/chat/completions

Send the usual OpenAI-compatible payload. ForgeRouter removes the provider routing object before forwarding the request to the selected endpoint.

curl "$FORGEROUTER_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $FORGEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nousresearch/hermes-3-llama-3.1-8b",
    "messages": [{"role": "user", "content": "Use a non-sensitive test prompt."}],
    "provider": {
      "routing_profile": "balanced",
      "countries": ["FR", "DE"],
      "max_price_per_million": 2.00
    },
    "stream": false
  }'

Exact selection uses a deployment slug as the model or provider.only. No fallback may bypass provider, tier, country, data policy, maximum price, quantization or required capability constraints.

Marketplace audit metadata

Successful JSON chat responses include a provider object. The same routing facts are also available from headers and request history.

• provider.id and X-Forge-Provider
• provider.deployment and X-Forge-Deployment
• provider.trust_tier and X-Forge-Trust-Tier
• provider.country and X-Forge-Country
• provider.pricing_version and X-Forge-Pricing-Version
• provider.request_policy and X-Forge-Request-Policy

Streaming SSE

Set stream: true to proxy provider SSE chunks. Client cancellation is propagated when the connection is aborted. Connection, first-token, inter-chunk and total timeouts are controls, not availability guarantees.

const response = await fetch(`${process.env.FORGEROUTER_BASE_URL}/v1/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORGEROUTER_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "provider-a/hermes-observed",
    messages: [{ role: "user", content: "Use a non-sensitive test prompt." }],
    stream: true
  }),
  signal: abortController.signal
});

Python example

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["FORGEROUTER_BASE_URL"],
    api_key=os.environ["FORGEROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="provider-a/hermes-observed",
    messages=[{"role": "user", "content": "Use a non-sensitive test prompt."}],
)

print(completion.choices[0].message.content)

Errors

Errors use an OpenAI-compatible error object. Common codes include:

• invalid_api_key for missing, revoked or suspended API keys.
• validation_failed for malformed request bodies.
• model_not_found when no deployment matches the hard routing constraints.
• insufficient_wallet_balance, request_budget_exceeded or api_key_rpm_limit_exceeded before provider calls.
• provider_capacity_exceeded, gateway_error, provider_network_blocked or provider_unreachable for gateway/provider controls.
• invalid_provider_stream_chunk or provider_stream_interrupted for degraded streaming.