> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140-feat-new-brand-design-system.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# REST API Overview
> Start here to call the Phoenix REST API: endpoint setup, authentication, and your first request.
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.
Browse every endpoint grouped by resource.
## Before You Call The API
* A remote deployment: `https://your-phoenix.example.com`
* Self-hosted Phoenix: your deployment URL (for example `http://localhost:6006`)
Use an API key or admin secret in a bearer token header:
`Authorization: Bearer `
All REST endpoints are under `/v1/...`.
If authentication is disabled in your self-hosted deployment, you can omit the `Authorization` header.
## First Request
The example below lists projects and includes common pagination query params.
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl --request GET \
--url "$PHOENIX_ENDPOINT/v1/projects?limit=10" \
--header "Authorization: Bearer $PHOENIX_API_KEY"
```
```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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);
```
```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import os
import requests
base_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:
```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
"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.
Phoenix is not an AI gateway. The same server also takes on trace ingestion traffic, so routing production LLM calls through it competes with ingestion. Use this endpoint only to quickly try out different models in non-production environments.
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.
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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
Start by listing projects and finding your project identifier.
Query spans for a project.
Create and manage evaluation datasets.
Manage prompt versions and tags.