Skip to main content
POST
/
integrations
Create a new integration
curl --request POST \
  --url https://api.getmembrane.com/integrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uuid": "<string>",
  "key": "<string>",
  "name": "<string>",
  "description": "<string>",
  "meta": {},
  "logoUri": "<string>",
  "externalAppId": "<string>",
  "externalAppUuid": "<string>",
  "oAuthCallbackUri": "<string>",
  "logoBase64": "<string>",
  "connectorVersion": "<string>",
  "connectorId": "<string>",
  "connectorUuid": "<string>",
  "connectorKey": "<string>",
  "parameters": {},
  "optionsConfig": {}
}
'
{
  "id": "<string>",
  "name": "<string>",
  "logoUri": "<string>",
  "uuid": "<string>",
  "key": "<string>",
  "description": "<string>",
  "meta": {},
  "state": "BUILDING",
  "errors": [
    {
      "message": "<string>",
      "type": "bad_request",
      "key": "<string>",
      "data": {},
      "stack": {},
      "causedByError": "<unknown>",
      "logs": [
        {}
      ]
    }
  ],
  "revision": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "archivedAt": "<string>",
  "isDeactivated": true,
  "isReadOnly": true,
  "connectorId": "<string>",
  "connectorVersion": "<string>",
  "oAuthCallbackUri": "<string>",
  "parameters": {},
  "hasMissingParameters": true,
  "hasDocumentation": true,
  "hasOperations": true,
  "operationsCount": 123,
  "hasData": true,
  "dataCollectionsCount": 123,
  "hasEvents": true,
  "eventsCount": 123,
  "hasGlobalWebhooks": true,
  "hasUdm": true,
  "isTest": true,
  "externalAppId": "<string>",
  "authType": "integration-app-token",
  "optionsConfig": {},
  "connection": {
    "id": "<string>",
    "name": "<string>",
    "userId": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "tenantId": "<string>",
    "key": "<string>",
    "isTest": true,
    "connected": true,
    "disconnected": true,
    "isDefunct": true,
    "state": "BUILDING",
    "errors": [
      {
        "message": "<string>",
        "type": "bad_request",
        "key": "<string>",
        "data": {},
        "stack": {},
        "causedByError": "<unknown>",
        "logs": [
          {}
        ]
      }
    ],
    "requestError": {
      "message": "<string>",
      "type": "bad_request",
      "key": "<string>",
      "data": {},
      "stack": {},
      "causedByError": "<unknown>",
      "logs": [
        {}
      ]
    },
    "error": {
      "message": "<string>",
      "type": "bad_request",
      "key": "<string>",
      "data": {},
      "stack": {},
      "causedByError": "<unknown>",
      "logs": [
        {}
      ]
    },
    "integrationId": "<string>",
    "connectorId": "<string>",
    "externalAppId": "<string>",
    "connectorVersion": "<string>",
    "authOptionKey": "<string>",
    "lastActiveAt": "<string>",
    "nextCredentialsRefreshAt": "<string>",
    "nextRetryTimestamp": "<string>",
    "retryAttempts": 123,
    "canTest": true,
    "canRefreshCredentials": true,
    "archivedAt": "<string>",
    "isDeactivated": true,
    "meta": {},
    "buildingAgentSessionId": "<string>",
    "clientAction": {
      "type": "connect",
      "description": "<string>",
      "uiUrl": "<string>",
      "agentInstructions": "<string>"
    }
  },
  "spec": {}
}

Authorizations

Authorization
string
header
required

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

Body

application/json
uuid
string

Stable unique identifier (UUID). Can be provided on create; otherwise generated. Must be unique across elements of this type.

key
string

Stable key for referencing the element (e.g. in selectors). Unique per (parent, integration) scope. Generated from name if not provided on create.

name
string

Display name. Optional on create; used to generate key when key is omitted.

description
string

Optional human-readable description.

meta
object

Optional key-value metadata.

logoUri
string
externalAppId
string
externalAppUuid
string
oAuthCallbackUri
logoBase64
string
connectorVersion
string
connectorId
string
connectorUuid
string
connectorKey
string

Key of the connector; alternative to connectorId. Resolved to connectorId by the API.

parameters
object
optionsConfig
object

Response

200 - application/json
id
string
required

Internal database ID of the element. Assigned by the API; unique per element.

name
string
required

Display name. Always present in API responses (filled by API if not set on create).

logoUri
string
required
uuid
string

Stable unique identifier (UUID). Can be provided on create; otherwise generated. Must be unique across elements of this type.

key
string

Stable key for referencing the element (e.g. in selectors). Unique per (parent, integration) scope. Generated from name if not provided on create.

description
string

Optional human-readable description.

meta
object

Optional key-value metadata.

state
enum<string>

Current lifecycle or health state (e.g. READY, SETUP_FAILED, CONFIGURATION_ERROR, BUILDING). Set by the engine during setup and validation.

Available options:
BUILDING,
CLIENT_ACTION_REQUIRED,
CONFIGURATION_ERROR,
SETUP_FAILED,
READY,
DISCONNECTING
errors
object[]

Validation or setup errors when state is not READY.

revision
string

Opaque revision token; changes on each update. Used for optimistic concurrency.

createdAt
string

ISO date when the element was created.

updatedAt
string

ISO date when the element was last updated.

archivedAt
string
isDeactivated
boolean
isReadOnly
boolean

When true, the element cannot be modified (e.g. published package elements or elements from another workspace).

connectorId
string
connectorVersion
string
oAuthCallbackUri
string
parameters
object
hasMissingParameters
boolean
hasDocumentation
boolean
hasOperations
boolean
operationsCount
number
hasData
boolean
dataCollectionsCount
number
hasEvents
boolean
eventsCount
number
hasGlobalWebhooks
boolean
hasUdm
boolean
isTest
boolean
externalAppId
string
authType
enum<string>
Available options:
integration-app-token,
membrane-token,
oauth2,
oauth1,
client-credentials,
proxy
optionsConfig
object
connection
object
spec
object