OpenAI Compatibility

Forra provides OpenAI-compatible endpoints that allow you to use Forra with any tool, library, or framework that supports OpenAI's API format. This means you can easily integrate Forra into existing workflows and applications without changing your code.

Endpoints

Forra offers two types of OpenAI-compatible endpoints:

General Endpoint

https://app.forra-ai.com/api/chat/openai_compatible

This endpoint uses the default Forra configuration and models.

Assistant-Specific Endpoint

https://app.forra-ai.com/api/chat/openai_compatible/{assistant_id}

This endpoint allows you to use a specific assistant with custom instructions, knowledge base, and configuration.

Configuration Examples

Export your config

Forra can generate a ready-to-use provider config for coding agents from the models you are allowed to use. Both endpoints require authentication and the openaiCompatible feature.

Tool	Endpoint	Typical config path
OpenCode	GET /api/chat/openai_compatible/export/opencode	~/.config/opencode/opencode.json or project opencode.json
pi.dev	GET /api/chat/openai_compatible/export/pi	~/.pi/agent/models.json

Example — write an OpenCode config:

curl -sS \
  -H "Authorization: Bearer $FORRA_API_KEY" \
  "https://app.forra-ai.com/api/chat/openai_compatible/export/opencode" \
  -o ~/.config/opencode/opencode.json

The OpenCode export does not embed an API key. Put the key in OpenCode's auth file instead (~/.local/share/opencode/auth.json):

{
  "forra": {
    "type": "api",
    "key": "YOUR_FORRA_API_KEY"
  }
}

The export also includes "plugin": ["@mirego/opencode-forra-attribution"] so git attribution works once the provider is configured.

Example — write a pi.dev models config:

curl -sS \
  -H "Authorization: Bearer $FORRA_API_KEY" \
  "https://app.forra-ai.com/api/chat/openai_compatible/export/pi" \
  -o ~/.pi/agent/models.json

The pi export also omits an API key — authenticate through pi's own provider login against the exported baseUrl. By default the export includes every LLM visible to the caller (costs, context limits, modalities, and reasoning options when available). Optionally pass model_ids as a comma-separated list to keep only specific models, or only_favorites=true to export the caller's favorite models from Settings (in favorite order). When both are provided, model_ids takes priority:

curl -sS \
  -H "Authorization: Bearer $FORRA_API_KEY" \
  "https://app.forra-ai.com/api/chat/openai_compatible/export/opencode?model_ids=claude-sonnet-4,gpt-5.2" \
  -o ~/.config/opencode/opencode.json

curl -sS \
  -H "Authorization: Bearer $FORRA_API_KEY" \
  "https://app.forra-ai.com/api/chat/openai_compatible/export/opencode?only_favorites=true" \
  -o ~/.config/opencode/opencode.json

OpenCode Configuration

Prefer the export endpoint above. If you cannot call the API, a minimal hand-authored OpenCode provider looks like this (claude-sonnet-4 is an example model id):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@mirego/opencode-forra-attribution"],
  "provider": {
    "forra": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Forra",
      "options": {
        "baseURL": "https://app.forra-ai.com/api/chat/openai_compatible"
      },
      "models": {
        "claude-sonnet-4": {
          "name": "Forra coding model",
          "cost": {
            "input": 3.0,
            "output": 15.0,
            "cache_read": 0.3,
            "cache_write": 3.75
          }
        }
      }
    }
  }
}

Store the API key in ~/.local/share/opencode/auth.json under provider id forra (see export section above) — do not put it in opencode.json.

OpenCode computes session cost client-side from streamed token counts multiplied by each model's cost rates (per 1M tokens). Forra does not drive the OpenCode dollar amount via total_cost; set cost to match the model rates shown in Forra for accurate display.

Usage is emitted when the client requests it with stream_options.include_usage (OpenCode sets this by default). Token fields follow OpenAI conventions: prompt_tokens includes cached input tokens, with the cache portion also reported under prompt_tokens_details.cached_tokens.

pi.dev Configuration

Prefer the export endpoint above. If you cannot call the API, a minimal hand-authored pi.dev provider in ~/.pi/agent/models.json looks like this:

{
  "providers": {
    "forra": {
      "name": "Forra",
      "baseUrl": "https://app.forra-ai.com/api/chat/openai_compatible",
      "api": "openai-completions",
      "compat": {
        "supportsDeveloperRole": true,
        "requiresThinkingAsText": true
      },
      "models": [
        {
          "id": "claude-sonnet-4",
          "name": "Forra coding model"
        }
      ]
    }
  }
}

Using with OpenAI SDK

You can use Forra with the official OpenAI SDK by changing the base URL:

from openai import OpenAI

client = OpenAI(
    base_url="https://app.forra-ai.com/api/chat/openai_compatible",
    api_key="your-forra-api-key"
)

response = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[
        {"role": "user", "content": "Hello, how can you help me?"}
    ]
)

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://app.forra-ai.com/api/chat/openai_compatible',
  apiKey: 'your-forra-api-key',
});

const chatCompletion = await openai.chat.completions.create({
  messages: [{ role: 'user', content: 'Hello, how can you help me?' }],
  model: 'claude-sonnet-4',
});

Available Models

Any model available in your Forra instance can be used through the OpenAI-compatible endpoints. To fetch the complete list of available models, make a GET request to:

https://app.forra-ai.com/api/chat/models/

This will return a JSON response with all available models and their configurations.

Authentication

You'll need a valid Forra API key to use these endpoints. To create an API token, go to https://app.forra-ai.com/settings/api-tokens and create a new token.

Supported Features

The OpenAI-compatible endpoints support:

• Chat completions
• Streaming responses
• Multiple message roles (system, user, assistant)
• Model selection
• Temperature and other generation parameters