0
# Core Client
1

2
The core Phoenix client provides direct access to all Phoenix API endpoints through a strongly-typed OpenAPI interface with automatic configuration management and middleware support.
3

4
## Capabilities
5

6
### Client Creation
7

8
Creates a Phoenix API client with optional configuration customization.
9

10
```typescript { .api }
11
/**
12
 * Create a Phoenix client with strongly-typed OpenAPI interfaces
13
 * @param config - Configuration object with options and environment function
14
 * @returns Configured Phoenix client instance
15
 */
16
function createClient(config?: {
17
  options?: Partial<ClientOptions>;
18
  getEnvironmentOptions?: () => Partial<ClientOptions>;
19
}): PhoenixClient;
20

21
interface ClientOptions {
22
  baseUrl?: string;
23
  headers?: Record<string, string>;
24
  signal?: AbortSignal;
25
  [key: string]: unknown;
26
}
27

28
interface PhoenixClient {
29
  GET<T = unknown>(
30
    url: string,
31
    options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
32
  ): Promise<{ data?: T; error?: unknown; response: Response }>;
33

34
  POST<T = unknown>(
35
    url: string,
36
    options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
37
  ): Promise<{ data?: T; error?: unknown; response: Response }>;
38

39
  PUT<T = unknown>(
40
    url: string,
41
    options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
42
  ): Promise<{ data?: T; error?: unknown; response: Response }>;
43

44
  DELETE<T = unknown>(
45
    url: string,
46
    options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
47
  ): Promise<{ data?: T; error?: unknown; response: Response }>;
48

49
  PATCH<T = unknown>(
50
    url: string,
51
    options?: { params?: { query?: Record<string, unknown>; path?: Record<string, unknown> }; body?: unknown; headers?: Record<string, string> }
52
  ): Promise<{ data?: T; error?: unknown; response: Response }>;
53

54
  config: ClientOptions;
55
  use(middleware: Middleware): void;
56
}
57

58
interface Middleware {
59
  onRequest?: (request: { url: string; options: RequestInit }) => void | Promise<void>;
60
  onResponse?: (response: { response: Response; url: string; options: RequestInit }) => void | Promise<void>;
61
}
62
```
63

64
**Usage Example:**
65

66
```typescript
67
import { createClient } from "@arizeai/phoenix-client";
68

69
// Default client (localhost:6006)
70
const client = createClient();
71

72
// Custom configuration
73
const client = createClient({
74
  options: {
75
    baseUrl: "https://your-phoenix-instance.com",
76
    headers: {
77
      "Custom-Header": "value"
78
    }
79
  }
80
});
81

82
// Make API calls
83
const traces = await client.GET("/v1/traces", {
84
  params: {
85
    query: {
86
      limit: 50,
87
      start_time: "2024-01-01T00:00:00Z"
88
    }
89
  }
90
});
91
```
92

93
### Configuration Merging
94

95
Utility for merging configuration options with priority handling.
96

97
```typescript { .api }
98
/**
99
 * Merge configuration options with priority: defaults < environment < explicit options
100
 * @param params - Configuration parameters
101
 * @returns Merged configuration options
102
 */
103
function getMergedOptions(params?: {
104
  options?: Partial<ClientOptions>;
105
  getEnvironmentOptions?: () => Partial<ClientOptions>;
106
}): ClientOptions;
107
```
108

109
**Usage Example:**
110

111
```typescript
112
import { getMergedOptions } from "@arizeai/phoenix-client";
113

114
// Get merged configuration before creating client
115
const config = getMergedOptions({
116
  options: {
117
    baseUrl: "https://custom-phoenix.com",
118
    headers: { "X-API-Version": "v1" }
119
  }
120
});
121

122
const client = createClient({ options: config });
123
```
124

125
### Environment Configuration
126

127
Default environment configuration system that reads from process environment variables.
128

129
```typescript { .api }
130
/**
131
 * Get environment-based configuration from process.env
132
 * Supports PHOENIX_API_KEY, PHOENIX_HOST, PHOENIX_CLIENT_HEADERS
133
 * @returns Configuration options from environment variables
134
 */
135
function defaultGetEnvironmentOptions(): Partial<ClientOptions>;
136

137
/**
138
 * Create default client configuration
139
 * @returns Default configuration with localhost:6006 as baseUrl
140
 */
141
function makeDefaultClientOptions(): Partial<ClientOptions>;
142
```
143

144
**Environment Variables:**
145

146
- `PHOENIX_API_KEY`: Sets Authorization header as Bearer token
147
- `PHOENIX_HOST`: Sets the baseUrl for the client
148
- `PHOENIX_CLIENT_HEADERS`: JSON string of additional headers
149

150
**Usage Example:**
151

152
```typescript
153
// Environment variables:
154
// PHOENIX_HOST=https://phoenix.company.com
155
// PHOENIX_API_KEY=your-secret-key
156
// PHOENIX_CLIENT_HEADERS={"X-Team": "ai-platform"}
157

158
import { createClient } from "@arizeai/phoenix-client";
159

160
// Automatically uses environment configuration
161
const client = createClient();
162
```
163

164
### Type Definitions
165

166
Complete OpenAPI-generated type definitions for all Phoenix API interactions.
167

168
```typescript { .api }
169
/**
170
 * Generated OpenAPI types organized by API version
171
 */
172
interface Types {
173
  V1: {
174
    paths: pathsV1;
175
    components: componentsV1;
176
    operations: operationsV1;
177
  };
178
}
179

180
type pathsV1 = {
181
  "/v1/traces": {
182
    get: operations["getTraces"];
183
  };
184
  "/v1/prompts": {
185
    get: operations["getPrompts"];
186
    post: operations["createPrompt"];
187
  };
188
  "/v1/datasets": {
189
    get: operations["getDatasets"];
190
    post: operations["createDataset"];
191
  };
192
  // ... all other API endpoints
193
};
194

195
type componentsV1 = {
196
  schemas: {
197
    Prompt: { /* OpenAPI schema */ };
198
    Dataset: { /* OpenAPI schema */ };
199
    Experiment: { /* OpenAPI schema */ };
200
    // ... all other component schemas
201
  };
202
};
203

204
type operationsV1 = {
205
  getTraces: {
206
    parameters: { /* parameter definitions */ };
207
    responses: { /* response definitions */ };
208
  };
209
  // ... all other operations
210
};
211
```
212

213
### Error Handling
214

215
The client includes built-in error handling middleware that throws errors for non-successful responses.
216

217
**Error Format:**
218

219
Errors thrown by the client follow the format: `"<URL>: <status> <statusText>"`
220

221
**Usage Example:**
222

223
```typescript
224
import { createClient } from "@arizeai/phoenix-client";
225

226
const client = createClient();
227

228
try {
229
  const result = await client.GET("/v1/nonexistent-endpoint");
230
} catch (error) {
231
  console.error(error.message);
232
  // Output: "http://localhost:6006/v1/nonexistent-endpoint: 404 Not Found"
233
}
234
```