Connector Instances

An instance is a workspace-scoped installation of a connector. One team may have multiple Slack instances (e.g., one for production alerts, one for general notifications), all derived from the same slack definition.

Endpoints

Method	Path	Description	Auth
GET	/connectors/instances	List instances	JWT
POST	/connectors/instances	Create an instance	JWT
GET	/connectors/instances/:id	Get an instance	JWT
PATCH	/connectors/instances/:id	Update an instance	JWT
DELETE	/connectors/instances/:id	Delete an instance	JWT
POST	/connectors/instances/:id/test	Test the connection	JWT

---

Instance Object

All instance endpoints return objects with this shape:

{
  "id": "inst_abc123",
  "connectorKey": "slack",
  "displayName": "Team Slack",
  "status": "pending_auth",
  "enabled": true,
  "config": {},
  "lastHealthCheck": null,
  "healthMessage": null,
  "createdAt": "2026-03-23T10:00:00Z",
  "updatedAt": "2026-03-23T10:00:00Z"
}

Status Values

Value	Meaning
pending_auth	Installed but credentials have not been provided yet
active	Authenticated and successfully health-checked
error	Health check failed or credentials expired
inactive	Manually disabled via enabled: false

---

GET /connectors/instances

List all connector instances in the current workspace.

Request

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Max results per page (default: 20, max: 100)
offset	number	No	Pagination offset (default: 0)

Response

Response Example

{
  "data": [
    {
      "id": "inst_abc123",
      "connectorKey": "slack",
      "displayName": "Team Slack",
      "status": "active",
      "enabled": true,
      "config": {},
      "lastHealthCheck": "2026-03-23T10:00:00Z",
      "healthMessage": "OK",
      "createdAt": "2026-03-20T08:00:00Z",
      "updatedAt": "2026-03-23T10:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasNextPage": false
  }
}

Code Examples

cURL

curl "https://api.chainabit.com/api/v1/connectors/instances?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const BASE_URL = process.env.BASE_URL;
const TOKEN = process.env.TOKEN;

const response = await fetch(`${BASE_URL}/connectors/instances`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data, meta } = await response.json();

Python

import requests, os

BASE_URL = os.environ["BASE_URL"]
TOKEN = os.environ["TOKEN"]

response = requests.get(
    f"{BASE_URL}/connectors/instances",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
result = response.json()
data, meta = result["data"], result["meta"]

---

POST /connectors/instances

Create a new connector instance in the current workspace. The instance starts with status pending_auth until credentials are provided.

Request

Request Body

Field	Type	Required	Description
connectorKey	string	Yes	The connector definition key (e.g. slack, sql-database)
displayName	string	Yes	A human-readable name for this instance (max 255 characters)
config	object	No	Connector-specific configuration (validated against the definition's configSchema)

Request DTO

{
  "connectorKey": "slack",
  "displayName": "Team Slack"
}

Response

Response Example

201 Created

{
  "data": {
    "id": "inst_abc123",
    "connectorKey": "slack",
    "displayName": "Team Slack",
    "status": "pending_auth",
    "enabled": true,
    "config": {},
    "lastHealthCheck": null,
    "healthMessage": null,
    "createdAt": "2026-03-23T10:00:00Z",
    "updatedAt": "2026-03-23T10:00:00Z"
  }
}

Save the instance id. You will need it to store credentials and execute tools.

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/connectors/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorKey": "slack",
    "displayName": "Team Slack"
  }'

cURL — SQL Database

curl -X POST https://api.chainabit.com/api/v1/connectors/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorKey": "sql-database",
    "displayName": "Production DB"
  }'

JavaScript

const response = await fetch(`${BASE_URL}/connectors/instances`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    connectorKey: "slack",
    displayName: "Team Slack",
  }),
});
const { data } = await response.json();
// Save data.id — you need it for authentication and tool execution

Python

response = requests.post(
    f"{BASE_URL}/connectors/instances",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"connectorKey": "slack", "displayName": "Team Slack"},
)
data = response.json()["data"]
instance_id = data["id"]

---

GET /connectors/instances/:id

Get the details of a specific connector instance.

Request

Path Parameters

Parameter	Type	Description
id	string	Instance ID

Response

