# Introduction

The Percolate API is RESTful in nature. Our APIs use HTTP resource-oriented URLs. HTTP methods are used to issue requests. HTTP response codes are used to indicate API successes or failures. All API requests and responses are in JSON representation. This document describes the HTTP resources and methods that form the Percolate API.

# Authentication

Percolate enables third party applications to authenticate REST API requests utilizing the OAuth 2.0 authorization code grant type per RFC 6749. Because the Percolate API requires requests to be made on behalf of a specific user, the client credentials grant type is NOT supported at this time.

Note: OAuth2 credentials are associated with Percolate Accounts, which own your Brand(s) and License(s). It is not possible to associate the credentials with a Brand or a License.

Registering a client application

Only a system admin or an integration client manager can register a new client application. Additionally, this user must have two-factor authentication enabled in Percolate. Click here to enable two-factor authentication.

The system admin or manager can click here to register a new client application.

Once a new application is registered, we will provide you with a Client ID and a Client Secret. The Client ID will be displayed at the top of the screen, underneath the name of your application. To see the Client Secret, click the "Show Secret" button, and enter your two-factor authentication code. You will then be shown the Client Secret.

If you need to reset the Client Secret, you can do so by selecting the "Reset Secret" button and entering your two-factor authentication code.

The Client Secret is a private value for your application only, and it MUST NOT be shared with anyone.

Obtaining a User Access Token

1. Redirect the User

To obtain an authorization code, the user’s browser must be redirected to Percolate’s authorization endpoint. Once redirected, the user will be presented with the Percolate login form, requesting that authorization be granted to your application to access their account.

GET https://percolate.com/auth/oauth2?response_type=code&client_id={client_id}&state={state}
  • response_type: Value MUST be "code"
  • client_id: Your application client ID
  • state: An opaque value that will be included when the authorization server redirects the user-agent to your applications redirect URL. This should be used for cross-site request forgery protection (Note: this is not required per the OAuth2 spec, but is required by Percolate)
Authorization Response:

Once a user has been authenticated and granted access to your application, the user’s browser will be redirected to your client redirect URL with the following query parameters:

  • code: The OAuth 2.0 authorization code. Valid for 300 seconds from time of issuance
  • state: The original, unaltered value included in the original redirect

As described in the next section, code is the value that will be exchanged for an OAuth 2.0 access token and is valid for three hundred (300) seconds.

2. Request an Access Token

Once your application receives the authorization code on your redirect endpoint, an access token request should be made to Percolate’s token endpoint (with said code).

Request/refresh a token

Pending Breaking Change - Token API

authorized_tenant_id will be added to the token API response. This will identify the tenant whose data the access token allows to be accessed. This ID will be derived from the user's choice of which tenant's data your integration may access.

Until this parameter is added to the response of the token API, you may assume that the authorized_tenant_id is the ID of the tenant that owns the OAuth2 client.

This means that, when using OAuth2, you may only access your own Percolate tenant's data. We are working to implement the feature whereby a user can choose to allow your integration to access other tenant's data. When that work is completed, you may receive a token API response that identifies a tenant other than your own. You may then use the returned access token to access other tenant's data on that user's behalf.

Once these updates are put into effect, existing access tokens may be invalidated, requiring users to re-authorize existing client apps.

Making an Authenticated Request

The access token issued by Percolate, a bearer token type as defined in RFC 6750, can be used to make authenticated API requests on behalf of the corresponding user. To do so, include the Authorization request header with the value found in your access token's access_token property. For example:

Authorization: Bearer pBkgJV_cEVKESx4SH7wm-kYdfVgnyhDGCdqoRtygQE7

If an access token has become invalid, API requests will receive a "401 Unauthorized" response. A token maybe become invalid for the following reasons:

  • The expires_at date/time has exceeded
  • The user has revoked the grant
  • A new access token has been issued for this user, invalidating the existing one

Note: As stated above, a token may only be used to access data from the tenant identified in the authorized_tenant_id of the token API response. Until we have implemented that change, you may assume that the authorized_tenant_id is the ID of the tenant that owns the OAuth2 configuration.

Refreshing an Access Token

The token api may be used to refresh an access token that meets all of the following conditions:

  1. The access token has not been disabled (which may happen either deliberately by the user, or by some internal system event).
  2. The access token is either not expired or has not been expired for more than 14 days.

In other words, if the access token has not been deliberately disabled by the user, the refresh token may be used up to 14 days after the access token expires.

If the token does not meet those conditions, the user must repeat the 3-legged OAuth2 flow to grant your application permission to retrieve an access token.

# Responses

The Percolate APIs use conventional HTTP response codes to indicate success or failure. The table below lists these conventions as followed by our API.

Response Description
200 Success - Worked as expected.
201 Success - New resource was created.
401 Bad or expired access_token.
403 Target resource was not found. Either because it does not exist or because the access token and scope do not provide permission for the target resource and method.
409 Resource conflict.
429 The API client has exceeded it's rate limiting quota.
5xx Errors have occurred within the Percolate server infrastructure.

The body of 4xx error responses is formatted as follows:

The value of the key parameter indicates the which input data triggered the error. A value of null for this parameter indicates errors that aren't specific to one input field. Depending on the API endpoint, there may be additional attributes on the error object that provides more context for the error.

# Pagination

The Percolate API supports pagination of batch GET. To enable pagination use the limit and offset query parameters, where offset refers to item offset, not page offset.

# Batching

Percolate APIs support a batch GET of objects through an ids parameter. As an example, a single GET operation can be issued to retrieve the three separate post objects as follows.

# References

API request and response objects related to one resource reference other objects through IDs. As an example, the response from a GET method request to the /v5/platform/ endpoint returns the following example response object.

In this object the ID field contains a reference to a specific platform object with an ID value of platform:594227513073503629. This value can be used in a call to the /platform/{platform_id} endpoint in order to retrieve the detailed information for a specific API with the following curl command.

# Download

Percolate API is generated from RAML (Restful APIs Markup Language), a human and machine readable API definition enabling the creation of automated and reusable ecosystems of tools. The Percolate API RAML definition will help you automate your work interacting with Percolate API, importing it into testing tools (like Postman or Paw) or monitoring tools (like SoapUI, Runscope or APIscience) and work efficiently with the large ecosystem or RAML plugins. Download the Percolate RAML file here.

# Access Token

# Request/refresh a token

POST https://percolate.com/auth/v5/token/

The access token request must be authenticated utilizing the "HTTP Basic authentication scheme" as defined in RFC 2617. This endpoint supports both standard submission using application/x-www-form-urlencoded and application/json for convenience.

Your Client ID and Client Secret must be joined by ":", then Base64 encoded, and included in the Authorization request header (ex. base64("{client_id}:{client_secret}")).

For example, for a Client ID "einstein" and Secret "itsallrelative", the following header would be expected:

Authorization: Basic ZWluc3RlaW46aXRzYWxscmVsYXRpdmU
Request
Response

Body

Post data to create a new access token

example:show
Properties:
  • # code

    The authorization code received from Percolate.

  • # grant_type

    Grant type must be authorization_code

# Asset

# Get a list of assets

GET https://percolate.com/api/v5/asset/

Get a list of assets

Request
Response

Query Parameters

  • # created_at:from
    date

    Filter by created_at date (inclusive)

  • # created_at:to
    date

    Filter by created_at date (exclusive)

  • # order_by
    string

    Order by the specified attribute

    Pattern: created_at|filename|title|modified_at|size
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # metadata.{schemaFieldId}
    string

    Filter by a metadata field using a dynamic query parameter name. The {schemaFieldId} template represents the schema id and field name concatenated together by a dot (.). In effect, it expands to the sub-template {schema-id}.{schema-field-name}. The {schema-id} template is the UID of a schema. The {schema-field-name} template is a path separated by the forward slash (/) (to allow for representation of nested objects). Valid metadata query parameters could look like:

    • metadata.schema:1.live_date_range
    • metadata.schema:1.live_date_range/from
    • metadata.schema:1.live_date_range/from.from

    The value of the query parameter is a CSV of strings appropriate for the given metadata field.

  • # has_metadata.{schemaFieldId}
    boolean

    Filter by the existence of a metadata field. See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # metadata.{schemaFieldId}.from
    date

    Filter by a metadata date field (inclusive). See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # metadata.{schemaFieldId}.to
    date

    Filter by a metadata date field (exclusive). See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # keywords
    string

    Filter objects by CSV of keywords

  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^asset:\d[\d_-]*$
  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # types
    string

    Filter by CSV of asset types

    Pattern: ^image|audio|video|artwork|pdf|document|presentation|spreadsheet$
  • # include
    string

    Includes related items in the response. creator_id and folder_id are valid parameters.

  • # content_types
    string

    Filter assets by CSV of content types

    Pattern: ^\w+\/[-.A-Za-z0-9_]+(?:\+[\w]+)?$
  • # creator_ids
    string

    Filter by CSV of creating user

    Pattern: ^user:\d+$
  • # orientation
    string

    Filter by CSV of orientations

    Pattern: ^square|landscape|portrait$
  • # size
    string

    Filter by CSV of sizes

    Pattern: ^small|medium|large|extra_large$
  • # folder_id
    string

    Filter by containing folder. The root folder (folder:primary) is assumed if no value is given. All query paramters apply to only the contents of a single folder unless the recursive parameter is also used.

    Use the value folder:trashcan to apply query parameters to deleted assets. Use folder:shared to apply query parameters to shared assets.

  • # recursive
    boolean

    Perform a deep search if presented with the value true. Combine with the folder_id query parmeter to perform a deep search from a specific folder.

    The default is to search only the contents of the folder specified with the folder_id parameter or otherwise the root folder.

