API Reference
Start typing to search…

Element Selectors

To simplify interacting with membrane workspace elements, the API supports multiple ways of addressing them via selectors (:selector in the API route) and query parameters.

By ID

If you have an id of an element you need, you can use it to address the element:

  • GET /actions/651488f5eba1bdf86a702ca3 - get action with id 651488f5eba1bdf86a702ca3.
  • POST /flows/63b30e09e9a70700c7dc5e82/run - run flow with id 63b30e09e9a70700c7dc5e82.

When you know an element id, you should always use this way of addressing it - its the most unambiguous one.

When addressing elements by id, you should not pass any additional parameters (integrationId, connectionId, etc).

By Key

Most workspace elements have keys act as human-readable identifiers of those elements. In many cases, you can address elements by key:

  • GET /actions/create-task - get action with key "create-task".
  • POST /flows/send-update/run - run a flow with key "send-update".

Addressing elements by key will work when:

  • There is only one element with this key in the workspace.
  • There is a universal element with this key and it can be used for the current request.

Addressing elements by key will not work when there are multiple elements with the same key and it's not possible to guess which one you need, for example:

  • GET /actions/create-task will not work when you have multiple integration-level actions with key create-task and no universal one.
  • POST /flows/send-update/run will not work without additional clarifying parameters if the current customer has multiple connections (which makes it impossible to determine which of them to use to run the flow).

By Integration Key + Element Key

It is the best way to address integration-specific elements. For example:

  • GET /actions/github.create-task will return action with key create-task for integration with key github.
  • POST /flows/slack.send-update/run will run flow with key send-update for integration slack (using default connection to Slack for the current user).

Addressing by integration key + element key lets you address integration-specific elements even when universal element with the same key exist. For example, if you have universal action create-task and Github connector provides github-specific action create-task, by addressing action as github.create-task you are guaranteed to get the github-specific version of the action (and not an implementation of universal create-task for github).

Parameters

Additionally to selector in the path, there are clarifying parameters you can pass to get the exact element you need when addressing it by key:

  • connectionId - will return connection-specific element for this id (and automatically create it from integration-specific element if it doesn't exist yet).
  • integrationKey or integrationId - will return integration-specific implementation of a given universal element if it exist (it will not be auto-created). For example, /flows/send-update?integrationKey=slack will address an implementation of universal flow send-update for slack integration.
  • layer (universal|integration|connection) - will return element of the specific layer (see Membrane Interfaces to know what it is). For example, /actions/github.create-task?layer=connection will return connection-layer task based on the integration-layer task. The connection-layer task will be returned for the default github connection for the current customer (if it can be determined).