Response Example

{
  "data": {
    "id": "inst_abc123",
    "connectorKey": "slack",
    "displayName": "Team Slack",
    "status": "active",
    "enabled": true,
    "config": {},
    "lastHealthCheck": "2026-03-23T10:00:00Z",
    "healthMessage": "OK",
    "createdAt": "2026-03-20T08:00:00Z",
    "updatedAt": "2026-03-23T10:00:00Z"
  }
}

Code Examples

cURL

curl https://api.chainabit.com/api/v1/connectors/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(`${BASE_URL}/connectors/instances/${INSTANCE_ID}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await response.json();

Python

response = requests.get(
    f"{BASE_URL}/connectors/instances/{INSTANCE_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()["data"]

---

PATCH /connectors/instances/:id

Update an instance's display name, configuration, or enabled state. All fields are optional — only send the fields you want to change.

Request

Path Parameters

Parameter	Type	Description
id	string	Instance ID

Request Body

Field	Type	Required	Description
displayName	string	No	New display name (max 255 characters)
config	object	No	Updated configuration
enabled	boolean	No	false disables the instance (status becomes inactive)

Request DTO

{
  "displayName": "Production Slack",
  "enabled": true
}

Response

Response Example

Returns the updated instance object.

{
  "data": {
    "id": "inst_abc123",
    "connectorKey": "slack",
    "displayName": "Production Slack",
    "status": "active",
    "enabled": true,
    "config": {},
    "lastHealthCheck": "2026-03-23T10:00:00Z",
    "healthMessage": "OK",
    "createdAt": "2026-03-20T08:00:00Z",
    "updatedAt": "2026-03-23T11:00:00Z"
  }
}

Code Examples

cURL

curl -X PATCH https://api.chainabit.com/api/v1/connectors/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production Slack",
    "enabled": true
  }'

JavaScript

const response = await fetch(`${BASE_URL}/connectors/instances/${INSTANCE_ID}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ displayName: "Production Slack", enabled: true }),
});
const { data } = await response.json();

Python

response = requests.patch(
    f"{BASE_URL}/connectors/instances/{INSTANCE_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"displayName": "Production Slack", "enabled": True},
)
data = response.json()["data"]

---

DELETE /connectors/instances/:id

Delete a connector instance and all associated credentials and tool data.

Request

Path Parameters

Parameter	Type	Description
id	string	Instance ID

Response

Response Example

Returns the deleted instance object.

{
  "data": {
    "id": "inst_abc123",
    "connectorKey": "slack",
    "displayName": "Production Slack",
    "status": "active",
    "enabled": true,
    "config": {},
    "lastHealthCheck": "2026-03-23T10:00:00Z",
    "healthMessage": "OK",
    "createdAt": "2026-03-20T08:00:00Z",
    "updatedAt": "2026-03-23T11:00:00Z"
  }
}

Code Examples

cURL

curl -X DELETE https://api.chainabit.com/api/v1/connectors/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(`${BASE_URL}/connectors/instances/${INSTANCE_ID}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await response.json();

Python

response = requests.delete(
    f"{BASE_URL}/connectors/instances/{INSTANCE_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()["data"]

---

POST /connectors/instances/:id/test

Send a health-check request to the external service to verify the connector is reachable and credentials are valid. The instance status and lastHealthCheck fields are updated based on the result.

Request

Path Parameters

Parameter	Type	Description
id	string	Instance ID

Response

Response Example

{
  "data": {
    "healthy": true,
    "message": "Connection successful",
    "latencyMs": 212
  }
}

Response Fields

Field	Type	Description
healthy	boolean	true if the external service responded successfully
message	string | null	Human-readable status message or error detail
latencyMs	number	Round-trip latency in milliseconds

If healthy is false, check credential status to confirm credentials are stored, then re-authenticate if needed.

Code Examples

cURL

curl -X POST https://api.chainabit.com/api/v1/connectors/instances/$INSTANCE_ID/test \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const response = await fetch(
  `${BASE_URL}/connectors/instances/${INSTANCE_ID}/test`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await response.json();

Python

response = requests.post(
    f"{BASE_URL}/connectors/instances/{INSTANCE_ID}/test",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = response.json()["data"]