> ## Documentation Index
> Fetch the complete documentation index at: https://www.posted.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Reserve a media upload

> Reserve a private image or video upload. PUT the approved file to the returned URL using its headers, then complete the upload. No post is created.

Write access: a member/administrator with a write-enabled credential, or an authorized signed-in user.

Reserve a private image or video upload. PUT the approved file to the returned URL using its headers, then complete the upload. No post is created.

Use the returned uploadUrl and headers for the separate storage PUT. Reserving an upload does not create a post. Keep signed URLs private and use them before expiry.

MCP clients can use [`reserve_media_upload`](/mcp-reference/reserve_media_upload) for this operation.

[Request conventions](/api-reference/overview) · [API keys](/api-keys) · [MCP connections](/mcp-connections)


## OpenAPI

````yaml api-reference/openapi.json POST /api/media/uploads
openapi: 3.1.0
info:
  title: Posted HTTP API
  version: 0.2.0
  description: >-
    All registered application, account, OAuth, MCP transport and health
    endpoints. Publishing and draft request schemas come from the shared runtime
    validators. Replace the example server with your installation. Documentation
    uses simple request examples and does not execute live publishing requests.
servers:
  - url: https://posted-api.example.com
security: []
paths:
  /api/media/uploads:
    post:
      tags:
        - Media
      summary: Reserve a media upload
      description: >-
        Reserve a private image or video upload. PUT the approved file to the
        returned URL using its headers, then complete the upload. No post is
        created.


        Use the returned uploadUrl and headers for the separate storage PUT.
        Reserving an upload does not create a post. Keep signed URLs private and
        use them before expiry.


        Write access: a member/administrator with a write-enabled credential, or
        an authorized signed-in user.
      operationId: post_api_media_uploads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fileName:
                  type: string
                  minLength: 1
                  maxLength: 255
                contentType:
                  type: string
                  enum:
                    - image/jpeg
                    - image/png
                    - image/webp
                    - video/mp4
                    - video/quicktime
                sizeBytes:
                  type: integer
                  minimum: 1
                  maximum: 104857600
                alt:
                  default: ''
                  type: string
                  maxLength: 2000
              required:
                - fileName
                - contentType
                - sizeBytes
              additionalProperties: false
            example:
              fileName: studio.jpg
              contentType: image/jpeg
              sizeBytes: 245760
              alt: A bright studio desk beside a window
      responses:
        '201':
          description: >-
            Successful response. Examples are illustrative; field values vary by
            record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mediaId:
                    type: string
                  uploadUrl:
                    type: string
                  headers:
                    type: object
                    properties:
                      Content-Type:
                        type: string
                    additionalProperties: true
                additionalProperties: true
              example:
                mediaId: 44444444-4444-4444-8444-444444444444
                uploadUrl: https://storage.example.test/signed-upload
                headers:
                  Content-Type: image/jpeg
        default:
          description: >-
            Request failure. Inspect code, message and requestId; respect
            Retry-After on HTTP 429.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
        - sessionCookie: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal or team Posted REST API key
    sessionCookie:
      type: apiKey
      in: cookie
      name: posted_session
      description: >-
        Signed-in human browser session; mutation requests also need the exact
        UI Origin

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.