Phoenix Rest Api

Phoenix REST API

Endpoints: src/phoenix/server/api/routers/v1/. Read the relevant reference.

Checklist — run before committing any endpoint change

1. make openapi — regenerate schema + client types, commit all generated files 2. Add endpoint to the correct list in tests/integration/_helpers.py:

• GET → _COMMON_RESOURCE_ENDPOINTS
• Admin-only → _ADMIN_ONLY_ENDPOINTS
• POST/PUT/DELETE → _VIEWER_BLOCKED_WRITE_OPERATIONS
• Path format: use fake-id-{} for path params, test-tag for tag/name params (these are normalized by _ensure_endpoint_coverage_is_exhaustive)

3. make lint-python — fix any lint errors before committing

Endpoint Patterns

Keywords per RFC 2119 / RFC 8174.

Design Rules

• JSON by default. Alternative formats (csv, jsonl) via URL only.
• Versioned under /v1/. Breaking changes MUST go under a new prefix.
• HTTP methods per RFC 9110: GET=read, POST=create, PUT=replace, PATCH=partial update, DELETE=remove.
• Status codes per RFC 9110 §15. 2xx=success, 4xx=client error, 5xx=server error. MUST NOT mix.
• Plural noun paths: /datasets/:dataset_id/examples. No verbs.
• Identifiers MAY be a GraphQL GlobalID or a natural key (e.g. name). SHOULD accept both when multiple exist.
• Query params for filtering/sorting/pagination. snake_case names.
• Cursor-based pagination only. Response: {"data": [...], "next_cursor": "..."}.
• All responses wrap payload in "data" key. snake_case field names.

Implementation

Code lives in src/phoenix/server/api/routers/v1/. See users.py for a complete example.

Models — extend V1RoutesBaseModel. Wrap with ResponseBody[T], PaginatedResponseBody[T], or RequestBody[T]. Use UNDEFINED from phoenix.db.types.db_helper_types for excludable optional fields. Use Annotated[Union[...], Field(..., discriminator="field")] for unions.

Route decorator — always include: operation_id (camelCase), response_model_by_alias=True, response_model_exclude_unset=True, response_model_exclude_defaults=True.

Registration — import router in __init__.py, call router.include_router(...) inside create_v1_router().

Auth — admin-only: dependencies=[Depends(require_admin)]. Auth-aware: check request.app.state.authentication_enabled then isinstance(request.user, PhoenixUser). Read-only and viewer restrictions are automatic at the router level.

`is_not_locked` — guards insert/update operations under storage pressure (returns 507). Only apply to endpoints that write data (POST, PUT, PATCH). Do NOT apply to DELETE endpoints — they free space rather than consume it.

DB — async with request.app.state.db() as session: with joinedload for relationships.

IDs — GlobalID("Type", str(db_id)) to create, from_global_id_with_expected_type(GlobalID.from_id(input), "Type") to parse.

OpenAPI & Codegen

Run make openapi after any endpoint change. Generates:

• schemas/openapi.json
• packages/phoenix-client/src/phoenix/client/__generated__/v1/__init__.py (Python TypedDict)
• js/packages/phoenix-client/src/__generated__/api/v1.ts (TypeScript, phoenix-client)
• app/src/api/__generated__/v1.ts (TypeScript, frontend)

Commit all four with your endpoint changes. CI fails on drift if any of them is stale.

CI runs openapi-diff on PRs modifying the schema. Incompatible = removed endpoints/fields, changed types, renamed operationIds. Compatible = new endpoints, new optional fields, new schemas/enum values.

Testing

Unit vs Integration

• Unit tests (tests/unit/): Pydantic validation, OpenAPI schema assertions, pure logic. These run in-process with authentication_enabled=False.
• Integration tests (tests/integration/): CRUD, auth, encryption roundtrips, cross-API verification. These spawn a real Phoenix subprocess with auth enabled.

If a test hits an HTTP endpoint to create/read/update/delete data, it belongs in integration.

Integration Test Pattern

Tests live in tests/integration/<feature>/ packages. See tests/integration/secrets/ or tests/integration/client/ for examples. Each package has a conftest.py with package-scoped _env and _app fixtures.

Key helpers from tests/integration/_helpers.py:

• _httpx_client(app, auth) — HTTP client. _User objects auto-login.
• _gql(app, auth, query=, variables=) — GraphQL requests.
• _get_user(app, role) — create users with _ADMIN, _MEMBER, _VIEWER roles.

Use token_hex(4) in keys/names for test isolation since the server is shared. Clean up in try/finally.

What to Cover

• CRUD through the HTTP stack
• E2E data verification — prefer writing via one API and reading back via another over asserting on raw DB state
• Authorization — admin access, non-admin rejection, unauthenticated rejection
• Validation — invalid inputs return 422

Every endpoint should be added to _COMMON_RESOURCE_ENDPOINTS, _ADMIN_ONLY_ENDPOINTS, or _VIEWER_BLOCKED_WRITE_OPERATIONS in tests/integration/_helpers.py.

Path normalization: The _ensure_endpoint_coverage_is_exhaustive() function normalizes paths to match against the router. Use fake-id-{} for ID path params and test-tag for non-ID path params like tag names. These get normalized to {id} for comparison. Using other placeholder values (e.g. fake-tag) will cause a mismatch.