openapi: 3.1.0
info:
  title: Salesforce Experience Cloud Salesforce CMS Delivery API
  description: >-
    Delivers CMS content to external applications and headless frontends.
    Enables content retrieval by channel, content type, and content key for
    building decoupled digital experiences. 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/delivery
    description: Salesforce Instance
    variables:
      instance:
        default: yourInstance
        description: Your Salesforce instance name or custom domain
security:
  - oauth2: []
  - bearerAuth: []
tags:
  - name: Collections
    description: Content collection delivery operations
  - name: Content Delivery
    description: Content delivery operations for headless consumption
  - name: Media Delivery
    description: Media content delivery operations
paths:
  /channels/{channelId}/contents/query:
    get:
      operationId: queryDeliveryContent
      summary: Salesforce Experience Cloud Query Delivery Content by Channel
      description: >-
        Retrieves published CMS content from the specified delivery channel.
        Returns content items matching the specified content type and
        optional filters. Used for headless content delivery to external
        applications and decoupled frontends.
      tags:
        - Content Delivery
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - name: managedContentType
          in: query
          required: true
          description: >-
            Developer name of the content type (e.g., news, cms_image,
            cms_document, custom content types)
          schema:
            type: string
        - name: language
          in: query
          description: Language code for content variant (e.g., en_US, fr, de)
          schema:
            type: string
        - name: contentKeys
          in: query
          description: Comma-separated list of content keys to retrieve
          schema:
            type: string
        - name: managedContentIds
          in: query
          description: Comma-separated list of managed content record IDs
          schema:
            type: string
        - name: topics
          in: query
          description: Comma-separated list of topic names to filter content
          schema:
            type: string
        - name: showAbsoluteUrl
          in: query
          description: Whether to return absolute URLs for media references
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Successfully retrieved delivery content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryContentCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /channels/{channelId}/contents/search:
    get:
      operationId: searchDeliveryContent
      summary: Salesforce Experience Cloud Search Delivery Content
      description: >-
        Searches published CMS content in the specified delivery channel
        using a full-text search term. Returns matching content items
        with relevance-based ordering.
      tags:
        - Content Delivery
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - name: q
          in: query
          required: true
          description: Full-text search term
          schema:
            type: string
        - name: managedContentType
          in: query
          description: Filter results to a specific content type
          schema:
            type: string
        - name: language
          in: query
          description: Language code for content filtering
          schema:
            type: string
        - name: showAbsoluteUrl
          in: query
          description: Whether to return absolute URLs
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Successfully searched delivery content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryContentCollection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /channels/{channelId}/contents/{contentKeyOrId}:
    get:
      operationId: getDeliveryContentItem
      summary: Salesforce Experience Cloud Get a Delivery Content Item
      description: >-
        Retrieves a specific published content item from the delivery
        channel by its content key or managed content ID. Returns all
        content nodes and metadata for the item.
      tags:
        - Content Delivery
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - name: contentKeyOrId
          in: path
          required: true
          description: Content key or managed content record ID
          schema:
            type: string
        - name: language
          in: query
          description: Language variant to retrieve
          schema:
            type: string
        - name: showAbsoluteUrl
          in: query
          description: Whether to return absolute URLs
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successfully retrieved content item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryContentItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /channels/{channelId}/contents/{contentKeyOrId}/binary:
    get:
      operationId: getDeliveryContentBinary
      summary: Salesforce Experience Cloud Get Content Binary Stream
      description: >-
        Returns the binary stream of published managed content such as
        images, documents, or videos. Used for downloading or streaming
        media files associated with CMS content.
      tags:
        - Media Delivery
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - name: contentKeyOrId
          in: path
          required: true
          description: Content key or managed content record ID
          schema:
            type: string
      responses:
        '200':
          description: Binary stream of the content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /channels/{channelId}/collections:
    get:
      operationId: listDeliveryCollections
      summary: Salesforce Experience Cloud List Content Collections
      description: >-
        Returns a list of published content collections available in the
        specified delivery channel. Collections group related content
        items for organized delivery.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: Successfully retrieved content collections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /channels/{channelId}/collections/{collectionKeyOrId}:
    get:
      operationId: getDeliveryCollection
      summary: Salesforce Experience Cloud Get a Content Collection
      description: >-
        Retrieves a specific content collection and its items from the
        delivery channel. Returns the collection metadata and all
        content items within the collection.
      tags:
        - Collections
      parameters:
        - $ref: '#/components/parameters/ChannelId'
        - name: collectionKeyOrId
          in: path
          required: true
          description: Collection key or record ID
          schema:
            type: string
        - name: language
          in: query
          description: Language variant to retrieve
          schema:
            type: string
        - name: showAbsoluteUrl
          in: query
          description: Whether to return absolute URLs
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successfully retrieved collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Bearer token obtained through OAuth 2.0 flow
  parameters:
    ChannelId:
      name: channelId
      in: path
      required: true
      description: The ID of the CMS delivery channel
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      description: Number of items per page (default 25, max 250)
      schema:
        type: integer
        default: 25
        maximum: 250
    PageParam:
      name: page
      in: query
      description: Page number (0-indexed)
      schema:
        type: integer
        default: 0
  schemas:
    DeliveryContentCollection:
      type: object
      description: Collection of delivered content items
      properties:
        currentPageUrl:
          type: string
          format: uri
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryContentItem'
        managedContentTypes:
          type: object
          description: Map of content type names to type metadata
          additionalProperties:
            type: object
            properties:
              developerName:
                type: string
              label:
                type: string
        nextPageUrl:
          type: string
          format: uri
        total:
          type: integer
        totalCount:
          type: integer
    DeliveryContentItem:
      type: object
      description: A delivered CMS content item
      properties:
        contentKey:
          type: string
          description: Unique content key for the item
        contentNodes:
          type: object
          description: Content field values organized as nodes
          additionalProperties:
            $ref: '#/components/schemas/ContentNode'
        contentUrlName:
          type: string
          description: URL-safe name for the content
        language:
          type: string
          description: Language code of this content version
        managedContentId:
          type: string
          description: Salesforce record ID
        publishedDate:
          type: string
          format: date-time
          description: When this content was published
        title:
          type: string
          description: Title of the content
        type:
          type: string
          description: Content type developer name
        typeLabel:
          type: string
          description: Content type display label
        unauthenticatedUrl:
          type: string
          format: uri
          description: Public URL for unauthenticated access
    ContentNode:
      type: object
      description: A content node representing a field value
      properties:
        altText:
          type: string
          description: Alternative text for media content
        contentKey:
          type: string
          description: Content key for referenced content
        fileName:
          type: string
          description: File name for media content
        mediaType:
          type: string
          description: Media type classification
        mimeType:
          type: string
          description: MIME type of the content
        nodeType:
          type: string
          description: Type of content node
          enum:
            - Media
            - MediaSource
            - MultilineText
            - NameField
            - RichText
            - Text
            - Url
            - DateTime
        referenceId:
          type: string
          description: Reference ID for the content
        title:
          type: string
          description: Title of the node
        unauthenticatedUrl:
          type: string
          format: uri
          description: Public URL
        url:
          type: string
          format: uri
          description: URL value
        value:
          type: string
          description: Text or value content
    CollectionList:
      type: object
      description: List of content collections
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/CollectionSummary'
        currentPageUrl:
          type: string
          format: uri
        nextPageUrl:
          type: string
          format: uri
        totalCount:
          type: integer
    CollectionSummary:
      type: object
      description: Summary of a content collection
      properties:
        collectionKey:
          type: string
          description: Unique key for the collection
        collectionType:
          type: string
          description: Type of collection
        label:
          type: string
          description: Display label
        name:
          type: string
          description: Developer name
    DeliveryCollection:
      type: object
      description: A content collection with its items
      properties:
        collectionKey:
          type: string
        collectionType:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryContentItem'
        label:
          type: string
        name:
          type: string
        totalCount:
          type: integer
    ErrorResponse:
      type: object
      description: Standard Salesforce API error response
      properties:
        errorCode:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or expired OAuth token
      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'