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

# Get an upload link

> A link to PUT one file to, up to 1 GB. Then send its path to POST /media.

Needs an API key with the `media` scope.



## OpenAPI

````yaml /openapi.json post /media/uploads
openapi: 3.1.0
info:
  title: PostMesh API
  version: 1.0.0
  description: >-
    The PostMesh API posts, schedules and reads your posts on every network you
    connected, with JSON in and out.


    **Authentication.** Send an API key from Settings, API & MCP as
    `Authorization: Bearer pm_live_...`. Each key has scopes (read, drafts,
    publish, media); every endpoint says which it needs.


    **Retries.** Send an `Idempotency-Key` header (up to 255 printable
    characters, a UUID is ideal) with every POST. Sending the same key again
    within 24 hours answers with the first request's status and body instead of
    posting twice, and says so with `Idempotent-Replayed: true`. A request still
    running under the key answers 409; one that failed with a 5xx or 429 frees
    the key, so the retry runs. The same key with a different body is refused
    with 422.


    **Rate limits.** Each key may make 120 requests a minute. Every answer
    carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`
    (Unix seconds); a 429 also carries `Retry-After`. Posting and uploads have
    their own, smaller limits.


    **Errors.** A refusal is JSON with `error` (plain words) and `code` (stable,
    to act on).
servers:
  - url: https://postmesh.app/api/v1
security:
  - apiKey: []
tags:
  - name: Posts
    description: Send, schedule, change and read posts.
  - name: Drafts
    description: Posts saved for later.
  - name: Media
    description: Images and videos for posts.
  - name: Accounts
    description: Your connected accounts and your plan.
  - name: Analytics
    description: How your posts did.
paths:
  /media/uploads:
    post:
      tags:
        - Media
      summary: Get an upload link
      description: >-
        A link to PUT one file to, up to 1 GB. Then send its path to POST
        /media.


        Needs an API key with the `media` scope.
      operationId: createUpload
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUpload'
      responses:
        '201':
          description: Upload the file here.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAnswer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Makes a retry safe: the same key within 24 hours answers with the first
        request's result. Up to 255 printable characters.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    CreateUpload:
      type: object
      properties:
        mime_type:
          type: string
          enum:
            - image/jpeg
            - image/png
            - image/webp
            - image/gif
            - image/avif
            - video/mp4
            - video/mpeg
            - video/webm
            - video/quicktime
        size_bytes:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: The file's exact size. One link takes up to 1 GB.
        name:
          type: string
          minLength: 1
          maxLength: 255
      required:
        - mime_type
        - size_bytes
      additionalProperties: false
      description: Asks for a link to upload one file to.
    UploadAnswer:
      type: object
      properties:
        upload:
          $ref: '#/components/schemas/Upload'
      required:
        - upload
      additionalProperties: false
    Upload:
      type: object
      properties:
        upload_url:
          type: string
          description: PUT the file's bytes here, with the headers below.
        method:
          type: string
          const: PUT
        headers:
          type: object
          additionalProperties:
            type: string
        path:
          type: string
        name:
          type: string
        mime_type:
          type: string
        size_bytes:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        expires_at:
          type: string
          format: date-time
      required:
        - upload_url
        - method
        - headers
        - path
        - name
        - mime_type
        - size_bytes
        - expires_at
      additionalProperties: false
      description: Where to upload a file. Then send its path to POST /media.
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in plain words.
        code:
          type: string
          description: >-
            A stable code to act on, such as invalid_request, rate_limited or
            idempotency_key_reused.
        field:
          description: The request field that was refused.
          type: string
        retry_after:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - error
        - code
      additionalProperties: false
      description: Every refusal looks like this.
  headers:
    X-RateLimit-Limit:
      description: Requests this key may make in a minute.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left this minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the minute resets, in Unix seconds.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        The request was refused: a field is missing or invalid. `field` names
        it.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No API key, or one that isn't valid any more.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Your plan doesn't include this, or it has ended.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The key can't do this: it needs another scope (`code` is
        `api_key_scope`), or it is in approval mode.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        The item changed since you read it, is being sent right now, or a
        request with this Idempotency-Key is still running.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unprocessable:
      description: This Idempotency-Key was already used for a different request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests. Wait for `Retry-After` seconds.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: PostMesh can't answer right now. Try again shortly.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from Settings, API & MCP: pm_live_...'

````

## Related topics

- [MCP tool reference](https://postmesh.app/docs/mcp-tools.md)
- [Get a draft](https://postmesh.app/docs/api-reference/drafts/get-a-draft.md)
- [Get a file](https://postmesh.app/docs/api-reference/media/get-a-file.md)
- [Get a post](https://postmesh.app/docs/api-reference/posts/get-a-post.md)
- [Get analytics](https://postmesh.app/docs/api-reference/analytics/get-analytics.md)


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