# Copy an asset.

POST https://percolate.com/api/v5/asset/

A new asset will be created that duplicates the referenced source asset. All basic metadata (e.g. name) will be copied but comments, followers, etc. will not be replicated.

Request
Response

Body

Properties:

# Fetch a single asset.

GET https://percolate.com/api/v5/asset/{asset_id}

Get a single asset

Request
Response

URI Parameters

  • # asset_id
    string
    Required
    Pattern: ^asset:[a-zA-Z0-9_-]+$

Query Parameters

  • # include
    string

    Includes related items in the response. creator_id and folder_id are valid parameters.

# Move, rename, or restore an asset, or rollback to a previous verison.

PUT https://percolate.com/api/v5/asset/{asset_id}

Only one of the request body parameters may be given at a time.

Request
Response

Body

Properties:
  • # context_id

    The post ID

    example:show
  • # deleted

    Send the value as 'false' for a deleted asset to restore it to its original location in the asset library.

  • # filename

    The filename of the asset

    example:show
  • # folder_id

    The folder ID

URI Parameters

  • # asset_id
    string
    Required
    Pattern: ^asset:[a-zA-Z0-9_-]+$

# Delete an asset.

DELETE https://percolate.com/api/v5/asset/{asset_id}

Delete a asset

Request
Response

URI Parameters

  • # asset_id
    string
    Required
    Pattern: ^asset:[a-zA-Z0-9_-]+$

# Download an asset

GET https://percolate.com/api/v5/asset/{asset_id}/download
Request
Response

Query Parameters

  • # disposition
    string

    Set the value the server will use for the Content-Disposition header (RFC 2616 Sec 19.5.1) of the response. The asset's content type and filename will also be included in this header. The default value is attachment.

    Allowed values: [attachment, inline]

# Channels

# Get channel objects

GET https://percolate.com/api/v5/channel/

Get a list of channels

Request
Response

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: platform_id
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^channel:\d+$
  • # has_capabilities
    boolean

    Filter channels with or without capabilities. Do not combine with capabilities.

  • # capabilities
    string

    A CSV of channel.capabilities to filter by, eg. ?capabilities=monitoring,posting. Do not combine with has_capabilities.

    Allowed values: [inbox, ingestion, monitoring, posting, publishing, publishing_queue, targeting]
  • # types
    string

    A CSV of channel.type to filter by

    Allowed values: [bitly, custom, eloqua, facebook, facebook_ads, gplus, instagram, linkedin.company_page, linkedin.group, linkedin.*, pinterest, public, rss, tumblr, twitter, twitter_ads, vimeo, weibo, youtube]
  • # xids
    string

    A CSV of external ID to filter by

  • # platform_ids
    string

    A CSV of platform_ids to filter by

    Pattern: ^(platform:\d+,?)+$
  • # active
    boolean

    Filter by active or inactive channels

# Create a channel

POST https://percolate.com/api/v5/channel/

Create a channel

Request
Response

Body

Properties:
  • # name

    The display name of this channel

  • # platform_id

    The platform ID

  • # scope_id

    A license ID

    example:show
  • # term_ids

    An array of term IDs

    Array items:

    The term ID

  • # type

    The channel type, e.g. facebook, twitter, linkedin.company_page

  • The external channel identifier (e.g. Facebook Page ID - 78287873929)

# Get a channel

GET https://percolate.com/api/v5/channel/{channel_id}

Get a single channel

Request
Response

URI Parameters

  • # channel_id
    string
    Required
    Pattern: ^channel:[a-zA-Z0-9_-]+$

# Update a channel

PUT https://percolate.com/api/v5/channel/{channel_id}

Update a channel

Request
Response

Body

Properties:
  • # active

    The flag indicating if channel is active

  • # name

    The display name of this channel

  • # platform_id

    The platform ID

  • # scope_id

    A license ID

    example:show
  • # term_ids

    An array of term IDs

    Array items:

    The term ID

  • # type

    The channel type, e.g. facebook, twitter, linkedin.company_page

  • The external channel identifier (e.g. Facebook Page ID - 78287873929)

URI Parameters

  • # channel_id
    string
    Required
    Pattern: ^channel:[a-zA-Z0-9_-]+$

# Comments

# Fetch comments

GET https://percolate.com/api/v5/comment/

Retrieve a list of comments. Required values: either of (ids | object_ids). Optional values: context_type, start_at & end_at.

Request
Response

Query Parameters

  • # order_by
    string

    Order by the specified attribute

    Pattern: created_at|updated_at
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # include
    string

    Includes related items in the response

    Pattern: user_id|object_id|parent_comment_id
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^comment:[a-zA-Z\d]+$
  • # object_ids
    string

    A CSV of object IDs to filter by

    Pattern: ^(folder|media|asset|channel|post|brief|campaign|post_set|market_request|market_response|monitoring_flag|task|link|comment|intake_request):\d+$
  • # context_type
    string

    Filter comments by context type

  • # start_at
    date

    Filter comments with start_at on or after date

  • # end_at
    date

    Filter comments with end_at on or before date

# Create a comment

POST https://percolate.com/api/v5/comment/

Create a comment

Request
Response

Body

Properties:

# Get a comment

GET https://percolate.com/api/v5/comment/{comment_id}

Get a single comment

Request
Response

URI Parameters

  • # comment_id
    string
    Required
    Pattern: ^comment:[a-zA-Z0-9_-]+$

Query Parameters

  • # context_type
    string

    Returns only the comments with a given context type

    Allowed values: [coordinate]

# Edit a comment

PUT https://percolate.com/api/v5/comment/{comment_id}

Update a comment

Request
Response

Body

Properties:

URI Parameters

  • # comment_id
    string
    Required
    Pattern: ^comment:[a-zA-Z0-9_-]+$

# Delete a comment

DELETE https://percolate.com/api/v5/comment/{comment_id}

Delete a comment

Request
Response

URI Parameters

  • # comment_id
    string
    Required
    Pattern: ^comment:[a-zA-Z0-9_-]+$

# Exports

A way to export data about Percolate resources.

The export object are dynamic in nature and defined by the following:

  • the type of report that you're creating
  • a CSV of field you'd like returned in the report

Different export types support different fields. Below you'll find a list of all possible types and their fields

