openapi: 3.0.3
info:
title: Showpad 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: assets
x-displayName: Assets
description: These are endpoints for managing Assets.
- name: authorization
x-displayName: Authorization
description: |
Each API request requires an `Authorization` header to be set.
* `Authorization` must be set with the Bearer token as value
<SecurityDefinitions />
```
Authorization: Bearer ABC123
```
A `401 Unauthorized` response status will be returned if the authorization has been refused.
A `403 Forbidden` response status will be returned if access to the resource is insufficient.
- name: crm
x-displayName: CRM
description: These are endpoints for managing crm recommendation rules and fetching shares and shared spaces cmr records
- name: divisions
x-displayName: Divisions
description: These are endpoints regarding fetching Division information.
- name: locale
x-displayName: Locale
description: These are endpoints for fetching available Languages and Countries information.
- name: mutual-action-plan
x-displayName: Mutual Action Plan
description: These are endpoints for managing Mutual Action Plans
- name: themes
x-displayName: Themes
description: These are endpoints for managing Themes
- name: shared-spaces
x-displayName: Shared Spaces
description: These are endpoints for managing Shared Spaces
- name: shared-space-templates
x-displayName: Shared Space Templates
description: These are endpoints for managing Shared Space Templates
- name: shared-spaces-quick-actions
x-displayName: Shared Spaces Quick Actions
description: These are endpoints for managing Shared Spaces Quick Actions
- name: tag-categories
x-displayName: Tag Categories
description: These are endpoints for managing Tag Categories.
- name: tags
x-displayName: Tags
description: These are endpoints for managing Tags.
- name: users
x-displayName: Users
description: These are endpoints for fetching User information.
- name: shares
x-displayName: Shares
description: These are endpoints for managing Shares
paths:
/divisions:
get:
operationId: getDivisions
summary: List all Divisions
description: |-
Retrieve a list of all Divisions available in your Showpad instance. Divisions represent organizational groupings that control access, content visibility, and administrative boundaries within the platform.
Use this endpoint when you need to:
- Display Division options in custom interfaces or admin tools
- Sync Division metadata with external systems
- Filter or segment content and users based on organizational structure
Supports pagination for large datasets and is ideal for reporting, permission modeling, or building integrations that rely on Division hierarchy or availability.
tags:
- divisions
security:
- BearerAuth: []
parameters:
- name: limit
in: query
description: Defines the maximum number of items to return in the response. Useful for paginating results when fetching items in batches.
example: limit=100
schema:
type: integer
format: int32
default: 50
minimum: 0
maximum: 1000
- name: offset
in: query
description: Specifies the number of items to skip before returning results. Use in combination with `limit` to implement pagination when retrieving large datasets.
required: false
example: offset=0
schema:
type: integer
format: int32
default: 0
minimum: 0
responses:
'200':
description: OK. The request was successful. Returns a paginated list of Divisions matching the applied filters.
content:
application/json:
schema:
type: object
properties:
count:
description: Total number of results matching the request criteria.
type: integer
format: int32
example: 20
items:
type: array
description: List of Divisions.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the Division.
example: f541710283954a89bdfd40f221882451
name:
type: string
example: My Global Division
description: Name of the Division.
isAssetSharingEnabled:
type: boolean
description: Whether or not `Share content globally` is enabled on the Division.
createdAt:
type: string
format: date-time
description: |
Timestamp when the resource was created, in `ISO 8601` UTC format.
updatedAt:
type: string
format: date-time
description: |
Timestamp when the resource was last updated, in `ISO 8601` UTC format.
'400':
description: Bad Request. Returned when the request payload is invalid or incomplete. The response provides structured error details to help identify and correct the issue.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
- status
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
'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
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
'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
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
'/divisions/{divisionId}':
parameters:
- name: divisionId
in: path
required: true
description: The division ID.
schema:
type: string
example: f541710283954a89bdfd40f221882451
get:
operationId: getDivisionById
summary: Retrieve a Division
description: |-
Retrieve detailed information for a single Division in your Showpad environment. Divisions help organize content, users, and permissions across your organization.
Use this endpoint when you need to:
- Display Division details in an admin or reporting interface
- Validate Division configuration before creating or updating related resources
- Sync organizational structure between Showpad and an external system
Returns the Division's name, settings, and timestamps, making it useful for management, auditing, and system integrations.
tags:
- divisions
security:
- BearerAuth: []
responses:
'200':
description: OK. The request was successful. Returns the requested Division object.
x-summary: OK. Request is successful.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique identifier of the Division.
example: f541710283954a89bdfd40f221882451
name:
type: string
example: My Global Division
description: Name of the Division.
isAssetSharingEnabled:
type: boolean
description: Whether or not `Share content globally` is enabled on the Division.
createdAt:
type: string
format: date-time
description: |
Timestamp when the resource was created, in `ISO 8601` UTC format.
updatedAt:
type: string
format: date-time
description: |
Timestamp when the resource was last updated, in `ISO 8601` UTC format.
'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
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
'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
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
'404':
description: Not Found. Returned when the requested resource does not exist or the user does not have permission to access it.
content:
application/problem+json:
schema:
type: object
required:
- title
- detail
- status
properties:
title:
type: string
description: |
A short summary of the error type. This is intended for engineers and technical users. It is always in English and not localized.
example: Invalid Payload
detail:
type: string
description: |
A human-readable explanation of the specific reason for the failure.
example: Property value provided is not valid.
status:
type: integer
format: int32
description: |
The HTTP status code returned by the server.
minimum: 400
maximum: 599
example: 400
meta:
type: array
nullable: true
description: Additional metadata entries providing field-level context about the error. Null if not applicable.
items:
type: object
description: Additional metadata entries providing field-level context about the error.
required:
- name
- reason
- category
properties:
name:
type: string
example: color
description: 'The name of the field or parameter associated with the error, if applicable.'
reason:
type: string
example: 'Value must be ''green'', ''red'' or ''blue''.'
description: A descriptive message explaining what is wrong with the field or parameter.
category:
type: string
example: propertyRequired
description: 'Classification of the error, useful for programmatic handling.'
type:
type: string
nullable: true
description: 'URI reference to a resource that defines the error type, if available. Null if not applicable.'
/assets:
get:
operationId: getAssets
summary: List all Assets
description: |-
Retrieve a list of assets available in your Showpad instance. Assets can include documents, videos, images, or other media files uploaded to the platform. This endpoint supports powerful filtering options by ID, name, tag, external identifiers, and more, enabling precise control over which assets are returned.
Use this endpoint when you need to:
- Build custom asset galleries or search interfaces
- Integrate Showpad asset metadata into external systems
- Filter assets by tag, name, or organizational Divisions for targeted access
Supports pagination for large datasets and is ideal for asset syncing, reporting, or content discovery use cases.
tags:
- assets
security:
- BearerAuth: []
parameters:
- name: limit
in: query
description: Defines the maximum number of items to return in the response. Useful for paginating results when fetching items in batches.
example: limit=100
schema:
type: integer
format: int32
default: 50
minimum: 0
maximum: 1000
- name: offset
in: query
description: Specifies the number of items to skip before returning results. Use in combination with `limit` to implement pagination when retrieving large datasets.
required: false
example: offset=0
schema:
type: integer
format: int32
default: 0
minimum: 0
- name: divisionIds
in: query
description: Filters the results to include only assets that belong to one or more specific Divisions. This is useful for multi-Division organizations to retrieve content scoped to particular business units or regions.
explode: false
style: form
example: 'division-id-1,division-id-2'
schema:
type: array
items:
type: string
- name: ids
in: query
description: Returns only the assets with the specified Showpad asset IDs. This is helpful when you already have a list of asset IDs and need to fetch full details.
explode: false
style: form
example: 'abc123,def456'
schema:
type: array
items:
type: string
- name: name
in: query
description: Searches by full or partial name. Use this for free-text search or to narrow down results by known naming conventions.
schema:
type: string
example: customer
- name: externalIds
in: query
description: Filters assets by custom external identifiers. Use this if your system assigns unique IDs to assets outside of Showpad and you need to cross-reference them.
explode: false
style: form
example: 'custom-id-1,custom-id-2'
schema:
type: array
items:
type: string
- name: tagIds
in: query
description: 'Returns only assets that are tagged with all of the provided tag IDs. Use this to refine results based on tagging taxonomies such as product type, industry, or content category.'
explode: false
style: form
example: 'tag-id-1,tag-id-2'
schema:
type: array
items:
type: string
- name: slugs
in: query
description: 'Filters assets by their slugs, which are unique, human-readable identifiers often used in URLs or integrations. Use this when referring to assets via slug-based references.'
explode: false
style: form
example: 'ea7134d3-1706-4a79-b808-617cb6b6d95c,245b9712-65d9-4bfc-8505-2d56939a8b6f'
schema:
type: array
items:
type: string
responses:
'200':
description: OK. The request was successful. Returns a paginated list of assets matching the applied filters.
content:
application/json:
schema:
type: object
properties:
count:
description: Total number of results matching the request criteria.
type: integer
format: int32
example: 20
items:
type: array
description: List of asset objects returned in the response.
items:
type: object
properties:
id:
type: string
description: Unique identifier of the asset.
example: my-asset-id
currentFile:
type: object
nullable: true
properties:
id:
type: string
description: Unique identifier of the object.
example: my-asset-file-id
name:
type: string
description: Name of the asset.
example: my-asset.png
division:
description: Information about the Division the asset belongs to. Cannot be changed after creation.
type: object
properties:
id:
type: string
description: Unique identifier of the Division.
example: f541710283954a89bdfd40f221882451
status:
type: string
description: |
Current processing state of the asset:
* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.
* `queued` - The asset is currently queued for processing.
* `processing` - The asset is currently being processed.
* `active` - The asset is done processing and can be used.
* `failed` - The asset encountered an error while processing.
enum:
- prepared
- queued
- processing
- active
- failed
type:
type: string
description: |
The type of the asset.
enum:
- 3d-model
- audio
- document
- page
- personal-video-recording
- photo
- raw
- scorm
- unkn
# --- truncated at 32 KB (852 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/showpad/refs/heads/main/openapi/showpad-v4-openapi-original.yml