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

# Start a large upload

> Authorize an upload that goes straight to storage.



## OpenAPI

````yaml /openapi.yaml post /v1/media/uploads
openapi: 3.1.0
info:
  title: Nylon API
  version: 1.0.0
  description: |
    One API for publishing to seventeen social networks.

    You address a post to connected profile ids; Nylon knows which network each
    one belongs to, what that network accepts, and how to get the media there.
    Character limits, media specs, upload protocols and threading rules are
    normalised before the request reaches a platform, and every failure comes
    back in one error taxonomy.

    ## Conventions

    - Request and response fields are `snake_case`.
    - Successful responses wrap the payload in `data`. List responses add
      `meta.pagination`.
    - Failures return `{ "error": { "code", "message", "details?" } }`.
      Branch on `code`; `message` is written for humans and may change.
    - Times are ISO 8601 with a `Z` offset.
    - Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and
      `RateLimit-Reset`. A `429` carries those plus `Retry-After`.
servers:
  - url: https://api.nylon.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Posts
    description: Create, schedule, inspect, edit and retry posts.
  - name: Profiles
    description: Social profiles connected to the authenticated Nylon account.
  - name: Connections
    description: Start a connection and see which networks are available.
  - name: Networks
    description: What each network accepts, as data.
  - name: Validation
    description: Dry-run a post without publishing it.
  - name: Webhooks
    description: Endpoints Nylon calls when a post finishes or a profile stops working.
  - name: Media
    description: >-
      Getting a file to a URL a network can fetch, when you do not already host
      one.
paths:
  /v1/media/uploads:
    post:
      tags:
        - Media
      summary: Start a large upload
      description: |
        Authorizes an upload that goes straight to storage without passing
        through Nylon — the only way to send a file larger than a few
        megabytes, because a serverless request body is capped and a video is
        not.

        This is the server half of `@vercel/blob`'s client upload, so the
        exchange is driven by that library rather than called by hand. For
        anything under 4 MB, `POST /v1/media` takes the bytes directly.
      operationId: createMediaUpload
      responses:
        '200':
          description: An upload authorization for the client library.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Media hosting is not enabled on this deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  responses:
    Unauthorized:
      description: The bearer API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingKey:
              value:
                error:
                  code: unauthorized
                  message: A valid Nylon API key is required.
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: The stable identifier to branch on.
          enum:
            - invalid_request
            - unauthorized
            - payment_required
            - forbidden
            - not_found
            - conflict
            - rate_limited
            - unsupported
            - publish_failed
            - internal_error
          example: unauthorized
        message:
          type: string
          description: Written for humans. Do not match on it.
          example: A valid Nylon API key is required.
        details:
          type: array
          description: Present when the failure has a per-field or per-network breakdown.
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      required:
        - message
      properties:
        field:
          type: string
          description: The request field the problem is about.
          example: profile_ids
        network:
          type: string
          description: The network the problem is about.
          example: instagram
        code:
          type: string
          description: |
            Machine-readable identifier for this problem. On a per-network
            detail this is a publishing code: `invalid_request`,
            `unsupported`, `media_error`, `reauthentication_required`,
            `rejected_by_network`, `network_error`, `timeout`,
            `profile_unavailable` or `internal_error`.
          example: invalid_request
        message:
          type: string
          example: >-
            Instagram requires at least 1 media item — text-only posts are not
            supported.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Nylon API key
      description: An API key beginning with `nylon_live_`.

````