export types field field label field type
activity platform Platform string
activity post_body Post Body string
activity post_permalink Post Permalink string
activity post_type Post Type string
activity posted_by Posted By string
activity stream_name Stream Name string
activity tags Tags string
activity uid Unique Id string
approval approval_workflow_completed_at Workflow Completed At date
approval approval_workflow_created_at Workflow Created At date
approval approval_workflow_name Workflow Name string
approval asset_name Asset Name string
approval asset_type Asset Type string
approval campaign_name Campaign string
approval channel Channel string
approval creative_type Creative Type string
approval facebook_dark_post Facebook Dark Post string
approval facebook_targeting Facebook Targeting string
approval feedback Feedback string
approval feedback_created_at Feedback Left At date
approval feedback_left_by Feedback Left By string
approval feedback_user_email Feedback User Email string
approval feedback_user_role Feedback User Role string
approval license_id License ID string
approval license_name License string
approval paid Paid string
approval platform Platform string
approval post_created_at Post Created At date
approval post_created_by Post Created By string
approval post_permalink Post Permalink string
approval status Status string
approval tags Tags string
approval topics Topics string
approval twitter_targeting Twitter Targeting string
approval uid Unique Id string
asset created_at Created At date
asset created_by Created By string
asset description Description string
asset edited_image Edited string
asset filename Filename string
asset ingested_from Ingested From string
asset media_subtype Media Subtype string
asset media_type Media Type string
asset tags Tags string
asset title Title string
asset post_ids Post Ids string
asset uid Unique Id string
campaign asset_count Number of Assets int
campaign budget Budget string
campaign created_at Created At date
campaign created_by Created By string
campaign creative_count Number of Createtives int
campaign description Description string
campaign end_date End Date date
campaign license_id License ID string
campaign license_name License Name string
campaign marketplace_request_count Number of Marketplace Requests int
campaign platforms Platforms string
campaign section_count Number of Sections int
campaign start_date Start Date date
campaign title Title string
campaign topics Topics string
campaign workspace_count Number of Workspaces int
campaign uid Unique Id string
flag assigned_to Assigned To string
flag channel_name Channel Name string
flag created_at Created At date
flag created_by Created By string
flag description Description string
flag platform Platform string
flag post_body Post Body string
flag post_permalink Post Permalink string
flag post_type Post Type string
flag posted_at Posted At date
flag posted_by Posted By string
flag resolve_time Time to Resolve string
flag resolved_at Resolved At date
flag resolved_by Resolved By string
flag status Status string
flag tags Tags string
flag topics Topics string
flag urgent Urgent string
flag uid Unique Id string
keyword created_at Created At date
keyword post_body Post Body string
keyword post_permalink Permalink string
keyword post_platform Post Platform string
keyword post_type Type string
keyword posted_by Posted By string
keyword query Raw Query string
keyword stream_name Stream string
keyword uid Unique Id string
post approval_workflow_completed_at Workflow Completed At date
post approval_workflow_created_at Workflow Created At date
post approval_workflow_name Workflow Name string
post approved_at Approved At date
post approved_by Approved By string
post asset_type Asset Type string
post brand_id Brand ID string
post brand_name Brand Name string
post campaign_name Campaign Name string
post channel_name Channel string
post created_at Created At date
post created_by Created By string
post facebook_comments Facebook Comments string
post facebook_consumptions Facebook Consumptions string
post facebook_consumptions_unique Facebook Consumptions Unique string
post facebook_dark_post Dark Post string
post facebook_engaged Facebook Engaged string
post facebook_engagement Facebook Engagement string
post facebook_impressions_fan Facebook Impressions Fan string
post facebook_impressions_fan_unique Facebook Impressions Fan Unique string
post facebook_impressions_organic Facebook Impressions Organic string
post facebook_impressions_organic_unique Facebook Impressions Organic Unique string
post facebook_impressions_paid Facebook Impressions Paid string
post facebook_impressions_paid_unique Facebook Impressions Paid Unique string
post facebook_impressions_viral Facebook Viral string
post facebook_impressions_viral_unique Facebook Viral Unique string
post facebook_likes Facebook Likes string
post facebook_link Facebook URL string
post facebook_negative_feedback Facebook Negative Feedback string
post facebook_negative_feedback_unique Facebook Negative Feedback Unique string
post facebook_reach Facebook Reach string
post facebook_shares Facebook Shares string
post facebook_stories Facebook Stories string
post facebook_storytellers Facebook Storytellers string
post facebook_talking Facebook Talking string
post facebook_targeting Facebook Targeting string
post gplus_link Google+ URL string
post gplus_plusones Google+ +1s string
post gplus_replies Google+ Replies string
post gplus_shares Google+ shares string
post instagram_comments Instagram Comments string
post instagram_link Instagram URL string
post instagram_loves Instagram Loves string
post license_id License ID string
post license_name License Name string
post linkedin_clicks Linkedin Clicks string
post linkedin_comments Linkedin Comments string
post linkedin_engagement Linkedin Engagement string
post linkedin_likes Linkedin Likes string
post linkedin_link Linkedin URL string
post linkedin_reach Linkedin Reach string
post linkedin_shares Linkedin Shares string
post paid_post Paid string
post pinterest_comments Pinterest Comments string
post pinterest_likes Pinterest Likes string
post pinterest_link Pinterest URL string
post pinterest_repins Pinterest Repins string
post platform Platform string
post post_permalink Post Permalink string
post post_type Creative Type string
post posted_at Posted At date
post status Status string
post tags Tags string
post topics Topics string
post tumblr_likes Tumblr Likes string
post tumblr_link Tumblr URL string
post tumblr_reblogs Tumblr Reblogs string
post twitter_favorites Favorites string
post twitter_link Twitter URL string
post twitter_replies Twitter Replies string
post twitter_retweets Retweets string
post twitter_targeting Twitter Targeting string
post weibo_comments Weibo Comments string
post weibo_reposts Weibo Reposts string
post youtube_comments YouTube Comments string
post youtube_dislikes YouTube Dislikes string
post youtube_favorites YouTube Favorites string
post youtube_likes YouTube Likes string
post youtube_views YouTube Views string
post uid Unique Id string
share comment_count Number of Comments int
share created_at Created At date
share created_by Created By string
share license_id License ID string
share license_name License Name string
share object_type Object string
share permalink Permalink string
share sent_to Sent To string
share object_uid Object Unique Id string
share uid Unique Id string
tag created_at Created At date
tag post_body Post Body string
tag post_permalink Permalink string
tag post_platform Post Platform string
tag posted_by Posted By string
tag tag Tag string
tag uid Unique Id string
user created_at Created At date
user email Email string
user name Name string
user role Role string
user status Status string
user username Username string
user last_active Last Active date
user uid Unique Id string

# Preview export data

GET https://percolate.com/api/v5/export/

Get a subset of the data as JSON for preview purposes.

Request
Response

Query Parameters

  • # end_date:from
    date

    Filter by end_date date (inclusive)

  • # end_date:to
    date

    Filter by end_date date (exclusive)

  • # start_date:from
    date

    Filter by start_date date (inclusive)

  • # start_date:to
    date

    Filter by start_date date (exclusive)

  • # resolved_at:from
    date

    Filter by resolved_at date (inclusive)

  • # resolved_at:to
    date

    Filter by resolved_at date (exclusive)

  • # approved_at:from
    date

    Filter by approved_at date (inclusive)

  • # approved_at:to
    date

    Filter by approved_at date (exclusive)

  • # posted_at:from
    date

    Filter by posted_at date (inclusive)

  • # posted_at:to
    date

    Filter by posted_at date (exclusive)

  • # perturbed_at:from
    date

    Filter by perturbed_at date (inclusive)

  • # perturbed_at:to
    date

    Filter by perturbed_at date (exclusive)

  • # last_active:from
    date

    Filter by last_active date (inclusive)

  • # last_active:to
    date

    Filter by last_active date (exclusive)

  • # created_at:from
    date

    Filter by created_at date (inclusive)

  • # created_at:to
    date

    Filter by created_at date (exclusive)

  • # completed_at:from
    date

    Filter by completed_at date (inclusive)

  • # completed_at:to
    date

    Filter by completed_at date (exclusive)

  • # FIELD:from
    date

    Filter by FIELD date (inclusive)

  • # FIELD:to
    date

    Filter by FIELD date (exclusive)

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^export:\d+$
  • # type
    string
    Required

    The type of data to export

    Allowed values: [activity, approval, asset, campaign, flag, keyword, post, share, tag, user, monitoring_item]
  • # fields
    string

    A CSV of fields to export determined by type

  • # limit
    number
    default is 10

    limits the number of exports to preview (maximum of 100)

# Create a export

POST https://percolate.com/api/v5/export/

Requesting the full set triggers an async job that emails a link to download a CSV to the current user

Note: the order of fields is preserved in CSV.

Request
Response

Body

Properties:
  • # fields

    A list of fields to export determined by type

    Array items:
  • # scope_ids

    A license ID

    example:show
  • # type

    The type of data to export

# Folders

# Get a list of Folders

GET https://percolate.com/api/v5/folder/

Get a list of folders

Request
Response

Query Parameters

  • # created_at:from
    date

    Filter by created_at date (inclusive)

  • # created_at:to
    date

    Filter by created_at date (exclusive)

  • # order_by
    string

    Order by the specified attribute

    Pattern: created_at|name
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    Filter by CSV of unique folder IDs. If folder:primary or folder:trashcan are used, scope_ids must also be presented.

    Pattern: ^folder:(primary|trashcan|\d+)$
  • # creator_ids
    string

    Filter by CSV of creating user

    Pattern: ^user:\d+$
  • # parent_ids
    string

    Filter by CSV of containing folders. The root folder (folder:primary) is assumed if no value is given. All query paramters apply to only the contents of a single folder unless the recursive parameter is also used. Use the value folder:trashcan to apply query parameters to deleted assets. Use the value folder:shared to appy query parameters to shared folders.

    Pattern: ^folder:(primary|trashcan|shared|\d+)$
  • # recursive
    boolean

    Perform a deep search if presented with the value true. Combine with the parent_id query parmeter to perform a deep search from a specific folder. The default is to search only the contents of the folder specified with the parent_id parameter or otherwise the root folder.

# Create a Folder

POST https://percolate.com/api/v5/folder/

Create a folder

Request
Response

Body

Properties:
  • # description

    The long description of this folder.

  • # name

    The user defined name of this folder.

  • # parent_id

    The folder ID

# Get a single Folder

GET https://percolate.com/api/v5/folder/{folder_id}

Get a single folder

Request
Response

URI Parameters

  • # folder_id
    string
    Required
    Pattern: ^folder:[a-zA-Z0-9_-]+$

# Update, move, or restore a Folder

PUT https://percolate.com/api/v5/folder/{folder_id}

Update a folder

Request
Response

Body

Properties:
  • # deleted

    Send the value as 'false' for a deleted folder to restore it to its original location in the asset library.

  • # description

    The long description of this folder.

  • # name

    The user defined name of this folder.

  • # parent_id

    The folder ID

  • # updated_at

    An absolute datetime indicating when this resource was last modified

    example:show

URI Parameters

  • # folder_id
    string
    Required
    Pattern: ^folder:[a-zA-Z0-9_-]+$

# Delete a Folder

DELETE https://percolate.com/api/v5/folder/{folder_id}

Delete a folder

Request
Response

URI Parameters

  • # folder_id
    string
    Required
    Pattern: ^folder:[a-zA-Z0-9_-]+$

# Import user roles from uploaded assets in CSV format

# Import user roles from uploaded asset identified by the asset ID.

POST https://percolate.com/api/v5/user_role_import/
Request
Response

Body

Properties:
  • # account_id

    Account UID to use when scope name is given as 'Account'

  • # asset_id

    The asset ID

    example:show

# Media

A new Asset API has been released, please refer to v5/asset for details. These v3/media endpoints are now deprecated and will be retired. We will continue to support calls made to v3/media for a limited time.

Media is defined by three high level types:

  • image: All images
  • folder: A directory-like structure to organize media
  • video: It's called video but it's all other assets types except image (ex. pdf, psd, avi, mpg...)

# Search a list of media

GET https://percolate.com/api/v3/media
Request
Response

