API Reference
Start typing to search…

Element Selectors

Some workspace elements (Actions, Flows, and others) have multiple layers: universal, integration-specific, and connection-specific.

To access the right element, the API uses a combination of selectors and query parameters with reasonable defaults.

Element Selection Logic

API endpoints for such elements look like this: <elementType>/<selector>/<operation>?<parameters, for example /actions/create-task/run?integrationKey=github. Here is how they work:

  • Selector has a format of [<integrationKey>.]<elementIdOrKey>.
    • You can always address any element by its id (i.e. /actions/651488f5eba1bdf86a702ca3 will always point to the a specific action).
    • You can address universal elements by their key (i.e. /actions/create-task will by default address a universal action with key create-task)
    • integrationKey is used to address integration-specific elements (for example, hubspot.create-task will address element with key create-task for integration with key hubspot.
  • Parameters help you select a correct version of the element:
    • integrationKey or integrationId will let you select an integration-specific version of universal element (i.e. /actions/create-task?integrationKey=github will return version of universal action create-task that will be used for github).
    • connectionId will return connection-specific version of universal or integration-specific element (i.e. /actions/create-task?connectionId=63b3eab482e698438c2c1e95 will return connection-level action created for universal action create-task).
    • layer controls what layer of the element is returned:
      • layer=universal will resolve to universal element(s)
      • layer=integration will resolve to integration-level element(s)
      • layer=connection will resolve to connection-level element(s)

Defaults

  • When you use operations that require connection-level element, such as run for actions or flows, layer=connection parameter is applied by default.
  • If layer is specified without specifying integration or connection, a default connection will be used if it can be identified (i.e. if the current customer has only one connection - it will be used, or if integration is specified and only one connection exist for this integration - it will be used).

Examples

Here are a few typical examples to understand how to access workspace elements:

  • List elements
    • /actions - get a list of all unique actions (ones that don't have parentId)
    • /actions?layer=universal - list all the universal actions
    • /actions?layer=connection - list all the connection-level actions (ones that have connectionId)
  • Get a single element
    • /actions/651488f5eba1bdf86a702ca3 - get action with a specific id
    • /actions/create-task - get universal action with key create-task
    • /actions/create-task?integrationKey=github - get github-specific version of universal action with key create-task.
    • /actions/github.create-task - get action for integration githgub with key create-task (regardless of universal action with key create-task). If there is a version of universal action create-task for hubspot and a hubspot-specific action create-taskthat is not linked to a universal action, the latter will be returned.
    • /actions/create-task?connectionId=63b3eab482e698438c2c1e95 - get connection-level version of universal action create-task created for connection with the specified id.
    • /actions/create-task?integrationKey=github&level=connection - get connection-level version of universal action with key create-task created for default github connection for the current customer.
  • Perform operation on an element
    • POST /actions/create-task/run - run universal action create-task for the default connection of the current customer. If current customer has more than one connection, this call will fail.
    • POST /actions/create-task/run?connectionId=63b3eab482e698438c2c1e95 - run a version of universal action with key create-task for connection with the specified id.
    • POST /actions/create-task/run?integrationKey=github. Run action create-task for default connection to Github for a current customer. If current customer have multiple connections to github or no connections to github - this call will fail.