Connect your own connector

POST
/v1/workspace-connectors/{name}/connections

Makes a connection of a connector that has a live version. The credentials are not in this body: save each in your vault first (POST /v1/connections, encrypted at rest) and give its id here. webhook verifies what the provider sends (a signing secret, a public key or a secret token, by the connector's declared scheme); handshakeToken answers an unsigned subscription check (needed when the connector declares one); primary is what its sends and live connection sign in with (needed when it declares either). host is one of the hosts the connector declares (needed when it declares more than one). With an agentId the agent answers at once; without it the connection waits as NEEDS_INPUT until POST /v1/connector-connections/{id}/bind. The answer carries webhookUrl: the address to give the provider.

Requires an API key with the workspace:write scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

name*string

The connector name: the last part of ws/<workspace>/<name>.

Request Body

application/json
  1. body
displayName*string

A name for this connection (1 to 120 characters).

Length1 <= length <= 120
credentials*

Vault ids: webhook, handshakeToken and primary, as the connector needs them.

host?string

Which declared host sends go to (optional when the connector declares one).

Length1 <= length <= 253
authType?string

How the primary credential is presented: bearer, basic, api_key, oauth2 or none.

Value in"oauth2""api_key""bearer""basic""none"
credentialPlacement?||

Where the primary credential goes on a request: a header, a path prefix holding {secret}, or a query parameter.

agentId?string

The agent that answers through the connection (optional).

Length1 <= length

Response Body

The connection, and the address to give the provider

application/json
  1. response
connectionId*string
Formatuuid
connectorId*string
Length1 <= length
displayName*string
status*string
host*string|null
webhookUrl*string
Length1 <= length
bound*boolean
Example Request
curl -X POST "https://api.vlayers.ai/v1/workspace-connectors/$CONNECTOR_NAME/connections" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "displayName": "Support bot",    "credentials": {      "webhook": "0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",      "primary": "0192f5c4-8b9c-7dbe-8f30-4b5c6d7e8f9a"    }  }'
Example Response
{  "connectionId": "0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",  "connectorId": "ws/0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45/telegram",  "displayName": "Support bot",  "status": "READY",  "host": "api.telegram.org",  "webhookUrl": "https://api.vlayers.ai/v1/connector-webhooks/ws%2F0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45%2Ftelegram/0192f5c3-7a8b-7cad-9e2f-3a4b5c6d7e89",  "bound": true}