Implementation:Langfuse Langfuse API Annotation Queues Schema

Knowledge Sources	Langfuse Langfuse API Reference
Domains	API, Annotation
Last Updated	2026-02-14 00:00 GMT

Overview

Fern API definition for the annotation queues system, enabling human review workflows with queue management, item tracking, and user assignment capabilities.

Description

This file defines the public API contract for managing annotation queues under /api/public. Annotation queues allow teams to organize human review tasks for traces, observations, and sessions. The file contains ten endpoints across three functional groups:

Queue Management:

• GET /api/public/annotation-queues -- List all annotation queues (paginated)
• POST /api/public/annotation-queues -- Create a new annotation queue
• GET /api/public/annotation-queues/{queueId} -- Get a queue by ID

Queue Item Management:

• GET /api/public/annotation-queues/{queueId}/items -- List items in a queue (paginated, filterable by status)
• GET /api/public/annotation-queues/{queueId}/items/{itemId} -- Get a specific queue item
• POST /api/public/annotation-queues/{queueId}/items -- Add an item to a queue
• PATCH /api/public/annotation-queues/{queueId}/items/{itemId} -- Update a queue item status
• DELETE /api/public/annotation-queues/{queueId}/items/{itemId} -- Remove an item from a queue

Queue Assignments:

• POST /api/public/annotation-queues/{queueId}/assignments -- Assign a user to a queue
• DELETE /api/public/annotation-queues/{queueId}/assignments -- Remove a user assignment

Usage

Developers reference this definition when:

• Building annotation workflow integrations or tooling
• Updating SDK types for annotation queue operations
• Implementing human-in-the-loop review processes via the API
• Understanding the annotation queue data model and status transitions

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/annotation-queues.yml
• Lines: 1-215

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    listQueues:
      method: GET
      path: /annotation-queues
      response: PaginatedAnnotationQueues

    createQueue:
      method: POST
      path: /annotation-queues
      request: CreateAnnotationQueueRequest
      response: AnnotationQueue

    getQueue:
      method: GET
      path: /annotation-queues/{queueId}
      response: AnnotationQueue

    listQueueItems:
      method: GET
      path: /annotation-queues/{queueId}/items
      response: PaginatedAnnotationQueueItems

    getQueueItem:
      method: GET
      path: /annotation-queues/{queueId}/items/{itemId}
      response: AnnotationQueueItem

    createQueueItem:
      method: POST
      path: /annotation-queues/{queueId}/items
      request: CreateAnnotationQueueItemRequest
      response: AnnotationQueueItem

    updateQueueItem:
      method: PATCH
      path: /annotation-queues/{queueId}/items/{itemId}
      request: UpdateAnnotationQueueItemRequest
      response: AnnotationQueueItem

    deleteQueueItem:
      method: DELETE
      path: /annotation-queues/{queueId}/items/{itemId}
      response: DeleteAnnotationQueueItemResponse

    createQueueAssignment:
      method: POST
      path: /annotation-queues/{queueId}/assignments
      request: AnnotationQueueAssignmentRequest
      response: CreateAnnotationQueueAssignmentResponse

    deleteQueueAssignment:
      method: DELETE
      path: /annotation-queues/{queueId}/assignments
      request: AnnotationQueueAssignmentRequest
      response: DeleteAnnotationQueueAssignmentResponse

I/O Contract

Endpoints

Method	Path	Description
GET	/api/public/annotation-queues	List all annotation queues (paginated)
POST	/api/public/annotation-queues	Create a new annotation queue with name, description, and score config IDs
GET	/api/public/annotation-queues/{queueId}	Get a specific annotation queue
GET	/api/public/annotation-queues/{queueId}/items	List queue items, optionally filtered by status
GET	/api/public/annotation-queues/{queueId}/items/{itemId}	Get a specific queue item
POST	/api/public/annotation-queues/{queueId}/items	Add a trace, observation, or session to the queue
PATCH	/api/public/annotation-queues/{queueId}/items/{itemId}	Update queue item status (PENDING/COMPLETED)
DELETE	/api/public/annotation-queues/{queueId}/items/{itemId}	Remove an item from the queue
POST	/api/public/annotation-queues/{queueId}/assignments	Assign a user to the queue
DELETE	/api/public/annotation-queues/{queueId}/assignments	Remove a user assignment from the queue

Key Types

Type Name	Description
AnnotationQueueStatus	Enum: PENDING, COMPLETED
AnnotationQueueObjectType	Enum: TRACE, OBSERVATION, SESSION
AnnotationQueue	Queue with id, name, description, scoreConfigIds, timestamps
AnnotationQueueItem	Queue item with id, queueId, objectId, objectType, status, timestamps
PaginatedAnnotationQueues	Paginated list of AnnotationQueue with MetaResponse
PaginatedAnnotationQueueItems	Paginated list of AnnotationQueueItem with MetaResponse
CreateAnnotationQueueRequest	Request body for queue creation (name, description, scoreConfigIds)
CreateAnnotationQueueItemRequest	Request body for adding items (objectId, objectType, optional status)
AnnotationQueueAssignmentRequest	Request body for user assignment (userId)

Usage Examples

# List all annotation queues
curl -X GET "https://cloud.langfuse.com/api/public/annotation-queues?page=1&limit=10" \
  -H "Authorization: Bearer $API_KEY"

# Create an annotation queue
curl -X POST "https://cloud.langfuse.com/api/public/annotation-queues" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quality Review",
    "description": "Review queue for production traces",
    "scoreConfigIds": ["config-1", "config-2"]
  }'

# Add a trace to the queue
curl -X POST "https://cloud.langfuse.com/api/public/annotation-queues/queue-123/items" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objectId": "trace-456", "objectType": "TRACE"}'

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime