Skip to main content
POST
/
act
{
  "connectionKey": "hubspot-prod",
  "api": {
    "method": "POST",
    "path": "/crm/v3/objects/contacts",
    "body": { "properties": { "email": "jane@example.com" } }
  }
}

{
  "output": {},
  "actionRunId": "<string>"
}
POST /act is Membrane’s unified entry point for running an action through a connection. See the Actions guide for the conceptual walkthrough — this page is the endpoint reference.

​
Dispatch styles

Exactly one of id, key, api, or code per call. Sending more than one returns 400.
FieldStyleWhen to use
apiInline apiMake an ad-hoc HTTP request through the connection’s auth and base URL.
codeInline codeRun a JavaScript snippet in a sandbox with a pre-wired authenticated membrane client.
keyReusableRun a saved (workspace- or integration-level) action by its stable key.
idReusableRun a catalog action or a saved action by its Membrane ID.

​
Resolving a connection

Every dispatch needs a connection. Membrane resolves one in this order:
  1. connectionId — direct.
  2. connectionKey — look up by key.
  3. integrationId or integrationKey — use that integration’s default connection.
  4. Workspace default connection.
Reusable-action dispatches that target a connection-scoped or integration-scoped action use the action’s own scope automatically — the body fields above only kick in when the action’s scope doesn’t already resolve a connection. For inline dispatches (api / code), the connection must resolve to something — otherwise the request returns 400.

​
Request body

{
  "connectionKey": "hubspot-prod",
  "api": {
    "method": "POST",
    "path": "/crm/v3/objects/contacts",
    "body": { "properties": { "email": "jane@example.com" } }
  }
}
FieldTypeDescription
apiobjectInline HTTP spec — { method, path, body?, headers?, query? }.
codestringInline JS module body, executed in a sandbox.
keystringAction key. Scope with integrationKey/integrationId/connectionId if non-unique.
idstringAction ID. Mutually exclusive with key / api / code.
connectionIdstringConnection to run against. See resolution priority.
connectionKeystringConnection key alternative to connectionId.
integrationIdstringIntegration ID — used to scope key lookups or pick a default connection.
integrationKeystringIntegration key alternative to integrationId.
inputobjectAction input. For reusable-action dispatches, validated against the action’s inputSchema.
metaobjectArbitrary metadata stored on the resulting Action Run Log.

​
Response

{
  "output": { "id": "12345", "email": "jane@example.com" },
  "actionRunId": "<action-run-id>"
}
Every response — success or failure — carries an actionRunId. Pass it to GET /action-run-logs/{id} to inspect the resolved action, mapped input, raw HTTP exchange, and any errors. On failure the body still includes actionRunId alongside the error.

​
Replay from a run log

Every action run log carries an action field — the complete /act body that was used. Pass it back unchanged to re-run the same dispatch: 
SNAPSHOT=$(curl -s https://api.integration.app/action-run-logs/<runId> \
  -H "Authorization: Bearer $TOKEN" | jq '.action')

curl -X POST https://api.integration.app/act \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$SNAPSHOT"
The snapshot is the source of truth for “what ran”. Top-level input and connectionId on the run log are deprecated — read them from action instead.

​
Legacy: POST /actions/{selector}/run

POST /actions/{selector}/run is the older endpoint for running a saved action. It still works for existing callers but is deprecated — /act covers all the same cases plus inline api and code dispatch.
BeforeAfter
POST /actions/<id>/run body: { ...input }POST /act body: { "id": "<id>", "input": {...}, "connectionKey": "..." }
POST /actions/<key>/run?connectionId=<id>POST /act body: { "key": "<key>", "connectionId": "<id>", "input": {...} }
Ad-hoc HTTP via a custom run-javascript actionPOST /act body: { "api": { "method": "...", "path": "..." }, "connectionKey": "..." }
Use /act for new code.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
id
string

ID of the action to run.

​
key
string

Key of the action to run. If the same key exists across multiple integrations, also pass integrationId, integrationKey, or connectionId so we know which one you mean.

​
api
object

Inline HTTP request spec, sent through the resolved connection's auth layer and base URL. Pair with connectionId, connectionKey, integrationId, or integrationKey to pick the connection.

​
code
string

Inline JavaScript executed in a sandbox. The module must export a function that receives { input, membrane, ... }. Its return value becomes the action output.

​
integrationId
string

ID of the integration to run the action on. When key is provided, looks up the action within this integration. When no connection is specified, runs against this integration's default connection.

​
integrationKey
string

Key of the integration to run the action on. When key is provided, looks up the action within this integration. When no connection is specified, runs against this integration's default connection.

​
connectionId
string

ID of the connection to run the action against. If a connection-level version of the action exists on this connection, that version is used; otherwise the integration-level or universal action is used.

​
connectionKey
string

Key of the connection to run the action against. Use when you have a stable key for the connection instead of an ID.

​
input
any

Input passed to the action, matching its input schema.

​
meta
object

Arbitrary metadata stored on the action run log.

Response

200 - application/json
​
output
object
​
actionRunId
string