<aside> đź’ˇ See Quickstart: How to build a Plugin for a guide on how to use the Playbook Plugin API.

</aside>

API_Requests.png

Invoke

This is a request to your invocation URL when someone uses your plugin.

POST plugin-invocation-url

Request Body

Name Type Description
pluginInvocationToken String - required Unique identifier of transaction
callbackUrl String - required Url to call for the createAssets / setStatus API
operation String - required Value “invokePlugin”
assets Array of Invoke Asset Objects Array of assets to process

Invoke Asset Object

Name Type Description
token String Unique identifier of asset
url String Signed url to download asset content
title String Title of asset
type String File type - usually an extension but can be special playbook type
Examples: .jpg, .png, .tif, note
thumbnails Array of Thumbnail Objects Array of thumbnails that can be used for easier image processing. Includes 2000, 1000, 500 px wide images

Thumbnail Objects

Name Type Description
url String Signed url to download thumbnail content
width Number Width of thumbnail
height Number Height of thumbnail
type String File type - extension
Examples: .jpg, .png,

Response

200 OK

{
  "pluginInvocationToken": "PAMwF9P8hxrCGvJJbUPU4zuj", 
  "callbackUrl": "<https://be.playbook.com/plugins/v1/GXE3rNvUQM1DhDhxdpQekXqX>", 
  "operation": "invokePlugin",
  "assets": [
    {
      "token": "XNyx47LXJF4atgi9AYu3ceAy",
      "url": "<https://storage.googleapis.com/>...", 
      "title": "Fancy Picture of a Cat",
      "type": ".jpg",
	    "thumbnails": [
        {
          "url": "<https://img.playbook.com/>...",
          "width": 2000,
          "height": 4000,
          "type": ".jpg"
        },
        {
          "url": "<https://img.playbook.com/>...",
          "width": 1000,
          "height": 2000,
          "type": ".jpg"
        }
        ...
      ] 
    }
  ]
}

Create Placeholder Asset

If your plugin processes and generates a new asset to put back into Playbook, this API requests the creation of a new asset for you to upload.

POST callbackUrl from Invocation Request

Request Body

Name Type Description
pluginInvocationToken String - required Unique identifier of transaction - must be the same as what was given from the Invoke request.
operation String - required value “createAssets”.
assets Array of Asset Request Objects Array of asset placeholders to be created.

Asset Request Object

Name Type Description
title String - required Title of the new placeholder asset.
mediaType String - optional The MIME type of the new asset, e.g. image/png, image/gif, image/jpeg.
group String - optional If left blank, the placeholder assets will be grouped with the input assets when possible.

To force grouping with a specific asset, plug in the asset token from the Invoke Asset Object.

Lastly, the special value new will force the creation of a new group, and none will avoid grouping entirely. | | type | String - optional | Only necessary for special Playbook types (e.g. specify note to create Note Assets). | | value | String - optional | If you want to create Note Assets, specify type note, and then value represents the content of the Playbook Note Asset. |

Response Body

201 created

Name Type Description
pluginInvocationToken String - required Matches the token from the request
operation String - required value “createAssets”
assets Array of Asset Response Objects Contains the token of the newly created placeholder asset and the uploadUrl to upload new asset to

Asset Response Object

Name Type Description
token String - required Unique token of the newly created asset
uploadUrl String - required signed url to PUT the file content 
**POST** <https://be.playbook.com/plugins/v1/GXE3rNvUQM1DhDhxdpQekXqX>

{
  "pluginInvocationToken": "PAMwF9P8hxrCGvJJbUPU4zuj",
  "operation": "createAssets",
	"assets": [
    {
      "title": "Fancy Picture of a Cat -- no background",
			"group": "XNyx47LXJF4atgi9AYu3ceAy",
			"mediaType": "image/png"
    }
  ]
}

{
  "pluginInvocationToken": "PAMwF9P8hxrCGvJJbUPU4zuj",
  "operation": "createAssets",
  "assets": [
    {
      "token": "PAMwF9P8hxrCGvJJbUPU4zuj",
      "uploadUrl": "<https://storage.googleapis.com/>..."
    }
  ]
}

<aside> 📌 When uploading to the uploadUrl, do a “PUT” request with the headers having the correct “Content-Type” e.g.: “Content-Type”: “image/png”

</aside>

Response

200 OK