---
title: "Ingest media from a public URL"
method: POST
path: "/v2/media/ingest-url"
tags: ["v2 - Media"]
---

# Ingest media from a public URL

`POST /v2/media/ingest-url`

## Request

- Base URL: `https://api.jubjubapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.jubjubapp.com/v2/media/ingest-url`
- Auth: HTTP bearer

Download a file from a public URL and ingest it into JubJub.

    The backend downloads the file server-side and uploads it to GCS.
    Useful for GPT Actions and MCP clients that cannot send binary data.

    The URL must be publicly accessible, on http or https, and must not
    redirect. Private and internal addresses are refused. Max download
    timeout is 120 seconds; files over MEDIA_INGEST_MAX_BYTES (256 MB by
    default) are refused with 413.

## Headers

- `Authorization` string
- `X-JubJub-Service-Key` string
- `X-JubJub-Agent-Key` string
- `X-JubJub-Platform-Key` string
- `Origin` string
- `Referer` string
- `X-JubJub-Trial-Token` string

## Request body

- MediaIngestUrlRequestDTO: Request to ingest media from a public URL. The backend downloads the file server-side and uploads it to GCS. Useful for GPT Actions and MCP clients that cannot send binary data.
  - `workspace_id` string, required: Workspace that will own this media
  - `url` string, required: Public URL to download the media from.
  - `filename` string, required: Filename to use for the ingested media (e.g., 'video.mp4').
  - `media_type` 'video' | 'image' | 'subtitle' | 'document', nullable: Type of media. Auto-detected from the filename if omitted (.pdf is a document, .jpg/.png/.webp an image).

## Response `201`

Successful Response

- MediaResponseDTO: Full media response. Returned after upload completion or when fetching media details.
  - `media_id` string, required
  - `workspace_id` string, required
  - `type` string, required: Media type: video, image, subtitle or document (a PDF)
  - `filename` string, required
  - `content_type` string, required
  - `size_bytes` integer, required
  - `duration_seconds` number, nullable: Duration in seconds (for videos)
  - `status` string, required: Processing status: uploading, processing, ready, failed, unreadable. `unreadable` is terminal: the bytes are not a usable file of their type, the stored object has been deleted, and re-uploading the same file will not help.
  - `status_reason` string, nullable: Why, in plain words, when the status needs explaining. Set with `unreadable`; null otherwise. Safe to show to the person.
  - `url` string, nullable: Signed URL of the file, valid for 120 minutes (when status is 'ready'). A document's URL opens inline as application/pdf. An image's URL is the original only for its uploader; everyone else gets a copy with EXIF (GPS included) removed, and null when that copy could not be made.
  - `video_metadata` MediaVideoMetadataDTO: Video-specific metadata for Smart Tags and Smart Rename.
    - `width` integer, nullable: Video width in pixels
    - `height` integer, nullable: Video height in pixels
    - `fps` number, nullable: Frames per second
    - `codec` string, nullable: Video codec (h264, h265, etc)
    - `bitrate_kbps` integer, nullable: Bitrate in kbps
    - `aspect_ratio` string, nullable: Aspect ratio like '16:9', '9:16', '1:1'
    - `resolution` string, nullable: Resolution label like '1080p', '4K', '720p'
    - `orientation` string, nullable: Orientation: 'horizontal', 'vertical', or 'square'
    - `duration_category` string, nullable: Duration category: 'short', 'reel', 'medium', 'long'
  - `image_metadata` MediaImageMetadataDTO: Image-specific metadata, from the Pillow probe at upload completion.
    - `width` integer, nullable: Image width in pixels
    - `height` integer, nullable: Image height in pixels
    - `aspect_ratio` string, nullable: Aspect ratio like '1:1', '4:5', '1.91:1', '16:9'
    - `orientation` string, nullable: Orientation: 'horizontal', 'vertical', or 'square'
    - `format` string, nullable: Stored format as a mime type: image/jpeg, image/png, image/webp, image/gif
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/jubjubapp/apis/jubjub-api.md) - [All operations](https://skmtc.dev/jubjubapp/apis/jubjub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jubjubapp/apis/jubjub-api/revisions/353157b296f2?raw)