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

# Presets

> Save reusable Gateway configurations for your team.

Presets are reusable configurations that help teams standardize prompts, model preferences, and routing defaults. They are managed with the `phaseo presets` CLI commands, the `/v1/presets` API or the Phaseo dashboard, and can be shared across a team.

## Quick start

**1. Create a preset**

Open **Dashboard -> Settings -> Presets** and create a preset with a clear slug, such as `release-summary`. Add only the defaults that should be shared across callers. From the CLI, run `phaseo presets create --name @release-summary --model <model-id>`.

**2. Reference the preset in a request**

Keep the caller focused on the user input while the preset supplies stable prompt, parameter, and routing defaults.

```bash cURL theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  -H "Content-Type: application/json" \
	  -d '{
	    "model": "@release-summary",
	    "input": "Generate a release summary for the last 24 hours."
	  }'
```

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

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

const response = await client.generateResponse({
	  model: "@release-summary",
	  input: "Generate a release summary for the last 24 hours.",
});
```

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

client = Phaseo(api_key="YOUR_API_KEY")

response = client.generate_response({
	    "model": "@release-summary",
	    "input": "Generate a release summary for the last 24 hours.",
})
```

**3. Check the routing result**

Open the request in **Gateway -> Usage** to confirm which defaults were applied and which provider served it.

## What a preset can include

* A system prompt to prepend to every request.
* A [prompt template](https://phaseo.app/docs/v1/guides/prompt-templates.md): messages with `{{variables}}` that each request fills in.
* Allowed models or model families.
* Provider allow/ignore lists for routing preferences.
* Default parameters (temperature, top\_p, max\_tokens, and similar settings).
* Optional reasoning defaults for supported models.

Preset names are prefixed with `@` to keep them easy to recognize.

Invoke a preset through the request's `model` field, or through `prompt.id` when the preset has a [prompt template](https://phaseo.app/docs/v1/guides/prompt-templates.md). Phaseo does not expose a separate `preset` request field.

* Private and workspace presets use `@{slug}` and resolve inside the API key's workspace.
* Public presets use `@{username}/{slug}` and can resolve from any workspace. For example, `@octavia/release-summary`.

Public publishing requires an enabled public profile and username. Public slug conflicts are scoped to that publisher, so two publishers may use the same slug without ambiguity. Usernames are globally unique. Slugs are normalised to lower case and support letters, numbers, hyphens, underscores, periods, and colons.

## Versions and marketplace forks

Saving changes updates a private draft. Use **Publish new version** when those changes are ready; Phaseo creates an immutable numbered release while retaining every earlier version for review.

Preset owners can choose how release labels are displayed:

* **Sequential:** `v1`, `v2`, `v3`.
* **Semantic Versioning:** explicit SemVer labels such as `1.2.0`, `2.0.0-beta.1`, or `1.4.2+build.7`.
* **Date versioning:** `YYYY.MM.DD`, with a numeric suffix when multiple releases are published on the same date, such as `2026.08.02.2`.

Phaseo maintains a separate monotonic release number internally, so chronology, upstream comparisons, and lineage remain deterministic regardless of the selected public label format.

Marketplace copies remain pinned to the exact upstream version they copied. When the publisher releases an update, the copied preset shows an update notice. Applying it updates the copy's draft only, so the workspace owner can review and explicitly publish it without an upstream author changing production behaviour.

Phaseo retains both the immediate source and the complete ancestry of every fork. Marketplace pages can therefore distinguish direct forks from all descendants, even when a preset has been copied and republished several times.

Requests can pin a published version by its label, such as `@support-triage@v3`, or by a named label such as `production` that you point at a version. Moving a label back to an earlier version is a rollback. See [Versions and labels](https://phaseo.app/docs/v1/guides/prompt-templates.md#versions-and-labels).

## How preset merging works

When a request resolves with a preset in gateway context, the preset is applied before provider routing:

* Default parameters only fill fields that are missing in the request body. They do not overwrite values already provided by the caller.
* If the request already has a system message, the preset prompt is prepended. If the request uses an Anthropic-style `system` field, the preset prompt is prepended there instead.
* Provider allow/ignore lists are applied before provider selection, so they narrow the fallback pool instead of acting as a cosmetic label.
* Requests outside the preset's allowed model list are rejected early instead of being silently rerouted.

This makes presets the main public surface for reusable request defaults and lightweight compatibility transforms without forcing every caller to duplicate the same prompt or parameter logic.

## Current public preset surface

The dashboard preset flow is intentionally scoped to a stable, explicit subset of request shaping:

* system prompt injection
* prompt templates with typed variables
* model allowlists
* provider allow/ignore routing constraints
* decoding and generation defaults
* reasoning defaults

If you need more complex caller-specific transforms, keep them in one application boundary layer and let presets carry the reusable team-wide defaults.

## Manage presets

Create and manage presets in **Dashboard -> Settings -> Presets**, or with `phaseo presets create|update`, `phaseo presets versions create` and `phaseo presets labels set` (the `/v1/presets` API). Use separate slugs when workflows need meaningfully different prompt, routing, or caching behavior.

## When to use presets

* Standardize system prompts across multiple services.
* Constrain routing to approved providers for compliance.
* Keep default parameters consistent across environments.
* Give migration projects one durable place to carry prompt, routing, and parameter defaults while the application code stays mostly unchanged.

## Related guides

* [Prompt Templates](https://phaseo.app/docs/v1/guides/prompt-templates.md)
* [Collect Feedback for Presets](https://phaseo.app/docs/v1/guides/preset-feedback.md)
* [Routing and Fallbacks](https://phaseo.app/docs/v1/guides/routing-and-fallbacks.md)
* [Inference Parameters](https://phaseo.app/docs/v1/guides/inference-parameters.md)
* [Feature Parity Matrix](https://phaseo.app/docs/v1/migration-guides/feature-parity-matrix.md)


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