> ## 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.

# Integrating with the Gateway

> Connect an application to Phaseo Gateway, choose an endpoint, and prepare the integration for production.

Use this how-to guide after the quickstart, when you are ready to put Phaseo behind a real application feature.

By the end, you should have:

* a safely stored API key
* a clear endpoint choice
* one working request in your app
* links to the right production guides for routing, SDKs, and operations

***

## Before you begin

Make sure you have the following in place:

* A Phaseo account with Gateway access.
* An API key from `phaseo keys create` in the [Phaseo CLI](https://phaseo.app/docs/v1/guides/integrations/phaseo-cli.md) or from the [dashboard](https://phaseo.app/settings/keys).
* An HTTP client, OpenAI-compatible SDK, or Phaseo SDK.
* A supported model ID, such as `google/gemma-3-27b:free` for a zero-credit start.

***

## 1. Store the API key

1. Run `phaseo keys create --name <app-and-environment> --json`, or open **Gateway -> API Keys** in the Phaseo dashboard.
2. Give the key a name that identifies the app and environment.
3. Store the value in a secret manager or local environment file:

```bash theme={null}
# .env
PHASEO_API_KEY="phaseo_v1_sk_<kid>_<secret>"
```

> [!TIP]
>
> Use separate keys for local development, preview deployments, and production. It makes rotation and usage review much easier.

***

## 2. Choose the endpoint

Choose the endpoint that best matches the job you are doing:

| Endpoint | When to use it |
| - | - |
| `/v1/responses` | New text builds, structured outputs, and multi-step workflows. |
| `/v1/chat/completions` | Chat interfaces, assistants, and OpenAI-style integrations. |
| `/v1/messages` | Anthropic-compatible integrations. |
| `/v1/decisions` | Typed decisions against application state with Jev 1.13. |
| `/v1/moderations` | Safety and content policy checks. |
| `/v1/images/generations` | Image generation from text prompts. |

Refer to the [API Reference](https://phaseo.app/docs/v1/api-reference/introduction.md) for the complete list of supported parameters and responses.

> [!NOTE]
>
> Free-model IDs end with `:free` and can be called without depositing credits. Paid-model calls require available wallet balance.

***

## 3. Send the app request

Start with the request shape your app is most likely to keep. This example uses Chat Completions because it works well for OpenAI-compatible clients.

```bash cURL theme={null}
curl https://api.phaseo.app/v1/chat/completions \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-3-27b:free",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Explain the benefits of AI." }
    ]
  }'
```

```typescript TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PHASEO_API_KEY,
  baseURL: "https://api.phaseo.app/v1",
});

const response = await client.chat.completions.create({
  model: "google/gemma-3-27b:free",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain the benefits of AI." },
  ],
});

console.log(response.choices[0]?.message?.content);
```

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.phaseo.app/v1",
)

response = client.chat.completions.create(
    model="google/gemma-3-27b:free",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the benefits of AI."},
    ],
)

print(response.choices[0].message.content)
```

```go Go 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.ChatCompletions(context.Background(), map[string]interface{}{
    "model": "google/gemma-3-27b:free",
    "messages": []map[string]string{
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain the benefits of AI."},
    },
  })
  if err != nil {
    panic(err)
  }

  fmt.Println(response)
}
```

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

var client = new Phaseo("YOUR_API_KEY");

var response = await client.ChatCompletions(new Dictionary<string, object>
{
    ["model"] = "google/gemma-3-27b:free",
    ["messages"] = new object[]
    {
        new Dictionary<string, object> { ["role"] = "system", ["content"] = "You are a helpful assistant." },
        new Dictionary<string, object> { ["role"] = "user", ["content"] = "Explain the benefits of AI." }
    }
});

Console.WriteLine(response);
```

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

use Phaseo\Sdk\Phaseo;

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

$response = $client->chatCompletions([
    'model' => 'google/gemma-3-27b:free',
    'messages' => [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user', 'content' => 'Explain the benefits of AI.'],
    ],
]);

print_r($response);
```

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

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

response = client.chat_completions(
  model: 'google/gemma-3-27b:free',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain the benefits of AI.' }
  ]
)

puts response
```

***

## 4. Configure environments

Store your API key in environment variables for different environments:

```bash theme={null}
# .env.local
PHASEO_API_KEY="phaseo_v1_sk_<kid>_<secret>"
PHASEO_BASE_URL="https://api.phaseo.app/v1"
```

When making requests, send the key in the `Authorization` header:

```http theme={null}
Authorization: Bearer $PHASEO_API_KEY
```

***

## 5. Production next steps

* Review [Authentication](https://phaseo.app/docs/v1/developers/authentication.md) for key handling and common auth failures.
* Learn [Routing and fallbacks](https://phaseo.app/docs/v1/guides/routing-and-fallbacks.md) before sending meaningful traffic.
* Browse [Examples](https://phaseo.app/docs/v1/guides/examples.md) for complete app and script patterns.
* Explore the [SDK Reference](https://phaseo.app/docs/v1/sdk-reference/typescript/overview.md) for language-specific clients.


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