---
title: "Create a streaming media upload session"
method: POST
path: "/media/upload-session"
tags: ["Media"]
---

# Create a streaming media upload session

`POST /media/upload-session`

## Request

- Base URL: `https://app.openpo.st/api/v1`
- URL: `https://app.openpo.st/api/v1/media/upload-session`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `openpost_session`

## Headers

- `Idempotency-Key` string: Replay key scoped to the caller, Workspace, and operation

## Request body

- CreateMediaUploadSessionInputBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `alt_text` string: Alt text for accessibility
  - `asset_kind` 'library' | 'brand_asset' | 'brand_font' | 'design_preview' | 'template_preview' | 'project_asset': Media library role
  - `client_sha256` string: Optional SHA-256 used to reuse an identical ready asset in this workspace
  - `design_document_id` string: Producing OpenPost Image Editor design ID
  - `design_page_id` string: Producing OpenPost Image Editor page ID
  - `filename` string, required: Original filename
  - `mime_type` string: Declared MIME type
  - `parent_media_id` string: Source media ID for a derivative
  - `project_asset_id` string: Reserved Project Asset receiving this upload
  - `retention_class` 'library' | 'temporary': Keep in the library or manage as temporary post media
  - `size` integer, required: Expected upload size in bytes
  - `source` 'upload' | 'media_copy' | 'camera' | 'image_editor_export' | 'image_editor_edit' | 'background_removal' | 'video_editor_source' | 'video_editor_export' | 'stock_import' | 'meme_generator' | 'screenshot_template' | 'image_generation': Media provenance
  - `stock_provenance` StockMediaProvenance
    - `attribution_text` string, required
    - `creator_name` string, required
    - `creator_url` string, required
    - `external_id` string, required
    - `license_name` string, required
    - `license_url` string, required
    - `provider` string, required
    - `source_url` string, required
  - `tag_id` string: Optional tag to assign to this upload
  - `workspace_id` string, required: Workspace ID

## Response `200`

OK

- CreateMediaUploadSessionResponse
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `complete_url` string, required: API path to call after the upload succeeds
  - `deduped` boolean, required: Whether an identical ready workspace asset was reused
  - `media_id` string, required: Pending media ID
  - `project_asset_id` string: Project Asset linked to the media
  - `upload` DirectMediaUploadTarget, required
    - `expires_at` string, required: Upload URL expiration time
    - `headers` object, required: Headers that must be sent with the upload request
    - `method` string, required: HTTP method to use for the upload
    - `object_key` string, required: Storage object key reserved for the upload
    - `url` string, required: Presigned or authenticated upload target URL

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openpo/apis/openpost-api.md) · [All operations](https://skmtc.dev/openpo/apis/openpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openpo/apis/openpost-api/revisions/67d3964458a7?raw)