Query Parameters

  • # order_by
    string

    Order by the specified attribute

    Pattern: creation_date|added_at|created_at|name|title
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # approval_workflow
    string
    Allowed values: [incomplete]
  • # approval_workflow_participant_user_ids
    string
    Pattern: ^user:\d+$
  • # approval_workflow_participant_feedbacks
    string
    Allowed values: [approved, pending]
  • # approval_workflow_participant_in_step
    string
    Allowed values: [current, any]
  • # approval_user_ids
    string

    Return only assets that have the given users as part of approval workflows (pending or complete) attached to an asset.

    Pattern: ^(user):\d+$
  • # content_type
    string

    A CSV of unique MIME types to filter by. Wildcards * are supported (ex. image/*).

  • # content_type_order
    string
  • # deleted
    string

    When true returns deleted media only

    Pattern: ^[tT]rue$|^[fF]alse$
  • # deleted_only
    string
    Pattern: ^[tT]rue$|^[fF]alse$
  • # end_at
    string

    Filter by start_at date (exclusive)

    Pattern: (\d{4})-(\d{2})-(\d{2})
  • # exclude_content_types
    string
  • # expires_after
    string
  • # expires_before
    string
  • # flat
    string

    When true search assets in the entire tree folder (as opposed to the current tree folder)

    Pattern: ^[tT]rue$|^[fF]alse$
  • # folder_uid
    string

    Filter by folder ID

    Pattern: ^(folder):\d+|primary$
  • # has_usage_rights
    string

    When true only assets that has usage rights information will be returned.

    Pattern: ^[tT]rue$|^[fF]alse$
  • # hide_facets
    boolean

    When true facets will not be part of the response

  • # index_license_id
    number
    Required

    The license asset library on which to perform the search

  • # ingested_from
    string
  • # is_photo
    string
    Pattern: ^[tT]rue$|^[fF]alse$
  • # orientations
    string

    A CSV of image orientations to filter by

    Allowed values: [vertical, horizontal, square]
  • # query
    string

    A CSV of search strings to filter by. Results will match at least one value.

  • # sizes
    string

    A CSV of unique size names to filter by.

    Allowed values: [small, medium, large, extra_large]
  • # start_at
    string

    Filter by start_at date (inclusive)

    Pattern: (\d{4})-(\d{2})-(\d{2})
  • # state
    string

    Filter by state

    Allowed values: [processing, approving, ready]
  • # tag
    string

    A CSV of tags to filter by.

  • # term_uids
    string
    Pattern: ^term:[a-zA-Z\d]+$
  • # type
    string

    A CSV of types to filter by

    Allowed values: [folder, image, video]
  • # uids
    string

    A CSV of unique UIDs to filter by

  • # user_ids
    string

    Return only the items created by the given user ids.

# Create a new folder. POST to a folder url to create within another folder

POST https://percolate.com/api/v3/media
Request
Response

Body

Properties:

# Get a single media item

GET https://percolate.com/api/v3/media/{media_id}
Request
Response

URI Parameters

  • # media_id
    string
    Required
    Pattern: ^(video:[a-zA-Z\d]+|license:\d+:image:\d+|folder:\d+)$

Query Parameters

  • # index_license_id
    integer
  • # license_id
    integer
  • # limit
    integer
  • # deleted
    string
    Pattern: ^[tT]rue$|^[fF]alse$
  • # state
    string
    Allowed values: [ready, processing]
  • # tags
    string

# Move items to a folder

POST https://percolate.com/api/v3/media/{media_id}
Request
Response

Body

Properties:

URI Parameters

  • # media_id
    string
    Required
    Pattern: ^(video:[a-zA-Z\d]+|license:\d+:image:\d+|folder:\d+)$

# Download a media item.

GET https://percolate.com/api/v3/media/{media_id}/download
Request
Response

Query Parameters

  • # brand_id
    integer
  • # license_id
    string
    Required

    The license asset library on which to perform the search

  • # image_size
    string
    default is "original"

    Specify the size of image to download. Only applicable to media of type image

    Allowed values: [small, medium, large, original, square]

# Get media item's metadata

GET https://percolate.com/api/v3/media/{media_id}/metadata
Request
Response

Query Parameters

  • # license_id
    string
    Required

    The license asset library on which to perform the search

  • # deleted
    string
    Pattern: ^[tT]rue$|^[fF]alse$
  • # term_uids
    string
    Pattern: ^term:[a-zA-Z\d]+$

# Update media item's metadata

PUT https://percolate.com/api/v3/media/{media_id}/metadata
Request
Response

Body

example:show
Properties:

Query Parameters

  • # license_id
    string
    Required

    The license asset library on which to perform the update

# Delete media item's metadata

DELETE https://percolate.com/api/v3/media/{media_id}/metadata
Request
Response

Query Parameters

  • # license_id
    string
    Required

    The license asset library on which to perform the search

# Get media item's license level custom metadata

GET https://percolate.com/api/v3/media/custom_metadata
Request
Response

Query Parameters

  • # license_id
    string
    Required

    The license asset library on which to perform the search

# Update media item's custom metadata

PUT https://percolate.com/api/v3/media/custom_metadata
Request
Response

Body

Properties:

Query Parameters

  • # license_id
    string
    Required

    The license asset library on which to perform the search

# Metadata

Metadata allows for customized enrichment of certain kinds of objects in the Percolate platform. By creating schemas for object types, any objects of those types can then be annotated with values captured from those schemas. This endpoint allows for the submission, manipulation and retrieval of values captured from schemas.

# Get a list of object metadata

GET https://percolate.com/api/v5/metadata/

Get a list of metadata

Request
Response

Query Parameters

  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^metadata:\d+$
  • # schema_id
    string

    The schema that defines this metadata

  • # object_ids
    string

    A CSV of object ids to filter by

# Create object metadata

POST https://percolate.com/api/v5/metadata/

Create a metadatum

Request
Response

Body

Properties:
  • The metadata values defined by schema_id

  • # object_id

    The resource ID

  • # schema_id

    The schema ID.

# Get metadata for a single object and schema

GET https://percolate.com/api/v5/metadata/{metadata_id}

Get a single metadatum

Request
Response

URI Parameters

  • # metadata_id
    string
    Required
    Pattern: ^metadata:[a-zA-Z0-9_-]+$

# Update an object\'s metadata

PUT https://percolate.com/api/v5/metadata/{metadata_id}

Update a metadatum

Request
Response

Body

Properties:
  • The metadata values defined by schema_id

URI Parameters

  • # metadata_id
    string
    Required
    Pattern: ^metadata:[a-zA-Z0-9_-]+$

# Delete an object\'s metadata

DELETE https://percolate.com/api/v5/metadata/{metadata_id}

Delete a metadatum

Request
Response

URI Parameters

  • # metadata_id
    string
    Required
    Pattern: ^metadata:[a-zA-Z0-9_-]+$

# Platforms

# Get platforms

GET https://percolate.com/api/v5/platform/

Get a list of platforms

Request
Response

Query Parameters

  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^platform:\d+$
  • # search
    string

    Search platform by name

  • # type
    string

    Platform type to filter by

    Pattern: ^(native|custom)$

# Create a platform

POST https://percolate.com/api/v5/platform/

Create a platform

Request
Response

Body

Properties:
  • # avatar_id

    An asset ID, a legacy video ID or a legacy image ID In the future will be replaced with consistent `^asset:\d[\d_-]*$`

  • # color

    The platform color

  • # name

    The name of the platform

    example:show
  • # scope_id

    Platforms of type native:* are owned by the built in scope. Only platforms of type custom can be edited

    example:show
  • # type

    The platform type

# Get a platform

GET https://percolate.com/api/v5/platform/{platform_id}

Get a single platform

Request
Response

URI Parameters

  • # platform_id
    string
    Required
    Pattern: ^platform:[a-zA-Z0-9_-]+$

# Update a platform

PUT https://percolate.com/api/v5/platform/{platform_id}

Update a platform

Request
Response

Body

Properties:
  • # avatar_id

    An asset ID, a legacy video ID or a legacy image ID In the future will be replaced with consistent `^asset:\d[\d_-]*$`

  • # color

    The platform color

  • # name

    The name of the platform

    example:show
  • # scope_id

    Platforms of type native:* are owned by the built in scope. Only platforms of type custom can be edited

    example:show
  • # type

    The platform type

URI Parameters

  • # platform_id
    string
    Required
    Pattern: ^platform:[a-zA-Z0-9_-]+$

# Post Webhooks

# Get post webhooks

GET https://percolate.com/api/v5/postwebhook/

Get a list of postwebhooks

Request
Response

Query Parameters

  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^postwebhook:\d+_\d+$
  • # post_id
    string

    Filter by post_id

    Pattern: ^post:\d+$

# Create a post webhook association

POST https://percolate.com/api/v5/postwebhook/

Create a postwebhook

Request
Response

Body

Properties:
  • # post_id

    The post ID

    example:show
  • # scope_id

    A license ID

    example:show
  • # webhook_id

    The webhook ID

    example:show

# Delete a post webhook association

DELETE https://percolate.com/api/v5/postwebhook/{postwebhook_id}

Delete a postwebhook

Request
Response

URI Parameters

  • # postwebhook_id
    string
    Required
    Pattern: ^postwebhook:[a-zA-Z0-9_-]+$

# Posts

# Get posts

GET https://percolate.com/api/v5/post/

Get a list of posts

Request
Response

Query Parameters

  • # order_by
    string

    Order by the specified attribute

    Pattern: live_at|created_at
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # topic_ids
    string

    A CSV of unique topic IDs to filter by

    Pattern: ^topic:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # term_ids
    string

    A CSV of unique term IDs to filter by

    Pattern: ^term:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # user_ids
    string

    A CSV of unique user IDs to filter by

    Pattern: ^user:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # platform_ids
    string

    A CSV of unique platform IDs to filter by

    Pattern: ^platform:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # channel_ids
    string

    A CSV of unique channel IDs to filter by

    Pattern: ^channel:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # metadata.{schemaFieldId}
    string

    Filter by a metadata field using a dynamic query parameter name. The {schemaFieldId} template represents the schema id and field name concatenated together by a dot (.). In effect, it expands to the sub-template {schema-id}.{schema-field-name}. The {schema-id} template is the UID of a schema. The {schema-field-name} template is a path separated by the forward slash (/) (to allow for representation of nested objects). Valid metadata query parameters could look like:

    • metadata.schema:1.live_date_range
    • metadata.schema:1.live_date_range/from
    • metadata.schema:1.live_date_range/from.from

    The value of the query parameter is a CSV of strings appropriate for the given metadata field.

  • # has_metadata.{schemaFieldId}
    boolean

    Filter by the existence of a metadata field. See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # metadata.{schemaFieldId}.from
    date

    Filter by a metadata date field (inclusive). See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # metadata.{schemaFieldId}.to
    date

    Filter by a metadata date field (exclusive). See the description of the metadata.{schemaFieldId} parameter for template formatting instructions.

  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # live_at:from
    date

    Filter by live_at date (inclusive)

  • # live_at:to
    date

    Filter by live_at date (exclusive)

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^post:\d+$
  • # access_scopes
    string
    default is "owned"

    Filter objects owned by the scope itself and/or shared from other scopes

    Pattern: ^(shared,owned|owned,shared|owned|shared)$
  • # include
    string

    Includes related items in the response

    Pattern: assignee_id|user_id|platform_id|channel_id|schema_id|interaction_id|targeting_id
  • # keywords
    string

    Keyword values to search for on posts

  • # name
    string

    Keyword values to search for on post titles

  • # asset_ids
    string

    A CSV of unique asset IDs to filter by

    Pattern: ^asset:[a-zA-Z0-9]+|license:\d+:image:\d+$
  • # access_scope
    string
    default is "owned"

    Filter posts owned by the scope itself vs. shared from other scopes

    Allowed values: [owned, shared]
  • # assignment_statuses
    string

    Filter posts if they are unassigned, assigned or both.

    Pattern: ^(assigned,unassigned|unassigned,assigned|unassigned|assigned)$
  • # assignee_ids
    string

    A CSV of user IDs to filter posts that are assigned to those users

    Pattern: ^user:\d+$
  • # approval_user_ids
    string

    A CSV of user IDs to filter by users that are part of approval workflows (pending or complete).

    Pattern: ^user:\d+$
  • # exclude_approved_by
    string

    A CSV of user IDs to exclude items that are approved by user

    Pattern: ^user:\d+$
  • # is_interaction
    boolean

    Filter posts to only those that are or are not interactions with external content. Defaults to being unspecified and including both interactions and non-interactions. :fire: This is provisional/unstable, only for use by Percolate frontend, may be removed in the future!

  • # live_at
    string

    When false, filters posts that are not scheduled to go live

    Pattern: ^[tT]rue$|^[fF]alse$|^null$
  • # origin_ids
    string

    A CSV of resource IDs to filter by

    Pattern: ^(brief:\d+|campaign:\d+)$
  • # statuses
    string

    Filter by statuses. The wildcard .* is supported for operations such as "all queued statuses queued.*"

    Allowed values: [draft, approvals.queued, approvals.draft, approvals.*, queued, queued.paused, queued.publishing, queued.error, queued.published, queued.*, live, queued.unpublishing, unpublished]

# Create a post

POST https://percolate.com/api/v5/post/

Create a post

Request
Response

Body

Properties:
  • # approval_group_id

    Creates an approval workflow for this post. If the post is already part of an approval workflow, this will overwrite it. (see approvals for details)

  • # assignee_id

    The id of user who is assigned to the post

  • # channel_id

    The channel to which this post has been or will be published.

  • # copy_from_id

    When copy_from_id is specified all CU fields become optional overrides of the original data.

    • only works with the same channel_id or another channel_id with the same type
    • only works if user has the ability to post:create in the target scope
    • copies all asset_ids to the primary library in the target scope and updates new post attributes with new asset IDs
    • term_ids are added to the new post only if found by name in the target scope
    • topic_ids (DEPRECATED - use terms obtained from /api/v5/metadata instead) are carried over on the same scope only
    • Plugs are copied over (specifically plug.budget, plug.start_at, plug.end_at)
    • live_at, url, approval_workflow_id, ingested are set to null
    • sets created_at and updated_at to now
    • origin_ids are carried over on the same scope (ex. post created from a brief or another post)
    • sets status to draft unless specified
    • links are re-shortened for new scope
    • replaces original user_id with the current user_id
    • activity will be the same as creating a new post
    • comments/Followers do not carry over

    V4 concepts:

    • Targeting does not carry over
    • Guardrail only carries over on same scope
    • Analytics does not carry over

    Below is an example of copying a post to a different scope, channel, change the name, and immediately queue it using POST /api/v5/post/.

    {
        "copy_from_id": "post:1",
        "channel_id": "channel:2",
        "name": "This is my new post",
        "scope_id": "license:2",
        "status": "queued"
    }
  • # description

    A short description about the post

    example:show
  • The structure defined by schema_id.

    example:show
  • # live_at

    When this post should/did go live. If null and status is live, live_at will be the current time. In all other cases null indicates that the post should go live ASAP. Note: regardless of whether a post is published or not, live_at reflects when the post goes live to the public.

    example:show
  • # live_at_timezone

    The timezone the post was intended to be scheduled in (usually the device's timezone unless an app specifies otherwise). live_at offset isn't enough to know.

  • # metadata

    This attribute can be used when post and metadata must be created under the same transaction.

    e.g. Publishing a post with metadata immediately with automatic link tracking.

  • The name of the post.

    example:show
  • # origin_ids

    Tracks where the post was created from

    Array items:

    The brief ID

    example:show
  • # platform_id

    The platform ID

  • # production_workflow_id

    ID of the production workflow that the post is attached to. Note: Post's production_workflow_id and approval_workflow_id values are independent of one another.

  • # schema_id

    The schema defining the type of post (must be a schema of type post matching the channel)

  • # scope_id

    A license ID

    example:show
  • # status

    Below you'll find all possible statuses during a post's life cycle.

    draft

    The post is in a holding pattern.

    approvals

    The post is currently part of an approval workflow. A post can be removed from approvals by reverting it back to draft. Users with post:publish permission may bypass approvals by setting the status to queued. Once approved, the post status will either be queued or set back to draft if the current status is approvals.queued or approvals.draft.

    queued

    The post is queued to be published to the associated channel. Publishing happens only once live_at is in the past or null. A post is either queued automatically upon approval or manually if a user has the post:publish permission. Only a queued or queued.paused status can be changed by the user (usually back to draft).

    • queued.paused: the post is queued but publishing is currently paused (the post cannot be published)
    • queued.publishing: The post is currently being published
    • queued.unpublishing: The post is currently being unpublished
    • queued.published: the post is still queued and has been successfully published. This indicates that the post hasn't gone live yet usually because of an external queue or some privacy controls.
    • queued.error: there was an error sending the post to the channel

    live

    The post is now live to the public on the associated channel. This state is either set automatically after queued.published or manually by a user with post:publish permission. In order to change the post's status to live url and live_at are required.

    Unpublished

    The post is now unpublished on the external platform. If post failed to unpublish, it will get reverted back to live from queued.unpublishing.

    example:show
  • # term_ids

    An array of term IDs

    Array items:

    The term ID

  • # topic_ids

    DEPRECATED - use terms obtained from /api/v5/metadata instead. An array of topic IDs.

    Array items:

    DEPRECATED - use terms obtained from /api/v5/metadata instead. The topic ID.

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: assignee_id|user_id|platform_id|channel_id|schema_id|interaction_id|targeting_id

# Get a post

GET https://percolate.com/api/v5/post/{post_id}

Get a single post

Request
Response

URI Parameters

  • # post_id
    string
    Required
    Pattern: ^post:[a-zA-Z0-9_-]+$

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: user_id|platform_id|channel_id|schema_id|post_attachment_id

# Update a post

PUT https://percolate.com/api/v5/post/{post_id}

Update a post

Request
Response

Body

Properties:
  • # approval_group_id

    Creates an approval workflow for this post. If the post is already part of an approval workflow, this will overwrite it. (see approvals for details)

  • # assignee_id

    The user ID

  • # channel_id

    The channel to which this post has been or will be published.

  • # description

    A short description about the post

    example:show
  • The structure defined by schema_id.

    example:show
  • # live_at

    When this post should/did go live. If null and status is live, live_at will be the current time. In all other cases null indicates that the post should go live ASAP. Note: regardless of whether a post is published or not, live_at reflects when the post goes live to the public.

    example:show
  • # live_at_timezone

    The timezone the post was intended to be scheduled in (usually the device's timezone unless an app specifies otherwise). live_at offset isn't enough to know.

  • # metadata

    This attribute can be used when post and metadata must be created under the same transaction.

    e.g. Publishing a post with metadata immediately with automatic link tracking.

  • The name of the post.

    example:show
  • # origin_ids

    Tracks where the post was created from

    Array items:

    The brief ID

    example:show
  • # platform_id

    The platform ID

  • # production_workflow_id

    ID of the production workflow that the post is attached to. Note: Post's production_workflow_id and approval_workflow_id values are independent of one another.

  • # schema_id

    The schema defining the type of post (must be a schema of type post matching the channel)

  • # scope_id

    A license ID

    example:show
  • # status

    Below you'll find all possible statuses during a post's life cycle.

    draft

    The post is in a holding pattern.

    approvals

    The post is currently part of an approval workflow. A post can be removed from approvals by reverting it back to draft. Users with post:publish permission may bypass approvals by setting the status to queued. Once approved, the post status will either be queued or set back to draft if the current status is approvals.queued or approvals.draft.

    queued

    The post is queued to be published to the associated channel. Publishing happens only once live_at is in the past or null. A post is either queued automatically upon approval or manually if a user has the post:publish permission. Only a queued or queued.paused status can be changed by the user (usually back to draft).

    • queued.paused: the post is queued but publishing is currently paused (the post cannot be published)
    • queued.publishing: The post is currently being published
    • queued.unpublishing: The post is currently being unpublished
    • queued.published: the post is still queued and has been successfully published. This indicates that the post hasn't gone live yet usually because of an external queue or some privacy controls.
    • queued.error: there was an error sending the post to the channel

    live

    The post is now live to the public on the associated channel. This state is either set automatically after queued.published or manually by a user with post:publish permission. In order to change the post's status to live url and live_at are required.

    Unpublished

    The post is now unpublished on the external platform. If post failed to unpublish, it will get reverted back to live from queued.unpublishing.

    example:show
  • # term_ids

    An array of term IDs

    Array items:

    The term ID

  • # topic_ids

    DEPRECATED - use terms obtained from /api/v5/metadata instead. An array of topic IDs.

    Array items:

    DEPRECATED - use terms obtained from /api/v5/metadata instead. The topic ID.

  • The URL this post was published to. Can only be set if status is "live" or "queued.published." For some platforms, directly setting url may not be supported; only custom platforms are guaranteed to allow this. NOTE this is always empty in bulk reads, for performance reasons.

    example:show
  • Opaque external ID of a live post on the external service. Can only be set if status is "live" or "queued.published."

    example:show

URI Parameters

  • # post_id
    string
    Required
    Pattern: ^post:[a-zA-Z0-9_-]+$

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: user_id|platform_id|channel_id|schema_id|post_attachment_id

# Delete a post

DELETE https://percolate.com/api/v5/post/{post_id}

Delete a post

Request
Response

URI Parameters

  • # post_id
    string
    Required
    Pattern: ^post:[a-zA-Z0-9_-]+$

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: user_id|platform_id|channel_id|schema_id|post_attachment_id

# Roles

# Get roles for scopes

GET https://percolate.com/api/v5/role/

Get a list of roles

Request
Response

Query Parameters

  • # scope_ids
    string
    Required

# Create a role

POST https://percolate.com/api/v5/role/

Create a role

Request
Response

Body

Properties:

# Get a role

GET https://percolate.com/api/v5/role/{role_id}

Get a single role

Request
Response

URI Parameters

  • # role_id
    string
    Required
    Pattern: ^role:[a-zA-Z0-9_-]+$

# Update a role

PUT https://percolate.com/api/v5/role/{role_id}

Update a role

Request
Response

Body

Properties:

URI Parameters

  • # role_id
    string
    Required
    Pattern: ^role:[a-zA-Z0-9_-]+$

# Delete a role

DELETE https://percolate.com/api/v5/role/{role_id}

Delete a role

Request
Response

URI Parameters

  • # role_id
    string
    Required
    Pattern: ^role:[a-zA-Z0-9_-]+$

# Schemas

# Get schemas

GET https://percolate.com/api/v5/schema/

Get a list of schemata

Request
Response

Query Parameters

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^schema:\d[_\d]*$
  • # type
    string

    Filter by type

    Allowed values: [campaign_section, post, targeting, metadata, post_attachment, intake_request]
  • # resource_types
    string
    default is "all"

    Filter by resource type

    Allowed values: [all, asset, campaign, campaign_section, channel, monitoring_flag, post, targeting, task]
  • # statuses
    string
    Allowed values: [active, inactive]
  • # ext.platform_ids
    string

    A CSV to filter by platform IDs

    Pattern: ^platform:\d+$
  • # ext.channel_types
    string

    A CSV to filter by channel type (see channel.type for possible values)

  • # slugs
    string

    A CSV to filter by schema slugs

# Create a schema

POST https://percolate.com/api/v5/schema/

Create a schema

Request
Response

Body

example:show
Properties:
  • Extra properties for schemas of type campaign_section

    example:show
  • # fields

    An ordered list of fields

    Array items:

    A field is used to describe the type of input and data a user can enter.

    Fields can be different types based on type attribute. Certain fields have additional configuration defined in ext. The field type also determines the type of data stored under the value of key.

    Given this field definition:

    {
        "key": "email",
        "label": "Email address",
        "description": "Your work email address",
        "required": true,
        "type": "email",
        "ext": null,
      }

    The following output is produced when a user enters "example@percolate.com" into the field:

    {
        "email": "example@percolate.com"
      }
    type description stored value example
    asset An assets field ["asset:1"]
    currency A currency field { "currency": "USD", "amount": "20.0000" }
    date-range A date range field { "from": "2014-12-25", "to": "2014-12-31" }
    date A date field "2014-04-30T20:32:18+00:00"
    email An email field "example@percolate.com"
    html An html field "<b>hello world</b>"
    hidden A field for data passing, that should not be shown in UI "string data"
    link A links field ["link:1"]
    multi-select A multi-select field (ex. checkbox, multi dropdown) ["checkbox 1", "checkbox 2"]
    number A number field 9, 100.25, 0.091231
    select A select field (ex. radio, single dropdown) "radio_1"
    string-array A list of strings. Values are represented as lists, not comma-separated strings. , and carriage return will automatically add a new value. ["hello", "24", "I'm another thing"]
    term A terms field ["term:XTN123", "term:XTN456"]
    text A single line text field "hello world"
    textarea A multi-line text field "hello\nworld"
    object-array A field that stores array of objects [{ body: "hello\nworld", age: 18 }, { body: "hi\nthere", age: 21 }]
    post_attachment A post attachment field ["post_attachment:1"]
  • # fieldsets

    An ordered array of fieldset objects

  • # limit_resource_types

    Ability to assign a schema to a specific resource type. Certain schema types must can only be applied to one resource type (ex. post). Others (ex. metadata), can be applied to multiple resource types.

    Array items:
  • # name

    A name identifying the schema

  • # plugins

    A list of plugins

    Array items:

    Plugins can be applied to fields to enhance their functionality.

    Plugins can be different types based on type attribute. Certain plugins have addition configuration defined in ext.

    autocomplete

    Adds autocomplete to fields of type select and multi-select. A server search on the autocomplete endpoint is triggered with search_url

    mentions

    Adds hyper-linking to fields of type textarea. A server search on the autocomplete endpoint is intialized with search_url when the regular expression of search_trigger is met. The user can then enhance parts of the text with values returned from the server. Multiple mentions can be applied to the same field and get stored on the key with the following JSON-Schema:

    type: array
    items:
      type: object
      required:
        - value
        - offset
        - length
      additionalProperties: false
      properties:
        value:
          description: The external ID of this mention.
          type: string
        offset:
          description: 0-based offset where this mention begins
          type: integer
        length:
          description: Number of characters
          type: integer

    Example plugin data:

    {
        "message": "I like Disney and Disney/Pixar",
        "mentions": [
            {"value": "11784025953", "offset": 7, "length": 6},
            {"value": "108014809233498", "offset": 18, "length": 12}
        ]
    }

    Adds URL metadata to fields of type textarea. The plugin enables identifying which parts of the text represent URLs (using offset and length, like the mentions plugin) and provides optional related information for each URL. Multiple links can be applied to the same textarea and get stored on the key as objects with the following JSON-Schema. (Note that the short_url and tracking_url attributes are read-only):

    type: array
    items:
      type: object
      required:
        - url
        - offset
        - length
      additionalProperties: false
      properties:
        url:
          description: The original URL found in the textarea.
          type: string
        offset:
          description: 0-based offset where this link begins
          type: integer
        length:
          description: Number of characters in the original url (not short or tracking)
          type: integer
        shorten:
          description: A boolean indicating whether the url should be shortened
          type: boolean
        track:
          description: A boolean indicating whether the url should be tracked
          type: boolean
        short_url:
          description: A bitly-shortened version of the URL. Can be empty if shortening is disabled. This value is read-only.
          type: string
        tracking_tag_ids:
          description: The tracking tag IDs to apply to the link before shortening. Same as in the `tracking_tags` plugin. Can be empty array.
          type: array
          items:
            type: string
            pattern: ^tracking_tag:\d+$
        tracking_url:
          description: The long URL that was used for shortening. Can be empty if shortening is disabled. This is the original URL with additional query parameters: automatic tracking tags (if configured) and a unique random __prclt parameter. This attribute is read-only.
          type: string

    Example plugin data:

    {
        "message": "Check out http://example.com and https://isitchristmas.com/",
        "links": [
          {
            "url": "http://example.com",
            "tracking_tag_ids": ["tracking_tag:1", "tracking_tag:2"],
            "tracking_url": "http://example.com?__prclt=123&__utm_foo=bar&__utm_xyz=pdq",
            "short_url": "http://bit.ly/28TtifN",
            "length": 18,
            "offset": 10,
            "shorten": true,
            "track": true
          },
          {
            "url": "https://isitchristmas.com",
            "tracking_tag_ids": [],
            "tracking_url": "",
            "short_url": "",
            "length": 25,
            "offset": 33,
            "shorten": true,
            "track": true
          }
        ]
    }

    timezone

    Adds timezone support to fields of type date. Since all times are converted to UTC, displaying the date varies based on the device's current timezone. By storing the timezone, we can display the date in its original/intended form. The selected timezone will be stored under the key value.

    tracking_tags

    Add tracking tags to fields of type link Selected tracking tags are stored on the key with the following JSON-Schema:

    type: array
    items:
      type: object
      required:
        - link_id
        - tracking_tag_ids
      additionalProperties: false
      properties:
        link_id:
          description: |
            The link ID to attach the tracking tags to.
    
            Important: The link ID must exist in associated array of link IDs defined by the `field_key`.
          type: string
          pattern: ^link:\d+$
        tracking_tag_ids:
          description: The tracking tag IDs associated with the link
          type: array
          items:
            type: string
            pattern: ^tracking_tag:\d+$

    Example:

    [
        {
            "link_id": "link:1",
            "tracking_tag_ids": ["tracking_tag:1", "tracking_tag:2"]
        }
    ]
  • # scope_id

    An account ID

    example:show
  • A permanent unique human-readable identifier for the schema

  • # type

    The schema type

# Get a schema

GET https://percolate.com/api/v5/schema/{schema_id}

Get a single schema

Request
Response

URI Parameters

  • # schema_id
    string
    Required
    Pattern: ^schema:[a-zA-Z0-9_-]+$

Query Parameters

  • # context_id
    string

    Object ID being passed in as the context

    Pattern: ^\w+:\w+$

# Update a schema

PUT https://percolate.com/api/v5/schema/{schema_id}

Update a schema

Request
Response

Body

Properties:
  • Extra properties for schemas of type campaign_section

    example:show
  • # fields

    An ordered list of fields

    Array items:

    A field is used to describe the type of input and data a user can enter.

    Fields can be different types based on type attribute. Certain fields have additional configuration defined in ext. The field type also determines the type of data stored under the value of key.

    Given this field definition:

    {
        "key": "email",
        "label": "Email address",
        "description": "Your work email address",
        "required": true,
        "type": "email",
        "ext": null,
      }

    The following output is produced when a user enters "example@percolate.com" into the field:

    {
        "email": "example@percolate.com"
      }
    type description stored value example
    asset An assets field ["asset:1"]
    currency A currency field { "currency": "USD", "amount": "20.0000" }
    date-range A date range field { "from": "2014-12-25", "to": "2014-12-31" }
    date A date field "2014-04-30T20:32:18+00:00"
    email An email field "example@percolate.com"
    html An html field "<b>hello world</b>"
    hidden A field for data passing, that should not be shown in UI "string data"
    link A links field ["link:1"]
    multi-select A multi-select field (ex. checkbox, multi dropdown) ["checkbox 1", "checkbox 2"]
    number A number field 9, 100.25, 0.091231
    select A select field (ex. radio, single dropdown) "radio_1"
    string-array A list of strings. Values are represented as lists, not comma-separated strings. , and carriage return will automatically add a new value. ["hello", "24", "I'm another thing"]
    term A terms field ["term:XTN123", "term:XTN456"]
    text A single line text field "hello world"
    textarea A multi-line text field "hello\nworld"
    object-array A field that stores array of objects [{ body: "hello\nworld", age: 18 }, { body: "hi\nthere", age: 21 }]
    post_attachment A post attachment field ["post_attachment:1"]
  • # fieldsets

    An ordered array of fieldset objects

  • # limit_resource_types

    Ability to assign a schema to a specific resource type. Certain schema types must can only be applied to one resource type (ex. post). Others (ex. metadata), can be applied to multiple resource types.

    Array items:
  • # name

    A name identifying the schema

  • # plugins

    A list of plugins

    Array items:

    Plugins can be applied to fields to enhance their functionality.

    Plugins can be different types based on type attribute. Certain plugins have addition configuration defined in ext.

    autocomplete

    Adds autocomplete to fields of type select and multi-select. A server search on the autocomplete endpoint is triggered with search_url

    mentions

    Adds hyper-linking to fields of type textarea. A server search on the autocomplete endpoint is intialized with search_url when the regular expression of search_trigger is met. The user can then enhance parts of the text with values returned from the server. Multiple mentions can be applied to the same field and get stored on the key with the following JSON-Schema:

    type: array
    items:
      type: object
      required:
        - value
        - offset
        - length
      additionalProperties: false
      properties:
        value:
          description: The external ID of this mention.
          type: string
        offset:
          description: 0-based offset where this mention begins
          type: integer
        length:
          description: Number of characters
          type: integer

    Example plugin data:

    {
        "message": "I like Disney and Disney/Pixar",
        "mentions": [
            {"value": "11784025953", "offset": 7, "length": 6},
            {"value": "108014809233498", "offset": 18, "length": 12}
        ]
    }

    Adds URL metadata to fields of type textarea. The plugin enables identifying which parts of the text represent URLs (using offset and length, like the mentions plugin) and provides optional related information for each URL. Multiple links can be applied to the same textarea and get stored on the key as objects with the following JSON-Schema. (Note that the short_url and tracking_url attributes are read-only):

    type: array
    items:
      type: object
      required:
        - url
        - offset
        - length
      additionalProperties: false
      properties:
        url:
          description: The original URL found in the textarea.
          type: string
        offset:
          description: 0-based offset where this link begins
          type: integer
        length:
          description: Number of characters in the original url (not short or tracking)
          type: integer
        shorten:
          description: A boolean indicating whether the url should be shortened
          type: boolean
        track:
          description: A boolean indicating whether the url should be tracked
          type: boolean
        short_url:
          description: A bitly-shortened version of the URL. Can be empty if shortening is disabled. This value is read-only.
          type: string
        tracking_tag_ids:
          description: The tracking tag IDs to apply to the link before shortening. Same as in the `tracking_tags` plugin. Can be empty array.
          type: array
          items:
            type: string
            pattern: ^tracking_tag:\d+$
        tracking_url:
          description: The long URL that was used for shortening. Can be empty if shortening is disabled. This is the original URL with additional query parameters: automatic tracking tags (if configured) and a unique random __prclt parameter. This attribute is read-only.
          type: string

    Example plugin data:

    {
        "message": "Check out http://example.com and https://isitchristmas.com/",
        "links": [
          {
            "url": "http://example.com",
            "tracking_tag_ids": ["tracking_tag:1", "tracking_tag:2"],
            "tracking_url": "http://example.com?__prclt=123&__utm_foo=bar&__utm_xyz=pdq",
            "short_url": "http://bit.ly/28TtifN",
            "length": 18,
            "offset": 10,
            "shorten": true,
            "track": true
          },
          {
            "url": "https://isitchristmas.com",
            "tracking_tag_ids": [],
            "tracking_url": "",
            "short_url": "",
            "length": 25,
            "offset": 33,
            "shorten": true,
            "track": true
          }
        ]
    }

    timezone

    Adds timezone support to fields of type date. Since all times are converted to UTC, displaying the date varies based on the device's current timezone. By storing the timezone, we can display the date in its original/intended form. The selected timezone will be stored under the key value.

    tracking_tags

    Add tracking tags to fields of type link Selected tracking tags are stored on the key with the following JSON-Schema:

    type: array
    items:
      type: object
      required:
        - link_id
        - tracking_tag_ids
      additionalProperties: false
      properties:
        link_id:
          description: |
            The link ID to attach the tracking tags to.
    
            Important: The link ID must exist in associated array of link IDs defined by the `field_key`.
          type: string
          pattern: ^link:\d+$
        tracking_tag_ids:
          description: The tracking tag IDs associated with the link
          type: array
          items:
            type: string
            pattern: ^tracking_tag:\d+$

    Example:

    [
        {
            "link_id": "link:1",
            "tracking_tag_ids": ["tracking_tag:1", "tracking_tag:2"]
        }
    ]
  • # scope_id

    An account ID

    example:show
  • # type

    The schema type

URI Parameters

  • # schema_id
    string
    Required
    Pattern: ^schema:[a-zA-Z0-9_-]+$

# Terms

# Fetch terms

GET https://percolate.com/api/v5/term/

Retrieve a list of terms. Required values: either of (ids | scope_ids | parent_ids). Optional values: depth & search.

Request
Response

Query Parameters

  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # include
    string

    Includes related items in the response

    Pattern: path_ids
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^term:[a-zA-Z\d]+$
  • # parent_ids
    string

    A CSV of parent term IDs to filter by

  • # depth
    integer
    default is 1

    Fetch children up to N levels deep

  • # search
    string

    Search terms by name

  • # namespace
    string

    Term namespace

  • # mode
    string
    default is "regular"

    A CSV of modes to filter by

    • regular: Filter "standalone" terms
    • taxonomy: Filter terms that are part of a taxonomy tree
    Allowed values: [regular, taxonomy]

# Create a term

POST https://percolate.com/api/v5/term/

Create a term

Request
Response

Body

Properties:

# Retrieve a term

GET https://percolate.com/api/v5/term/{term_id}

Get a single term

Request
Response

URI Parameters

  • # term_id
    string
    Required
    Pattern: ^term:[a-zA-Z0-9_-]+$

# Edit a term

PUT https://percolate.com/api/v5/term/{term_id}

Update a term

Request
Response

Body

Properties:
  • # name

    Term name

  • # parent_id

    ID of the parent term

  • # status

    Whether this term can be used in other resources

    example:show

URI Parameters

  • # term_id
    string
    Required
    Pattern: ^term:[a-zA-Z0-9_-]+$

# Upload

A way to make files available to the Percolate platform.

Currently this endpoint is used for assets, taxonomies and all other cases where a file upload is required. Uploading files into Percolate can be done through two sources: uploading from a file or uploading from a URL. Uploading from a file requires three basic steps, namely: creating an upload object, creating an upload policy object, and uploading the file to AWS S3. Uploading from a URL can be done by creating only an upload object. Percolate recommends uploading files directly for automated processes in order to maintain greater control over the process. Uploading from a file using this process supports files up to a size of 5 GiB. Files larger than 5 GiB can be uploaded into Percolate (the absolute file limit is 5 TiB), following a similar procedure, but the submission to S3 would need to be split into several separate requests, following a process that is beyond the scope of this document but may be found at here.

1. Create upload object

This Percolate object represents the upload process for a given file. It provides the status of the upload as well as a reference to the final ingested asset once the upload is complete.

Example request and response are shown under Create an upload section.

The response will contain a status field with the possible values of “uploading” for newly created objects, “ready” for complete uploads, “duplicate” for files that already exist within the same license, or “error” in the case of an error. The available types for an upload are "url" and "file". If the type is "url" then steps 2 and 3 can be skipped, moving straight to step 4 in this example.

2. Create an upload policy object

This object contains a one-time-use set of credentials for Percolate and the end user. This allows the user to upload a file to an s3 location that Percolate can then read from. Once the user uploads the file to the specified location, this upload_policy object will allow Percolate to associate the uploaded file with the upload object.

Example request and response are shown under Create a upload_policy section.

The mandatory field type can be either "s3" for a single part upload, or "s3_multipart" for chunked uploads (available for any file with a size of at least 5 MiB).

3. Upload to S3 directly

Both the file stream, as well as the form data in the payload below as a multipart/form request in the order specified. The successful upload results in a 204 No Content response being returned. Please refer to Amazon’s documentation of this process here.

Example Request: POST <s3_url_from_previous_upload_policy_response>

Example Payload (values are extracted the previous upload policy response):

{
  "AWSAccessKeyId": "AKIAJP3A7RU5IILBSMCA",
  "acl": "public-read",
  "key": "ugc/image/raw/CaOr9N1dsZU.jpg",
  "signature": "XxU367OHbizjN6FfJ4asaQkxXF0=",
  "policy": "eyJjb25kaXRpb25zIjogW1sic3RhcnRzLXdpdGgiLCAiJENvbnRlbnQtVHlwZSIsICIiXSwgeyJidWNrZXQiOiAiY2RuLnBlcmNvbGF0ZS5jb20ifSwgeyJrZXkiOiAidWdjL2ltYWdlL3Jhdy9DYU9yOU4xZHNaVS5qcGcifSwgeyJhY2wiOiAicHVibGljLXJlYWQifV0sICJleHBpcmF0aW9uIjogIjIwMTYtMDQtMDdUMTY6NDY6MzQuNzg5OTQ2WiJ9",
  "Content": "Type=image/jpeg",
  "file": "<binary data>"
}

Example Response: 204 status (No Content)

This is a direct post to S3 in order to upload the file and triggers the creation of a new asset in Percolate.

4. Verify

Poll upload object for status and asset object reference. Once the upload is complete, the upload object will change its status to “ready ”and get updated with a reference to the newly created asset ID.

Example request and response are shown under Get an upload section.

Once the asset ID has been created, the object will exist within the Percolate library. Due to the version mismatch between the upload and media endpoints, the asset_id needs to be translated from "asset:x" to "video:x".

# Create an upload

POST https://percolate.com/api/v5/upload/

Create a upload

Request
Response

Body

Properties:

# Get an upload

GET https://percolate.com/api/v5/upload/{upload_id}

Get a single upload

Request
Response

URI Parameters

  • # upload_id
    string
    Required
    Pattern: ^upload:[a-zA-Z0-9_-]+$

# Update an upload

PUT https://percolate.com/api/v5/upload/{upload_id}

Update a upload

Request
Response

Body

Properties:
  • # scope_id

    A license ID

    example:show
  • # status

    The status of the upload. Exists means content already existed for current tenant but metadata had to be created for current scope.

    example:show

URI Parameters

  • # upload_id
    string
    Required
    Pattern: ^upload:[a-zA-Z0-9_-]+$

# Upload Policies

# Create an upload policy

POST https://percolate.com/api/v5/upload_policy/

Create a upload_policy

Request
Response

Body

Properties:

# User Roles

# Get a list of user roles

GET https://percolate.com/api/v5/user_role/

Get a list of user_roles

Request
Response

Query Parameters

  • # order_by
    string

    Order by the specified attribute

    Pattern: id|user_id\.name
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # role_ids
    string

    A CSV of unique role IDs to filter by

    Pattern: ^role:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # user_ids
    string

    A CSV of unique user IDs to filter by

    Pattern: ^user:[a-zA-Z0-9][a-zA-Z0-9_]*$
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # extend_scopes
    boolean
    default is false

    Look inside any child scopes in addition to the supplied ones

  • # scope_ids
    string

    A CSV of license IDs to filter by

    Pattern: ^(?:brand|account|license(?:_group)?):\d+$|builtin_scope:system$
  • # ids
    string

    A CSV of unique IDs to filter by

    Pattern: ^user_role:\d+$
  • # include
    string

    Includes related items in the response

    Pattern: user_id|role_id
  • # capabilities
    string

    A CSV of capability codes. Filters results for roles having the specified capabilities.

  • # distinct
    string

    Reduce the result set so that the user_id or role_id is unique. If there are multiple scopes with the same role/user, best effort is made to select one.

    Pattern: user_id|role_id
  • # exclude_disabled
    boolean

    If true, disabled users should be filtered out.

  • # exclude_hierarchical
    boolean
    default is false

    If true, only return user_roles explicitly in the requested scope.

# Create a user role

POST https://percolate.com/api/v5/user_role/

Create a user_role

Request
Response

Body

Properties:

Query Parameters

  • # include
    string

    Includes related items in the response

    Pattern: user_id|role_id

# Get a single user role

GET https://percolate.com/api/v5/user_role/{user_role_id}

Get a single user_role

Request
Response

URI Parameters

  • # user_role_id
    string
    Required
    Pattern: ^user_role:[a-zA-Z0-9_-]+$

# Delete a user role

DELETE https://percolate.com/api/v5/user_role/{user_role_id}

Delete a user_role

Request
Response

URI Parameters

  • # user_role_id
    string
    Required
    Pattern: ^user_role:[a-zA-Z0-9_-]+$

# Users

# Create a user

POST https://percolate.com/api/v5/user/

Create a user

Request
Response

Body

Properties:
  • # email

    User's login email

    example:show
  • # name

    The full name of the User

    example:show
  • # timezone

    A timezone name from the tz database. Timezone abbreviations (eg. EST) are not supported.

  • # user_role

    Automatically create a user role alongside the user

Query Parameters

  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

# Get a single user

GET https://percolate.com/api/v5/user/{user_id}

Get a single user

Request
Response

URI Parameters

  • # user_id
    string
    Required
    Pattern: ^user:[a-zA-Z0-9_-]+$

# Update a user

PUT https://percolate.com/api/v5/user/{user_id}

Update a user

Request
Response

Body

Properties:
  • # active

    The status of the user which is used for disabling/reactivating user

  • # email

    User's login email

    example:show
  • # name

    The full name of the User

    example:show
  • # timezone

    A timezone name from the tz database. Timezone abbreviations (eg. EST) are not supported.

URI Parameters

  • # user_id
    string
    Required
    Pattern: ^user:[a-zA-Z0-9_-]+$

# Disable a user

DELETE https://percolate.com/api/v5/user/{user_id}

Delete a user

Request
Response

URI Parameters

  • # user_id
    string
    Required
    Pattern: ^user:[a-zA-Z0-9_-]+$

# Change user password

PUT https://percolate.com/api/v5/user/{user_id}/password
Request
Response

Body

Properties:
  • # new_password

    The new password

  • # old_password

    The old password

# Send reset password email

DELETE https://percolate.com/api/v5/user/password

Email the user a password reset email. Available to unauthenticated users. Heavily rate-limited.

Request
Response

Query Parameters

  • # email
    string
    Required

    The email associated with the account who's password you want to reset

# Variant

# Get a list of variants

GET https://percolate.com/api/v5/variant/

Get a list of variants

Request
Response

Query Parameters

  • # order_by
    string

    Order by the specified attribute

    Pattern: size|created_at|dimensions
  • # order_direction
    string

    Control order direction

    Allowed values: [asc, desc]
  • # limit
    integer

    Limit the number of paginated results

  • # offset
    integer

    A 0-based offset to adjust the pagination window.

  • # asset_id
    string
    Required

    filter by variants derived from the given asset

    Pattern: ^asset:\d[\d_-]*$
  • # types
    string

    Filter by CSV of types

    Pattern: ^image|audio|video$
  • # ext.width
    integer

    filter by width greater than or equal to the given value

  • # ext.height
    integer

    filter by height greater than or equal to the given value

  • # max_width
    integer

    filter by width less than or equal to the given value

  • # max_height
    integer

    filter by height less than or equal to the given value

  • # download
    string

    Download the result variant\'s file data instead of the object. This parameter will only be honored if there is a single result.

    Responses to requests with this parameter will use the Content-Disposition header with the privided value (RFC 2616 Sec 19.5.1), including the variant\'s content type and a filename. It is crucial that all redirects returned from this call are followed as the first response will almost certainly be a 303. In addition, URLs returned from redirects must not be cached, they will have a short TTL.

    Allowed values: [inline, attachment]

# Get a single variant

GET https://percolate.com/api/v5/variant/{variant_id}

Get a single variant

Request
Response

URI Parameters

  • # variant_id
    string
    Required
    Pattern: ^variant:[a-zA-Z0-9_-]+$

# Download a variant

GET https://percolate.com/api/v5/variant/{variant_id}/download
Request
Response

Query Parameters

  • # disposition
    string

    Set the value the server will use for the Content-Disposition header (RFC 2616 Sec 19.5.1) of the response. The variant's content type and filename will also be included in this header. The default value is attachment.

    Allowed values: [inline, attachment]