Showpad Shares API

openapi: 3.2.0
info:
  title: Showpad Shares API
  description: 'This [OAS](https://swagger.io/specification/) document is intended for developers or engineers who will be

    integrating their platform with Showpad API.


    The base URL of this API is patterned as `https://{subdomain}.api.showpad.com/v4` where `{subdomain}` is the

    provided subdomain of the customer, i.e., `https://xyz-org.api.showpad.com/v4` will be the API base URL of a

    customer that has a `xyz-org` subdomain.

    '
  version: '4'
  termsOfService: https://www.showpad.com/terms-of-service
  contact:
    name: Showpad
    email: support@showpad.com
    url: https://help.showpad.com/hc/en-us/requests/new
  x-serviceName: Showpad API
  x-logo:
    url: ./Showpad-logo-vertical-blue.png
    altText: Showpad Developer API
  x-audience: external-partner
servers:
- url: https://{subdomain}.api.showpad.com/v4
  description: Production server
  x-environment: production
  variables:
    subdomain:
      default: customer
      description: Showpad customer subdomain
tags:
- name: shares
  x-displayName: Shares
  description: These are endpoints for managing Shares
paths:
  /shares:
    post:
      operationId: create-share
      summary: Create a Share
      description: "Create a new Share to distribute one or more assets with external recipients via a downloadable or view-only link. \nShares can be customized with a title, expiration date, download permissions, and a visual theme.\n\nThis endpoint supports setting Share-level metadata, targeting specific asset pages, and restricting access to \nprotect sensitive content.\n\nUse this endpoint when you need to:\n\n* Share documents, media, or Collections with external users\n* Customize the look and feel of the Share\n* Control asset availability through download restrictions or expiration settings\n"
      tags:
      - shares
      security:
      - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  maxLength: 200
                  example: Customer X – Q3 Sales Material
                  description: "A descriptive title for the Share, visible to recipients and used to identify the shared content.\n        This title appears on the Shares tab in the Web App and in notification emails."
                assets:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 9c5f3aa0784df25db1db821354e337e9
                        description: The unique identifier of the asset to share.
                      page:
                        type: integer
                        exclusiveMinimum: 0
                        example: 1
                        description: 'Optional. The 1-based page number to open when the asset is viewed.

                          Ignored for non-paginated assets like image assets.

                          '
                    required:
                    - id
                  maxItems: 300
                  example:
                  - id: 9c5f3aa0784df25db1db821354e337e9
                    page: 1
                  - id: 9c5f3aa0784df25db1db821354e337e9
                  description: A list of assets to include in the Share, with a maximum of `300` items. Each asset must include an id, and can optionally specify a `page` number to open by default.
                origin:
                  type: string
                  maxLength: 20
                  example: Showpad Web-app
                  description: The name of the platform or client application where the Share was created. Used for tracking and analytics purposes.
                isDownloadAllowed:
                  type: boolean
                  default: true
                  example: true
                  description: Indicates whether the shared assets can be downloaded by external consumers, the default value for this field is true
                expiresAt:
                  type: string
                  format: date-time
                  example: '2021-08-24T14:15:22Z'
                  description: Specifies the date and time when the Share will expire. After this timestamp, the Share becomes inaccessible to recipients. If omitted, the Share will not expire automatically. Use ISO 8601 format
                theme:
                  type: object
                  properties:
                    id:
                      type: string
                      example: 9c5f3aa0784df25db1db821354e337e9
                      description: The unique identifier of the theme
                  required:
                  - id
                  description: Defines the visual theme used for the Share, such as branding, layout, and styling. If not provided, the Global Theme will be applied. You can retrieve available theme IDs by using the `List of Themes` endpoint.
              required:
              - title
              - assets
              - origin
      responses:
        '201':
          description: Share created
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - title
                - assets
                - origin
                - isDownloadAllowed
                - expiresAt
                - theme
                - anonymousUrl
                - untrackedUrl
                - dynamicUrl
                - createdAt
                properties:
                  id:
                    type: string
                    example: 9c5f3aa0784df25db1db821354e337e9
                  title:
                    type: string
                    maxLength: 200
                    example: Customer X – Q3 Sales Material
                    description: "A descriptive title for the Share, visible to recipients and used to identify the shared content.\n        This title appears on the Shares tab in the Web App and in notification emails."
                  assets:
                    type: array
                    maxItems: 300
                    example:
                    - id: 9c5f3aa0784df25db1db821354e337e9
                      page: 1
                    - id: 9c5f3aa0784df25db1db821354e337e9
                    description: A list of assets to include in the Share, with a maximum of `300` items. Each asset must include an id, and can optionally specify a `page` number to open by default.
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          example: 9c5f3aa0784df25db1db821354e337e9
                          description: The unique identifier of the asset to share.
                        page:
                          type: integer
                          exclusiveMinimum: 0
                          example: 1
                          description: 'Optional. The 1-based page number to open when the asset is viewed.

                            Ignored for non-paginated assets like image assets.

                            '
                  origin:
                    type: string
                    maxLength: 20
                    example: Showpad Web-app
                    description: The name of the platform or client application where the Share was created. Used for tracking and analytics purposes.
                  isDownloadAllowed:
                    type:
                    - boolean
                    - 'null'
                    example: true
                    description: Specifies whether external recipients are allowed to download the shared assets. If not provided, the default behavior is to allow downloads. Set this to `false` to restrict recipients to view-only access, which can be useful for confidential or time-sensitive materials.
                  expiresAt:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    example: '2021-08-24T14:15:22Z'
                    description: Specifies the date and time when the Share will expire. After this timestamp, the Share becomes inaccessible to recipients. If omitted, the Share will not expire automatically. Use ISO 8601 format
                  theme:
                    type: object
                    required:
                    - id
                    description: Defines the visual theme used for the Share, such as branding, layout, and styling.
                    properties:
                      id:
                        type: string
                        example: 9c5f3aa0784df25db1db821354e337e9
                        description: The unique identifier of the theme
                  anonymousUrl:
                    type: string
                    format: uri
                    example: https://showpad.com/anonymous-share
                    description: The anonymous URL of the Share
                  untrackedUrl:
                    type: string
                    format: uri
                    example: https://showpad.com/untracked-share
                    description: The untracked URL of the Share
                  dynamicUrl:
                    type: string
                    format: uri
                    example: https://showpad.com/dynamic-share
                    description: The dynamic URL of the Share
                  createdAt:
                    type: string
                    format: date-time
                    description: The share's creation datetime
                    example: '2019-08-24T14:15:22Z'
        '400':
          description: Bad Request. Invalid or missing payload.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        '401':
          description: Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        '403':
          description: Forbidden. The server understood the request but refuses to authorize it. The authenticated user does not have the necessary permissions to perform this action.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
        default:
          description: An error occurred. See the HTTP status code and problem object for more information.
          content:
            application/problem+json:
              schema:
                type: object
                required:
                - title
                - detail
                - status
                - type
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  title:
                    type: string
                    description: "A short summary of the problem type. Written in English and readable\n        for engineers (usually not suited for non-technical stakeholders and\n        not localized)."
                    example: Invalid payload
                  detail:
                    type: string
                    description: A human readable explanation specific to this occurrence of the problem
                    example: Property value provided is not a valid.
                  status:
                    type: integer
                    format: int32
                    description: The HTTP status code generated by the origin server for this occurrence of the problem.
                    minimum: 400
                    maximum: 599
                    example: 400
                  meta:
                    type: array
                    description: Additional information to support the error
                    items:
                      type: object
                      required:
                      - name
                      - reason
                      - category
                      description: Additional payload to support the encountered error.
                      properties:
                        name:
                          type: string
                          description: The name of the affected resource attribute.
                          example: color
                        reason:
                          type: string
                          description: The explanation of the problem.
                          example: Value must be 'green', 'red' or 'blue'.
                        category:
                          type: string
                          description: The error category.
                          example: propertyRequired
                  type:
                    type: string
                    pattern: ^(\/[a-z]+(-[a-z]+)*)+$
                    description: URI reference of the error.
                    example: /errors/not-found
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'This is the Bearer token to identify the current requesting user.

        Please check out this [page](https://docs.api.showpad.com/docs/apis/concepts/authentication) for a more

        in-depth explanation on Showpad authentication.

        '