openapi: 3.0.3
info:
title: Arize-Phoenix REST annotation_configs annotations API
description: Schema for Arize-Phoenix REST API
version: '1.0'
tags:
- name: annotations
paths:
/v1/projects/{project_identifier}/span_annotations:
get:
tags:
- annotations
summary: Get span annotations filtered by span_ids and/or identifier.
description: Return span annotations for a project, filtered by `span_ids`, `identifier`, or both. At least one of `span_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
operationId: listSpanAnnotationsBySpanIds
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: span_ids
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of span ids to fetch annotations for. If omitted, `identifier` must be supplied.
title: Span Ids
description: Optional list of span ids to fetch annotations for. If omitted, `identifier` must be supplied.
- name: identifier
in: query
required: false
schema:
type: array
items:
type: string
minLength: 1
nullable: true
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `span_ids` must be supplied. When combined with `span_ids`, results are the AND-intersection of both filters.
title: Identifier
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `span_ids` must be supplied. When combined with `span_ids`, results are the AND-intersection of both filters.
- name: include_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
title: Include Annotation Names
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
- name: exclude_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to exclude from results.
title: Exclude Annotation Names
description: Optional list of annotation names to exclude from results.
- name: cursor
in: query
required: false
schema:
type: string
nullable: true
description: A cursor for pagination
title: Cursor
description: A cursor for pagination
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10000
exclusiveMinimum: 0
description: The maximum number of annotations to return in a single request
default: 10
title: Limit
description: The maximum number of annotations to return in a single request
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SpanAnnotationsResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project or spans not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
delete:
tags:
- annotations
summary: Delete span annotations in a project that match the supplied filter.
description: "Hard-delete span annotations within the named project that match the\nsupplied filter.\n\n- The request must either supply both `start_time` AND `end_time`\n to bound the delete to a `[start_time, end_time)` time window,\n OR set `delete_all=true` to acknowledge an unbounded sweep. A request\n that satisfies neither is rejected with 422.\n- `name`, `identifier`, and `annotator_kind` are optional narrowing\n filters; on their own they do NOT authorize the request — they only\n narrow within an already-authorized request (bounded time range or\n `delete_all=true`).\n- All supplied filters are combined with AND. `name` and `identifier`,\n when present, must be non-empty.\n- `start_time` is inclusive (`>=`); `end_time` is exclusive\n (`<`). When both are supplied, `start_time` must be strictly earlier\n than `end_time` (else 422). A half-bounded range (only one of\n the two) does NOT satisfy the gate and is rejected unless\n `delete_all=true` is also set. Naive datetimes are interpreted as UTC.\n- The endpoint is idempotent: a request that matches no rows still\n returns 204.\n- When authentication is enabled, non-admin callers can only delete rows\n they own (`user_id == current_user.id`); admins delete all matching\n rows."
operationId: deleteSpanAnnotations
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: name
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
title: Name
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
- name: identifier
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
title: Identifier
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
- name: annotator_kind
in: query
required: false
schema:
enum:
- LLM
- CODE
- HUMAN
type: string
nullable: true
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
title: Annotator Kind
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
title: Start Time
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
title: End Time
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
- name: delete_all
in: query
required: false
schema:
type: boolean
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
default: false
title: Delete All
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
responses:
'204':
description: Successful Response
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
/v1/projects/{project_identifier}/trace_annotations:
get:
tags:
- annotations
summary: Get trace annotations filtered by trace_ids and/or identifier.
description: Return trace annotations for a project, filtered by `trace_ids`, `identifier`, or both. At least one of `trace_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
operationId: listTraceAnnotationsByTraceIds
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: trace_ids
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of trace ids to fetch annotations for. If omitted, `identifier` must be supplied.
title: Trace Ids
description: Optional list of trace ids to fetch annotations for. If omitted, `identifier` must be supplied.
- name: identifier
in: query
required: false
schema:
type: array
items:
type: string
minLength: 1
nullable: true
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `trace_ids` must be supplied. When combined with `trace_ids`, results are the AND-intersection of both filters.
title: Identifier
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `trace_ids` must be supplied. When combined with `trace_ids`, results are the AND-intersection of both filters.
- name: include_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
title: Include Annotation Names
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
- name: exclude_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to exclude from results.
title: Exclude Annotation Names
description: Optional list of annotation names to exclude from results.
- name: cursor
in: query
required: false
schema:
type: string
nullable: true
description: A cursor for pagination
title: Cursor
description: A cursor for pagination
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10000
exclusiveMinimum: 0
description: The maximum number of annotations to return in a single request
default: 10
title: Limit
description: The maximum number of annotations to return in a single request
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TraceAnnotationsResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project or traces not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
delete:
tags:
- annotations
summary: Delete trace annotations in a project that match the supplied filter.
description: "Hard-delete trace annotations within the named project that match the\nsupplied filter.\n\n- The request must either supply both `start_time` AND `end_time`\n to bound the delete to a `[start_time, end_time)` time window,\n OR set `delete_all=true` to acknowledge an unbounded sweep. A request\n that satisfies neither is rejected with 422.\n- `name`, `identifier`, and `annotator_kind` are optional narrowing\n filters; on their own they do NOT authorize the request — they only\n narrow within an already-authorized request (bounded time range or\n `delete_all=true`).\n- All supplied filters are combined with AND. `name` and `identifier`,\n when present, must be non-empty.\n- `start_time` is inclusive (`>=`); `end_time` is exclusive\n (`<`). When both are supplied, `start_time` must be strictly earlier\n than `end_time` (else 422). A half-bounded range (only one of\n the two) does NOT satisfy the gate and is rejected unless\n `delete_all=true` is also set. Naive datetimes are interpreted as UTC.\n- The endpoint is idempotent: a request that matches no rows still\n returns 204.\n- When authentication is enabled, non-admin callers can only delete rows\n they own (`user_id == current_user.id`); admins delete all matching\n rows."
operationId: deleteTraceAnnotations
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: name
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
title: Name
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
- name: identifier
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
title: Identifier
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
- name: annotator_kind
in: query
required: false
schema:
enum:
- LLM
- CODE
- HUMAN
type: string
nullable: true
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
title: Annotator Kind
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
title: Start Time
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
title: End Time
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
- name: delete_all
in: query
required: false
schema:
type: boolean
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
default: false
title: Delete All
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
responses:
'204':
description: Successful Response
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
/v1/projects/{project_identifier}/session_annotations:
get:
tags:
- annotations
summary: Get session annotations filtered by session_ids and/or identifier.
description: Return session annotations for a project, filtered by `session_ids`, `identifier`, or both. At least one of `session_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.
operationId: listSessionAnnotationsBySessionIds
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: session_ids
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of session ids to fetch annotations for. If omitted, `identifier` must be supplied.
title: Session Ids
description: Optional list of session ids to fetch annotations for. If omitted, `identifier` must be supplied.
- name: identifier
in: query
required: false
schema:
type: array
items:
type: string
minLength: 1
nullable: true
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `session_ids` must be supplied. When combined with `session_ids`, results are the AND-intersection of both filters.
title: Identifier
description: Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `session_ids` must be supplied. When combined with `session_ids`, results are the AND-intersection of both filters.
- name: include_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
title: Include Annotation Names
description: Optional list of annotation names to include. If provided, only annotations with these names will be returned (allowlist). When omitted, the response includes every matching row regardless of name (no annotation names are excluded by default).
- name: exclude_annotation_names
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Optional list of annotation names to exclude from results.
title: Exclude Annotation Names
description: Optional list of annotation names to exclude from results.
- name: cursor
in: query
required: false
schema:
type: string
nullable: true
description: A cursor for pagination
title: Cursor
description: A cursor for pagination
- name: limit
in: query
required: false
schema:
type: integer
maximum: 10000
exclusiveMinimum: 0
description: The maximum number of annotations to return in a single request
default: 10
title: Limit
description: The maximum number of annotations to return in a single request
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SessionAnnotationsResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project or sessions not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
delete:
tags:
- annotations
summary: Delete session annotations in a project that match the supplied filter.
description: "Hard-delete session annotations within the named project that match the\nsupplied filter.\n\n- The request must either supply both `start_time` AND `end_time`\n to bound the delete to a `[start_time, end_time)` time window,\n OR set `delete_all=true` to acknowledge an unbounded sweep. A request\n that satisfies neither is rejected with 422.\n- `name`, `identifier`, and `annotator_kind` are optional narrowing\n filters; on their own they do NOT authorize the request — they only\n narrow within an already-authorized request (bounded time range or\n `delete_all=true`).\n- All supplied filters are combined with AND. `name` and `identifier`,\n when present, must be non-empty.\n- `start_time` is inclusive (`>=`); `end_time` is exclusive\n (`<`). When both are supplied, `start_time` must be strictly earlier\n than `end_time` (else 422). A half-bounded range (only one of\n the two) does NOT satisfy the gate and is rejected unless\n `delete_all=true` is also set. Naive datetimes are interpreted as UTC.\n- The endpoint is idempotent: a request that matches no rows still\n returns 204.\n- When authentication is enabled, non-admin callers can only delete rows\n they own (`user_id == current_user.id`); admins delete all matching\n rows."
operationId: deleteSessionAnnotations
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name as the identifier, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: name
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
title: Name
description: Optional annotation name. When provided, must be non-empty and narrows the delete to annotations of that name.
- name: identifier
in: query
required: false
schema:
type: string
minLength: 1
nullable: true
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
title: Identifier
description: Optional annotation identifier. When provided, must be non-empty and narrows the delete to annotations with that identifier.
- name: annotator_kind
in: query
required: false
schema:
enum:
- LLM
- CODE
- HUMAN
type: string
nullable: true
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
title: Annotator Kind
description: Optional annotator kind. When provided, narrows the delete to annotations produced by this annotator kind.
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
title: Start Time
description: Optional inclusive lower bound on `created_at` (>=). Naive datetimes are interpreted as UTC.
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
title: End Time
description: Optional exclusive upper bound on `created_at` (<). Naive datetimes are interpreted as UTC.
- name: delete_all
in: query
required: false
schema:
type: boolean
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
default: false
title: Delete All
description: Opt-in flag that authorizes the request without a bounded `[start_time, end_time)` time window. When `false` (default) or absent, the request must supply both `start_time` AND `end_time` to bound the delete. When `true`, the time-range bound is waived and any other filters (`name`, `identifier`, `annotator_kind`) still narrow the delete within the project — e.g. `delete_all=true&name=X` deletes all annotations named X regardless of time.
responses:
'204':
description: Successful Response
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Project not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid parameters
components:
schemas:
SpanAnnotation:
properties:
id:
type: string
title: Id
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
source:
type: string
enum:
- API
- APP
title: Source
user_id:
type: string
nullable: true
title: User Id
name:
type: string
title: Name
description: The name of the annotation
annotator_kind:
type: string
enum:
- LLM
- CODE
- HUMAN
title: Annotator Kind
description: The kind of annotator used for the annotation
result:
$ref: '#/components/schemas/AnnotationResult'
nullable: true
description: The result of the annotation
metadata:
additionalProperties: true
type: object
nullable: true
title: Metadata
description: Metadata for the
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/phoenix/refs/heads/main/openapi/phoenix-annotations-api-openapi.yml