Abilities

create-connection Create Connection
delete-connection Delete Connection
list-connections List Connections
update-connection Update Connection

Create Connection

lh-connections/create-connection

Create a new site-level connection. Credentials are encrypted at rest. Note: for sensitive credential types, prefer entering values via the Network Admin -> Network Tools -> Connections screen directly rather than this ability, so secret values never pass through a conversation. Requires install_plugins.

Parameter	Type	Required	Description
`site_id`	integer	Yes	Site ID.
`type`	string	Yes	Connection type. One of: `smtp`, `imap`, `github`.
`slug`	string	Yes	Unique slug, e.g. the from-email address.
`label`	string	Yes	Human-readable label.
`credentials`	object	Yes	Key-value credential fields – shape depends on type, see that type's registered credential fields.
`task_id`	integer	No	Optional. The lh-tasks task this call is working on. Pass with `claim_token`: the call is refused unless you hold that claim, and a successful call renews it.
`claim_token`	string	No	Optional. The `claim_token` from claim-next-task for `task_id`. Required when `task_id` is given.

Delete Connection

lh-connections/delete-connection Destructive Idempotent

Delete a site-level connection by site_id, type, and slug. Requires install_plugins.

Parameter	Type	Required	Description
`site_id`	integer	Yes	Site ID.
`type`	string	Yes	Connection type. One of: `smtp`, `imap`, `github`.
`slug`	string	Yes	Slug of the connection to delete.
`task_id`	integer	No	Optional. The lh-tasks task this call is working on. Pass with `claim_token`: the call is refused unless you hold that claim, and a successful call renews it.
`claim_token`	string	No	Optional. The `claim_token` from claim-next-task for `task_id`. Required when `task_id` is given.

List Connections

lh-connections/list-connections Read-only Idempotent

List all site-level connections, optionally filtered by site_id and/or type. Returns the names of the credential fields that are set, never their values. Requires install_plugins.

Parameter	Type	Required	Default	Description
`site_id`	integer	No		Site ID to filter by. Defaults to current site.
`type`	string	No		Connection type to filter by. Omit for all types. One of: `smtp`, `imap`, `github`.

Update Connection

lh-connections/update-connection Destructive Idempotent

Update an existing site-level connection. Omitted credential fields are preserved. Note: for sensitive credential types, prefer updating values via the Network Admin -> Network Tools -> Connections screen directly rather than this ability, so secret values never pass through a conversation. Requires install_plugins.

Parameter	Type	Required	Description
`site_id`	integer	Yes	Site ID.
`type`	string	Yes	Connection type. One of: `smtp`, `imap`, `github`.
`slug`	string	Yes	Slug of the connection to update.
`label`	string	No	Updated label (optional).
`credentials`	object	No	Credential fields to update. Omitted fields are preserved.
`task_id`	integer	No	Optional. The lh-tasks task this call is working on. Pass with `claim_token`: the call is refused unless you hold that claim, and a successful call renews it.
`claim_token`	string	No	Optional. The `claim_token` from claim-next-task for `task_id`. Required when `task_id` is given.