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

• Implementation:Arize_ai_Phoenix_OpenAPI_Spec_Docs - Documentation-embedded copy of this specification
• Implementation:Arize_ai_Phoenix_Docs_Site_Config - Mintlify documentation site configuration
• Implementation:Arize_ai_Phoenix_Pyproject_Config - Python package configuration for the FastAPI server that implements these endpoints