The connector object

Shape of the Connector resource, a third-party integration like Zendesk, Slack, or Shopify.

A Connector represents one configured instance of a third-party integration, one Zendesk account, one Slack workspace, one Shopify store. Connectors expose the tools agents can call.

Object shape (summary)

{
  "id": "connector_64f1c0ef2ec711ef6dc1dcf",
  "type": "zendesk",
  "name": "Production Zendesk",
  "status": "connected",
  "status_reason": null,
  "is_active": true,
  "created_at": "2026-06-01T00:00:00.000Z",
  "updated_at": "2026-06-20T12:00:00.000Z"
}

Detail shape (with tool surface)

The single-connector endpoint adds a tools[] array listing every tool this connector type exposes. Use this to know which tool names you can assign to agents.

{
  "id": "connector_64f1c0...",
  "type": "zendesk",
  "name": "Production Zendesk",
  "status": "connected",
  "is_active": true,
  "tools": [
    {
      "name": "zendesk_get_ticket",
      "label": "Get Zendesk Ticket",
      "description": "Fetch a ticket by ID.",
      "type": "read",
      "requires_confirmation": false,
      "disabled": false
    }
  ]
}

Attributes

Field	Type	Notes
`id`	string	`connector_<24 hex>`.
`type`	string	e.g. `zendesk`, `slack`, `shopify`, `notion`, `freshdesk`, `stripe`. See the integrations directory for the full list.
`name`	string	Display name. Distinguishes multiple instances of the same `type` ("Production Zendesk" vs "Sandbox Zendesk").
`status`	enum	`"connected"` \| `"auth_failed"` \| `"token_expired"`. Drives agent deactivation cascades.
`status_reason`	string \| null	Human-readable reason when status is not `connected`.
`is_active`	boolean	Whether the connector is enabled. Inactive connectors are hidden from agent tool pickers.
`created_at`	ISO 8601	When the connector was added.
`updated_at`	ISO 8601	Bumped on status changes and reconfigurations.

The `tools[]` array (detail only)

Field	Type	Notes
`name`	string	Base tool name. Use this when assigning to an agent.
`label`	string	Human-friendly name shown in the dashboard.
`description`	string	LLM-facing description.
`type`	enum	`"read"` or `"write"`. Write tools require approval in chat (read tools auto-execute).
`requires_confirmation`	boolean	Whether agents must ask before executing.
`disabled`	boolean	`true` if this tool has been turned off for this connector instance via the dashboard.

Why credentials are never returned

API keys, OAuth tokens, refresh tokens, signing secrets, none of these are ever exposed via the API. They're encrypted at rest and only used server-side when agents call tools. Even the masked-credential hint shown in the dashboard catalog is computed at request time and not part of the public connector object.

📘

Connector creation is dashboard-only in v1

OAuth flows for connectors require redirect URIs and browser-driven user consent, which doesn't fit the headless REST model. Add and disconnect connectors in the dashboard; read their state via the API.