Salesforce Assets API

openapi: 3.2.0
info:
  title: Salesforce Marketing Cloud REST Assets API
  description: 'The Salesforce Marketing Cloud REST API provides access to Marketing Cloud resources including contacts, journeys, data extensions, triggered sends, and transactional messaging. It uses OAuth 2.0 for authentication and is the primary interface for programmatic Marketing Cloud integrations.

    '
  version: v1
  contact:
    name: Salesforce Marketing Cloud Developers
    url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rest-api.html
  license:
    name: Salesforce Developer Terms
    url: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{subdomain}.rest.marketingcloudapis.com
  description: 'Marketing Cloud REST API endpoint. The subdomain is the tenant-specific subdomain for the Marketing Cloud account.

    '
  variables:
    subdomain:
      default: YOUR_SUBDOMAIN
      description: 'The Marketing Cloud tenant subdomain (also known as the MID-specific subdomain). Obtain this from the Marketing Cloud Setup > Company Settings > Account Info.

        '
security:
- BearerAuth: []
tags:
- name: Assets
  description: 'Operations for managing Marketing Cloud Content Builder assets including emails, images, and other content items.

    '
paths:
  /asset/v1/content/assets:
    get:
      operationId: listAssets
      summary: List content assets
      description: 'Returns a paginated list of Marketing Cloud Content Builder assets including emails, images, documents, and other content items. Supports filtering by asset type and searching by name.

        '
      tags:
      - Assets
      parameters:
      - name: page
        in: query
        required: false
        description: The page number to retrieve. Defaults to 1.
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        required: false
        description: The number of assets to return per page. Defaults to 50.
        schema:
          type: integer
          default: 50
      - name: assetType
        in: query
        required: false
        description: 'Filter by asset type name (e.g., templatebasedemail, htmlemail, image, document, block).

          '
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of content assets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of assets matching the filter.
                  page:
                    type: integer
                    description: The current page number.
                  pageSize:
                    type: integer
                    description: The number of assets per page.
                  items:
                    type: array
                    description: Array of content asset objects.
                    items:
                      $ref: '#/components/schemas/ContentAsset'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createAsset
      summary: Create a content asset
      description: 'Creates a new content asset in Marketing Cloud Content Builder. Assets can be emails, templates, images, blocks, or other content types. The asset type is specified using the assetType object. File content can be provided inline as a base64 string or referenced by URL.

        '
      tags:
      - Assets
      requestBody:
        required: true
        description: Content asset definition to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentAsset'
      responses:
        '201':
          description: Content asset created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '400':
          description: Bad request. Invalid asset definition or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /asset/v1/content/assets/{id}:
    get:
      operationId: getAsset
      summary: Get a content asset by ID
      description: 'Retrieves a single Marketing Cloud Content Builder asset by its numeric ID. Returns the asset metadata and content.

        '
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/assetId'
      responses:
        '200':
          description: The requested content asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Asset not found for the specified ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateAsset
      summary: Update a content asset
      description: 'Replaces the content and metadata of an existing Marketing Cloud Content Builder asset. The entire asset definition must be provided; partial updates are not supported. Returns the updated asset.

        '
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/assetId'
      requestBody:
        required: true
        description: Complete updated content asset definition.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentAsset'
      responses:
        '200':
          description: Content asset updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentAsset'
        '400':
          description: Bad request. Invalid asset definition or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Asset not found for the specified ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteAsset
      summary: Delete a content asset
      description: 'Deletes a Marketing Cloud Content Builder asset by its numeric ID. Deletion is permanent and cannot be undone. Ensure the asset is not in use by active journeys or sends before deleting.

        '
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/assetId'
      responses:
        '204':
          description: Asset deleted successfully. No body is returned.
        '401':
          description: Unauthorized. Invalid or expired access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Asset not found for the specified ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      description: An error response from the Marketing Cloud REST API.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        errorcode:
          type: integer
          description: Marketing Cloud numeric error code.
        documentation:
          type: string
          description: URL to documentation about this error.
    ContentAsset:
      type: object
      description: 'A Marketing Cloud Content Builder asset such as an email, template, image, block, or document.

        '
      properties:
        id:
          type: integer
          description: The unique numeric ID of the asset assigned by Marketing Cloud.
        name:
          type: string
          description: The display name of the asset in Content Builder.
        description:
          type: string
          description: Optional description of the asset.
        assetType:
          type: object
          description: Object describing the type of content asset.
          properties:
            id:
              type: integer
              description: The numeric ID of the asset type.
            name:
              type: string
              description: 'The name of the asset type (e.g., templatebasedemail, htmlemail, image, block, document).

                '
        content:
          type: string
          description: 'The HTML or text content of the asset. For email assets, this contains the email HTML body.

            '
        data:
          type: object
          description: 'Additional structured data for the asset. Content varies by asset type.

            '
          additionalProperties: true
        category:
          type: object
          description: The Content Builder folder/category the asset belongs to.
          properties:
            id:
              type: integer
              description: The numeric ID of the category.
            name:
              type: string
              description: The display name of the category.
        createdDate:
          type: string
          format: date-time
          description: The date and time the asset was created.
        modifiedDate:
          type: string
          format: date-time
          description: The date and time the asset was last modified.
        customerKey:
          type: string
          description: The external key for this asset, used to reference it in API calls.
  parameters:
    assetId:
      name: id
      in: path
      required: true
      description: The numeric ID of the Marketing Cloud content asset.
      schema:
        type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 Bearer token obtained from the /v2/token endpoint. Include this token in the Authorization header as "Bearer {access_token}".

        '