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. '