REST API Overview

Use the REST API when you want to script Phoenix workflows: creating datasets, running experiments, querying spans, or managing prompts and projects. Use the API Reference page for the full endpoint list.

Before You Call The API#

First Request#

The example below lists projects and includes common pagination query params.

curl --request GET \  --url "$PHOENIX_ENDPOINT/v1/projects?limit=10" \  --header "Authorization: Bearer $PHOENIX_API_KEY"

const baseUrl = process.env.PHOENIX_ENDPOINT;const apiKey = process.env.PHOENIX_API_KEY;const response = await fetch(  `${baseUrl}/v1/projects?limit=10`,  {    headers: {      Authorization: `Bearer ${apiKey}`,    },  });const body = await response.json();console.log(body.data);

import osimport requestsbase_url = os.environ["PHOENIX_ENDPOINT"]api_key = os.environ.get("PHOENIX_API_KEY")headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}response = requests.get(    f"{base_url}/v1/projects",    params={"limit": 10},    headers=headers,    timeout=30,)response.raise_for_status()body = response.json()print(body["data"])

Response Pattern#

Most list endpoints return a shape like:

{  "data": [],  "next_cursor": null}

When next_cursor is not null, pass it back as the cursor query param to fetch the next page.

Chat Completions Proxy#

POST /v1/chat/completions accepts the OpenAI wire format and proxies the call to the provider you name, resolving provider credentials on the server (secret store first, environment second) so callers never handle provider API keys.

Set model to {provider}:{model_name} for a built-in provider, or custom:{provider_id}:{model_name} for a custom provider you have stored. Pass stream: true for server-sent chat.completion.chunk events terminated by data: [DONE]. Tool calling is not supported.

curl --request POST \  --url "$PHOENIX_BASE_URL/v1/chat/completions" \  --header "Authorization: Bearer $PHOENIX_API_KEY" \  --header "Content-Type: application/json" \  --data '{    "model": "openai:gpt-4o",    "messages": [{"role": "user", "content": "Hello!"}]  }'

Where To Go Next#