Connectors¶

Audience: Everyone / Developers · Tags: connectors, marketplace, integrations

A connector is how a flow talks to the outside world. SnapLink's core model is Trigger → Action(s) — a connector supplies the trigger, the action(s), or both. Six connectors exist today: one trigger (Webhook) and five actions (REST, Email, Slack, Microsoft Teams, HubSpot).

The connector model¶

Every connector is described by:

Field	Meaning
`connectorKey`	Stable id used in flow definitions, e.g. `slack`, `rest_sdk`, `webhook`.
`authType`	How it authenticates: `none` (no credential — e.g. REST, Webhook), `oauth` (Slack, Teams, HubSpot), or `custom` (Email — operator-configured SMTP, not per-user OAuth).
Capabilities	The trigger type(s) and/or action type(s) it exposes, e.g. `send_message`, `request`, `send_email`.

Each capability declares an input schema — the exact fields it accepts, each marked required or optional with a data type (string, number, object, …). The field tables on each connector's page below are that schema. SnapLink validates a flow against these schemas before it can go active — missing a required field fails validation, not the run.

The marketplace lifecycle¶

Slack, Teams, and HubSpot are installed per-workspace and walk a lifecycle before they can run in a live flow:

installed → configured → certified → active
    ↓            ↓            ↓          ↓
    └──────→ disabled / deprecated ←─────┘

Any of installed, configured, certified, or active can move to disabled or deprecated at any time (e.g. to pause a connector or retire it). disabled can move back to active to re-enable it. deprecated is terminal.

State	Meaning
`installed`	Added to the workspace. Not yet usable in an active flow.
`configured`	Marked ready to certify (settings/credential wiring acknowledged).
`certified`	Passed a certification check (SnapLink calls the connector's health check). Certifying with a failing check returns `422 CERTIFICATION_FAILED` and does not advance the state.
`active`	Usable in live flows.
`disabled`	Paused — flows using it will fail validation until re-enabled.
`deprecated`	Retired. Terminal.

Email and REST don't go through this lifecycle — they have authType custom/none and are always available in every workspace without an install step. Webhook (the trigger) is likewise always available and isn't a marketplace item at all — there's nothing to install or authenticate.

Browsing and installing (walkthrough)¶

All calls need Authorization: Bearer $TOKEN (see the API Reference for how to get one). Base URL: https://api.snaplink.cloudsolutionaccelerators.com/api/v1.

1. Browse the catalog

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/connectors?q=slack" \
  -H "Authorization: Bearer $TOKEN"

Omit ?q= to list everything. GET /marketplace/categories returns each category with a connector count.

2. Look at one connector

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/connectors/slack" \
  -H "Authorization: Bearer $TOKEN"

3. Install it into your workspace

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"slack"}'
# → 201 { "data": { "id": "inst_...", "state": "installed", ... } }

4. Walk the lifecycle to active

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"slack","action":"configure"}'

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"slack","action":"certify"}'

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"slack","action":"activate"}'

action is one of configure | certify | activate | disable | deprecate.

5. See what's installed

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/ws_abc123" \
  -H "Authorization: Bearer $TOKEN"

6. Analytics

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/analytics" -H "Authorization: Bearer $TOKEN"
curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/analytics/slack" -H "Authorization: Bearer $TOKEN"

Returns install counts, run counts, and success rate per connector.

Envelope note: marketplace endpoints return { "data": ... } on success — no ok field. This differs from most of the rest of the API, which wraps responses as { "ok": true, "data": ... } (see the API Reference). Marketplace errors still use the standard error envelope on failure.

Once a connector is active (or, for REST/Email, without any install step), reference its connectorKey in a flow definition's actions array. Snap Studio and the marketplace install flow are the same mechanism — approving a flow that needs a connector installs it through this same API.

The lower-level `/connections` API¶

For developers who want to wire a credential directly (bypassing the marketplace lifecycle), there's a separate, lower-level registry:

Method	Path	Purpose
GET	`/connections?workspaceId=`	List connections in a workspace
POST	`/connections`	Create one: `{workspaceId, connectorDefinitionId, name, credential?: {credentialType, secret}}`
GET/PUT/DELETE	`/connections/:id`	Read, rename, or remove
POST	`/connections/:id/validate`	Check the credential works
GET	`/connections/:id/health`	Current health status

credentialType is one of api_key | oauth_access | oauth_refresh | signing_secret | basic_auth. This is a building block for custom integrations — the recommended path for end users is the marketplace install flow above.

Available connectors¶

Connector	Type	`connectorKey`	Auth	Docs
Webhook	Trigger	`webhook`	None (per-flow secret in the URL)	webhook.md
REST / HTTP Request	Action	`rest_sdk`	None	rest.md
Email (SMTP)	Action	`email`	Custom (operator SMTP)	email.md
Slack	Action	`slack`	OAuth	slack.md
Microsoft Teams	Action	`teams`	OAuth	teams.md
HubSpot	Action	`hubspot`	OAuth	hubspot.md

There is no public marketplace where third parties publish their own connectors yet, and no scheduled/polling trigger — Webhook is the only trigger type today. Developers can build new connectors with the Connector SDK; see the Developer Center.

If something goes wrong¶

An action failing inside a run (auth, rate limiting, bad input, a blocked URL) is a run-time failure, not a marketplace problem — start at Connector failed. Trouble installing or transitioning a connector's lifecycle state usually means it's not workspace-member-authorized, or you skipped a lifecycle step (you can't activate before certify).