Overview
The Projects Resource module provides synchronous and asynchronous CRUD clients for interacting with the Phoenix Projects REST API endpoints.
Description
This module defines two classes -- Projects (synchronous) and AsyncProjects (asynchronous) -- that wrap the Phoenix v1/projects REST API endpoints using httpx as the HTTP client. Both classes provide identical CRUD operations:
get() retrieves a single project by either project_id or project_name. Exactly one of the two identifiers must be provided, or a ValueError is raised.
list() retrieves all projects using cursor-based pagination, automatically following next_cursor values until all pages are consumed.
create() creates a new project with a required name and optional description.
update() updates a project identified by project_id or project_name. Currently only the description field can be updated (project names cannot be changed). A ValueError is raised if description is not provided.
delete() deletes a project identified by project_id or project_name.
All methods use encode_path_param() to safely encode project identifiers in URL paths. HTTP errors are propagated via httpx.HTTPError through response.raise_for_status(). Response bodies are cast to the appropriate generated types (v1.GetProjectResponseBody, v1.CreateProjectResponseBody, etc.) and the data field is returned as a v1.Project TypedDict.
Usage
Access the Projects resource via the Phoenix client as client.projects. Use it to programmatically manage projects -- creating observability workspaces, listing existing projects, updating descriptions, or cleaning up old projects.
Code Reference
Source Location
Signature
class Projects:
def __init__(self, client: httpx.Client) -> None: ...
def get(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None) -> v1.Project: ...
def list(self) -> list[v1.Project]: ...
def create(self, *, name: str, description: Optional[str] = None) -> v1.Project: ...
def update(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None, description: Optional[str] = None) -> v1.Project: ...
def delete(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None) -> None: ...
class AsyncProjects:
def __init__(self, client: httpx.AsyncClient) -> None: ...
async def get(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None) -> v1.Project: ...
async def list(self) -> list[v1.Project]: ...
async def create(self, *, name: str, description: Optional[str] = None) -> v1.Project: ...
async def update(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None, description: Optional[str] = None) -> v1.Project: ...
async def delete(self, *, project_id: Optional[str] = None, project_name: Optional[str] = None) -> None: ...
Import
from phoenix.client.resources.projects import Projects, AsyncProjects
I/O Contract
get()
Inputs
| Name |
Type |
Required |
Description
|
| project_id |
Optional[str] |
No* |
The ID of the project to retrieve (* exactly one of project_id or project_name required)
|
| project_name |
Optional[str] |
No* |
The name of the project to retrieve
|
Outputs
| Name |
Type |
Description
|
| return |
v1.Project |
Project data including id, name, description, and timestamps
|
list()
Outputs
| Name |
Type |
Description
|
| return |
list[v1.Project] |
All projects, automatically paginated via cursor-based pagination
|
create()
Inputs
| Name |
Type |
Required |
Description
|
| name |
str |
Yes |
The name of the project to create
|
| description |
Optional[str] |
No |
An optional description for the project
|
Outputs
| Name |
Type |
Description
|
| return |
v1.Project |
The newly created project data
|
update()
Inputs
| Name |
Type |
Required |
Description
|
| project_id |
Optional[str] |
No* |
The ID of the project to update (* exactly one of project_id or project_name required)
|
| project_name |
Optional[str] |
No* |
The name of the project to update
|
| description |
Optional[str] |
Yes |
The new description for the project (required)
|
Outputs
| Name |
Type |
Description
|
| return |
v1.Project |
The updated project data
|
delete()
Inputs
| Name |
Type |
Required |
Description
|
| project_id |
Optional[str] |
No* |
The ID of the project to delete (* exactly one of project_id or project_name required)
|
| project_name |
Optional[str] |
No* |
The name of the project to delete
|
Outputs
| Name |
Type |
Description
|
| return |
None |
No return value; raises httpx.HTTPError on failure
|
Usage Examples
from phoenix.client import Client
client = Client()
# List all projects
projects = client.projects.list()
for project in projects:
print(f"Project: {project['name']} (ID: {project['id']})")
# Get a specific project by name
project = client.projects.get(project_name="my-rag-app")
# Create a new project
new_project = client.projects.create(
name="experiment-v2",
description="Second iteration of the RAG pipeline experiment",
)
# Update a project description
updated = client.projects.update(
project_id=new_project["id"],
description="Updated description with new findings",
)
# Delete a project
client.projects.delete(project_name="old-experiment")
# Async usage
from phoenix.client import AsyncClient
async_client = AsyncClient()
projects = await async_client.projects.list()
new_project = await async_client.projects.create(name="async-project")
Related Pages
