Skip to main content
PUT
replace-integration

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string
required

Integration id, uuid, or key to replace

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

External app id; alternative to connectorId — resolves to the app's default connector.

externalAppUuid
string
appUuid
string

[INTERNAL] Deprecated: resolved to externalAppId

oAuthCallbackUri
logoBase64
string
connectorVersion
string
connectorId
string

ID of the connector this integration uses.

connectorUuid
string
connectorKey
string

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

parameters
object

Connector-specific parameters (e.g. OAuth { clientId, clientSecret, scopes }).

optionsConfig
object
intent
string

[Experimental] Intent-based instruction for an agent to configure this element.

Response

200 - application/json

Replace an existing integration, or create it with the provided key when it does not exist.

name
string
required

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

id
string
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).

logoUri
string

Resolved app logo for this element (integration -> connector -> external app -> favicon).

connectorId
string
connectorVersion
string
oAuthCallbackUri
string
parameters
any
hasMissingParameters
boolean
hasDocumentation
boolean
hasUdm
boolean
isTest
boolean
externalAppId
string
appUuid
string

[INTERNAL] Deprecated: Use externalAppId instead

authType
enum<string>
Available options:
integration-app-token,
membrane-token,
oauth2,
oauth1,
client-credentials,
proxy
optionsConfig
object
spec
any
appUri
string
isCustom
boolean

Marks integrations derived from workspace-owned, non-public connectors or external apps.