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

# Upload a file

> Uploads media and returns an id to reference from a post's `image`
array.

Send `multipart/form-data`. Size limits come from the deployment's
upload configuration, not from this API.




## OpenAPI

````yaml public-api/openapi.yaml POST /upload
openapi: 3.1.0
info:
  title: Nushir Public API
  version: 1.0.0
  description: >
    Schedule, publish and measure social posts on Nushir from your own code.


    Every route below is derived from the running application

    (`public.integrations.controller.ts`), so this document describes what the

    API actually does rather than what it is intended to do.


    ## Base URL


    ```

    https://platform.nushir.com/api/public/v1

    ```


    ## Authentication


    Send your key in the `Authorization` header. There is no `Bearer` prefix.


    ```

    Authorization: your-api-key

    ```


    Two kinds of credential are accepted on the same header:


    - **An API key**, created in *Settings → Developers*. It is scoped to the
      organisation that created it.
    - **An OAuth token**, issued to an approved app. These are recognised by
      their `pos_` prefix and resolve to the organisation that granted access.

    A missing or unrecognised credential returns `401`.


    ## Rate limits


    **90 requests per hour** per organisation, counted across every endpoint.

    Crossing the limit returns `429`; the window is one hour from each request.


    ## Try it from these pages


    Every endpoint page has a runnable panel. Paste your API key into the

    `Authorization` field, fill the parameters, and send - the request runs

    against your real organisation, so anything you create or delete is real.


    ## Channel or integration?


    The interface says **channel**. The API says **integration**. They are the

    same object; the name simply never got reconciled. Anywhere this document

    says *integration*, the calendar calls it a channel.


    ## Dates


    All dates are ISO-8601 in **UTC**. A post scheduled for
    `2026-09-01T09:00:00Z`

    publishes at 09:00 UTC regardless of the timezone on the account.


    ## Errors


    | Status | Meaning |

    |---|---|

    | `400` | The body failed validation. The response names the offending
    fields. |

    | `401` | Missing or invalid `Authorization` header. |

    | `403` | Authenticated, but the plan does not permit the action. |

    | `404` | No such object **in your organisation**. |


    A `404` is returned rather than `403` when an object exists but belongs to

    someone else, so the API never confirms that another organisation's id is

    real.
servers:
  - url: https://platform.nushir.com/api/public/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Integrations
    description: The connected social channels.
  - name: Posts
    description: Create, schedule, inspect and delete posts.
  - name: Uploads
    description: Get media into the library so a post can reference it.
  - name: Analytics
    description: Performance figures, where the platform reports them.
  - name: Notifications
    description: Account-level messages.
  - name: Video
    description: Generated video, where enabled.
paths:
  /upload:
    post:
      tags:
        - Uploads
      summary: Upload a file
      description: |
        Uploads media and returns an id to reference from a post's `image`
        array.

        Send `multipart/form-data`. Size limits come from the deployment's
        upload configuration, not from this API.
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The stored media item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaItem'
components:
  schemas:
    MediaItem:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: An id returned by one of the upload routes.
        path:
          type: string
          description: Public URL of the stored file.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Your API key from *Settings → Developers*, or an OAuth token beginning
        `pos_`. Sent raw — do **not** prefix it with `Bearer`.

````

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