{
"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\nintegrating their platform with Showpad API.\n\nThe base URL of this API is patterned as `https://{subdomain}.api.showpad.com/v4` where `{subdomain}` is the\nprovided subdomain of the customer, i.e., `https://xyz-org.api.showpad.com/v4` will be the API base URL of a\ncustomer that has a `xyz-org` subdomain.\n",
"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"
}
}
},
{
"url": "https://{subdomain}.api.staging.showpad.com/v4",
"description": "Staging server",
"x-environment": "staging",
"variables": {
"subdomain": {
"default": "customer",
"description": "Showpad customer subdomain"
}
}
},
{
"url": "https://{subdomain}.api.development.showpad.io/v4",
"description": "Development server",
"x-environment": "development",
"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.\n* `Authorization` must be set with the Bearer token as value\n\n\n\n```\nAuthorization: Bearer ABC123\n```\n\nA `401 Unauthorized` response status will be returned if the authorization has been refused.\nA `403 Forbidden` response status will be returned if access to the resource is insufficient.\n"
},
{
"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.\n\nUse this endpoint when you need to:\n- Display Division options in custom interfaces or admin tools\n- Sync Division metadata with external systems\n- Filter or segment content and users based on organizational structure\n\nSupports 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.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n\nUse this endpoint when you need to:\n- Display Division details in an admin or reporting interface\n- Validate Division configuration before creating or updating related resources\n- Sync organizational structure between Showpad and an external system\n\nReturns 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.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n\nUse this endpoint when you need to:\n- Build custom asset galleries or search interfaces\n- Integrate Showpad asset metadata into external systems\n- Filter assets by tag, name, or organizational Divisions for targeted access\n\nSupports 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:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"type": {
"type": "string",
"description": "The type of the asset.\n",
"enum": [
"3d-model",
"audio",
"document",
"page",
"personal-video-recording",
"photo",
"raw",
"scorm",
"unknown",
"url",
"video",
"webapp"
]
},
"slug": {
"type": "string",
"description": "URL-friendly identifier of the asset."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was created, in `ISO 8601` UTC format."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was last updated, in `ISO 8601` UTC format."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"lastUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the latest version of the asset was uploaded, in `ISO 8601` UTC format.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the actions the current user is permitted to take on the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"description": "Indicates if the asset can be shared (`true`) or not (`false`). Defaults to `true`."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"isDivisionShared": {
"type": "boolean",
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"isSensitive": {
"type": "boolean",
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For `url` assets only. Indicates whether the URL should be opened:\n- `true` – in a new tab (target=\"_blank\")\n- `false` – embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"duration": {
"type": "integer",
"description": "The duration in seconds of the video/audio file.",
"nullable": true,
"readOnly": true
},
"pageCount": {
"type": "integer",
"description": "Total number of pages in the document. Applicable to `document` assets only.",
"nullable": true
},
"wordCount": {
"type": "integer",
"format": "int64",
"description": "The number of words in the content.",
"example": 100,
"nullable": true,
"readOnly": true
},
"competencies": {
"type": "array",
"description": "List of competency UUIDs associated with this asset.",
"readOnly": true,
"items": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
"example": "a3e72bbf-ae0b-8738-1106-b1beb685ea88"
}
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"checksum": {
"type": "string",
"description": "MD5 hash of the uploaded file, used to verify data integrity.",
"nullable": true
},
"size": {
"type": "integer",
"description": "Size of the uploaded asset file, in bytes.",
"nullable": true
},
"tags": {
"type": "array",
"description": "List of tags assigned to the asset. Only the `id` is returned.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"countries": {
"type": "array",
"description": "List of countries assigned to the asset.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"languages": {
"type": "array",
"description": "List of languages assigned to the asset.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"downloadableInternal": {
"type": "array",
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"required": [
"primary",
"variants"
],
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"asset",
"status"
],
"properties": {
"asset": {
"type": "object",
"required": [
"id",
"languages",
"countries",
"authors"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"description": "List of assigned languages.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Current status of the variant:\n* `to-be-localized` - The variant refers to the binary file of the primary asset; it must be localized.\n* `outdated` - The variant is explicitly marked as outdated by a Showpad user.\n* `localized` - The variant is a localized variant with its own binary file.\n",
"enum": [
"to-be-localized",
"outdated",
"localized"
]
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "postAssets",
"summary": "Create an asset",
"description": "This endpoint creates a new asset record in Showpad. An asset represents a digital resource such as a document, image, video, or URL. Creating an asset involves providing its metadata, assigning it to a Division, and optionally setting additional properties such as tags, countries, languages, authors, sharing permissions, and expiration details.\n\nNote: The asset file (binary content) is not uploaded through this endpoint. Once the asset has been created successfully, you must upload the file by creating an asset file (see [Create an asset file](https://developer.showpad.com/docs/apis/references/v4#/operations/postAssetFiles)).\n\nAssets can be created as either:\n- Local assets — Files that are stored and managed directly in Showpad.\n- External assets — Assets managed by external OAuth2 clients.\n\nThe request requires authentication and appropriate content management permissions for the specified Division.",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "The request payload to create a new asset.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"division"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the asset.",
"example": "My Document.pdf"
},
"division": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
}
],
"description": "The Division the asset belongs to. Cannot be changed after creation."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the user actions that are permitted for this asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"default": true,
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"default": true,
"description": "Indicates if the asset can be shared (`true`) or not (`false`)."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isDivisionShared": {
"type": "boolean",
"default": false,
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"isSensitive": {
"type": "boolean",
"default": false,
"description": "If `true`, the asset is hidden in kiosk mode.\n"
},
"isArchived": {
"type": "boolean",
"default": false,
"nullable": true,
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For URL assets only. Indicates whether the URL should be opened:\n- `true`: in a new tab (target=\"_blank\").\n- `false`: embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format."
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"url": {
"type": "string",
"description": "Only for URL-based assets. The target URL.",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"description": "List of tags assigned to the asset."
},
"languages": {
"type": "array",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
},
"description": "List of assigned languages."
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
},
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n"
},
"downloadableInternal": {
"type": "array",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
},
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n"
},
"origin": {
"type": "object",
"description": "Defines the source of the asset, determining whether it is managed locally within Showpad or externally by an OAuth2 client.\n- Local asset: Either omit the origin object entirely, or provide an origin object with type set to `local` and id set to `showpad`.\n- External asset: Provide an origin object with type set to `oauth2client`, linking the asset to the external OAuth2 client associated with the authenticated user.\nAny other combination of values will result in a 400 Bad Request error.",
"properties": {
"id": {
"type": "string",
"enum": [
"showpad"
],
"description": "Required for local assets with `id` set to `showpad`.\n"
},
"type": {
"type": "string",
"enum": [
"local",
"oauth2client"
],
"description": "Asset origin type.\n- Local asset: `type` must be set to `local` and `id` set to `showpad`.\n- External asset: `type` must be set to `oauth2client`. This links the asset to the external OAuth2 client associated with the authenticated user."
}
},
"required": [
"type"
],
"example": "{\n \"type\": \"oauth2client\"\n}\n"
}
}
},
"examples": {
"Microsoft Word document (docx)": {
"summary": "A Division-shared Microsoft Word (docx) asset",
"description": "This example creates a Microsoft Word (docx) asset. The `isDivisionShared` property is used to indicate that this asset is shared across Divisions. The permissions are set to allow annotations, editing and sharing of the asset.\n",
"value": "{\n \"name\": \"My Document.docx\",\n \"division\": {\n \"id\": \"26092c300714ba38ecc245b0da65daef\"\n },\n \"isDivisionShared\": true,\n \"permissions\": {\n \"isAnnotatable\": true,\n \"isEditable\": true,\n \"isShareable\": true\n }\n}\n"
},
"PDF document": {
"summary": "A PDF asset with tags, languages, countries and authors.",
"description": "This example creates a PDF (document) asset in a Division. A tag is set on the asset as well as other metadata like languages, countries and authors. The permissions to share and annotate the asset have been allowed. Note that the `isEditable` permission is not applicable to PDF assets and providing this will result in a 400 (`Bad request`) response.\n",
"value": "{\n \"name\": \"My Document.pdf\",\n \"division\": {\n \"id\": \"f541710283954a89bdfd40f221882451\"\n },\n \"description\": \"the asset description\",\n \"tags\": [\n {\n \"id\": \"df391e1da6ed4db8a8085838f7abd130\"\n }\n ],\n \"permissions\": {\n \"isAnnotatable\": true,\n \"isShareable\": true\n },\n \"languages\": [\n {\n \"code\": \"en\"\n }\n ],\n \"countries\": [\n {\n \"code\": \"US\"\n }\n ],\n \"authors\": [\n {\n \"id\": \"83a5a807b3c487c91f39d1c3da00b5d6\"\n }\n ]\n}\n"
},
"Photo asset (png)": {
"summary": "A photo (png) asset",
"description": "This example creates a photo (png) asset. The asset is not allowed to be shared.\n",
"value": "{\n \"name\": \"My Photo.png\",\n \"division\": {\n \"id\": \"26092c300714ba38ecc245b0da65daef\"\n },\n \"permissions\": {\n \"isShareable\": false\n }\n}\n"
},
"URL asset": {
"summary": "A URL asset",
"description": "This example creates a URL (hyperlink) asset in a Division. Note that the name needs to have a `.url` extension.\nThe `url` field must be used to provide the location.\n",
"value": "{\n \"name\": \"Showpad.url\",\n \"division\": {\n \"id\": \"26092c300714ba38ecc245b0da65daef\"\n },\n \"url\": \"https://www.showpad.com\"\n}\n"
},
"Video asset linked to the integration": {
"summary": "A video asset linked to your integration",
"description": "This example creates an video (mp4) asset. This asset is linked to the integration.\nThe `externalId` is optional but can be provided to maintain a reference to another system.\n",
"value": "{\n \"name\": \"how-to-use-showpad.mp4\",\n \"division\": {\n \"id\": \"26092c300714ba38ecc245b0da65daef\"\n },\n \"origin\": {\n \"type\": \"oauth2client\"\n },\n \"externalId\": \"abc-123\"\n}\n"
}
}
}
}
},
"responses": {
"201": {
"description": "Created. The asset record was successfully created.",
"content": {
"application/json": {
"schema": {
"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:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"type": {
"type": "string",
"description": "The type of the asset.\n",
"enum": [
"3d-model",
"audio",
"document",
"page",
"personal-video-recording",
"photo",
"raw",
"scorm",
"unknown",
"url",
"video",
"webapp"
]
},
"slug": {
"type": "string",
"description": "URL-friendly identifier of the asset."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was created, in `ISO 8601` UTC format."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was last updated, in `ISO 8601` UTC format."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"lastUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the latest version of the asset was uploaded, in `ISO 8601` UTC format.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the actions the current user is permitted to take on the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"description": "Indicates if the asset can be shared (`true`) or not (`false`). Defaults to `true`."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"isDivisionShared": {
"type": "boolean",
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"isSensitive": {
"type": "boolean",
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For `url` assets only. Indicates whether the URL should be opened:\n- `true` – in a new tab (target=\"_blank\")\n- `false` – embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"duration": {
"type": "integer",
"description": "The duration in seconds of the video/audio file.",
"nullable": true,
"readOnly": true
},
"pageCount": {
"type": "integer",
"description": "Total number of pages in the document. Applicable to `document` assets only.",
"nullable": true
},
"wordCount": {
"type": "integer",
"format": "int64",
"description": "The number of words in the content.",
"example": 100,
"nullable": true,
"readOnly": true
},
"competencies": {
"type": "array",
"description": "List of competency UUIDs associated with this asset.",
"readOnly": true,
"items": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
"example": "a3e72bbf-ae0b-8738-1106-b1beb685ea88"
}
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"checksum": {
"type": "string",
"description": "MD5 hash of the uploaded file, used to verify data integrity.",
"nullable": true
},
"size": {
"type": "integer",
"description": "Size of the uploaded asset file, in bytes.",
"nullable": true
},
"tags": {
"type": "array",
"description": "List of tags assigned to the asset. Only the `id` is returned.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"countries": {
"type": "array",
"description": "List of countries assigned to the asset.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"languages": {
"type": "array",
"description": "List of languages assigned to the asset.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"downloadableInternal": {
"type": "array",
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"required": [
"primary",
"variants"
],
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"asset",
"status"
],
"properties": {
"asset": {
"type": "object",
"required": [
"id",
"languages",
"countries",
"authors"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"description": "List of assigned languages.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Current status of the variant:\n* `to-be-localized` - The variant refers to the binary file of the primary asset; it must be localized.\n* `outdated` - The variant is explicitly marked as outdated by a Showpad user.\n* `localized` - The variant is a localized variant with its own binary file.\n",
"enum": [
"to-be-localized",
"outdated",
"localized"
]
}
}
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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/query": {
"post": {
"operationId": "postAssetsQuery",
"summary": "Query assets using ShowQL",
"description": "This endpoint enables you to query your asset library using [ShowQL](https://developer.showpad.com/docs/apis/content/showql), a Showpad domain-specific language (DSL) that allows for flexible and complex filtering of assets based on metadata, tags, languages, countries, and more.\nUse this endpoint when you need to: \n- Retrieve a precise set of assets using complex filter logic\n- Search by metadata, custom fields, tags, or localized attributes\n- Page through large result sets with consistent performance using cursor-based pagination \n#### Iterating over results\nThere are two ways to paginate through the results of a ShowQL query: offset-based and cursor-based pagination. The method you choose depends on the expected number of results and performance considerations. Only one pagination strategy can be used at a time. Providing both an `offset` and a `cursor` in the same request is not supported.\n- **Offset-based pagination** - Use for fewer than 10,000 results
To fetch the first page of results, either omit the `offset` property or set it to `0`. The `limit` property controls the maximum number of assets returned per page. If its omitted, the default value is applied.
To fetch the next page of results, calculate the new offset by adding the number of items returned in the previous page to the current offset:
`offset = offset + items.length`
Pagination should stop when the next offset value would be greater than or equal to the `count` value returned in the response.
**Note**:- If the number of remaining results is fewer than the `limit`, only the remaining items will be returned.
- If the `offset` exceeds the number of available results, an empty `items` array will be returned.
- Attempting to retrieve more than 10,000 results using offset-based pagination will result in a 400 (Bad Request) response.
\n\n- **Cursor-based pagination** - Use for more than 10,000 results
To fetch the first page, omit the `cursor` property.
Each response includes a `next` property containing a cursor string. To retrieve the next page, set the `cursor` property in your request to this `next` value. Continue this process until `next` is `null`, which indicates there are no more results.
The `limit` property can be used to control the number of assets returned per page.
Important considerations:- **Do not change the sort order or filtering criteria** between cursor-based requests, as doing so may result in inconsistent or unexpected pagination behavior.
- Cursors may become invalid if large changes occur in the underlying data between paginated requests.
\n",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"description": "A valid ShowQL string to query assets.",
"type": "string",
"maxLength": 20000
},
"cursor": {
"description": "Use this value from the previous response's `next` field to paginate using cursor-based pagination.",
"type": "string"
},
"offset": {
"description": "The zero-based offset of the first asset returned in the result (used with offset-based pagination). This query parameter is used together with the `limit` query parameter to paginate through assets in the result.\n",
"type": "integer",
"minimum": 0,
"maximum": 99999,
"default": 0
},
"limit": {
"description": "The maximum number of assets to return in one page of results. Note that the actual number of assets returned in one page might be less than this limit.\n",
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 20
}
}
},
"examples": {
"Simple": {
"summary": "An example using `name`, `updatedAt` and `createdAt`",
"description": "This query returns all non-archived assets whose name contains “eOS” and that were updated within the last 7 days, sorted by creation date in descending order.\n",
"value": "{\n \"query\": \"name ~ \\\"eOS\\\" AND updatedAt >= -1w ORDER BY createdAt DESC\"\n}\n"
},
"Archived": {
"summary": "An example using `archivedAt` and `IS (NOT) EMPTY`",
"description": "A query that finds all assets of type \"video\" with more than 500 views, and that have been archived.\n",
"value": "{\n \"query\": \"type = \\\"video\\\" AND views > 500 AND archivedAt IS NOT EMPTY\"\n}\n"
},
"Offset": {
"summary": "An example using offset-based paging",
"description": "A simple query that is also accompanied by an `offset` property to get a page of the search result different from the first one.\n",
"value": "{\n \"query\": \"name ~ \\\"eOS\\\" AND likes > 5\",\n \"offset\": 21\n}\n"
},
"Cursor": {
"summary": "An example using cursor-based paging",
"description": "A simple query that is also accompanied by an `cursor` property to get the next page of the search result. The `limit` parameter is used to specify the number of results to return but may be omitted to use the default value.\n",
"value": "{\n \"query\": \"name ~ \\\"eOS\\\" AND likes > 5\",\n \"limit: 10,\n \"cursor\": \"bm90aGluZ3Rvc2Vl\"\n}\n"
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns a list of assets that match the given ShowQL query.",
"content": {
"application/json": {
"schema": {
"description": "The response to a ShowQL query for assets.",
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"description": "Total number of results matching the request criteria.",
"type": "integer",
"format": "int32",
"example": 20
},
"items": {
"type": "array",
"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:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"type": {
"type": "string",
"description": "The type of the asset.\n",
"enum": [
"3d-model",
"audio",
"document",
"page",
"personal-video-recording",
"photo",
"raw",
"scorm",
"unknown",
"url",
"video",
"webapp"
]
},
"slug": {
"type": "string",
"description": "URL-friendly identifier of the asset."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was created, in `ISO 8601` UTC format."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was last updated, in `ISO 8601` UTC format."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"lastUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the latest version of the asset was uploaded, in `ISO 8601` UTC format.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the actions the current user is permitted to take on the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"description": "Indicates if the asset can be shared (`true`) or not (`false`). Defaults to `true`."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"isDivisionShared": {
"type": "boolean",
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"isSensitive": {
"type": "boolean",
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For `url` assets only. Indicates whether the URL should be opened:\n- `true` – in a new tab (target=\"_blank\")\n- `false` – embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"duration": {
"type": "integer",
"description": "The duration in seconds of the video/audio file.",
"nullable": true,
"readOnly": true
},
"pageCount": {
"type": "integer",
"description": "Total number of pages in the document. Applicable to `document` assets only.",
"nullable": true
},
"wordCount": {
"type": "integer",
"format": "int64",
"description": "The number of words in the content.",
"example": 100,
"nullable": true,
"readOnly": true
},
"competencies": {
"type": "array",
"description": "List of competency UUIDs associated with this asset.",
"readOnly": true,
"items": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
"example": "a3e72bbf-ae0b-8738-1106-b1beb685ea88"
}
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"checksum": {
"type": "string",
"description": "MD5 hash of the uploaded file, used to verify data integrity.",
"nullable": true
},
"size": {
"type": "integer",
"description": "Size of the uploaded asset file, in bytes.",
"nullable": true
},
"tags": {
"type": "array",
"description": "List of tags assigned to the asset. Only the `id` is returned.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"countries": {
"type": "array",
"description": "List of countries assigned to the asset.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"languages": {
"type": "array",
"description": "List of languages assigned to the asset.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"downloadableInternal": {
"type": "array",
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"required": [
"primary",
"variants"
],
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"asset",
"status"
],
"properties": {
"asset": {
"type": "object",
"required": [
"id",
"languages",
"countries",
"authors"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"description": "List of assigned languages.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Current status of the variant:\n* `to-be-localized` - The variant refers to the binary file of the primary asset; it must be localized.\n* `outdated` - The variant is explicitly marked as outdated by a Showpad user.\n* `localized` - The variant is a localized variant with its own binary file.\n",
"enum": [
"to-be-localized",
"outdated",
"localized"
]
}
}
}
}
}
}
}
}
},
"next": {
"description": "The next cursor to use for retrieving more results.",
"type": "string",
"nullable": true
}
}
},
"example": "{\n \"count\": 5,\n \"next\": \"bm90aGluZ3Rvc2Vl\",\n \"items\": [{\n \"id\": \"5a1b013f3c84478889b1b26fecb7d58d\",\n \"currentFile\": {\n \"id\": \"1d5bd771a4a0e9e2b32b59440f19683c\"\n },\n \"name\": \"eOS.pdf\",\n \"division\": {\n \"id\": \"d1633a97f47671aa77a1d947a169dcf9\"\n },\n \"status\": \"active\",\n \"type\": \"document\",\n \"externalId\": null,\n \"description\": \"The most flexible & complete operating system\",\n \"createdAt\": \"2023-04-18T12:00:00Z\",\n \"updatedAt\": \"2023-04-18T18:41:00Z\",\n \"expiresAt\": null,\n \"releasedAt\": null,\n \"draftedAt\": null,\n \"lastUploadedAt\": \"2023-04-18T12:02:36Z\",\n \"permissions\": {\n \"isAnnotatable\": false,\n \"isEditable\": false,\n \"isShareable\": true\n },\n \"isProcessedUsed\": false,\n \"isDivisionShared\": false,\n \"isSensitive\": false,\n \"isArchived\": false,\n \"isRenderExternalAllowed\": true,\n \"isOnlyDocumentShareable\": true,\n \"isSpeakerNotesEnabled\": false,\n \"lockedPages\": [],\n \"pageCount\": 5,\n \"checksum\": \"5633b7f75c44f76f0b3f97e73f529cf6\",\n \"size\": 1800531,\n \"tags\": [],\n \"countries\": [\n {\n \"code\": \"US\"\n },\n {\n \"code\": \"UK\"\n }\n ],\n \"languages\": [\n {\n \"code\": \"en\"\n }\n ],\n \"authors\": [\n {\n \"id\": \"83a5a807b3c487c91f39d1c3da00b5d6\"\n }\n ],\n \"downloadableExternal\": [],\n \"downloadableInternal\": []\n }]\n}\n"
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
},
"example": "{\n \"title\": \"Bad Request\",\n \"detail\": \"The ShowQL query is invalid\",\n \"status\": \"400\",\n \"meta\": {\n \"name\": \"query\",\n \"reason\": \"Syntax error at character 50\",\n \"category\": \"ParseError\"\n },\n \"type\": \"/problems/bad-request\"\n}\n"
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
},
"example": "{\n \"title\": \"Unauthorized\",\n \"detail\": \"Authorization is either invalid or expired\",\n \"status\": 401,\n \"type\": \"/problems/unauthorized\"\n}\n"
}
}
}
}
}
},
"/assets/{assetId}": {
"parameters": [
{
"name": "assetId",
"in": "path",
"required": true,
"description": "The asset ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
}
],
"get": {
"operationId": "getAsset",
"summary": "Retrieve an Asset",
"description": "Retrieves a single asset by its unique ID. This is helpful when you need to inspect or work with a specific piece of content and require its full details.\n\nUse this endpoint when you need to:\n- Fetch all available details for a specific asset\n- Display or preview asset content in an application\n- Retrieve metadata, tags, file info, and processing status\n- Check localization or download options for a given asset\n- Confirm the current state of an asset before performing an update or action.",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the requested asset object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"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:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"type": {
"type": "string",
"description": "The type of the asset.\n",
"enum": [
"3d-model",
"audio",
"document",
"page",
"personal-video-recording",
"photo",
"raw",
"scorm",
"unknown",
"url",
"video",
"webapp"
]
},
"slug": {
"type": "string",
"description": "URL-friendly identifier of the asset."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was created, in `ISO 8601` UTC format."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was last updated, in `ISO 8601` UTC format."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"lastUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the latest version of the asset was uploaded, in `ISO 8601` UTC format.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the actions the current user is permitted to take on the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"description": "Indicates if the asset can be shared (`true`) or not (`false`). Defaults to `true`."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"isDivisionShared": {
"type": "boolean",
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"isSensitive": {
"type": "boolean",
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For `url` assets only. Indicates whether the URL should be opened:\n- `true` – in a new tab (target=\"_blank\")\n- `false` – embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"duration": {
"type": "integer",
"description": "The duration in seconds of the video/audio file.",
"nullable": true,
"readOnly": true
},
"pageCount": {
"type": "integer",
"description": "Total number of pages in the document. Applicable to `document` assets only.",
"nullable": true
},
"wordCount": {
"type": "integer",
"format": "int64",
"description": "The number of words in the content.",
"example": 100,
"nullable": true,
"readOnly": true
},
"competencies": {
"type": "array",
"description": "List of competency UUIDs associated with this asset.",
"readOnly": true,
"items": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
"example": "a3e72bbf-ae0b-8738-1106-b1beb685ea88"
}
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"checksum": {
"type": "string",
"description": "MD5 hash of the uploaded file, used to verify data integrity.",
"nullable": true
},
"size": {
"type": "integer",
"description": "Size of the uploaded asset file, in bytes.",
"nullable": true
},
"tags": {
"type": "array",
"description": "List of tags assigned to the asset. Only the `id` is returned.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"countries": {
"type": "array",
"description": "List of countries assigned to the asset.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"languages": {
"type": "array",
"description": "List of languages assigned to the asset.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"downloadableInternal": {
"type": "array",
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"required": [
"primary",
"variants"
],
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"asset",
"status"
],
"properties": {
"asset": {
"type": "object",
"required": [
"id",
"languages",
"countries",
"authors"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"description": "List of assigned languages.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Current status of the variant:\n* `to-be-localized` - The variant refers to the binary file of the primary asset; it must be localized.\n* `outdated` - The variant is explicitly marked as outdated by a Showpad user.\n* `localized` - The variant is a localized variant with its own binary file.\n",
"enum": [
"to-be-localized",
"outdated",
"localized"
]
}
}
}
}
}
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "updateAsset",
"summary": "Update an asset",
"description": "Use this endpoint to update the properties of an existing asset by its unique ID. This is typically used to modify metadata, tags, external IDs, or other editable fields after the asset has been created.\n- Modify metadata such as name, description, or external ID\n- Update tags, countries, or languages assigned to the asset\n- Adjust sharing permissions or visibility settings",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "The request payload for updating an asset.\n",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "my-asset.png"
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "Description of the asset.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the user actions that are permitted for the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"default": true,
"description": "Indicates if the asset supports annotations (`true`) or not (`false`).\n"
},
"isEditable": {
"type": "boolean",
"default": false,
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs.\n"
},
"isShareable": {
"type": "boolean",
"default": true,
"description": "Indicates if the asset can be shared (`true`) or not (`false`)."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isDivisionShared": {
"type": "boolean",
"default": false,
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"isSensitive": {
"type": "boolean",
"default": false,
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"default": false,
"nullable": true,
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For URL assets only. Indicates whether the URL should be opened:\n- `true`: in a new tab (target=\"_blank\").\n- `false`: embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format."
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"description": "List of tags assigned to the asset. Use an empty array to remove all tags."
},
"languages": {
"type": "array",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
},
"description": "List of languages assigned to the asset."
},
"countries": {
"type": "array",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
},
"description": "List of countries assigned to the asset."
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
},
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n"
},
"downloadableInternal": {
"type": "array",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
},
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n"
},
"origin": {
"type": "object",
"description": "Defines the source of the asset, determining whether it is managed locally within Showpad or externally by an OAuth2 client.\n- Local asset: Either omit the origin object entirely, or provide an origin object with type set to `local` and id set to `showpad`.\n- External asset: Provide an origin object with type set to `oauth2client`, linking the asset to the external OAuth2 client associated with the authenticated user.\nAny other combination of values will result in a 400 Bad Request error.",
"properties": {
"id": {
"type": "string",
"enum": [
"showpad"
],
"description": "Required for local assets with `id` set to `showpad`.\n"
},
"type": {
"type": "string",
"enum": [
"local",
"oauth2client"
],
"description": "Asset origin type.\n- Local asset: `type` must be set to `local` and `id` set to `showpad`.\n- External asset: `type` must be set to `oauth2client`. This links the asset to the external OAuth2 client associated with the authenticated user."
}
},
"required": [
"type"
],
"example": "{\n \"type\": \"oauth2client\"\n}\n"
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"description": "Link to an existing asset.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
},
"description": "List of assigned languages."
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
},
"required": [
"id"
]
}
}
},
{
"type": "object",
"description": "Representation of a placeholder asset, containing the same properties as the primary asset, combined with the specified languages, countries and authors.",
"properties": {
"asset": {
"type": "object",
"properties": {
"languages": {
"type": "array",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
},
"description": "List of assigned languages."
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
},
"required": [
"languages",
"countries"
]
}
}
}
]
}
}
},
"required": [
"primary",
"variants"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated asset object.",
"x-summary": "OK. Request was successful.",
"content": {
"application/json": {
"schema": {
"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:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"type": {
"type": "string",
"description": "The type of the asset.\n",
"enum": [
"3d-model",
"audio",
"document",
"page",
"personal-video-recording",
"photo",
"raw",
"scorm",
"unknown",
"url",
"video",
"webapp"
]
},
"slug": {
"type": "string",
"description": "URL-friendly identifier of the asset."
},
"externalId": {
"type": "string",
"description": "A custom external reference ID for the asset. Only editable when the application owns the asset and the user has `manage_content` permissions for the Division.",
"nullable": true,
"example": "my-custom-id",
"minLength": 1,
"maxLength": 128
},
"description": {
"type": "string",
"description": "A description of the asset.",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was created, in `ISO 8601` UTC format."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the asset was last updated, in `ISO 8601` UTC format."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Optional expiration date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"releasedAt": {
"type": "string",
"format": "date-time",
"description": "Optional release date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"draftedAt": {
"type": "string",
"format": "date-time",
"description": "Optional draft date of the asset, in `ISO 8601` UTC format.",
"nullable": true
},
"lastUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the latest version of the asset was uploaded, in `ISO 8601` UTC format.",
"nullable": true
},
"permissions": {
"type": "object",
"description": "Defines the actions the current user is permitted to take on the asset.",
"properties": {
"isAnnotatable": {
"type": "boolean",
"description": "Indicates if the asset supports annotations (`true`) or not (`false`)."
},
"isEditable": {
"type": "boolean",
"description": "Indicates if the asset is editable (true) or not (false). This permission is applicable to `document` assets except PDFs."
},
"isShareable": {
"type": "boolean",
"description": "Indicates if the asset can be shared (`true`) or not (`false`). Defaults to `true`."
}
}
},
"isProcessedUsed": {
"type": "boolean",
"description": "Indicates if the optimized version (`true`) or the original file (`false`) is used when downloaded. Defaults to `true`."
},
"isSpeakerNotesEnabled": {
"type": "boolean",
"description": "Indicates whether speaker notes are enabled for the asset (`true`) or not (`false`). When enabled, allows presenters to add and view speaker notes associated with the asset. Defaults to `false`."
},
"isDivisionShared": {
"type": "boolean",
"description": "Indicates whether the asset is shared across multiple Divisions (`true`) or restricted to its own Division (`false`). To enable cross-Division sharing, Division-level asset sharing must be enabled on the Division provided (`isAssetSharingEnabled` set to true).\n"
},
"isSensitive": {
"type": "boolean",
"description": "If `true`, the asset is hidden in kiosk mode."
},
"isArchived": {
"type": "boolean",
"description": "If `true`, the asset has been archived and is no longer active."
},
"isRenderExternalAllowed": {
"type": "boolean",
"description": "For `url` assets only. Indicates whether the URL should be opened:\n- `true` – in a new tab (target=\"_blank\")\n- `false` – embedded in an iframe."
},
"isOnlyEntireDocumentShareable": {
"type": "boolean",
"description": "Indicates whether individual pages of a document can be shared (`true`) or not (`false`). Defaults to `false`."
},
"lockedPages": {
"type": "array",
"description": "Defines a range of pages that cannot be shared individually.",
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"enforcedPages": {
"type": "object",
"description": "Pages that are enforced to be prepended or appended when sharing.",
"nullable": true,
"properties": {
"prepend": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
},
"append": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"start": {
"type": "integer",
"description": "The first page in the range (inclusive)."
},
"end": {
"type": "integer",
"description": "The last page in the range (inclusive)."
}
}
}
}
}
},
"duration": {
"type": "integer",
"description": "The duration in seconds of the video/audio file.",
"nullable": true,
"readOnly": true
},
"pageCount": {
"type": "integer",
"description": "Total number of pages in the document. Applicable to `document` assets only.",
"nullable": true
},
"wordCount": {
"type": "integer",
"format": "int64",
"description": "The number of words in the content.",
"example": 100,
"nullable": true,
"readOnly": true
},
"competencies": {
"type": "array",
"description": "List of competency UUIDs associated with this asset.",
"readOnly": true,
"items": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
"example": "a3e72bbf-ae0b-8738-1106-b1beb685ea88"
}
},
"url": {
"type": "string",
"description": "For `url` assets only. The external URL the asset points to.",
"nullable": true
},
"checksum": {
"type": "string",
"description": "MD5 hash of the uploaded file, used to verify data integrity.",
"nullable": true
},
"size": {
"type": "integer",
"description": "Size of the uploaded asset file, in bytes.",
"nullable": true
},
"tags": {
"type": "array",
"description": "List of tags assigned to the asset. Only the `id` is returned.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"countries": {
"type": "array",
"description": "List of countries assigned to the asset.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"languages": {
"type": "array",
"description": "List of languages assigned to the asset.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
},
"downloadableExternal": {
"type": "array",
"description": "List of asset versions available for external download. An empty array means the asset is not downloadable externally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"downloadableInternal": {
"type": "array",
"description": "List of asset versions available for download by authenticated users. An empty array means the asset is not downloadable internally.\n",
"items": {
"type": "string",
"enum": [
"original",
"pdf"
],
"description": "Types of downloads that are possible:\n* `original` - The original file can be downloaded\n* `pdf` - The generated PDF version can be downloaded\n"
}
},
"localization": {
"type": "object",
"nullable": true,
"description": "Details about localized versions of the asset. Null if not applicable.",
"required": [
"primary",
"variants"
],
"properties": {
"primary": {
"type": "object",
"description": "The primary asset of the localization configuration.",
"properties": {
"asset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
}
}
}
}
},
"variants": {
"type": "array",
"description": "List of variants associated with the primary asset.",
"minItems": 0,
"maxItems": 50,
"items": {
"type": "object",
"required": [
"asset",
"status"
],
"properties": {
"asset": {
"type": "object",
"required": [
"id",
"languages",
"countries",
"authors"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the asset.",
"example": "my-asset-id"
},
"languages": {
"type": "array",
"description": "List of assigned languages.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
},
"countries": {
"type": "array",
"description": "List of assigned countries.",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
},
"authors": {
"type": "array",
"description": "List of assigned content authors.",
"items": {
"type": "object",
"properties": {
"id": {
"description": "User ID of the content author.",
"type": "string",
"example": "83a5a807b3c487c91f39d1c3da00b5d6"
}
}
}
}
}
},
"status": {
"type": "string",
"description": "Current status of the variant:\n* `to-be-localized` - The variant refers to the binary file of the primary asset; it must be localized.\n* `outdated` - The variant is explicitly marked as outdated by a Showpad user.\n* `localized` - The variant is a localized variant with its own binary file.\n",
"enum": [
"to-be-localized",
"outdated",
"localized"
]
}
}
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteAsset",
"summary": "Delete an asset",
"description": "Use this endpoint to permanently delete an asset from your Showpad library by its unique ID. Once deleted, the asset and its associated files, metadata, and permissions will no longer be accessible.\n- Remove outdated or incorrect content from the library\n- Ensure only current and approved assets remain available\n- Clean up assets that are no longer in use or have expired",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"204": {
"description": "The asset was successfully deleted and no longer exists in the system. No response body is returned.",
"x-summary": "No Content. Accepted the changes."
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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/{assetId}/files": {
"parameters": [
{
"name": "assetId",
"in": "path",
"required": true,
"description": "The asset ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
}
],
"get": {
"operationId": "getAssetFiles",
"summary": "List Asset Files",
"description": "Use this endpoint to retrieve all file versions that belong to a specific asset. Asset files may include the original upload, optimized formats, or alternative versions of the same asset.\n\nThis is useful when you need to:\n- Display all available file formats for a given asset\n- Download or preview specific asset versions\n- Inspect file-level metadata, such as size, checksum, or extension\n- Paginate through large sets of files associated with a single asset",
"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
}
}
],
"responses": {
"200": {
"description": "OK. Request was successful.",
"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 file objects.",
"items": {
"description": "Created File object.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the object.",
"example": "my-asset-file-id"
},
"name": {
"type": "string",
"description": "The name of the uploaded file.",
"example": "video.mp4",
"nullable": true
},
"status": {
"type": "string",
"description": "Current processing state of the asset:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"error": {
"type": "string",
"description": "A short explanation of the issue during file processing. The value\nwill be set to `null` if there is no error.\n",
"nullable": true,
"example": null
},
"draftedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was moved to draft state, in `ISO 8601` UTC format."
},
"scheduledActivateAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file is scheduled to be activated, in `ISO 8601` UTC format."
},
"activatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was activated, in `ISO 8601` UTC format."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "postAssetFiles",
"summary": "Create an Asset File",
"description": "This endpoint attaches a new binary file to an existing asset. Use this endpoint when you need to:\n- Add a new file to an existing asset\n- Replace or update the binary content while keeping metadata intact\n- Verify file integrity with a checksum\n- Upload large files using a temporary upload link\n\nAttaching a new binary file happens in two steps:\n\nStep 1: Request an upload link.\n- Send a `POST` request with the `assetId` in the path.\n- Optionally provide a new `fileName` or a Base64-encoded `contentMD5`` checksum for validation.\n- The response body includes:\n - `uploadMeta`: Information required to perform the upload\n - `uploadUrl`: A temporary signed link where the binary file must be uploaded\n - `suggestedContentType`: The `Content-Type` header value required for the upload\n\nStep 2: Upload the file.\n- Send a `PUT` request to the `uploadUrl`.\n- Use the `suggestedContentType` header, and include the `Content-MD5` header if you provided a checksum.\n- If the checksum doesn’t match, you’ll get a `400` error.\n\nOnce the file is uploaded, Showpad processes it. After processing, the uploaded file becomes the `currentFile` for the asset.",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"201": {
"description": "The file was successfully created and associated with the asset. Returns the created File object.",
"x-summary": "Created. The resource was successfully created.",
"content": {
"application/json": {
"schema": {
"description": "Created File object.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the object.",
"example": "my-asset-file-id"
},
"name": {
"type": "string",
"description": "The name of the uploaded file.",
"example": "video.mp4",
"nullable": true
},
"status": {
"type": "string",
"description": "Current processing state of the asset:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"error": {
"type": "string",
"description": "A short explanation of the issue during file processing. The value\nwill be set to `null` if there is no error.\n",
"nullable": true,
"example": null
},
"draftedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was moved to draft state, in `ISO 8601` UTC format."
},
"scheduledActivateAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file is scheduled to be activated, in `ISO 8601` UTC format."
},
"activatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was activated, in `ISO 8601` UTC format."
},
"uploadMeta": {
"type": "object",
"properties": {
"uploadUrl": {
"type": "string",
"description": "The signed URL where the binary file must be uploaded via a `PUT` request. The URL is valid for 15 minutes.",
"format": "uri",
"nullable": true,
"example": "https://s3.amazonaws.com/path/to/bucket/with/signed/credentials"
},
"suggestedContentType": {
"type": "string",
"description": "The suggested `Content-Type` header for the upload request to `uploadUrl`.",
"example": "video/mp4"
},
"metadata": {
"type": "object",
"description": "Additional metadata that must be sent with the upload request.",
"nullable": true,
"example": {
"origin": "api"
},
"additionalProperties": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
},
"requestBody": {
"description": "The request payload for attaching a new file to an existing asset.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional. A new name for the asset. If omitted, the asset’s current name is preserved.",
"example": "video.mp4"
},
"contentMD5": {
"type": "string",
"description": "Optional. A Base64-encoded MD5 checksum of the file to be uploaded. When provided, the uploaded file must match this checksum. This ensures data integrity during transfer. See [RFC-1864](https://datatracker.ietf.org/doc/html/rfc1864) for details.\n",
"example": "Q2hlY2sgSW50ZWdyaXR5IQ=="
}
}
}
}
}
}
}
},
"/assets/{assetId}/files/{fileId}": {
"parameters": [
{
"name": "assetId",
"in": "path",
"required": true,
"description": "The asset ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
},
{
"name": "fileId",
"in": "path",
"required": true,
"description": "The File ID.",
"schema": {
"type": "string",
"example": "1b513fa042db4c95b673721527852cbb"
}
}
],
"get": {
"operationId": "getAssetFileById",
"summary": "Retrieve an Asset File",
"description": "Use this endpoint to retrieve the metadata of a single asset file by its unique ID. This does not return the binary file itself but provides detailed information about the file.\n\nThis is useful when you need to:\n- Inspect file-level metadata such as name, size, or status\n- Check the current processing state of an asset file (e.g., queued, processing, active)\n- Retrieve error details if file processing failed\n- Confirm creation and update timestamps for version tracking",
"tags": [
"assets"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the requested asset file object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"description": "Created File object.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the object.",
"example": "my-asset-file-id"
},
"name": {
"type": "string",
"description": "The name of the uploaded file.",
"example": "video.mp4",
"nullable": true
},
"status": {
"type": "string",
"description": "Current processing state of the asset:\n* `prepared` - The asset is prepared and waiting for the binary file to be uploaded.\n* `queued` - The asset is currently queued for processing.\n* `processing` - The asset is currently being processed.\n* `active` - The asset is done processing and can be used.\n* `failed` - The asset encountered an error while processing.\n",
"enum": [
"prepared",
"queued",
"processing",
"active",
"failed"
]
},
"error": {
"type": "string",
"description": "A short explanation of the issue during file processing. The value\nwill be set to `null` if there is no error.\n",
"nullable": true,
"example": null
},
"draftedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was moved to draft state, in `ISO 8601` UTC format."
},
"scheduledActivateAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file is scheduled to be activated, in `ISO 8601` UTC format."
},
"activatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp when the file was activated, in `ISO 8601` UTC format."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/tags": {
"get": {
"operationId": "getTags",
"summary": "List all Tags",
"description": "This endpoint retrieves all existing tags that are available for the requester.",
"tags": [
"tags"
],
"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": "ids",
"in": "query",
"description": "One or multiple IDs to filter on.",
"explode": false,
"style": "form",
"example": "abc123,def456",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"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": "tagCategoryIds",
"in": "query",
"description": "One or multiple tag category IDs to filter on.",
"example": "tagcat1,tagcat2",
"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": "exactName",
"in": "query",
"description": "Searches by exact name.",
"schema": {
"type": "string",
"example": "customer"
}
}
],
"responses": {
"200": {
"description": "OK. Request was successful.",
"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 Tag objects.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"division": {
"description": "the ID of the Division to which this tag belongs. This cannot be updated once set.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"name": {
"type": "string",
"example": "TagA",
"description": "Name of the tag."
},
"tagCategories": {
"type": "array",
"description": "List of tag categories this tag is linked to.",
"items": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"isDivisionShared": {
"type": "boolean",
"description": "Whether or not the tag is a shared tag. \nCan only have the value `true` if `isAssetSharingEnabled` is set to `true` on the Division, and shared tags are enabled for the organization.\n",
"readOnly": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "postTags",
"summary": "Create a tag",
"description": "This endpoint creates a new tag.",
"tags": [
"tags"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "The request payload for creating a tag.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"division"
],
"properties": {
"name": {
"type": "string",
"description": "The name of a tag needs to be a non-empty string, up to 255 characters long. Both leading and trailing whitespace will be trimmed. Line break, carriage return and tab characters are not allowed.\n",
"minLength": 1,
"maxLength": 255,
"example": "my-tag"
},
"division": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
}
],
"description": "The ID of the Division this object will belong to. This cannot be updated once set."
},
"origin": {
"type": "object",
"description": "By specifying an `origin`, a client controls whether the tag will be local or external. To create an external tag, specify an `origin` object with `type` set to `oauth2client`. To create a local tag, either omit `origin` entirely or specify an `origin` object with `type` set to `local` and `id` set to `showpad`. Any other values are illegal and will result in a response with a `400` status code.\n",
"properties": {
"id": {
"type": "string",
"enum": [
"showpad"
],
"description": "When creating a local tag, i.e. `type` is `local`, `id` must be `showpad`.\n"
},
"type": {
"type": "string",
"enum": [
"local",
"oauth2client"
],
"description": "Use `local` to make the tag local. Use `oauth2client` to make the tag external, and associate it to the OAuth2 client part of the identity making the request.\n"
}
},
"required": [
"type"
],
"example": "{\n \"type\": \"oauth2client\"\n}\n"
},
"externalServiceId": {
"type": "string",
"nullable": true,
"example": "Cs131Da51fage1d1488f29e74756ee60"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Returns the created tag object.",
"x-summary": "Created. The resource was successfully created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"division": {
"description": "the ID of the Division to which this tag belongs. This cannot be updated once set.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"name": {
"type": "string",
"example": "TagA",
"description": "Name of the tag."
},
"tagCategories": {
"type": "array",
"description": "List of tag categories this tag is linked to.",
"items": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"isDivisionShared": {
"type": "boolean",
"description": "Whether or not the tag is a shared tag. \nCan only have the value `true` if `isAssetSharingEnabled` is set to `true` on the Division, and shared tags are enabled for the organization.\n",
"readOnly": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Tag already exists.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/tags/{tagId}": {
"parameters": [
{
"name": "tagId",
"in": "path",
"required": true,
"description": "The tag ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
}
],
"get": {
"operationId": "getTag",
"summary": "Retrieve a Tag",
"description": "This endpoint retrieves a single tag.",
"tags": [
"tags"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the requested tag object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"division": {
"description": "the ID of the Division to which this tag belongs. This cannot be updated once set.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"name": {
"type": "string",
"example": "TagA",
"description": "Name of the tag."
},
"tagCategories": {
"type": "array",
"description": "List of tag categories this tag is linked to.",
"items": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"isDivisionShared": {
"type": "boolean",
"description": "Whether or not the tag is a shared tag. \nCan only have the value `true` if `isAssetSharingEnabled` is set to `true` on the Division, and shared tags are enabled for the organization.\n",
"readOnly": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "updateTag",
"summary": "Update a Tag",
"description": "This endpoint updates a tag.",
"tags": [
"tags"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "The request payload for updating a tag.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The name of a tag needs to be a non-empty string, up to 255 characters long. Both leading and trailing whitespace will be trimmed. Line break, carriage return and tab characters are not allowed.\n",
"minLength": 1,
"maxLength": 255,
"example": "my-tag"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated tag.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"division": {
"description": "the ID of the Division to which this tag belongs. This cannot be updated once set.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"name": {
"type": "string",
"example": "TagA",
"description": "Name of the tag."
},
"tagCategories": {
"type": "array",
"description": "List of tag categories this tag is linked to.",
"items": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"isDivisionShared": {
"type": "boolean",
"description": "Whether or not the tag is a shared tag. \nCan only have the value `true` if `isAssetSharingEnabled` is set to `true` on the Division, and shared tags are enabled for the organization.\n",
"readOnly": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Tag is already exist.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteTag",
"summary": "Delete a Tag",
"description": "This endpoint deletes a tag.",
"tags": [
"tags"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"204": {
"description": "The tag was removed successfully.",
"x-summary": "No Content. Accepted the changes."
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Tag is used in a filter.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/tag-categories": {
"get": {
"operationId": "getTagCategories",
"summary": "List all Tag Category",
"description": "This endpoint retrieves all existing Tag Categories available for the requester.",
"tags": [
"tag-categories"
],
"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": "One or multiple IDs to filter on.",
"explode": false,
"style": "form",
"example": "abc123,def456",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK. Request was successful.",
"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 Tag Categories.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"name": {
"type": "string",
"description": "Name of Tag Category.",
"example": "my-tag-category"
},
"division": {
"type": "object",
"description": "The ID of the Division this object will belong to. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"isPublished": {
"type": "boolean",
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
}
}
}
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "postTagCategories",
"summary": "Create a Tag Category",
"description": "This endpoint creates a new Tag Category resource.",
"tags": [
"tag-categories"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "Creating a tag category.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"division"
],
"properties": {
"name": {
"type": "string",
"example": "my-tag-name",
"description": "Name of Tag Category"
},
"division": {
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
}
],
"description": "The ID of the Division this object will belong to. This cannot be updated once set."
},
"isPublished": {
"type": "boolean",
"default": true,
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"tags": {
"type": "array",
"description": "List of all tags to be linked to this tag category.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Returns the created Tag Category object.",
"x-summary": "Created. The resource was successfully created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"name": {
"type": "string",
"description": "Name of Tag Category.",
"example": "my-tag-category"
},
"division": {
"type": "object",
"description": "The ID of the Division this object will belong to. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"isPublished": {
"type": "boolean",
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"400": {
"description": "Bad Request. Invalid or missing payload.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Resource already exists.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/tag-categories/{tagCategoryId}": {
"parameters": [
{
"name": "tagCategoryId",
"in": "path",
"required": true,
"description": "The tag category ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
}
],
"get": {
"operationId": "getTagCategory",
"summary": "Retrieve a Tag Category",
"description": "This endpoint retrieves a single Tag Category resource.",
"tags": [
"tag-categories"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the Tag Category details.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"name": {
"type": "string",
"description": "Name of Tag Category.",
"example": "my-tag-category"
},
"division": {
"type": "object",
"description": "The ID of the Division this object will belong to. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"isPublished": {
"type": "boolean",
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"post": {
"operationId": "updateTagCategory",
"summary": "Update a Tag Category",
"description": "This endpoint updates an existing Tag Category's details.",
"tags": [
"tag-categories"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"description": "The request payload for updating a tag category.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "my-category-tag-name"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"isPublished": {
"type": "boolean",
"description": "true when a tagcategory should be published and available for all users. false otherwise\n"
},
"tags": {
"type": "array",
"description": "List of all tags to be linked to this tag category. Will replace all tags linked to it.\n* Use empty array for removing all linked tags\n* Send `null` or don't include this property to leave the linked tags untouched\n",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated Tag Category object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"name": {
"type": "string",
"description": "Name of Tag Category.",
"example": "my-tag-category"
},
"division": {
"type": "object",
"description": "The ID of the Division this object will belong to. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"isPublished": {
"type": "boolean",
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"400": {
"description": "Bad Request. Invalid or missing payload.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Resource already exists.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteTagCategory",
"summary": "Delete a Tag Category",
"description": "This endpoint deletes a Tag Category resource.",
"tags": [
"tag-categories"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"204": {
"description": "The Tag Category was removed successfully.",
"x-summary": "No Content. Accepted the changes."
},
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/tag-categories/{tagCategoryId}/tags": {
"parameters": [
{
"name": "tagCategoryId",
"in": "path",
"required": true,
"description": "The tag category ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
}
],
"post": {
"operationId": "updateTagCategoryTags",
"summary": "Update tags of a Tag Category",
"description": "This endpoint updates an existing Tag Category's Tags.",
"tags": [
"tag-categories"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"add": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"remove": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the tag.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
}
},
"clear": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated Tag Category object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
},
"name": {
"type": "string",
"description": "Name of Tag Category.",
"example": "my-tag-category"
},
"division": {
"type": "object",
"description": "The ID of the Division this object will belong to. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Division.",
"example": "f541710283954a89bdfd40f221882451"
}
}
},
"isPublished": {
"type": "boolean",
"description": "Has the value `true` when a Tag Category should be published and available for all users. Otherwise, `false`.\n"
},
"parent": {
"nullable": true,
"type": "object",
"description": "ID of parent Tag Category. This can be used to nest multiple Tag Category levels. Set ID to\ninherit hierarchy, otherwise `null` to make it root-level.\n",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the object.",
"example": "df391e1da6ed4db8a8085838f7abd130"
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was created, in `ISO 8601` UTC format.\n"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp when the resource was last updated, in `ISO 8601` UTC format.\n"
}
}
}
}
}
},
"400": {
"description": "Bad Request. Invalid or missing payload.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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 asset 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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
},
"409": {
"description": "Conflict. Resource already exists.",
"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.\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.\n",
"example": "Property value provided is not valid."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.\n",
"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."
}
}
}
}
}
}
}
}
},
"/languages": {
"get": {
"operationId": "getLanguages",
"summary": "List all Languages",
"description": "Retrieve a list of all supported languages in your Showpad environment. Languages are provided in `ISO 639-1` format and can be used to localize content, configure user preferences, or build language-aware integrations.\n\nUse this endpoint when you need to:\n- Display available languages in setup or configuration interfaces\n- Validate language codes for content or metadata updates\n- Sync language options between Showpad and external systems\n\nIdeal for localization workflows and system integrations that depend on standardized language identifiers.",
"tags": [
"locale"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns a list of language codes.",
"x-summary": "Ok. Request was successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Total count of supported languages and a list of their `ISO 639-1` language codes.",
"properties": {
"count": {
"type": "integer",
"format": "int32",
"example": 123,
"description": "The total number of available language codes returned in this response."
},
"items": {
"type": "array",
"description": "A list of supported languages, each represented by an `ISO 639-1` language code.",
"items": {
"description": "The `ISO 639-1` language code identifying the supported language.",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "`BCP 47` language tag.",
"example": "en"
}
}
}
}
}
}
}
}
}
}
}
},
"/countries": {
"get": {
"operationId": "getCountries",
"summary": "List all Countries",
"description": "Retrieve a list of all supported country codes in ISO 3166-1 alpha-2 format.\n\nUse this endpoint when you need to:\n- Support geographic filtering or segmentation\n- Validate country inputs in forms or integrations\n- Power localization workflows that depend on standardized country identifiers",
"tags": [
"locale"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the list of country codes.",
"x-summary": "Ok. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "A list of country codes, with a count",
"properties": {
"count": {
"type": "integer",
"format": "int32",
"example": 123,
"description": "The size of the items array"
},
"items": {
"type": "array",
"description": "The list of country codes",
"items": {
"description": "using `ISO 3166-1 alpha-2` country code",
"type": "object",
"properties": {
"code": {
"type": "string",
"format": "iso-3166",
"description": "The `ISO 3166-1 alpha-2` country code identifying the supported country.",
"example": "US"
}
}
}
}
}
}
}
}
}
}
}
},
"/users": {
"get": {
"operationId": "getUsers",
"summary": "List Users",
"description": "Returns a list of existing Users that are available to the requester.\n\n**Note:** This API endpoint only support basic `GET` functionality in this version (`v4`). Please refer to version 3\n(`/v3`) for more advanced operations.\n",
"tags": [
"users"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "A limit on the number of objects to be returned, between `0` and `1000`.",
"schema": {
"type": "integer",
"format": "int32",
"default": 50,
"minimum": 0,
"maximum": 1000
}
},
{
"name": "offset",
"in": "query",
"description": "Offset of the returned result, to be used in combination with `limit`.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 0,
"minimum": 0
}
},
{
"name": "ids",
"in": "query",
"description": "One or multiple IDs to filter on. Combined in an **OR** fashion.",
"explode": false,
"style": "form",
"example": [
"abc123",
"def456"
],
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "emails",
"in": "query",
"description": "One or multiple emails to filter on.",
"explode": false,
"style": "form",
"example": [
"bob@example.com",
"john@example.com"
],
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"count": {
"description": "Total number of results.",
"type": "integer",
"format": "int32",
"example": 1
},
"items": {
"type": "array",
"description": "List of Users.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "UserId",
"description": "Unique identifier for the object.",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
},
"email": {
"type": "string",
"description": "The email address of the user.",
"format": "email",
"example": "bob.smith@example.com"
},
"firstName": {
"type": "string",
"example": "Bob",
"description": "The first name of the user."
},
"lastName": {
"type": "string",
"example": "Smith",
"description": "The last name of the user."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was created. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T00:00:00Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was last updated. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T08:00:00Z"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized. Authorization is either invalid or expired.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"title",
"detail",
"status"
],
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
},
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
},
"examples": {
"UnauthorizedExample": {
"value": {
"title": "Unauthorized",
"detail": "Authorization is either invalid or expired.",
"status": 401
}
}
}
}
}
},
"403": {
"description": "Forbidden. Requester does not have the right permissions to execute request.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"title",
"detail",
"status"
],
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
},
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
},
"examples": {
"ForbiddenExample": {
"value": {
"title": "Forbidden",
"detail": "Server refuses to authorize the request.",
"status": 403
}
}
}
}
}
}
}
}
},
"/users/{userId}": {
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "The user ID.",
"schema": {
"type": "string",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
}
}
],
"get": {
"operationId": "getUserById",
"summary": "Retrieve a User",
"description": "Retrieves the details of an existing User object.\n\n**Note:** This API endpoint only support basic `GET` functionality in this version (`v4`). Please refer to version 3\n(`/v3`) for more advanced operations.\n",
"tags": [
"users"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Returns the requested User object.",
"x-summary": "OK. Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "UserId",
"description": "Unique identifier for the object.",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
},
"email": {
"type": "string",
"description": "The email address of the user.",
"format": "email",
"example": "bob.smith@example.com"
},
"firstName": {
"type": "string",
"example": "Bob",
"description": "The first name of the user."
},
"lastName": {
"type": "string",
"example": "Smith",
"description": "The last name of the user."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was created. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T00:00:00Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was last updated. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T08:00:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized. Authorization is either invalid or expired.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"title",
"detail",
"status"
],
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
},
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
},
"examples": {
"UnauthorizedExample": {
"value": {
"title": "Unauthorized",
"detail": "Authorization is either invalid or expired.",
"status": 401
}
}
}
}
}
},
"403": {
"description": "Forbidden. Requester does not have the right permissions to execute request.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"title",
"detail",
"status"
],
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
},
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
},
"examples": {
"ForbiddenExample": {
"value": {
"title": "Forbidden",
"detail": "Server refuses to authorize the request.",
"status": 403
}
}
}
}
}
},
"404": {
"description": "Not found. Resource does not exists.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"title",
"detail",
"status"
],
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
},
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
},
"examples": {
"NotFoundExample": {
"value": {
"title": "Missing Resource",
"detail": "The requested resource does not exist.",
"status": 404
}
}
}
}
}
}
}
}
},
"/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.\nIgnored for non-paginated assets like image assets.\n"
}
},
"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",
"example": true,
"description": "Indicates whether the shared assets can be downloaded by external consumers. Defaults to `true` when omitted."
},
"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.\nIgnored for non-paginated assets like image assets.\n"
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces": {
"get": {
"operationId": "shared-spaces-list",
"summary": "List of Shared Spaces",
"description": "Get a list of Shared Spaces.\n\nAccess rules:\n- Regular users: Only Shared Spaces to which you have access (shared by or with you) are returned.\n- Managers: Your accessible Shared Spaces plus Shared Spaces where your team members are owners or participants.\n- Promoted members: Your accessible Shared Spaces plus Shared Spaces owned by users belonging to the divisions you are allowed to manage.\n- Admins: All Shared Spaces are returned.\n",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": false,
"name": "title",
"in": "query",
"description": "Filter by Shared Space title.\n\nPerforms a contains match on the title."
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"required": false,
"name": "isOwnerDeactivated",
"in": "query",
"description": "Owner deactivation filter.\n\n- `true`: return Shared Spaces whose owner is deactivated\n- `false`: return Shared Spaces whose owner is active"
},
{
"schema": {
"type": "string",
"format": "date-time"
},
"required": false,
"name": "lastActivitySince",
"in": "query",
"description": "Filter Shared Spaces with lastActivityAt on or after the given timestamp.\n\nFormat: ISO 8601 date-time (UTC)."
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "ownerUserId",
"in": "query",
"deprecated": true,
"description": "Deprecated: use `userId` with `userRole=OWNER`.\n\nFilter by owners. Accepts a comma-separated list of User IDs."
},
{
"schema": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "string",
"enum": [
"mine"
]
}
]
},
"required": false,
"name": "participantEmail",
"in": "query",
"description": "Participant email to filter by.\n\nUse `mine` to filter by the requester's own email."
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "managerId",
"in": "query",
"description": "Filter Shared Spaces by a manager's team members. Use `mine` to filter by your own team. Administrators can specify any User ID to filter by a specific manager; non-admin users can only use `mine`. Use with `teamRole` to further filter by roles.",
"example": "mine"
},
{
"schema": {
"type": "string",
"enum": [
"OWNER",
"PARTICIPANT",
"ANY"
],
"default": "ANY"
},
"required": false,
"name": "teamRole",
"in": "query",
"description": "Filter the manager's team access by role (applies only when `managerId` is provided).\n\n- `OWNER`: Shared Spaces owned by the manager's team members\n- `PARTICIPANT`: Shared Spaces where at least one of the manager's team members is a participant (inclusive: allowed even if another team member is the owner)\n- `ANY`: both owners and participants (default)",
"example": "ANY"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "userId",
"in": "query",
"description": "Filter by a specific user being an owner or participant.\n\nAccepts a comma-separated list of User IDs. Use together with `userRole` to control whether the user(s) must be owners, participants, or either (default).",
"example": "737d1a9383ce691b266d9ea3c41a32c9,fc868cc511c06acc0f0c2ca42ca176ea,509194af26d163c739a5442ecdac8732"
},
{
"schema": {
"type": "string",
"enum": [
"OWNER",
"PARTICIPANT",
"ANY"
],
"default": "ANY"
},
"required": false,
"name": "userRole",
"in": "query",
"description": "Role to apply for the specified user(s).\n\n- `OWNER`: user(s) who own Shared Spaces\n- `PARTICIPANT`: user(s) who are participants (non-owners). Inclusive: a Shared Space matches if at least one of the specified users is a participant, even if another specified user is the owner of that Shared Space\n- `ANY`: either owner or participant (default)",
"example": "ANY"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "usergroupId",
"in": "query",
"description": "Filter by a single User Group ID.\n\nNarrows results to Shared Spaces where members of this group are owners or participants (see `usergroupRole`).",
"example": "9c11d0bcd2c45f6825c05c716a55bc29"
},
{
"schema": {
"type": "string",
"enum": [
"OWNER",
"PARTICIPANT",
"ANY"
],
"default": "ANY"
},
"required": false,
"name": "usergroupRole",
"in": "query",
"description": "Role to apply for the specified user group.\n\n- `OWNER`: members who own Shared Spaces\n- `PARTICIPANT`: members who are participants (non-owners). Inclusive: a Shared Space matches if the group has at least one member as a participant, even if another member is the owner of that Shared Space\n- `ANY`: either owner or participant (default)",
"example": "ANY"
},
{
"schema": {
"type": "string",
"enum": [
"title",
"-title",
"createdAt",
"-createdAt",
"lastActivityAt",
"-lastActivityAt",
"archivedAt",
"-archivedAt",
"updatedAt",
"-updatedAt",
"status",
"-status"
],
"default": "-lastActivityAt"
},
"required": false,
"name": "sort",
"in": "query",
"description": "Specifies the field and direction used to sort the results. Prefix the field name with a hyphen (`-`) for descending sort order."
},
{
"schema": {
"type": "integer",
"default": "1000",
"minimum": 1,
"maximum": 1000
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "integer",
"default": "0",
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"minimum": 0
},
"required": false,
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"publicUri",
"publicUrl",
"owner",
"sharedSpaceTemplate",
"customerLogo",
"status",
"accessType",
"isExternalUploadAllowed",
"isExternalInviteAllowed",
"isExternalDownloadAllowed",
"isCommentAllowed",
"isSearchAIAllowed",
"createdAt",
"updatedAt",
"lastActivityAt",
"archivedAt",
"theme"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "ID of the Shared Space"
},
"title": {
"type": "string",
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"publicUri": {
"type": "string",
"description": "Public Uri for the Shared Space",
"example": "nice-shared-space"
},
"publicUrl": {
"type": "string",
"description": "Public URL for the Shared Space",
"example": "https://example.showpad.biz/s/nice-shared-space"
},
"owner": {
"type": "object",
"required": [
"userId"
],
"description": "Owner of the Shared Space",
"properties": {
"userId": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"sharedSpaceTemplate": {
"type": [
"object",
"null"
],
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"name": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"customerLogo": {
"type": [
"object",
"null"
],
"required": [
"url",
"height",
"isTransparent"
],
"properties": {
"url": {
"type": "string",
"example": "https://example.showpad.biz/api/v3/shares/99ef5dc98c4a962174b60bdf81ef6031/logo?cacheBust=1738772218"
},
"height": {
"type": "integer",
"example": 100
},
"isTransparent": {
"type": "boolean",
"example": true
}
}
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"description": "The status of the Shared Space",
"example": "ACTIVE"
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. `PRIVATE_EMAIL_VERIFIED`: access by invite/login (default). `PUBLIC_EMAIL_REQUIRED`: anyone enters by typing an email (not verified).",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not"
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not"
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not"
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space"
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's update datetime",
"example": "2019-08-24T14:15:22Z"
},
"lastActivityAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The Shared Space's last activity datetime",
"example": "2019-08-24T14:15:22Z"
},
"archivedAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The datetime Shared Space was archived",
"example": "2019-08-24T14:15:22Z"
},
"theme": {
"type": "object",
"required": [
"id"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
}
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
},
"post": {
"operationId": "shared-space-create",
"summary": "Create a Shared Space",
"description": "Create Space Space",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"publicUri": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[a-z0-9-_]+$",
"example": "nice-shared-space",
"description": "Unique public URI for the Shared Space. Allowed characters: lowercase letters, numbers, underscores, and hyphens (/^[a-z0-9-_]+$/). If not provided, it will be generated automatically. If provided and the URI is already in use, the API will return an error."
},
"owner": {
"type": "object",
"properties": {
"userId": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
},
"required": [
"userId"
],
"description": "This field can only be set by a requester with admin rights. If `ownerId` is not provided, the requester will automatically be assigned as the owner. However, for integration requests, this field is mandatory and must be explicitly specified."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space. The title is `optional` but must be provided either in the request or in the sharedSpaceTemplate, if one is being used."
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not. Defaults to `false` when omitted at creation."
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not. Defaults to `true` when omitted at creation."
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not. Defaults to `true` when omitted at creation."
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space. Defaults to `true` when omitted at creation."
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space. Defaults to `true` when omitted at creation."
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. Defaults to `PRIVATE_EMAIL_VERIFIED` when omitted at creation.",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"description": {
"type": "string",
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
},
"theme": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
},
"required": [
"id"
],
"description": "If not set, the Global Theme will be used"
},
"sharedSpaceTemplate": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"description": "The values from the template have lower priority. For example, if a `description` was provided in the request, the `description` from the template will be ignored."
}
}
}
}
}
},
"responses": {
"201": {
"description": "Shared Space was successfully created",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"publicUri",
"publicUrl",
"owner",
"sharedSpaceTemplate",
"customerLogo",
"status",
"accessType",
"isExternalUploadAllowed",
"isExternalInviteAllowed",
"isExternalDownloadAllowed",
"isCommentAllowed",
"isSearchAIAllowed",
"createdAt",
"updatedAt",
"lastActivityAt",
"archivedAt",
"theme",
"description"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "ID of the Shared Space"
},
"title": {
"type": "string",
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"publicUri": {
"type": "string",
"description": "Public Uri for the Shared Space",
"example": "nice-shared-space"
},
"publicUrl": {
"type": "string",
"description": "Public URL for the Shared Space",
"example": "https://example.showpad.biz/s/nice-shared-space"
},
"owner": {
"type": "object",
"required": [
"userId"
],
"description": "Owner of the Shared Space",
"properties": {
"userId": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"sharedSpaceTemplate": {
"type": [
"object",
"null"
],
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"name": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"customerLogo": {
"type": [
"object",
"null"
],
"required": [
"url",
"height",
"isTransparent"
],
"properties": {
"url": {
"type": "string",
"example": "https://example.showpad.biz/api/v3/shares/99ef5dc98c4a962174b60bdf81ef6031/logo?cacheBust=1738772218"
},
"height": {
"type": "integer",
"example": 100
},
"isTransparent": {
"type": "boolean",
"example": true
}
}
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"description": "The status of the Shared Space",
"example": "ACTIVE"
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. `PRIVATE_EMAIL_VERIFIED`: access by invite/login (default). `PUBLIC_EMAIL_REQUIRED`: anyone enters by typing an email (not verified).",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not"
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not"
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not"
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space"
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's update datetime",
"example": "2019-08-24T14:15:22Z"
},
"lastActivityAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The Shared Space's last activity datetime",
"example": "2019-08-24T14:15:22Z"
},
"archivedAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The datetime Shared Space was archived",
"example": "2019-08-24T14:15:22Z"
},
"theme": {
"type": "object",
"required": [
"id"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
}
},
"description": {
"type": "string",
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces/{shareId}": {
"get": {
"operationId": "shared-space-get",
"summary": "Get a Shared Space",
"description": "Get Shared Space details",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Shared Space details",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"publicUri",
"publicUrl",
"owner",
"sharedSpaceTemplate",
"customerLogo",
"status",
"accessType",
"isExternalUploadAllowed",
"isExternalInviteAllowed",
"isExternalDownloadAllowed",
"isCommentAllowed",
"isSearchAIAllowed",
"createdAt",
"updatedAt",
"lastActivityAt",
"archivedAt",
"theme",
"description"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "ID of the Shared Space"
},
"title": {
"type": "string",
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"publicUri": {
"type": "string",
"description": "Public Uri for the Shared Space",
"example": "nice-shared-space"
},
"publicUrl": {
"type": "string",
"description": "Public URL for the Shared Space",
"example": "https://example.showpad.biz/s/nice-shared-space"
},
"owner": {
"type": "object",
"required": [
"userId"
],
"description": "Owner of the Shared Space",
"properties": {
"userId": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"sharedSpaceTemplate": {
"type": [
"object",
"null"
],
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"name": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"customerLogo": {
"type": [
"object",
"null"
],
"required": [
"url",
"height",
"isTransparent"
],
"properties": {
"url": {
"type": "string",
"example": "https://example.showpad.biz/api/v3/shares/99ef5dc98c4a962174b60bdf81ef6031/logo?cacheBust=1738772218"
},
"height": {
"type": "integer",
"example": 100
},
"isTransparent": {
"type": "boolean",
"example": true
}
}
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"description": "The status of the Shared Space",
"example": "ACTIVE"
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. `PRIVATE_EMAIL_VERIFIED`: access by invite/login (default). `PUBLIC_EMAIL_REQUIRED`: anyone enters by typing an email (not verified).",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not"
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not"
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not"
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space"
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's update datetime",
"example": "2019-08-24T14:15:22Z"
},
"lastActivityAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The Shared Space's last activity datetime",
"example": "2019-08-24T14:15:22Z"
},
"archivedAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The datetime Shared Space was archived",
"example": "2019-08-24T14:15:22Z"
},
"theme": {
"type": "object",
"required": [
"id"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
}
},
"description": {
"type": "string",
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
},
"patch": {
"operationId": "shared-space-update",
"summary": "Update a Shared Space",
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"description": "Update Space Space",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space. The title is `optional` but must be provided either in the request or in the sharedSpaceTemplate, if one is being used."
},
"description": {
"type": "string",
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not. Defaults to `false` when omitted at creation."
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not. Defaults to `true` when omitted at creation."
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not. Defaults to `true` when omitted at creation."
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space. Defaults to `true` when omitted at creation."
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space. Defaults to `true` when omitted at creation."
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. Defaults to `PRIVATE_EMAIL_VERIFIED` when omitted at creation.",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"theme": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
},
"required": [
"id"
],
"description": "If not set, the Global Theme will be used"
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"description": "The status of the Shared Space",
"example": "ACTIVE"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Shared Space was successfully updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"publicUri",
"publicUrl",
"owner",
"sharedSpaceTemplate",
"customerLogo",
"status",
"accessType",
"isExternalUploadAllowed",
"isExternalInviteAllowed",
"isExternalDownloadAllowed",
"isCommentAllowed",
"isSearchAIAllowed",
"createdAt",
"updatedAt",
"lastActivityAt",
"archivedAt",
"theme",
"description"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "ID of the Shared Space"
},
"title": {
"type": "string",
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"publicUri": {
"type": "string",
"description": "Public Uri for the Shared Space",
"example": "nice-shared-space"
},
"publicUrl": {
"type": "string",
"description": "Public URL for the Shared Space",
"example": "https://example.showpad.biz/s/nice-shared-space"
},
"owner": {
"type": "object",
"required": [
"userId"
],
"description": "Owner of the Shared Space",
"properties": {
"userId": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"sharedSpaceTemplate": {
"type": [
"object",
"null"
],
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"name": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
}
}
},
"customerLogo": {
"type": [
"object",
"null"
],
"required": [
"url",
"height",
"isTransparent"
],
"properties": {
"url": {
"type": "string",
"example": "https://example.showpad.biz/api/v3/shares/99ef5dc98c4a962174b60bdf81ef6031/logo?cacheBust=1738772218"
},
"height": {
"type": "integer",
"example": 100
},
"isTransparent": {
"type": "boolean",
"example": true
}
}
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"ARCHIVED"
],
"description": "The status of the Shared Space",
"example": "ACTIVE"
},
"accessType": {
"type": "string",
"enum": [
"PRIVATE_EMAIL_VERIFIED",
"PUBLIC_EMAIL_REQUIRED"
],
"description": "How participants access the Shared Space. `PRIVATE_EMAIL_VERIFIED`: access by invite/login (default). `PUBLIC_EMAIL_REQUIRED`: anyone enters by typing an email (not verified).",
"example": "PRIVATE_EMAIL_VERIFIED"
},
"isExternalUploadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can upload files or not"
},
"isExternalInviteAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can invite or not"
},
"isExternalDownloadAllowed": {
"type": "boolean",
"description": "Indicates whether external participants can download content or not"
},
"isCommentAllowed": {
"type": "boolean",
"description": "Indicates whether comments are allowed in this Shared Space"
},
"isSearchAIAllowed": {
"type": "boolean",
"description": "Indicates whether participants can use SearchAI in this Shared Space"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The Shared Space's update datetime",
"example": "2019-08-24T14:15:22Z"
},
"lastActivityAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The Shared Space's last activity datetime",
"example": "2019-08-24T14:15:22Z"
},
"archivedAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The datetime Shared Space was archived",
"example": "2019-08-24T14:15:22Z"
},
"theme": {
"type": "object",
"required": [
"id"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
}
},
"description": {
"type": "string",
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "shared-space-delete",
"summary": "Delete a Shared Space",
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"description": "Delete a Shared Space",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"204": {
"description": "Shared Space was successfully deleted"
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces/{shareId}/transfer-ownership": {
"post": {
"operationId": "shared-space-transfer-ownership",
"summary": "Transfer ownership of the Shared Space",
"description": "Transfer ownership of the Shared Space to another User",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "ID of the User who will become the new owner"
}
},
"required": [
"userId"
],
"title": "transfer-ownership-request-body"
}
}
}
},
"responses": {
"204": {
"description": "Ownership was successfully transferred"
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces/{shareId}/items": {
"post": {
"operationId": "shared-spaces-items-add",
"summary": "Add items to Shared Space",
"description": "Add items to Shared Space.\nYou can add individual files and create folders on-the-fly.\nSupports nested structures with folders containing other items.",
"tags": [
"shared-spaces"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"asset"
]
},
"assetId": {
"type": "string",
"description": "The unique identifier of the asset to add."
},
"page": {
"type": "integer",
"exclusiveMinimum": 0,
"example": 1,
"description": "The page number of the asset, this is 1-based"
}
},
"required": [
"type",
"assetId"
],
"title": "AssetItem"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"folder"
]
},
"name": {
"type": "string",
"example": "Price Lists",
"description": "The name of the folder"
},
"description": {
"type": "string",
"description": "The description of the folder"
},
"folderItems": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"asset"
]
},
"assetId": {
"type": "string",
"description": "The unique identifier of the asset to add."
},
"page": {
"type": "integer",
"exclusiveMinimum": 0,
"example": 1,
"description": "The page number of the asset, this is 1-based"
}
},
"required": [
"type",
"assetId"
],
"title": "AssetItem"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"folder"
]
},
"name": {
"type": "string",
"example": "Price Lists",
"description": "The name of the folder"
},
"description": {
"type": "string",
"description": "The description of the folder"
},
"folderItems": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"asset"
]
},
"assetId": {
"type": "string",
"description": "The unique identifier of the asset to add."
},
"page": {
"type": "integer",
"exclusiveMinimum": 0,
"example": 1,
"description": "The page number of the asset, this is 1-based"
}
},
"required": [
"type",
"assetId"
],
"title": "AssetItem"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"folder"
]
},
"name": {
"type": "string",
"example": "Price Lists",
"description": "The name of the folder"
},
"description": {
"type": "string",
"description": "The description of the folder"
}
},
"required": [
"type",
"name"
],
"title": "FolderItem"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"asset": "#/components/schemas/SharedSpace-DevPortalAssetItem",
"folder": "#/components/schemas/SharedSpace-FolderItemLevel3"
}
}
}
}
},
"required": [
"type",
"name"
],
"title": "FolderItem"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"asset": "#/components/schemas/SharedSpace-DevPortalAssetItem",
"folder": "#/components/schemas/SharedSpace-FolderItemLevel2"
}
}
}
}
},
"required": [
"type",
"name"
],
"title": "FolderItem"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"asset": "#/components/schemas/SharedSpace-DevPortalAssetItem",
"folder": "#/components/schemas/SharedSpace-FolderItemLevel1"
}
},
"description": "Represents an item being added to a Shared Space - either an asset (file) or a folder.\nFolders may contain nested items of these two types (assets, folders).\nIf a folder with the same name already exists, a new folder will still be created"
}
}
},
"required": [
"items"
],
"example": {
"folderItemId": "9c5f3aa0784df25db1db821354e337e9",
"items": [
{
"type": "folder",
"name": "Documents",
"folderItems": [
{
"type": "asset",
"assetId": "a5f01a23f94aaf6195c1012694a404ea"
},
{
"type": "folder",
"name": "Second lvl",
"folderItems": [
{
"type": "asset",
"assetId": "a5f01a23f94aaf6195c1012694a404ea"
},
{
"type": "asset",
"assetId": "a5f01a23f94aaf6195c1012694a404ea"
}
]
}
]
},
{
"type": "asset",
"assetId": "a5f01a23f94aaf6195c1012694a404ea"
}
]
}
}
}
}
},
"responses": {
"201": {
"description": "Items were successfully added",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"summary",
"failedItems"
],
"example": {
"summary": {
"assetSuccessCount": 7,
"assetFailureCount": 3
},
"failedItems": [
{
"type": "asset",
"assetId": "c7f03c45f96ccf8397e3134896c606gc",
"page": 2,
"reason": "NON_SHAREABLE"
},
{
"type": "asset",
"assetId": "d8f04d56fa7ddf9498f4245997d707hd",
"reason": "INACCESSIBLE"
},
{
"type": "asset",
"assetId": "e9f05e67fb8eefa599f5356a98e808ie",
"page": 1,
"reason": "LOCKED_RANGE_INCOMPLETE"
},
{
"type": "asset",
"assetId": "f0f06f78fc9ffb65a0f6467b99f909jf",
"reason": "ASSET_NOT_FOUND"
},
{
"type": "asset",
"assetId": "01f07089fd0ffc76b1f7578c9af00akg",
"page": 3,
"reason": "ONLY_ENTIRE_DOCUMENT_ALLOWED"
},
{
"type": "asset",
"assetId": "12f08190fe1ffd87c2f8689d9bf11blh",
"reason": "ARCHIVED"
}
]
},
"properties": {
"summary": {
"type": "object",
"required": [
"assetSuccessCount",
"assetFailureCount"
],
"properties": {
"assetSuccessCount": {
"type": "integer",
"minimum": 0,
"description": "Number of assets that were successfully added.",
"example": 7
},
"assetFailureCount": {
"type": "integer",
"minimum": 0,
"description": "Number of assets that failed to be added. Details about each failed asset, including failure reasons, are provided in the failedItems array.",
"example": 3
}
}
},
"failedItems": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"assetId": {
"type": "string"
},
"name": {
"type": "string"
},
"page": {
"type": "integer",
"exclusiveMinimum": 0
},
"type": {
"type": "string",
"enum": [
"asset"
]
},
"reason": {
"type": "string",
"enum": [
"NON_SHAREABLE",
"INACCESSIBLE",
"LOCKED_RANGE_INCOMPLETE",
"ASSET_NOT_FOUND",
"ONLY_ENTIRE_DOCUMENT_ALLOWED",
"ARCHIVED",
"ENFORCED_PAGES_INCOMPLETE"
]
}
},
"required": [
"assetId",
"type",
"reason"
]
}
]
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/themes": {
"get": {
"operationId": "theme-list",
"summary": "List of Themes",
"description": "Retrieve a list of themes available in your Showpad instance. Themes include branding configurations, layout styles, and visual assets used to customize the platform interface.\n\nUse this endpoint when you need to:\n- Fetch a paginated collection of design configurations for your organization.\n- Look up specific theme details by filtering results using a title string.\n- Organize theme collections using predefined sorting fields like creation or modification dates.\n\nThis endpoint supports pagination constraints via limit and offset parameters and allows filtering.",
"tags": [
"themes"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": false,
"name": "divisionId",
"in": "query",
"description": "Filters the results to include only those that belong to a specific Division. This is useful for multi-division organizations to retrieve visual styles scoped to particular business units or regions."
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false"
},
"required": false,
"name": "includeGlobal",
"in": "query",
"description": "Controls whether the Global Theme is included in the response. Use `includeGlobal=true` to include the Global Theme in the results, regardless of `divisionId` filter. If not provided, defaults to false."
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false"
},
"required": false,
"name": "isDefault",
"in": "query",
"description": "Controls whether the response filters by the theme's default status attribute. Use `isDefault=true` to return only the default organization theme. If not provided, defaults to false."
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "title",
"in": "query",
"description": "Filters results by the theme's title. Returns only the themes where the `title` contains the specified string value."
},
{
"schema": {
"type": "string",
"enum": [
"title",
"-title",
"createdAt",
"-createdAt",
"updatedAt",
"-updatedAt"
],
"default": "-createdAt"
},
"required": false,
"name": "sort",
"in": "query",
"description": "Specifies the field and direction used to sort the results. Prefix the field name with a hyphen (`-`) for descending sort order."
},
{
"schema": {
"type": "integer",
"default": "50",
"description": "Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.",
"minimum": 1,
"maximum": 1000
},
"required": false,
"description": "Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "integer",
"default": "0",
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"minimum": 0
},
"required": false,
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "The request was successful. Returns a paginated collection of available themes, including their configurations, color properties, and visual metadata.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"isGlobal",
"isDefault",
"displayData",
"colorSettings",
"createdAt",
"updatedAt",
"division"
],
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the theme."
},
"title": {
"type": "string",
"description": "The display name of the theme."
},
"isGlobal": {
"type": "boolean",
"description": "Indicates whether the theme is a Global Theme. A Global Theme is available to all users across all Divisions."
},
"isDefault": {
"type": "boolean",
"description": "Controls whether the theme is set as the default option within its designated Division. The default theme is automatically assigned to all experiences in that Division. A Global Theme cannot be marked as default, meaning this value remains false for global entities. Only one theme can be configured as the default per Division."
},
"displayData": {
"type": "object",
"required": [
"aboutDescription",
"logo",
"displayImage"
],
"properties": {
"aboutDescription": {
"type": "string",
"maxLength": 800,
"description": "The descriptive text displayed within the Shared Content Viewer. This property does not apply to Shared Spaces, which lack an about section."
},
"logo": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
},
"displayImage": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
}
},
"colorSettings": {
"type": "object",
"required": [
"headerColor",
"headerFontColor",
"accentColor",
"accentFontColor"
],
"description": "A collection of hex color codes that define the theme's color palette across different user interface components.",
"properties": {
"headerColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for the interface header background color. Do not include a leading hashtag (#)."
},
"headerFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements inside the header background. Do not include a leading hashtag (#)."
},
"accentColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for primary buttons, highlights, and interactive accents. Do not include a leading hashtag (#)."
},
"accentFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements placed on top of accent-colored components. Do not include a leading hashtag (#)."
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the theme was created.",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the theme was last modified.",
"example": "2019-08-24T14:15:22Z"
},
"division": {
"type": [
"object",
"null"
],
"required": [
"id"
],
"description": "The scope of the Division to which this theme is assigned. This object returns `NULL` exclusively for a Global Theme, as global configurations are available across all business units.",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the scoping Division. This parent object returns `NULL` exclusively for a Global Theme."
}
}
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"/themes/{themeId}": {
"get": {
"operationId": "theme-get",
"summary": "Get a Theme",
"description": "Retrieves the full configuration, color settings, visual assets, and metadata for a specific theme.\n\nThis endpoint allows you to:\n- Fetch localized branding components for a specific business unit.\n- Verify active color configurations before rendering custom UI elements.\n- Access asset URLs for logos and cover images.",
"tags": [
"themes"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "The request was successful. Returns the detailed configuration, color properties, and asset metadata for the specified theme.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"isGlobal",
"isDefault",
"displayData",
"colorSettings",
"createdAt",
"updatedAt",
"division"
],
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the theme."
},
"title": {
"type": "string",
"description": "The display name of the theme."
},
"isGlobal": {
"type": "boolean",
"description": "Indicates whether the theme is a Global Theme. A Global Theme is available to all users across all Divisions."
},
"isDefault": {
"type": "boolean",
"description": "Controls whether the theme is set as the default option within its designated Division. The default theme is automatically assigned to all experiences in that Division. A Global Theme cannot be marked as default, meaning this value remains false for global entities. Only one theme can be configured as the default per Division."
},
"displayData": {
"type": "object",
"required": [
"aboutDescription",
"logo",
"displayImage"
],
"properties": {
"aboutDescription": {
"type": "string",
"maxLength": 800,
"description": "The descriptive text displayed within the Shared Content Viewer. This property does not apply to Shared Spaces, which lack an about section."
},
"logo": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
},
"displayImage": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
}
},
"colorSettings": {
"type": "object",
"required": [
"headerColor",
"headerFontColor",
"accentColor",
"accentFontColor"
],
"description": "A collection of hex color codes that define the theme's color palette across different user interface components.",
"properties": {
"headerColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for the interface header background color. Do not include a leading hashtag (#)."
},
"headerFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements inside the header background. Do not include a leading hashtag (#)."
},
"accentColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for primary buttons, highlights, and interactive accents. Do not include a leading hashtag (#)."
},
"accentFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements placed on top of accent-colored components. Do not include a leading hashtag (#)."
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the theme was created.",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The date and time when the theme was last modified.",
"example": "2019-08-24T14:15:22Z"
},
"division": {
"type": [
"object",
"null"
],
"required": [
"id"
],
"description": "The scope of the Division to which this theme is assigned. This object returns `NULL` exclusively for a Global Theme, as global configurations are available across all business units.",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the scoping Division. This parent object returns `NULL` exclusively for a Global Theme."
}
}
},
"experiences": {
"type": "array",
"description": "List of Experience IDs the theme is assigned to. This field is omitted for a Global Theme. For non-global themes, an empty list restricts access to administrators.",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/shared-space-templates": {
"get": {
"operationId": "shared-space-templates-list",
"summary": "List of Shared Space Templates",
"description": "List of Shared Space templates",
"tags": [
"shared-space-templates"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false"
},
"required": false,
"name": "includeUnpublished",
"in": "query",
"description": "This filter works only for users with administrator rights. `true` to include unpublished templates in results (templates with isPublished: false). `false` to return only published templates. default: `false`"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "divisionId",
"in": "query",
"description": "Filters the results to include only those that belong to a specific Division. This is useful for multi-division organizations to retrieve visual styles scoped to particular business units or regions."
},
{
"schema": {
"type": "string",
"enum": [
"createdAt",
"-createdAt",
"updatedAt",
"-updatedAt",
"name",
"-name",
"usageCount",
"-usageCount"
],
"default": "-createdAt"
},
"required": false,
"name": "sort",
"in": "query",
"description": "Specifies the field and direction used to sort the results. Prefix the field name with a hyphen (`-`) for descending sort order."
},
{
"schema": {
"type": "integer",
"default": "50",
"description": "Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.",
"minimum": 1,
"maximum": 1000
},
"required": false,
"description": "Defines the maximum number of results to return in a single response. Use in combination with `offset` to implement pagination when retrieving large datasets in batches.",
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "integer",
"default": "0",
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"minimum": 0
},
"required": false,
"description": "Specifies the number of results to skip before starting to return data. Use in combination with `limit` to implement pagination when retrieving large datasets.",
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "Request is successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"isPublished",
"creator",
"name",
"description",
"division",
"sharedSpaceData",
"usageCount",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"isPublished": {
"type": "boolean",
"description": "Indicates whether the template is available for use"
},
"creator": {
"type": "object",
"required": [
"id"
],
"description": "The user who created the template.",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
},
"name": {
"type": "string",
"example": "New Employee Onboarding"
},
"description": {
"type": [
"string",
"null"
],
"example": "An efficient template designed to streamline the onboarding process for new employees"
},
"division": {
"type": "object",
"required": [
"id"
],
"description": "The division to which the template belongs. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
},
"sharedSpaceData": {
"type": "object",
"required": [
"title",
"description",
"theme"
],
"properties": {
"title": {
"type": [
"string",
"null"
],
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
},
"theme": {
"type": "object",
"required": [
"id"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
}
}
}
}
},
"usageCount": {
"type": "integer",
"description": "Total number of shared spaces created from this template in last 2 years"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The template's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The template's last update datetime",
"example": "2019-08-24T14:15:22Z"
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
},
"/shared-space-templates/{templateId}": {
"get": {
"operationId": "shared-space-templates-get",
"summary": "Get a Shared Space Template",
"description": "Get Shared Space template",
"tags": [
"shared-space-templates"
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "templateId",
"in": "path",
"description": "ID of the Shared Space Template"
}
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Shared Space template details",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"createdAt",
"creator",
"description",
"division",
"id",
"isPublished",
"name",
"sharedSpaceData",
"updatedAt",
"usageCount",
"userGroups",
"users"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9"
},
"isPublished": {
"type": "boolean",
"description": "Indicates whether the template is available for use"
},
"creator": {
"type": "object",
"required": [
"id"
],
"description": "The user who created the template.",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
},
"name": {
"type": "string",
"example": "New Employee Onboarding"
},
"description": {
"type": [
"string",
"null"
],
"example": "An efficient template designed to streamline the onboarding process for new employees"
},
"division": {
"type": "object",
"required": [
"id"
],
"description": "The division to which the template belongs. This cannot be updated once set.",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
},
"sharedSpaceData": {
"type": "object",
"required": [
"title",
"description",
"theme"
],
"properties": {
"title": {
"type": [
"string",
"null"
],
"example": "Sales and Marketing teams",
"description": "The title of the Shared Space"
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 65535,
"example": "Team members can use this space to exchange ideas, discuss upcoming campaigns, analyze market trends, and track performance metrics."
},
"theme": {
"type": "object",
"required": [
"colorSettings",
"displayData",
"id",
"title"
],
"description": "If not set, the Global Theme will be used",
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the theme"
},
"title": {
"type": "string",
"description": "The display name of the theme."
},
"displayData": {
"type": "object",
"required": [
"aboutDescription",
"logo",
"displayImage"
],
"properties": {
"aboutDescription": {
"type": "string",
"maxLength": 800,
"description": "The descriptive text displayed within the Shared Content Viewer. This property does not apply to Shared Spaces, which lack an about section."
},
"logo": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
},
"displayImage": {
"type": [
"object",
"null"
],
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
}
},
"colorSettings": {
"type": "object",
"required": [
"headerColor",
"headerFontColor",
"accentColor",
"accentFontColor"
],
"description": "A collection of hex color codes that define the theme's color palette across different user interface components.",
"properties": {
"headerColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for the interface header background color. Do not include a leading hashtag (#)."
},
"headerFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements inside the header background. Do not include a leading hashtag (#)."
},
"accentColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for primary buttons, highlights, and interactive accents. Do not include a leading hashtag (#)."
},
"accentFontColor": {
"type": "string",
"maxLength": 6,
"example": "F6F6F6",
"description": "The hex code configuration for text overlay elements placed on top of accent-colored components. Do not include a leading hashtag (#)."
}
}
}
}
}
}
},
"usageCount": {
"type": "integer",
"description": "Total number of shared spaces created from this template in last 2 years"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "The template's creation datetime",
"example": "2019-08-24T14:15:22Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "The template's last update datetime",
"example": "2019-08-24T14:15:22Z"
},
"users": {
"type": "array",
"description": "List of User's IDs to which template is assigned. If the template is not assigned to any group or user, it will only be accessible to users with administrator rights.",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
}
},
"userGroups": {
"type": "array",
"description": "List of Usergroup's IDs to which template is assigned. If the template is not assigned to any group or user, it will only be accessible to users with administrator rights.",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"example": "9c5f3aa0784df25db1db821354e337e9",
"description": "The unique identifier of the Experience."
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces/{shareId}/quick-actions": {
"get": {
"operationId": "shared-spaces-quick-actions-list",
"summary": "Get a list of Shared Space Quick Actions",
"description": "List of Shared Space Quick Actions that are created for a Shared Space",
"tags": [
"shared-spaces-quick-actions"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"responses": {
"200": {
"description": "Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer"
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"url",
"sharedSpaceExtension"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Quick Action",
"example": "d1a1c1a1-1a1a-1a1a-1a1a-1a1a1a1a1a1a"
},
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
},
"sharedSpaceExtension": {
"type": "object",
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Shared Space Extension",
"example": "01XXXXX4XXXXXCCXXXX6XXXXXXPK"
},
"name": {
"type": "string",
"description": "Name of the Shared Space Extension",
"example": "Shared Space Meetings"
},
"description": {
"type": "string",
"description": "Description of the Shared Space Extension",
"example": "Several integrations to schedule a meeting as part of a Shared Space"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL pointing to the icon of the Shared Space Extension",
"example": "https://example.com/icon.png"
}
}
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
},
"post": {
"operationId": "create-shared-space-quick-action",
"summary": "Create a Shared Space Quick Action",
"description": "Create a Shared Space Quick Action for a Shared Space",
"tags": [
"shared-spaces-quick-actions"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"sharedSpaceExtensionId": {
"type": "string",
"description": "The ID of the Shared Space Extension",
"example": "01XXXXX4XXXXXCCXXXX6XXXXXXPK"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
}
},
"required": [
"title",
"sharedSpaceExtensionId",
"url"
]
}
}
}
},
"responses": {
"201": {
"description": "Shared Space Quick Action was successfully created",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"url",
"sharedSpaceExtension"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Quick Action",
"example": "d1a1c1a1-1a1a-1a1a-1a1a-1a1a1a1a1a1a"
},
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
},
"sharedSpaceExtension": {
"type": "object",
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Shared Space Extension",
"example": "01XXXXX4XXXXXCCXXXX6XXXXXXPK"
},
"name": {
"type": "string",
"description": "Name of the Shared Space Extension",
"example": "Shared Space Meetings"
},
"description": {
"type": "string",
"description": "Description of the Shared Space Extension",
"example": "Several integrations to schedule a meeting as part of a Shared Space"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL pointing to the icon of the Shared Space Extension",
"example": "https://example.com/icon.png"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/shared-spaces/{shareId}/quick-actions/{quickActionId}": {
"get": {
"operationId": "get-shared-spaces-quick-action",
"summary": "Get a Shared Space Quick Action",
"description": "Get a Shared Space Quick Action details.",
"tags": [
"shared-spaces-quick-actions"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "quickActionId",
"in": "path",
"description": "ID of the Quick Action created for a Shared Space"
}
],
"responses": {
"200": {
"description": "Request is successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"url",
"sharedSpaceExtension"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Quick Action",
"example": "d1a1c1a1-1a1a-1a1a-1a1a-1a1a1a1a1a1a"
},
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
},
"sharedSpaceExtension": {
"type": "object",
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Shared Space Extension",
"example": "01XXXXX4XXXXXCCXXXX6XXXXXXPK"
},
"name": {
"type": "string",
"description": "Name of the Shared Space Extension",
"example": "Shared Space Meetings"
},
"description": {
"type": "string",
"description": "Description of the Shared Space Extension",
"example": "Several integrations to schedule a meeting as part of a Shared Space"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL pointing to the icon of the Shared Space Extension",
"example": "https://example.com/icon.png"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
},
"patch": {
"operationId": "update-shared-spaces-quick-action",
"summary": "Update a Shared Space Quick Action",
"description": "Update a Quick Action within a Shared Space",
"tags": [
"shared-spaces-quick-actions"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "quickActionId",
"in": "path",
"description": "ID of the Quick Action created for a Shared Space"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Shared Space Quick Action was successfully updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"url",
"sharedSpaceExtension"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Quick Action",
"example": "d1a1c1a1-1a1a-1a1a-1a1a-1a1a1a1a1a1a"
},
"title": {
"type": "string",
"description": "The title of the Quick Action that will be displayed in the Shared Space",
"example": "Schedule a meeting with John"
},
"url": {
"type": "string",
"description": "URL to the external link/website to be embedded",
"example": "https://example.com/meet-with-john"
},
"isInternal": {
"type": "boolean",
"description": "`true` to only display the Quick Action to the Seller. `false` to display the Quick Action for both Buyer and Seller. If not passed - defaulted to `false`",
"example": true
},
"sharedSpaceExtension": {
"type": "object",
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the Shared Space Extension",
"example": "01XXXXX4XXXXXCCXXXX6XXXXXXPK"
},
"name": {
"type": "string",
"description": "Name of the Shared Space Extension",
"example": "Shared Space Meetings"
},
"description": {
"type": "string",
"description": "Description of the Shared Space Extension",
"example": "Several integrations to schedule a meeting as part of a Shared Space"
},
"icon": {
"type": [
"string",
"null"
],
"description": "URL pointing to the icon of the Shared Space Extension",
"example": "https://example.com/icon.png"
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "delete-shared-spaces-quick-action",
"summary": "Delete a Shared Space Quick Action",
"description": "Delete a Quick Action from a Shared Space",
"tags": [
"shared-spaces-quick-actions"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "shareId",
"in": "path",
"description": "ID of the Shared Space"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "quickActionId",
"in": "path",
"description": "ID of the Quick Action created for a Shared Space"
}
],
"responses": {
"204": {
"description": "Shared Space Quick Action was successfully deleted"
},
"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"
}
}
}
}
}
},
"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",
"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"
}
}
}
}
}
}
}
}
},
"/crm/recommendations/rules": {
"get": {
"operationId": "recommendation-rules-list",
"summary": "List of recommendation rules",
"description": "Use this endpoint to retrieve the list of recommendation rules configured for a CRM instance. These rules define how content is suggested to users based on CRM data and tags. You can filter rules by CRM instance or tags and paginate results for large datasets.\n\nThis is useful when you need to:\n- Retrieve all rules that apply to a specific CRM instance\n- Search for rules across multiple CRM instances using tag filters\n- Inspect rule conditions, operators, and associated tags to understand why recommendations are being made\n- Manage pagination when working with a large number of rules.",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "crmInstanceId",
"required": false,
"schema": {
"type": "string"
},
"description": "The CRM instance ID associated with the rule."
},
{
"in": "query",
"name": "tagIds",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "List of tag PIDs to filter rules by. This searches across all configured rules, across all instances, considering both `all` and `any` conditions.",
"example": "tag_pid_1,tag_pid_2,tag_pid_3"
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"type": "integer"
},
"description": "The maximum number of rules returned in a single page. Default: 1000, Maximum: 1000.",
"example": 1000
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"type": "string"
},
"description": "Used together with limit for pagination. Pass the cursor value from a previous response to get the next set of results.",
"example": "An4Fcs"
}
],
"responses": {
"200": {
"description": "Returns a JSON array with recommendation rules for either a specific CRM instance or a list of tags.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "integer",
"example": 1,
"description": "The total number of rules found."
},
"cursor": {
"type": "string",
"description": "Pagination cursor for fetching additional results. If `null`, there are no more results."
},
"items": {
"type": "array",
"description": "List of recommendation rules.",
"items": {
"title": "RecommendationRule",
"type": "object",
"required": [
"id",
"crmInstanceId",
"conditions",
"tags",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier (PID) of the rule."
},
"crmInstanceId": {
"type": "string",
"description": "The CRM instance ID associated with the rule."
},
"conditions": {
"type": "array",
"description": "The list of rule conditions defining when the recommendation applies.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"description": "Timestamp when the rule was created, in `ISO-8601` UTC format.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the rule was last updated, in `ISO 8601` UTC format.",
"format": "date-time"
}
}
}
}
}
},
"examples": {
"example-1": {
"value": {
"count": 1,
"items": [
{
"id": "1a9538350e983a7e12c59e52573f3c591469d27d651b4800279848a1531b2edc",
"crmInstanceId": "399286287f83da55ce90f90549139aad",
"conditions": [
{
"items": [
{
"objectName": "lead",
"fieldName": "LeadSource",
"operator": "equals",
"value": "Web"
}
]
}
],
"tags": {
"all": [
"ba16a6afc2d4247862c9986aa09772fd",
"951aca1a3576e1d1488f29e74756ee60"
],
"any": [],
"none": []
},
"createdAt": "2023-09-04T07:35:39.000Z",
"updatedAt": "2023-09-04T07:35:39.000Z"
}
]
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
},
"post": {
"operationId": "create-recommendation-rule",
"summary": "Create a recommendation rule",
"description": "Use this endpoint to create a new recommendation rule within a CRM instance. Recommendation rules define how content is suggested to users based on CRM data and tag configurations.\n\nUse this endpoint when you need to:\n- Add a new rule that links CRM fields to asset tags\n- Automate content recommendations based on CRM conditions or values\n- Manage dynamic associations between CRM data and assets\n\nEach rule includes conditions, operators, and tag logic (ALL, ANY, NONE) to determine which assets should be recommended.",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"title": "CreateOrUpdateRecommendationRulePayload",
"type": "object",
"required": [
"crmInstanceId",
"conditions",
"tags"
],
"properties": {
"crmInstanceId": {
"type": "string",
"description": "The unique identifier (PID) of the CRM instance where the recommendation rule will be created."
},
"conditions": {
"type": "array",
"description": "A list of conditions that define when the rule applies. Each condition specifies a CRM field, operator, and comparison value.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Created. The recommendation rule was successfully created.",
"content": {
"application/json": {
"schema": {
"title": "RecommendationRule",
"type": "object",
"required": [
"id",
"crmInstanceId",
"conditions",
"tags",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier (PID) of the rule."
},
"crmInstanceId": {
"type": "string",
"description": "The CRM instance ID associated with the rule."
},
"conditions": {
"type": "array",
"description": "The list of rule conditions defining when the recommendation applies.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"description": "Timestamp when the rule was created, in `ISO-8601` UTC format.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the rule was last updated, in `ISO 8601` UTC format.",
"format": "date-time"
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
}
},
"/crm/recommendations/rules/{ruleId}": {
"get": {
"operationId": "get-recommendation-rule",
"summary": "Get a single recommendation rule",
"description": "Use this endpoint to retrieve the details of a specific recommendation rule by its unique ID.\nEach rule defines how assets are recommended within a CRM instance based on conditions, operators, and associated tags.\n\nThis is useful when you need to:\n- View the configuration of a specific recommendation rule\n- Inspect conditions and tag criteria that determine which assets are recommended\n- Debug or validate rule behavior in a CRM integration\n- Retrieve rule metadata such as creation and update timestamps for auditing or version tracking",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "ruleId",
"required": true,
"schema": {
"type": "string"
},
"description": "The Rule PID to retrieve."
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the requested recommendation rule.",
"content": {
"application/json": {
"schema": {
"title": "RecommendationRule",
"type": "object",
"required": [
"id",
"crmInstanceId",
"conditions",
"tags",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier (PID) of the rule."
},
"crmInstanceId": {
"type": "string",
"description": "The CRM instance ID associated with the rule."
},
"conditions": {
"type": "array",
"description": "The list of rule conditions defining when the recommendation applies.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"description": "Timestamp when the rule was created, in `ISO-8601` UTC format.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the rule was last updated, in `ISO 8601` UTC format.",
"format": "date-time"
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested rule does not exist or the user does not have permission to access it.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
},
"delete": {
"operationId": "recommendation-rules-delete",
"summary": "Deletes a recommendation rule",
"description": "Use this endpoint to delete a specific recommendation rule by its unique Rule PID.\nDeleting a rule removes it permanently from the system and it can no longer be used for asset recommendations.\n\nThis is useful when you need to:\n- Remove outdated or invalid recommendation rules\n- Clean up rules that are no longer relevant\n- Ensure rules do not interfere with current CRM configurations\n- Maintain a tidy and accurate recommendation ruleset",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "ruleId",
"required": true,
"schema": {
"type": "string"
},
"description": "The Rule PID to delete."
}
],
"responses": {
"204": {
"description": "The recommendation rule was successfully deleted and no longer exists in the system. No response body is returned."
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested rule does not exist or the user does not have permission to access it.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
},
"put": {
"operationId": "update-recommendation-rule",
"summary": "Updates a recommendation rule",
"description": "Use this endpoint to update an existing recommendation rule by its unique ID. Updating a rule allows you to change its conditions, operators, tag logic, or recommended items so that content suggestions remain accurate and aligned with evolving CRM workflows.\n\nThis is useful when you need to:\n- Modify rule conditions based on updated CRM fields or business logic\n- Adjust tag requirements to refine which assets are recommended\n- Update recommended items as content changes over time\n- Maintain, tune, or troubleshoot CRM-driven content recommendations",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "ruleId",
"required": true,
"schema": {
"type": "string"
},
"description": "The Rule PID to update."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"title": "CreateOrUpdateRecommendationRulePayload",
"type": "object",
"required": [
"crmInstanceId",
"conditions",
"tags"
],
"properties": {
"crmInstanceId": {
"type": "string",
"description": "The unique identifier (PID) of the CRM instance where the recommendation rule will be created."
},
"conditions": {
"type": "array",
"description": "A list of conditions that define when the rule applies. Each condition specifies a CRM field, operator, and comparison value.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated recommendation rule.",
"content": {
"application/json": {
"schema": {
"title": "RecommendationRule",
"type": "object",
"required": [
"id",
"crmInstanceId",
"conditions",
"tags",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier (PID) of the rule."
},
"crmInstanceId": {
"type": "string",
"description": "The CRM instance ID associated with the rule."
},
"conditions": {
"type": "array",
"description": "The list of rule conditions defining when the recommendation applies.",
"items": {
"title": "RecommendationRuleCondition",
"type": "object",
"description": "The list of rule conditions defining when the recommendation applies.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "The assets that are recommended when the rule matches.",
"items": {
"title": "RecommendationRuleItem",
"type": "object",
"required": [
"objectName",
"fieldName",
"operator",
"value"
],
"properties": {
"objectName": {
"type": "string",
"description": "The CRM object name used in the rule."
},
"fieldName": {
"type": "string",
"description": "The CRM field evaluated in the rule condition."
},
"childObjectName": {
"type": "string",
"description": "If applicable, the child object name for a related CRM record."
},
"operator": {
"type": "string",
"description": "The operator used to evaluate the rule condition.",
"enum": [
"equals",
"equalsnot",
"contains",
"containsnot",
"startswith",
"startswithnot",
"endswith",
"endswithnot"
]
},
"value": {
"type": "string",
"description": "The value compared against the CRM field using the defined operator."
}
}
}
}
}
}
},
"tags": {
"title": "ContentTags",
"type": "object",
"description": "The tag configuration that defines which assets the rule affects.",
"required": [
"all",
"any",
"none"
],
"properties": {
"all": {
"type": "array",
"description": "Tag PIDs — the asset must have **all** these tags to match.",
"items": {
"type": "string"
}
},
"any": {
"type": "array",
"description": "Tag PIDs — the asset must have **any** of these tags to match.",
"items": {
"type": "string"
}
},
"none": {
"type": "array",
"description": "Tag PIDs — the asset must have **none** of these tags to match. Used only in combination with `all` or `any`.",
"items": {
"type": "string"
}
}
}
},
"createdAt": {
"type": "string",
"description": "Timestamp when the rule was created, in `ISO-8601` UTC format.",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the rule was last updated, in `ISO 8601` UTC format.",
"format": "date-time"
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"404": {
"description": "Not Found. Returned when the requested rule does not exist or the user does not have permission to access it.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
}
},
"/crm/shared-space-records/{sharedSpaceId}": {
"get": {
"operationId": "shared-space-records-list",
"summary": "Crm records related to specific shared space",
"description": "Retrieve CRM records related to a specific Shared Space by its unique Shared Space ID.\nThis endpoint returns the history of all activities and CRM records associated with the given Shared Space.\n\nThis is useful when you need to:\n- View all CRM records tied to a Shared Space\n- Track the history of interactions and activities within a Shared Space\n- Access associated account information if present\n- Monitor and audit Shared Space usage in your CRM system",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"name": "sharedSpaceId",
"in": "path",
"required": true,
"description": "ID of a Shared Space"
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns a paginated list of CRM records associated with the Shared Space.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "number",
"description": "The total number of CRM records retrieved."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"type",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The unique ID of the CRM record."
},
"type": {
"type": "string",
"description": "The type of CRM record, typically represented as the API name."
},
"name": {
"type": "string",
"description": "The name of the CRM record."
},
"url": {
"type": "string",
"description": "The URL linking to the CRM record, if present."
},
"accountId": {
"type": "string",
"description": "The account ID associated with the CRM record, if present."
}
}
}
}
}
},
"examples": {
"Example 1": {
"value": {
"count": 2,
"items": [
{
"type": "opportunity",
"id": "0064x00000LITLNAA5",
"name": "Edna Frank",
"url": "https://company.my.salesforce.com/0064x00000LITLNAA5",
"accountId": "0014x00000BQkwdAAD"
},
{
"id": "0014x00000BQkwdAAD",
"type": "account",
"name": "GenePoint",
"url": "https://company.my.salesforce.com/0014x00000BQkwdAAD"
}
]
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
},
"example": {
"title": "Forbidden",
"detail": "You are not an admin",
"status": 403
}
}
}
}
}
}
},
"/crm/share-records/{shareId}": {
"get": {
"operationId": "share-records-list",
"summary": "Crm records related to specific share",
"description": "Retrieve CRM records related to a specific Share by its unique Share ID.\nThis endpoint returns the history of all activities and CRM records associated with the given Share.\n\nThis is useful when you need to:\n- View all CRM records tied to a Share\n- Track the history of interactions and activities for a specific Share\n- Access associated account information if present\n- Monitor and audit Share usage in your CRM system",
"tags": [
"crm"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"name": "shareId",
"in": "path",
"required": true,
"description": "ID of a Share"
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns a paginated list of CRM records associated with the Share.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"count",
"items"
],
"properties": {
"count": {
"type": "number",
"description": "The total number of CRM records retrieved."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"type",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "The unique ID of the CRM record."
},
"type": {
"type": "string",
"description": "The type of CRM record, typically represented as the API name."
},
"name": {
"type": "string",
"description": "The name of the CRM record."
},
"url": {
"type": "string",
"description": "The URL linking to the CRM record, if present."
},
"accountId": {
"type": "string",
"description": "The account ID associated with the CRM record, if present."
}
}
}
}
}
},
"examples": {
"Example 1": {
"value": {
"count": 2,
"items": [
{
"type": "opportunity",
"id": "0064x00000LITLNAA5",
"name": "Edna Frank",
"url": "https://company.my.salesforce.com/0064x00000LITLNAA5",
"accountId": "0014x00000BQkwdAAD"
},
{
"id": "0014x00000BQkwdAAD",
"type": "account",
"name": "GenePoint",
"url": "https://company.my.salesforce.com/0014x00000BQkwdAAD"
}
]
}
}
}
}
}
},
"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": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
},
"401": {
"description": "Unauthorized. The request lacks valid authentication credentials, or the provided token has expired.",
"content": {
"application/problem+json": {
"schema": {
"title": "Error",
"type": "object",
"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": "Unauthorized"
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the specific reason for the failure.",
"example": "Authorization is either invalid or expired."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned by the server.",
"example": 401
}
}
}
}
}
}
}
}
},
"/mutual-action-plan": {
"post": {
"operationId": "postMap",
"summary": "Create MAP",
"description": "Create a new Mutual Action Plan (MAP) associated with a specific context, such as a Shared Space or Shared Space Template. A MAP helps structure collaboration by defining shared goals, actions, and timelines between participants.\n\nUse this endpoint when you need to:\n- Create a MAP for a specific Shared Space or template context\n- Initialize a new MAP based on an existing source MAP\n- Programmatically manage MAP creation as part of a workflow or integration",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"contextType": {
"type": "string",
"enum": [
"SHARED-SPACE",
"SHARED-SPACE-TEMPLATE"
],
"description": "The type of context the Mutual Action Plan (MAP) is created for. This determines whether the MAP is associated with a Shared Space or a Shared Space Template."
},
"contextId": {
"type": "string",
"description": "The unique identifier of the context (Shared Space or Shared Space Template) to which the MAP will be attached."
},
"sourceMapId": {
"type": "string",
"description": "Optional identifier of an existing MAP to use as a starting point. When provided, the new MAP is created by copying the structure of the source MAP."
}
},
"required": [
"contextType",
"contextId"
]
}
}
}
},
"responses": {
"201": {
"description": "Mutual Action Plan created successfully. The response returns the newly created MAP and its associated context.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"context",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
"context": {
"type": "object",
"required": [
"type",
"id"
],
"description": "Context to which the Mutual Action Plan (MAP) belongs, including its type and identifier.",
"properties": {
"type": {
"type": "string",
"enum": [
"SHARED-SPACE",
"SHARED-SPACE-TEMPLATE"
],
"description": "The type of context the Mutual Action Plan (MAP) is associated with."
},
"id": {
"type": "string",
"description": "The unique identifier of the context (Shared Space or Shared Space Template)."
}
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the Mutual Action Plan (MAP) was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the Mutual Action Plan (MAP) was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
},
"get": {
"operationId": "gesMaps",
"summary": "Get list of MAPs",
"description": "Retrieve a list of Mutual Action Plans (MAPs) available to the authenticated user. MAPs are returned based on access to their associated context, such as Shared Spaces. Administrators can retrieve all MAPs across the organization.\n\nUse this endpoint when you need to:\n- List MAPs associated with a specific Shared Space\n- Filter MAPs by context to support targeted workflows\n- Build dashboards or interfaces displaying MAP activity\n\nSupports filtering by context and is useful for managing collaboration workflows and tracking shared plans across different contexts.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"SHARED-SPACE"
]
},
"required": true,
"name": "contextType",
"in": "query",
"description": "Specifies the type of context to filter Mutal Action Plans (MAPs) by. Currently, only Shared Space contexts are supported."
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "contextId",
"in": "query",
"description": "Optional filter to return only Mutual Action Plans (MAPs) associated with a specific context. When provided, only MAPs linked to this context ID are included in the response."
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the list of Mutual Action Plans (MAPs) accessible to the user based on context permissions.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"description": "A list of Mutual Action Plans (MAPs) matching the request criteria.",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"context",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
"context": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"SHARED-SPACE"
]
},
"id": {
"type": "string",
"description": "The unique identifier of the associated context."
},
"title": {
"type": "string",
"description": "The title of the associated Shared Space."
}
},
"required": [
"type",
"id",
"title"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"SHARED-SPACE-TEMPLATE"
]
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
]
}
],
"description": "The context to which the Mutual Action Plan is associated."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the Mutual Action Plan (MAP) was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the Mutual Action Plan (MAP) was last updated."
}
}
}
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}": {
"delete": {
"operationId": "deleteMap",
"summary": "Delete MAP",
"description": "Permanently delete a Mutual Action Plan (MAP) by its unique identifier. Once deleted, the MAP and all associated data, including milestones and actions, are permanently removed and cannot be recovered.\n\nUse this endpoint when you need to:\n- Remove a MAP that is no longer needed\n- Clean up MAPs associated with a specific context\n- Programmatically manage MAP lifecycle as part of a workflow or integration\n\nThis action is irreversible. Ensure the correct MAP identifier is provided before proceeding.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"responses": {
"204": {
"description": "The MAP was successfully deleted and no longer exists in the system. No response body is returned."
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/participants": {
"get": {
"operationId": "getParticipants",
"summary": "Get Participants",
"description": "Retrieve a list of participants associated with a specific Mutual Action Plan (MAP). Participants are the users who have been granted access to collaborate on the MAP.\n\nUse this endpoint when you need to:\n- View all participants associated with a specific MAP\n- Identify collaborators and their roles within a MAP\n- Build interfaces that display MAP membership and participation\n\nOnly participants belonging to the specified MAP are returned. Access is limited based on the authenticated user's permissions.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the list of participants associated with the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"description": "A list of participants associated with the specified Mutual Action Plan (MAP).",
"items": {
"type": "object",
"required": [
"id",
"status",
"userId",
"email",
"avatar",
"firstName",
"lastName"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the participant."
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"INACTIVE"
],
"description": "The current status of the participant within the MAP."
},
"userId": {
"type": "string",
"nullable": true,
"description": "The unique identifier of the user associated with this participant."
},
"email": {
"type": "string",
"description": "The email address of the participant."
},
"avatar": {
"type": "string",
"nullable": true,
"description": "URL of the participant's avatar image."
},
"firstName": {
"type": "string",
"nullable": true,
"description": "The first name of the participant."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "The last name of the participant."
}
}
}
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/participants/self": {
"get": {
"operationId": "getParticipantSelf",
"summary": "Get current participant",
"description": "Retrieve the participant profile of the currently authenticated user within a specific Mutual Action Plan (MAP).\n\nUse this endpoint when you need to:\n- Retrieve your own participant details within a MAP\n- Determine your role and status within a specific MAP\n- Display the current user's participation information in a MAP interface\n\nOnly the participant record associated with the authenticated user is returned. If the user is not a participant of the specified MAP, an error is returned.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the participant profile of the currently authenticated user within the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"status",
"userId",
"email",
"avatar",
"firstName",
"lastName"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the participant."
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"INACTIVE"
],
"description": "The current status of the participant within the MAP."
},
"userId": {
"type": "string",
"nullable": true,
"description": "The unique identifier of the user associated with this participant."
},
"email": {
"type": "string",
"description": "The email address of the participant."
},
"avatar": {
"type": "string",
"nullable": true,
"description": "URL of the participant's avatar image."
},
"firstName": {
"type": "string",
"nullable": true,
"description": "The first name of the participant."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "The last name of the participant."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/participants/self/settings": {
"get": {
"operationId": "getParticipantSettings",
"summary": "Get Participant's Settings",
"description": "Retrieve the notification settings for the currently authenticated user within a specific Mutual Action Plan (MAP).\n\nUse this endpoint when you need to:\n- Retrieve the current user's notification preferences for a specific MAP\n- Display notification settings in a user preferences interface\n- Determine which notifications are enabled for the authenticated participant\n\nOnly the settings belonging to the authenticated user are returned. Settings are specific to the MAP identified by the provided identifier.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"responses": {
"200": {
"description": "OK. The request was successful. Returns the notification settings for the currently authenticated user within the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"assignedActionNotifications",
"completedActionNotifications"
],
"properties": {
"assignedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is assigned to them."
},
"completedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is marked as completed."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
},
"patch": {
"operationId": "updateParticipantSettings",
"summary": "Update Participant's Settings",
"description": "Update the notification settings for the currently authenticated user within a specific Mutual Action Plan (MAP).\n\nUse this endpoint when you need to:\n- Enable or disable notifications for actions assigned to the current user\n- Enable or disable notifications for actions marked as completed\n- Programmatically manage notification preferences as part of a workflow or integration\n\nOnly the settings belonging to the authenticated user can be updated. At least one setting must be provided in the request body.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"assignedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is assigned to them."
},
"completedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is marked as completed."
}
},
"minProperties": 1
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated notification settings for the currently authenticated user within the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"assignedActionNotifications",
"completedActionNotifications"
],
"properties": {
"assignedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is assigned to them."
},
"completedActionNotifications": {
"type": "boolean",
"description": "Indicates whether the participant receives notifications when an action is marked as completed."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones": {
"post": {
"operationId": "postMilestone",
"summary": "Create Milestone",
"description": "Create a new milestone within a specific Mutual Action Plan (MAP). Milestones help structure the MAP by grouping related actions under a shared goal or phase.\n\nUse this endpoint when you need to:\n- Add a new milestone to an existing MAP\n- Structure collaboration by defining phases or goals within a MAP\n- Programmatically manage milestone creation as part of a workflow or integration\n\nThe milestone is created within the MAP identified by the provided identifier. The new milestone is returned in the response upon successful creation.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The title of the milestone. Must be between 1 and 50 characters."
}
},
"required": [
"title"
]
}
}
}
},
"responses": {
"201": {
"description": "Milestone created successfully. The response returns the newly created milestone within the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the milestone."
},
"title": {
"type": "string",
"description": "The title of the milestone."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the milestone was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the milestone was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones/{milestoneId}": {
"delete": {
"operationId": "deleteMilestone",
"summary": "Delete Milestone",
"description": "Permanently delete a milestone from a specific Mutual Action Plan (MAP) by its unique identifier. Once deleted, the milestone and all of its associated actions are permanently removed and cannot be recovered.\n\nUse this endpoint when you need to:\n- Remove a milestone that is no longer relevant to the MAP\n- Clean up milestones and their associated actions within a MAP\n- Programmatically manage milestone lifecycle as part of a workflow or integration\n\nThis action is irreversible. Ensure the correct milestone identifier is provided before proceeding.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
}
],
"responses": {
"204": {
"description": "The milestone was successfully deleted and no longer exists in the system. No response body is returned."
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
},
"patch": {
"operationId": "updateMilestone",
"summary": "Update Milestone",
"description": "Update an existing milestone within a specific Mutual Action Plan (MAP). Use this endpoint to modify the title or position of a milestone to reflect changes in the collaboration structure.\n\nUse this endpoint when you need to:\n- Update the title of an existing milestone\n- Reorder milestones within a MAP\n- Programmatically manage milestone updates as part of a workflow or integration\n\nAt least one field must be provided in the request body. The updated milestone is returned in the response upon successful update.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The title of the milestone. Must be between 1 and 50 characters."
},
"position": {
"type": "number",
"description": "The position of the milestone within the MAP. When updated, all existing milestones with a position greater than or equal to the new position will be shifted down by one."
}
},
"minProperties": 1
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. Returns the updated milestone within the specified MAP.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the milestone."
},
"title": {
"type": "string",
"description": "The title of the milestone."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the milestone was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the milestone was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones/{milestoneId}/actions": {
"post": {
"operationId": "postAction",
"summary": "Create Action",
"description": "Create a new action within a specific milestone of a Mutual Action Plan (MAP). Actions represent individual tasks or steps that need to be completed as part of a milestone.\n\nUse this endpoint when you need to:\n- Add a new action to an existing milestone\n- Define tasks or steps that contribute to a milestone's goal\n- Programmatically manage action creation as part of a workflow or integration\n\nThe action is created within the milestone identified by the provided identifier. The new action is returned in the response upon successful creation.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The title of the action. Must be between 1 and the maximum allowed characters."
},
"dueAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The due date and time of the action. Can be null or omitted if no due date is set."
}
},
"required": [
"title"
]
}
}
}
},
"responses": {
"201": {
"description": "Action created successfully. The response returns the newly created action within the specified milestone.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"dueAt",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the action."
},
"title": {
"type": "string",
"description": "The title of the action."
},
"dueAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The due date and time of the action. Can be null if no due date is set."
},
"status": {
"type": "string",
"enum": [
"COMPLETED",
"NOT_COMPLETED"
],
"description": "The current status of the action."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the action was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the action was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones/{milestoneId}/actions/{actionId}": {
"delete": {
"operationId": "deleteAction",
"summary": "Delete Action",
"description": "Permanently delete an action from a specific milestone within a Mutual Action Plan (MAP) by its unique identifier. Once deleted, the action and all of its associated assignees are permanently removed and cannot be recovered.\n\nUse this endpoint when you need to:\n- Remove an action that is no longer relevant to the milestone\n- Clean up actions and their associated assignees within a milestone\n- Programmatically manage action lifecycle as part of a workflow or integration\n\nThis action is irreversible. Ensure the correct action identifier is provided before proceeding.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "actionId",
"in": "path",
"description": "Unique identifier of the action."
}
],
"responses": {
"204": {
"description": "The action was successfully deleted and no longer exists in the system. No response body is returned."
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
},
"patch": {
"operationId": "updateAction",
"summary": "Update Action",
"description": "Update an existing action within a specific milestone in a Mutual Action Plan (MAP). Use this endpoint to modify the title, due date, or status of an action to reflect changes in the collaboration structure.\n\nUse this endpoint when you need to:\n- Update the title of an existing action\n- Set or change the due date of an action\n- Update the status of an action to reflect its current progress\n- Programmatically manage action updates as part of a workflow or integration\n\nAt least one field must be provided in the request body. The updated action is returned in the response upon successful update.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "actionId",
"in": "path",
"description": "Unique identifier of the action."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "The title of the action. Must be between 1 and the maximum allowed characters."
},
"dueAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The due date and time of the action. Can be null or omitted if no due date is set."
},
"status": {
"type": "string",
"enum": [
"COMPLETED",
"NOT_COMPLETED"
]
},
"milestoneId": {
"type": "string"
},
"position": {
"type": "number",
"description": "The position of the action within the milestone. When updated, all existing actions with a position greater than or equal to the new position will be shifted down by one."
}
},
"minProperties": 1
}
}
}
},
"responses": {
"200": {
"description": "OK. The request was successful. The response returns the updated action.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"title",
"dueAt",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the action."
},
"title": {
"type": "string",
"description": "The title of the action."
},
"dueAt": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "The due date and time of the action. Can be null if no due date is set."
},
"status": {
"type": "string",
"enum": [
"COMPLETED",
"NOT_COMPLETED"
],
"description": "The current status of the action."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the action was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the action was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones/{milestoneId}/actions/{actionId}/assignees": {
"post": {
"operationId": "postAssignee",
"summary": "Create Assignee",
"description": "Assign a participant to a specific action within a milestone in a Mutual Action Plan (MAP). Once assigned, the participant will be associated with the action and can be notified of updates.\n\nUse this endpoint when you need to:\n- Assign a participant to an action to indicate ownership or responsibility\n- Programmatically manage action assignments as part of a workflow or integration\n\nThe created assignee is returned in the response upon successful creation.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "actionId",
"in": "path",
"description": "Unique identifier of the action."
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"participantId": {
"type": "string",
"description": "The unique identifier of the participant to assign to the action."
}
},
"required": [
"participantId"
]
}
}
}
},
"responses": {
"201": {
"description": "Assignee created successfully. The response returns the newly created assignee within the specified action.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"participantId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the assignee."
},
"participantId": {
"type": "string",
"description": "Unique identifier of the participant assigned to the action."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the assignee was created."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the assignee was last updated."
}
}
}
}
}
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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"
}
}
}
}
}
}
}
}
},
"/mutual-action-plan/{mutualActionPlanId}/milestones/{milestoneId}/actions/{actionId}/assignees/{assigneeId}": {
"delete": {
"operationId": "deleteAssignee",
"summary": "Delete Assignee",
"description": "Permanently remove an assignee from a specific action within a milestone in a Mutual Action Plan (MAP). Once removed, the participant will no longer be associated with the action.\n\nUse this endpoint when you need to:\n- Remove a participant from an action when they are no longer responsible for it\n- Programmatically manage action assignments as part of a workflow or integration\n\nThis action is irreversible. Ensure the correct assignee identifier is provided before proceeding.",
"tags": [
"mutual-action-plan"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "mapId",
"in": "path",
"description": "Unique identifier of the Mutual Action Plan (MAP)."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "milestoneId",
"in": "path",
"description": "Unique identifier of the milestone."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "actionId",
"in": "path",
"description": "Unique identifier of the action."
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "assigneeId",
"in": "path",
"description": "Unique identifier of the assignee."
}
],
"responses": {
"204": {
"description": "The assignee was successfully deleted and no longer exists in the system. No response body is returned."
},
"default": {
"description": "An error occurred while processing the request. The response provides structured error details to help identify and resolve the issue.",
"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": {
"schemas": {
"Count": {
"description": "Total number of results.",
"type": "integer",
"format": "int32",
"example": 1
},
"User": {
"allOf": [
{
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "UserId",
"description": "Unique identifier for the object.",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
}
}
},
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The email address of the user.",
"format": "email",
"example": "bob.smith@example.com"
},
"firstName": {
"type": "string",
"example": "Bob",
"description": "The first name of the user."
},
"lastName": {
"type": "string",
"example": "Smith",
"description": "The last name of the user."
}
}
}
]
},
{
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was created. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T00:00:00Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was last updated. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T08:00:00Z"
}
}
}
]
},
"UserId": {
"type": "string",
"title": "UserId",
"description": "Unique identifier for the object.",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was created. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T00:00:00Z"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was last updated. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T08:00:00Z"
},
"TimestampProperties": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was created. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T00:00:00Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time at which the object was last updated. Serialized in the `ISO-8601` string format (UTC timezone).\n",
"example": "2021-01-01T08:00:00Z"
}
}
},
"Problem": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
},
"ProblemMeta": {
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
},
"BadRequest": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
},
"Unauthorized": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
},
"Forbidden": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
},
"NotFound": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
},
"Conflict": {
"type": "object",
"allOf": [
{
"required": [
"title",
"detail",
"status"
]
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non-technical stakeholders and\nnot localized).\n",
"example": "Invalid Payload"
},
"detail": {
"type": "string",
"description": "A human readable explanation specific to this occurrence of the problem.\n",
"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\nof the problem.\n",
"minimum": 400,
"maximum": 599,
"example": 400
}
}
},
{
"type": "object",
"properties": {
"meta": {
"type": "array",
"nullable": true,
"description": "Additional information to support the error.",
"items": {
"anyOf": [
{
"type": "object",
"description": "Additional payload to support the encountered error.",
"required": [
"name",
"reason",
"category"
],
"properties": {
"name": {
"type": "string",
"example": "color",
"description": "The name of the affected resource attribute."
},
"reason": {
"type": "string",
"example": "must be 'green', 'red' or 'blue'",
"description": "The explanation of the problem."
},
"category": {
"type": "string",
"example": "propertyRequired",
"description": "The error category."
}
}
}
]
}
}
}
}
]
}
},
"parameters": {
"assetIdPathParam": {
"name": "assetId",
"in": "path",
"required": true,
"description": "The asset ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
},
"divisionIdPathParam": {
"name": "divisionId",
"in": "path",
"required": true,
"description": "The division ID.",
"schema": {
"type": "string",
"example": "f541710283954a89bdfd40f221882451"
}
},
"fileIdPathParam": {
"name": "fileId",
"in": "path",
"required": true,
"description": "The File ID.",
"schema": {
"type": "string",
"example": "1b513fa042db4c95b673721527852cbb"
}
},
"tagIdPathParam": {
"name": "tagId",
"in": "path",
"required": true,
"description": "The tag ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
},
"tagCategoryIdPathParam": {
"name": "tagCategoryId",
"in": "path",
"required": true,
"description": "The tag category ID.",
"schema": {
"type": "string",
"example": "ab4756bbdeytifj334tppqef"
}
},
"divisionIdsQueryParam": {
"name": "divisionIds",
"in": "query",
"description": "One or multiple division IDs to filter on.",
"explode": false,
"style": "form",
"example": [
"division-id-1",
"division-id-2"
],
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"limitQueryParam": {
"name": "limit",
"in": "query",
"description": "A limit on the number of objects to be returned, between `0` and `1000`.",
"schema": {
"type": "integer",
"format": "int32",
"default": 50,
"minimum": 0,
"maximum": 1000
}
},
"offsetQueryParam": {
"name": "offset",
"in": "query",
"description": "Offset of the returned result, to be used in combination with `limit`.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 0,
"minimum": 0
}
},
"userIdPathParam": {
"name": "userId",
"in": "path",
"required": true,
"description": "The user ID.",
"schema": {
"type": "string",
"example": "c143c05d12c1433ba1358c7eb2e07c75"
}
},
"nameQueryParam": {
"name": "name",
"in": "query",
"description": "Full or partial name to filter on.",
"schema": {
"type": "string",
"example": "customer"
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "This is the Bearer token to identify the current requesting user.\nPlease check out this [page](https://docs.api.showpad.com/docs/apis/concepts/authentication) for a more\nin-depth explanation on Showpad authentication.\n"
}
},
"examples": {
"UnauthorizedExample": {
"value": {
"title": "Unauthorized",
"detail": "Authorization is either invalid or expired.",
"status": 401
}
},
"ForbiddenExample": {
"value": {
"title": "Forbidden",
"detail": "Server refuses to authorize the request.",
"status": 403
}
},
"NotFoundExample": {
"value": {
"title": "Missing Resource",
"detail": "The requested resource does not exist.",
"status": 404
}
},
"ConflictExample": {
"value": {
"title": "Conflict",
"detail": "Request conflicts current state of the target resource.",
"status": 409
}
}
}
}
}