> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Launch on the free router

> Start with phaseo/free so your first integration can run without choosing a single fixed free model up front.

Use this recipe to get your first Phaseo integration running without picking a paid model yet.

Instead of picking one free model yourself, send requests to `phaseo/free`. Phaseo will choose an available free model that supports the request you are making.

## When to use this

* You want a working prototype before choosing a paid model.
* You expect the best free option to change over time.
* You want one stable model ID in application code while Phaseo handles free-provider changes behind the scenes.

## Example request

```bash cURL theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "phaseo/free",
    "input": "Summarize why provider-aware free routing helps prototypes.",
    "temperature": 0.2
  }'
```

```typescript TypeScript SDK theme={null}
import Phaseo from "@phaseo/sdk";

const client = new Phaseo({ apiKey: process.env.PHASEO_API_KEY! });

const response = await client.generateResponse({
  model: "phaseo/free",
  input: "Summarize why provider-aware free routing helps prototypes.",
  temperature: 0.2,
});

console.log(response.output_text);
```

```python Python SDK theme={null}
from phaseo import Phaseo

client = Phaseo(api_key="YOUR_API_KEY")

response = client.generate_response(
    {
        "model": "phaseo/free",
        "input": "Summarize why provider-aware free routing helps prototypes.",
        "temperature": 0.2,
    }
)

print(response.get("output_text"))
```

```go Go SDK theme={null}
package main

import (
  "context"
  "fmt"

  phaseo "github.com/phaseoteam/Phaseo/packages/sdk/sdk-go/v3"
)

func main() {
  client := phaseo.New("YOUR_API_KEY", "https://api.phaseo.app/v1")

  response, err := client.GenerateResponse(context.Background(), phaseo.ResponsesRequest{
    Model: "phaseo/free",
    Input: map[string]interface{}{
      "role": "user",
      "content": []map[string]string{
        {
          "type": "input_text",
          "text": "Summarize why provider-aware free routing helps prototypes.",
        },
      },
    },
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(response)
}
```

```csharp C# SDK theme={null}
using PhaseoSdk;
using System.Collections.Generic;

var client = new Phaseo("YOUR_API_KEY");

var response = await client.GenerateResponse(new Dictionary<string, object>
{
    ["model"] = "phaseo/free",
    ["input"] = "Summarize why provider-aware free routing helps prototypes.",
    ["temperature"] = 0.2
});

Console.WriteLine(response);
```

```php PHP SDK theme={null}
<?php
require 'vendor/autoload.php';

use Phaseo\Sdk\Phaseo;

$client = new Phaseo(getenv('PHASEO_API_KEY') ?: 'YOUR_API_KEY');

$response = $client->generateResponse([
    'model' => 'phaseo/free',
    'input' => 'Summarize why provider-aware free routing helps prototypes.',
    'temperature' => 0.2,
]);

print_r($response);
```

```ruby Ruby SDK theme={null}
require 'phaseo_sdk'

client = PhaseoSdk::Phaseo.new(api_key: ENV.fetch('PHASEO_API_KEY', 'YOUR_API_KEY'))

response = client.generate_response(
  model: 'phaseo/free',
  input: 'Summarize why provider-aware free routing helps prototypes.',
  temperature: 0.2
)

puts response
```

## What happens behind the scenes

1. Your request goes to the shared `phaseo/free` alias.
2. Phaseo checks which free models can handle that request.
3. One available free model is selected and used for the response.
4. Request details still show the exact model that ran, so you can inspect or debug it later.

## After your first request

* In **Gateway -> Usage**, open the request details and confirm which model was used.
* If the request is blocked by workspace policy, check the request details to see which setting stopped it.
* If no free model supports the feature you need, switch from `phaseo/free` to a specific paid model instead of retrying the same request.

## Production notes

* Keep `phaseo/free` for prototypes, demos, and low-stakes traffic.
* If you need predictable latency, output style, or provider choice, move to a specific model once you know what works best.
* If you need stable prompt behavior across services, pair this recipe with [Presets](https://phaseo.app/docs/v1/guides/presets.md).

## Related guides

* [Quickstart](https://phaseo.app/docs/v1/quickstart.md)
* [Routing and Fallbacks](https://phaseo.app/docs/v1/guides/routing-and-fallbacks.md)
* [API Errors](https://phaseo.app/docs/v1/api-reference/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.