Implementation:Arize ai Phoenix OpenAPI Spec Canonical
Overview
The schemas/openapi.json file is the canonical OpenAPI specification and the source of truth for the Phoenix REST API. It is an OpenAPI 3.1.0 document that exhaustively defines every REST endpoint, request/response schema, query parameter, and error response for the Phoenix server. Other copies of the specification (such as the one embedded in the documentation site) are derived from this file.
The specification declares the API as Arize-Phoenix REST API version 1.0.
Code Reference
| Attribute | Value |
|---|---|
| Source File | schemas/openapi.json |
| Lines | 9,817 |
| Domain | API_Documentation |
| OpenAPI Version | 3.1.0 |
| API Version | 1.0 |
API Resource Groups
All endpoints are versioned under the /v1/ prefix. The specification covers the following resource groups:
| Resource Group | Endpoints | Operations |
|---|---|---|
| Annotation Configs | /v1/annotation_configs, /v1/annotation_configs/{config_identifier}, /v1/annotation_configs/{config_id} |
CRUD for annotation configuration definitions |
| Annotations | Span, Trace, Session, and Document annotation endpoints under /v1/projects/{project_identifier}/ |
Create/list annotations scoped to projects |
| Datasets | /v1/datasets, /v1/datasets/{id}, /v1/datasets/upload, /v1/datasets/{id}/examples |
Dataset management, CSV/JSONL export (OpenAI fine-tuning and evals formats) |
| Experiments | /v1/datasets/{dataset_id}/experiments, /v1/experiments/{experiment_id}, /v1/experiments/{experiment_id}/runs |
Experiment lifecycle, run tracking, JSON/CSV export |
| Evaluations | /v1/evaluations, /v1/experiment_evaluations |
Evaluation submission and retrieval |
| Traces & Spans | /v1/traces/{trace_identifier}, /v1/spans/{span_identifier}, /v1/projects/{project_identifier}/spans |
Trace and span querying, OTLP ingestion |
| Prompts | /v1/prompts, /v1/prompts/{prompt_identifier}/versions, /v1/prompt_versions/{prompt_version_id}/tags |
Prompt management with versioning and tagging |
| Projects | /v1/projects, /v1/projects/{project_identifier} |
Project CRUD operations |
| Users | /v1/users, /v1/users/{user_id} |
User management |
Schema Components
The components/schemas section defines reusable data models including request bodies (e.g., CreateAnnotationConfigData), response envelopes (e.g., GetAnnotationConfigsResponseBody), pagination cursors, and validation error schemas (HTTPValidationError).
Relationship to Documentation Copy
This file at schemas/openapi.json (9,817 lines) is the authoritative version. The copy at docs/openapi.json (9,770 lines) is a derivative embedded in the Mintlify documentation site. The slight line count difference may reflect formatting or documentation-specific adjustments.
Related Pages
- Arize_ai_Phoenix_OpenAPI_Spec_Docs - Documentation-embedded copy of this specification
- Arize_ai_Phoenix_Docs_Site_Config - Mintlify documentation site configuration
- Arize_ai_Phoenix_Pyproject_Config - Python package configuration for the FastAPI server that implements these endpoints