Salesforce Experience Cloud Media API

openapi: 3.1.0
info:
  title: Salesforce Experience Cloud Salesforce CMS Connect Actions Media API
  description: Manage content, channels, and media in Experience Cloud CMS. Supports creating, updating, and delivering managed content across channels for headless content delivery and site publishing. Part of the Salesforce Connect REST API.
  version: 59.0.0
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/
  license:
    name: Salesforce Master Subscription Agreement
    url: https://www.salesforce.com/company/legal/sfdc-website-terms-of-service/
servers:
- url: https://{instance}.salesforce.com/services/data/v59.0/connect/cms
  description: Salesforce Instance
  variables:
    instance:
      default: yourInstance
      description: Your Salesforce instance name or custom domain
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Media
  description: CMS media file operations
paths:
  /media:
    get:
      operationId: listCmsMedia
      summary: Salesforce Experience Cloud List CMS Media
      description: Returns a list of media files (images, documents) stored in the CMS workspace.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageParam'
      - name: folderId
        in: query
        description: Filter media by folder ID
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved CMS media list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: uploadCmsMedia
      summary: Salesforce Experience Cloud Upload CMS Media
      description: Uploads a media file (image, document, or video) to the CMS workspace.
      tags:
      - Media
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The media file to upload
                title:
                  type: string
                  description: Title for the media file
                folderId:
                  type: string
                  description: Folder to upload the media into
      responses:
        '201':
          description: Media file uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /media/{mediaId}:
    get:
      operationId: getCmsMedia
      summary: Salesforce Experience Cloud Get CMS Media
      description: Returns metadata about a specific media file including its URL, dimensions, file type, and alt text.
      tags:
      - Media
      parameters:
      - name: mediaId
        in: path
        required: true
        description: The ID of the media file
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved media details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCmsMedia
      summary: Salesforce Experience Cloud Delete CMS Media
      description: Deletes the specified media file from the CMS workspace.
      tags:
      - Media
      parameters:
      - name: mediaId
        in: path
        required: true
        description: The ID of the media file
        schema:
          type: string
      responses:
        '204':
          description: Media file deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Unauthorized - invalid or expired OAuth token
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number to retrieve (0-indexed)
      schema:
        type: integer
        default: 0
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page (default 25, max 250)
      schema:
        type: integer
        default: 25
        maximum: 250
  schemas:
    ErrorResponse:
      type: object
      description: Standard Salesforce API error response
      properties:
        errorCode:
          type: string
        message:
          type: string
    MediaFile:
      type: object
      description: A CMS media file
      properties:
        id:
          type: string
          description: Unique identifier of the media file
        altText:
          type: string
          description: Alternative text for the media
        fileName:
          type: string
          description: Original file name
        mediaType:
          type: string
          description: Type of media
          enum:
          - Image
          - Document
          - Video
        mimeType:
          type: string
          description: MIME type of the file
        referenceId:
          type: string
          description: Reference ID for the media
        title:
          type: string
          description: Display title of the media
        url:
          type: string
          format: uri
          description: URL to access the media file
    MediaCollection:
      type: object
      description: Collection of CMS media files
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MediaFile'
        currentPageUrl:
          type: string
          format: uri
        nextPageUrl:
          type: string
          format: uri
        totalCount:
          type: integer
  securitySchemes:
    oauth2:
      type: oauth2
      description: Salesforce OAuth 2.0 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://login.salesforce.com/services/oauth2/authorize
          tokenUrl: https://login.salesforce.com/services/oauth2/token
          scopes:
            api: Access and manage your data
            content: Manage CMS content
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Bearer token obtained through OAuth 2.0 flow