Implementation:Langfuse Langfuse API Media Schema

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

Overview

Fern API definition for the media API, handling upload, retrieval, and patching of media records (images, audio, video, documents) attached to traces and observations.

Description

This file defines the public API contract for managing media records under /api/public. Media records support attaching binary content (images, audio, video, text, documents) to trace and observation fields. The file contains three endpoints:

• GET /api/public/media/{mediaId} -- Get a media record including a time-limited download URL
• PATCH /api/public/media/{mediaId} -- Update a media record with upload completion status
• POST /api/public/media -- Request a presigned upload URL for a new media record

The definition includes a comprehensive MediaContentType enum with 42 MIME types across six categories: images (10 types), audio (9 types), video (6 types), text (6 types), and applications (11 types).

Usage

Developers reference this definition when:

• Adding support for new media content types
• Generating SDK types for media upload/download workflows
• Implementing the two-step upload flow (get presigned URL, then upload)
• Understanding how media records are linked to traces and observations

Code Reference

Source Location

• Repository: Langfuse
• File: fern/apis/server/definition/media.yml
• Lines: 1-207

Signature

service:
  auth: true
  base-path: /api/public
  endpoints:
    get:
      docs: Get a media record
      method: GET
      path: /media/{mediaId}
      response: GetMediaResponse

    patch:
      docs: Patch a media record
      method: PATCH
      path: /media/{mediaId}
      request: PatchMediaBody

    getUploadUrl:
      docs: Get a presigned upload URL for a media record
      method: POST
      path: /media
      request: GetMediaUploadUrlRequest
      response: GetMediaUploadUrlResponse

types:
  GetMediaResponse:
    properties:
      mediaId: string
      contentType: string
      contentLength: integer
      uploadedAt: datetime
      url: string
      urlExpiry: string

  GetMediaUploadUrlRequest:
    properties:
      traceId: string
      observationId: optional<string>
      contentType: MediaContentType
      contentLength: integer
      sha256Hash: string
      field: string

  MediaContentType:
    enum:
      - value: image/png
        name: IMAGE_PNG
      - value: image/jpeg
        name: IMAGE_JPEG
      # ... 40 more MIME types

I/O Contract

Endpoints

Method	Path	Description
GET	/api/public/media/{mediaId}	Get media record metadata and a time-limited download URL
PATCH	/api/public/media/{mediaId}	Update media record with upload status (uploadedAt, HTTP status, timing)
POST	/api/public/media	Request a presigned upload URL for a new media record

Key Types

Type Name	Description
GetMediaResponse	Media metadata with contentType, contentLength, uploadedAt, download url, and url expiry
PatchMediaBody	Upload completion data: uploadedAt, uploadHttpStatus, optional uploadHttpError and uploadTimeMs
GetMediaUploadUrlRequest	Request with traceId, optional observationId, contentType, contentLength, sha256Hash, and field name
GetMediaUploadUrlResponse	Response with optional uploadUrl (null if already uploaded) and mediaId
MediaContentType	Enum of 42 supported MIME types across image, audio, video, text, and application categories

Supported Content Types

Category	Types
Image	png, jpeg, jpg, webp, gif, svg+xml, tiff, bmp, avif, heic
Audio	mpeg, mp3, wav, ogg, oga, aac, mp4, flac, opus, webm
Video	mp4, webm, ogg, mpeg, quicktime, x-msvideo, x-matroska
Text	plain, html, css, csv, markdown, x-python
Application	javascript, x-typescript, x-yaml, pdf, msword, ms-excel, openxml (spreadsheet, word, presentation), zip, json, xml, octet-stream, rtf, x-ndjson, parquet, gzip, x-tar, x-7z-compressed

Usage Examples

# Step 1: Get a presigned upload URL
curl -X POST "https://cloud.langfuse.com/api/public/media" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace-123",
    "contentType": "image/png",
    "contentLength": 102400,
    "sha256Hash": "abc123...",
    "field": "input"
  }'

# Step 2: Upload the file to the presigned URL (returned from step 1)
curl -X PUT "$PRESIGNED_URL" \
  -H "Content-Type: image/png" \
  --data-binary @screenshot.png

# Step 3: Confirm the upload
curl -X PATCH "https://cloud.langfuse.com/api/public/media/media-456" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadedAt": "2026-02-14T00:00:00Z",
    "uploadHttpStatus": 200,
    "uploadTimeMs": 1500
  }'

# Get media record with download URL
curl -X GET "https://cloud.langfuse.com/api/public/media/media-456" \
  -H "Authorization: Bearer $API_KEY"

Related Pages

• Environment:Langfuse_Langfuse_Node_24_Runtime