Hootsuite Media API

openapi: 3.2.0
info:
  description: '![Run in Postman](https://app.getpostman.com/run-collection/eeda0fcdf55ea26bd0ec#?env%5BHootsuite%5D=W3sidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJ1cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vcGxhdGZvcm0uaG9vdHN1aXRlLmNvbSJ9LHsidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJhdXRob3JpemF0aW9uX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi9hdXRoIn0seyJ0eXBlIjoidGV4dCIsImVuYWJsZWQiOnRydWUsImtleSI6InRva2VuX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi90b2tlbiJ9LHs…'
  version: '1.0'
  title: Hootsuite REST Media API
  contact:
    email: dev.support@hootsuite.com
  license:
    name: Hootsuite Developer Terms and API License Agreement
    url: https://hootsuite.com/legal/dev-api-terms
servers:
- url: https://platform.hootsuite.com
security:
- OAuth2: []
tags:
- name: Media
paths:
  /v1/media:
    post:
      tags:
      - Media
      operationId: createMedia
      summary: Create media upload url
      description: 'Creates an Amazon S3 upload URL that can be used to transfer media to Hootsuite which ensures the media is available when a scheduled message is sent to the social network.

        Hootsuite will generate thumbnails and key frames and return a unique media identifier that can be passed when creating a message.

        Subsequent uploads to an upload URL will be accepted by Amazon but immediately deleted by Hootsuite and only the first valid media file uploaded will be used.

        The MIME type and size provided in this call must match the MIME type and size of the media uploaded.


        After requesting an upload URL, make a `PUT` request to the `uploadUrl` returned, an example cURL request would look like the following, replace the fields as appropriate:


        ```

        curl --location --request PUT ''https://hootsuite-video.s3.amazonaws.com/production/12255244_01942650-3d42-42b8-a191-aa84eb45d105.mp4?AWSAccessKeyId=REDACTED_AWS_ACCESS_KEY_ID&Expires=1471978770&Signature=b%2B196oEHxySdmE%2FC34ZRL6pXSAI%3D'' \

        --header ''Content-Type: video/mp4'' \

        --header ''Content-Length: 383631'' \

        --data ''SOURCE-MEDIA-LOCATION''

        ```


        Hootsuite will remove uploaded media 90 days after using the media in a message.'
      parameters:
      - $ref: '#/components/parameters/bearerToken'
      requestBody:
        content:
          application/json;charset=utf-8:
            schema:
              $ref: '#/components/schemas/MediaUploadUrlRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/MediaUploadUrlResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ErrorsResponseEnvelope'
  /v1/media/{mediaId}:
    get:
      tags:
      - Media
      operationId: getMedia
      summary: Retrieve media upload status
      description: Retrieves the status of a media upload to Hootsuite.
      parameters:
      - $ref: '#/components/parameters/bearerToken'
      - name: mediaId
        in: path
        description: The Media ID to retrieve
        required: true
        example: aHR0cHM6Ly9ob290c3VpdGUtdmlkZW8uczMuYW1hem9uYXdzLmNvbS9wcm9kdWN0aW9uLzEyMjU1MjQ0XzgyOTVmZjllLWFkOWYtNGNlNy1iOGE3LTgwNzI0NDAwYTBhZS5tcDQ=
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/MediaDownloadUrlResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/ErrorsResponseEnvelope'
components:
  parameters:
    bearerToken:
      in: header
      name: Authorization
      description: A bearer token string used for authentication
      required: true
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        code:
          type: number
          description: An error code indicating the type of error that occurred.
          example: 1234
        message:
          type: string
          description: A description of error.
          example: An error message
        id:
          type: string
          description: A unique error id for tracing purposes
          example: f7d32670-4e6a-48c0-a2a7-87803536a712
        resource:
          type: object
          description: A reference to the resource in error
          title: ResourceReference
          properties:
            type:
              type: string
              description: The resource type.
              example: socialProfile
            id:
              type: string
              description: The resource ID.
              example: '7534653235'
    MediaUploadUrl:
      type: object
      properties:
        id:
          type: string
          description: The media identifier.
          example: aHR0cHM6Ly9ob290c3VpdGUtdmlkZW8uczMuYW1hem9uYXdzLmNvbS9wcm9kdWN0aW9uLzEyMjU1MjQ0XzgyOTVmZjllLWFkOWYtNGNlNy1iOGE3LTgwNzI0NDAwYTBhZS5tcDQ=
        uploadUrl:
          type: string
          description: An S3 URL to upload media to Hootsuite.
          example: https://hootsuite-video.s3.amazonaws.com/production/12255244_01942650-3d42-42b8-a191-aa84eb45d105.mp4?AWSAccessKeyId=REDACTED_AWS_ACCESS_KEY_ID&Expires=1471978770&Signature=b%2B196oEHxySdmE%2FC34ZRL6pXSAI%3D
        uploadUrlDurationSeconds:
          type: integer
          description: The number of seconds until the upload url is no longer valid.
          example: 1799
    MediaUploadUrlRequest:
      type: object
      properties:
        sizeBytes:
          type: integer
          description: Size in bytes of the media file to be uploaded.
          example: 383631
        mimeType:
          type: string
          description: MIME type of the media to be uploaded. Supported media types are video/mp4, image/gif, image/jpeg, image/jpg, image/png.
          example: video/mp4
    MediaDownloadUrl:
      type: object
      properties:
        id:
          type: string
          description: The media identifier.
          example: aHR0cHM6Ly9ob290c3VpdGUtdmlkZW8uczMuYW1hem9uYXdzLmNvbS9wcm9kdWN0aW9uLzEyMjU1MjQ0XzgyOTVmZjllLWFkOWYtNGNlNy1iOGE3LTgwNzI0NDAwYTBhZS5tcDQ=
        state:
          type: string
          description: The state of the uploaded media. This is used to determine whether the media has been processed by Hootsuite and is ready to attach to a message.
          example: READY
          enum:
          - READY
          - QUEUED
        downloadUrl:
          type: string
          description: An S3 URL to download the media from Hootsuite. This is only available after the media has been processed
          example: https://hootsuiteapis.s3-us-east-1.amazonaws.com/2147563588/5eb2d61a-1812-44d9-b1b2-a475d4238daf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=REDACTED_AWS_ACCESS_KEY_ID%2F20160418%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160418T215337Z&X-Amz-Expires=21&X-Amz-SignedHeaders=host&X-Amz-Signature=ea25ef6b4dabad49ec8a9cf0da2a227219222065f15a38dde2955312e2f1501d
        downloadUrlDurationSeconds:
          type: integer
          description: The number of seconds until the download url is no longer valid. This is only available after the media has been processed
          example: 1799
    MediaUploadUrlResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MediaUploadUrl'
      description: The response data wrapper for a Media Upload Url.
    ErrorsResponseEnvelope:
      type: object
      properties:
        errors:
          type: array
          description: The errors response envelope.
          items:
            $ref: '#/components/schemas/Error'
    MediaDownloadUrlResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MediaDownloadUrl'
      description: The response data wrapper for a Media Download Url.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.hootsuite.com/oauth2/auth
          tokenUrl: https://platform.hootsuite.com/oauth2/token
          scopes:
            offline: Request refresh tokens
            analytics:read: Request analytics API access
    Basic_Auth:
      type: http
      scheme: basic
x-provenance:
  generated: '2026-08-13'
  method: searched
  source: https://apidocs.hootsuite.com/docs/api/swagger.yaml
  note: First-party Hootsuite REST API contract. Discovered from the ReDoc loader at https://platform.hootsuite.com/docs/api/index.html (spec-url ./swagger.yaml) and confirmed as the canonical service-desc link in Hootsuite's RFC 9727 API catalog at https://www.hootsuite.com/.well-known/api-catalog. Published as Swagger 2.0; converted to OpenAPI 3.0 with swagger2openapi 7 for this working copy. The verbatim Swagger 2.0 source is kept at openapi/_original/hootsuite-rest-api-swagger.yaml.
  ownership: host platform.hootsuite.com, info.title "Hootsuite REST API", contact dev.support@hootsuite.com - the contract identifies itself as Hootsuite's.