Self-Integration

Connect to any external app and perform actions on it. Uses the Membrane API.

Making API Requests

All requests go to ${MEMBRANE_API_URL:-https://api.getmembrane.com} with a Bearer token:

Authorization: Bearer $MEMBRANE_TOKEN
Content-Type: application/json

Get the API token from the Membrane dashboard.

Workflow

Step 1: Get a Connection

A connection is an authenticated link to an external app (e.g. a user's Slack workspace, a HubSpot account). You need one before you can run actions.

1a. Check for existing connections

GET /connections

Look for a connection matching the target app. Key fields: id, name, connectorId, disconnected.

If a matching connection exists and disconnected is false, skip to Step 2.

1b. Find a connector

A connector is a pre-built adapter for an external app. Search by app name:

GET /search?q=slack

Look for results with elementType: "connector". Use element.id as connectorId in step 1d.

If nothing is found, go to step 1c to build a connector.

1c. Build a connector (if none exists)

Create a Membrane Agent session to build a connector:

POST /agent/sessions with body {"prompt": "Build a connector for Slack (https://slack.com)"}

Adjust the prompt to describe the actual app you need. Poll GET /agent/sessions/{sessionId}?wait=true&timeout=30 until state is "idle" or status is "completed".

You can send follow-up instructions via POST /agent/sessions/{sessionId}/message or abort via POST /agent/sessions/{sessionId}/interrupt.

After the connector is built, search for it again (step 1b).

1d. Request a connection

Create a connection request so the user can authenticate with the external app:

POST /connection-requests with body {"connectorId": "cnt_abc123"}

The response includes a url. Tell the user to open the url to complete authentication (OAuth, API key, etc.).

1e. Check connection result

Poll until the user completes authentication:

GET /connection-requests/{requestId}

• status: "pending" — user hasn't completed yet, poll again.
• status: "success" — done. Use resultConnectionId as the connection ID going forward.
• status: "error" — failed. Check resultError for details.

Step 2: Get an Action

An action is an operation you can perform on a connected app (e.g. "Create task", "Send message", "List contacts").

2a. Search for actions

Search using a natural language description of what you want to do:

GET /actions?connectionId=con_abc123&intent=send+a+message&limit=10

Each result includes id, name, description, inputSchema (what parameters the action accepts), and outputSchema (what it returns).

If no suitable action exists, go to step 2b.

2b. Build an action (if none exists)

Use Membrane Agent. ALWAYS include the connection ID in the prompt: