Connectors

A connector is a named HTTPS system the firm can call from an automation, and from Capsure AI when the connector allows it. Administration, the designer, and agent profiles read the same definition.

Method	Path	What it does
GET	/api/v1/x/connectors	Connectors you may see, and whether each is active. No secrets
POST	/api/v1/x/connectors	Create an inactive draft
GET	/api/v1/x/connectors/{id}	The definition, operations, definitionRevision, and secretSet
PUT	/api/v1/x/connectors/{id}	Save the draft. The published call stays as it is
POST	/api/v1/x/connectors/{id}/secret	Set or rotate the secret. The response is { secretSet: true }
POST	/api/v1/x/connectors/{id}/test	Call it once. Does not publish
POST	/api/v1/x/connectors/{id}/publish	Copy the draft onto the published call and turn it on
POST	/api/v1/x/connectors/{id}/activate	Turn the published call back on. Does not copy the draft
POST	/api/v1/x/connectors/{id}/deactivate	Stop every revision immediately
DELETE	/api/v1/x/connectors/{id}	Remove it. The key can be used again. The stored secret is left in place

Every call needs admin.connectors.manage.

The secret is write-only. The response never includes the value, and you do not choose where it is stored.

baseUrl is HTTPS only. No userinfo, query, or fragment. Loopback, link-local, metadata addresses, and Capsure’s own hosts are rejected, so a connector cannot call this API. Redirects are not followed.

auth is none, api_key, or bearer. effect on an operation is read, write, or destructive. The HTTP method does not decide the effect. A search that uses POST is still read.

surfaces is automations, assistant, or both. useRoleIds is who may run it. Empty is rejected. Authoring and running are different checks.

POST /api/v1/x/connectors with this body saves an inactive draft. Replace useRoleIds with a role id from the firm.

{
  "connectorKey": "northwind_lookup",
  "name": "Northwind lookup",
  "baseUrl": "https://lookup.northwind.example",
  "auth": "bearer",
  "surfaces": "automations",
  "useRoleIds": ["00000000-0000-4000-8000-000000000001"],
  "operations": [
    {
      "key": "company",
      "label": "Company",
      "description": "Read one company",
      "method": "GET",
      "effect": "read",
      "path": "/companies/{id}",
      "parameters": [
        { "name": "id", "valueType": "string", "required": true, "in": "path" }
      ],
      "outputs": [
        { "name": "name", "path": "$.name" }
      ]
    }
  ]
}

POST /api/v1/x/connectors/{id}/secret sends { "secret": "replace-with-the-real-secret" }. The response is { "secretSet": true }. Publish with POST /api/v1/x/connectors/{id}/publish and an empty body.

Publish bumps definitionRevision when the base URL, the auth scheme, or an operation’s method, path, effect, parameter schema, or outputs change. A label, a description, or a variable value does not. A published automation keeps the revision it was published with and fails that step when the revision differs.

Active means the published call is on. It does not mean every user may call it. Turning it off stops every revision immediately. Turning it on resumes the published call and leaves unpublished edits in the draft.

There is no route that runs a connector as a general effect. Test is the one call this API makes. A live call is a step in a published automation.