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 annotation identifier: type: string title: Identifier description: The identifier of the annotation. If provided, the annotation will be updated if it already exists. default: '' span_id: type: string title: Span Id description: OpenTelemetry Span ID (hex format w/o 0x prefix) type: object required: - id - created_at - updated_at - source - user_id - name - annotator_kind - span_id title: SpanAnnotation TraceAnnotation: 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 annotation identifier: type: string title: Identifier description: The identifier of the annotation. If provided, the annotation will be updated if it already exists. default: '' trace_id: type: string title: Trace Id description: OpenTelemetry Trace ID (hex format w/o 0x prefix) type: object required: - id - created_at - updated_at - source - user_id - name - annotator_kind - trace_id title: TraceAnnotation AnnotationResult: properties: label: type: string nullable: true title: Label description: The label assigned by the annotation score: type: number nullable: true title: Score description: The score assigned by the annotation explanation: type: string nullable: true title: Explanation description: Explanation of the annotation result type: object title: AnnotationResult SessionAnnotationsResponseBody: properties: data: items: $ref: '#/components/schemas/SessionAnnotation' type: array title: Data next_cursor: type: string nullable: true title: Next Cursor type: object required: - data - next_cursor title: SessionAnnotationsResponseBody SpanAnnotationsResponseBody: properties: data: items: $ref: '#/components/schemas/SpanAnnotation' type: array title: Data next_cursor: type: string nullable: true title: Next Cursor type: object required: - data - next_cursor title: SpanAnnotationsResponseBody TraceAnnotationsResponseBody: properties: data: items: $ref: '#/components/schemas/TraceAnnotation' type: array title: Data next_cursor: type: string nullable: true title: Next Cursor type: object required: - data - next_cursor title: TraceAnnotationsResponseBody SessionAnnotation: 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 annotation identifier: type: string title: Identifier description: The identifier of the annotation. If provided, the annotation will be updated if it already exists. default: '' session_id: type: string title: Session Id description: Session ID type: object required: - id - created_at - updated_at - source - user_id - name - annotator_kind - session_id title: SessionAnnotation