> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-ehutt-trail-benchmark-new-tasks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Typed TypeScript client for Phoenix platform APIs

`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, secrets, users, and CI-friendly dataset-backed eval tests.

## Install

```bash theme={null}
npm install @arizeai/phoenix-client
```

## Minimal Example

```ts theme={null}
import { createClient } from "@arizeai/phoenix-client";
import { listDatasets } from "@arizeai/phoenix-client/datasets";

const client = createClient();
const datasets = await listDatasets({ client });
```

## Docs And Source In `node_modules`

After install, a coding agent can inspect the installed package directly:

```text theme={null}
node_modules/@arizeai/phoenix-client/docs/
node_modules/@arizeai/phoenix-client/src/
```

That gives the agent version-matched docs plus the exact implementation and generated API types that shipped with your project.

## Module Map

| Import | Purpose |
| - | - |
| `@arizeai/phoenix-client` | `createClient`, generated OpenAPI types, config helpers |
| `@arizeai/phoenix-client/projects` | Project listing and retention-policy assignment |
| `@arizeai/phoenix-client/prompts` | Prompt CRUD plus `toSDK` conversion |
| `@arizeai/phoenix-client/datasets` | Dataset creation and retrieval |
| `@arizeai/phoenix-client/experiments` | Experiment execution and lifecycle |
| `@arizeai/phoenix-client/spans` | Span search, notes, and span/document annotations |
| `@arizeai/phoenix-client/sessions` | Session listing, retrieval, and session annotations |
| `@arizeai/phoenix-client/traces` | Project trace retrieval, transfers, and trace annotations |
| `@arizeai/phoenix-client/secrets` | Atomic secret creation, rotation, and deletion |
| `@arizeai/phoenix-client/users` | Current authenticated user retrieval |
| `@arizeai/phoenix-client/vitest` | Vitest entrypoint for dataset-backed eval tests |
| `@arizeai/phoenix-client/vitest/reporter` | Vitest reporter for Phoenix eval summaries |
| `@arizeai/phoenix-client/jest` | Jest entrypoint for dataset-backed eval tests |
| `@arizeai/phoenix-client/jest/reporter` | Jest reporter for Phoenix eval summaries |

## Configuration

`createClient()` resolves Phoenix client options in this order: library defaults, environment variables, then explicit options. In most applications, the normal setup is to set `PHOENIX_ENDPOINT` and `PHOENIX_API_KEY` in the environment and call `createClient()` with no overrides.

### Recommended Setup

Use the environment-driven path unless you have a specific reason to override client options in code.

```bash theme={null}
export PHOENIX_ENDPOINT=http://localhost:6006
export PHOENIX_API_KEY=<your-api-key>
```

For a remote deployment, `PHOENIX_ENDPOINT` is that instance's base URL, e.g. `https://your-phoenix.example.com`.

```ts theme={null}
import { createClient } from "@arizeai/phoenix-client";

const client = createClient();

const datasets = await client.GET("/v1/datasets");
```

`PHOENIX_API_KEY` is converted into `Authorization: Bearer <key>` automatically. You do not need to build that header yourself unless you are explicitly overriding `headers`.

### Explicit Overrides

```ts theme={null}
import { createClient } from "@arizeai/phoenix-client";

const client = createClient({
  options: {
    baseUrl: "https://phoenix.example.com",
    headers: {
      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
    },
  },
});
```

Use explicit options when you want configuration to live in code or when you need to override the environment for a specific client instance.

### createClient Parameters

| Field | Type | Description |
| - | - | - |
| `options` | `Partial<ClientOptions>` | Explicit options passed to the underlying `openapi-fetch` client. |
| `getEnvironmentOptions` | `() => Partial<ClientOptions>` | Optional resolver for environment-derived options. The default implementation reads `process.env` when available. |

### Resolved Phoenix Options

These are the Phoenix-specific options this package resolves before creating the underlying OpenAPI client:

| Option | Type | Description |
| - | - | - |
| `baseUrl` | `string` | Base Phoenix URL. Defaults to `http://localhost:6006`, or `PHOENIX_ENDPOINT` when that environment variable is set. |
| `headers` | `ClientOptions["headers"]` | Headers sent on every request. `PHOENIX_API_KEY` populates `Authorization` automatically. Explicit `headers` replace environment-derived headers. |

### Header Override Rule

If you pass `options.headers`, they replace the environment-derived header object rather than deep-merging with it. That means if you override `headers` and still want API key authentication, include `Authorization` yourself:

```ts theme={null}
const client = createClient({
  options: {
    headers: {
      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,
    },
  },
});
```

### Environment Variables

| Variable | Maps to | Description |
| - | - | - |
| `PHOENIX_ENDPOINT` | `options.baseUrl` | Base Phoenix URL, for example `http://localhost:6006`. |
| `PHOENIX_API_KEY` | `options.headers.Authorization` | Bearer token for authenticated environments. |
| `PHOENIX_CLIENT_HEADERS` | `options.headers` | Optional JSON-encoded object of additional headers to send on every request. Most setups do not need this. |

## API Client

`createClient()` returns an `openapi-fetch` client that is typed against Phoenix's generated OpenAPI schema. Use this layer when you need an endpoint that does not yet have a high-level helper.

```ts theme={null}
import { createClient } from "@arizeai/phoenix-client";

const client = createClient();

const datasets = await client.GET("/v1/datasets");

const prompt = await client.GET("/v1/prompts/{prompt_identifier}/latest", {
  params: {
    path: {
      prompt_identifier: "support-response",
    },
  },
});
```

The root export exposes generated API types: `pathsV1`, `componentsV1`, `operationsV1`, `Types`, and `PhoenixClient`.

Prefer this layer when:

* you need a newly added endpoint before a helper exists
* you want direct control over route, body, and query params
* you are building thin wrappers around Phoenix routes in your own codebase

## Where To Start

* [Projects](./projects), [Prompts](./prompts), [Datasets](./datasets), [Experiments](./experiments) — higher-level workflows
* [Annotations](./annotations) — annotation concepts, then [Span](./span-annotations), [Document](./document-annotations), and [Session](./session-annotations) annotations for detailed usage
* [CI Eval Tests](./ci-evals) — Vitest/Jest eval suites backed by Phoenix datasets and experiments
* [Spans](./spans), [Sessions](./sessions), [Traces](./traces), [Users](./users) — retrieval and maintenance
* [Secrets](./secrets) — encrypted provider credential management

<section className="hidden" data-agent-context="source-map" aria-label="Source map">
  <h2>Source Map</h2>

  <ul>
    <li><code>src/client.ts</code></li>
    <li><code>src/authFetch.ts</code></li>
    <li><code>src/config.ts</code></li>
    <li><code>src/**generated**/api/v1.ts</code></li>
    <li><code>src/types/core.ts</code></li>
    <li><code>src/projects/</code></li>
    <li><code>src/prompts/</code></li>
    <li><code>src/datasets/</code></li>
    <li><code>src/experiments/</code></li>
    <li><code>src/spans/</code></li>
    <li><code>src/sessions/</code></li>
    <li><code>src/traces/</code></li>
    <li><code>src/secrets/</code></li>
    <li><code>src/users/</code></li>
    <li><code>src/vitest/</code></li>
    <li><code>src/jest/</code></li>
    <li><code>src/testing/</code></li>
    <li><code>src/types/</code></li>
  </ul>
</section>