Connectors in Code
Declare connectors as YAML files in your project. Every deploy creates, updates, or retires them for its environment, and a rollback restores them.
On this page
Connectors can be created in the dashboard, through the REST API or Connic MCP, or declared in your project under connectors/. Deploys create, update, and retire connectors declared in code, so their settings are versioned with the agents they link. Every connector type except Slack can be declared in code.
Each file declares one connector. The file name without .yaml is the connector's key and identity: connectors/order-events.yaml has the key order-events.
Declare a connector
type: kafka
mode: inbound
name: Order events # optional, defaults to the file name
connection: orders-kafka-staging # saved Connection, by name
bridge: staging-cluster # Bridge name or ID
config: # connector fields, same names as config_json in the REST API and MCP
topic: ${ORDER_EVENTS_TOPIC}
agents:
- order-processor
- name: audit-logger
files_required: true
environments: # omit to deploy to every environment
Staging: {}
Production:
connection: orders-kafka-prod
bridge: prod-cluster
config:
group_id: connic-orders-prod| Field | Description |
|---|---|
| type | Connector type, for example webhook, kafka, email, or twilio_messaging. Twilio Voice is twilio and Telnyx Voice is telnyx. http is accepted for webhook. |
| mode | inbound, outbound, or sync. Required when the type supports more than one mode; otherwise it defaults to the only mode. |
| name | Display name. Defaults to the file name. |
| connection | Name of a saved Connection. Required for types that use Connections. |
| bridge | Bridge name or ID, for types that can use the Bridge. |
| domain | Hostname of an active custom domain, for types that support custom domains. |
| config | Connector fields, with the same names as config_json in the REST API and Connic MCP. The deploy rejects unknown fields. |
| agents | Linked agents. Every connector links at least one agent, and each must exist in agents/. |
| environments | Environments that get the connector, with optional overrides. Omit it to deploy to every environment. |
Files must sit directly in connectors/ and use the .yaml extension. A file name starts with a letter or digit, contains only letters, digits, -, and _, and has at most 100 characters.
Link agents
List agents by name, or as objects with files_required and, on outbound connectors, outbound. With files_required: true, a run fails before it starts when the input has no files or a file was omitted.
type: webhook
mode: outbound
config:
outbound_url: ${ORDER_RESULTS_URL}
agents:
- name: order-processor
outbound: { usage: automatic, source: [order-events] } # keys of other connector files
- name: invoice-checker
outbound: { usage: middleware, action_name: send_invoice_result }outbound.usage is automatic, agent_tool, or middleware, matching the outbound connector modes. Agent-tool and middleware links need an action_name that starts with a lowercase letter and contains only lowercase letters, digits, and underscores. An automatic link can set source to the keys of other connector files; it then sends only for runs those connectors started. Without outbound, an outbound connector sends after every completed run.
Environments and overrides
Without environments, the connector is deployed to every environment with the same settings. With it, the connector exists only in the listed environments. Keys are environment names and must match exactly. Staging: {} deploys the file unchanged.
An override can set name, connection, bridge, domain, agents, and config. agents replaces the list. config is merged key by key, so Production in the example keeps topic and adds group_id. A key that matches no environment in the project fails the deploy.
Variables and secrets
${NAME} reads a Variable of the target environment, with the same syntax as mcp_servers in agent YAML. References work in config, connection, bridge, and domain. Connic resolves them once, when the deploy starts. A missing Variable fails the deploy, and a changed Variable takes effect with the next deploy.
Secrets that you supply, such as a Telegram bot_token or a Stripe webhook_secret, must be a ${NAME} reference. A literal value fails the deploy.
Connections and Bridges
Kafka, SQS, S3, PostgreSQL, Email, Twilio Voice, Twilio Messaging, Telnyx Voice, and Telnyx Messaging connectors take their credentials from a Connection, so the file never contains them. Reference the Connection by name with connection, which these types require. Fields that belong to the Connection, such as Kafka bootstrap servers, are rejected in config.
Connections are reusable credential sets for the whole project. Manage them in Project Settings → Connections, which lists the connectors using each Connection per environment, or through the REST API and Connic MCP. Rotating a Connection updates every connector that uses it, without a deploy. A Connection can't be deleted while a connector uses it. To give each environment its own credentials, set connection in the environment overrides.
bridge takes the name or ID of a Bridge. domain takes the hostname of an active custom domain of the project.
Values Connic generates
Connic generates some values itself: webhook URLs, the secrets of webhook, WebSocket, and MCP connectors, the outbound webhook signing secret, the S3 URL secret, and the Telegram secret token. Leave them out of the file; connic lint rejects them. Connic creates them on the first deploy, keeps them across later deploys, and shows them on the connector in the dashboard as usual. An omitted Kafka group_id is generated as well.
Voice connectors
Twilio Voice and Telnyx Voice connectors set config.phone_number in E.164 format. The deploy looks the number up in the referenced Connection. A voice connector links exactly one agent, and that agent needs voice_config.
type: twilio
connection: support-twilio
config:
phone_number: "+4930123456"
agents:
- support-voiceWhat deploys change
Every deploy resolves the files for its environment into a snapshot that is stored with the deployment. Environment names, Connections, Bridges, Variables, and phone numbers are checked at this point, and any error fails the deploy before the build starts. The deployment log lists the changes the snapshot makes when it goes live:
Connector changes on activation:
create: connectors/order-events.yaml (kafka)
update: connectors/support-inbox.yaml (email)
retire: connectors/legacy-orders.yaml (sqs)Activating a deployment applies its snapshot. This happens when a new deploy goes live, when you redeploy an older commit (Variables are resolved again), and when you activate an older deployment as a rollback. connic dev, test runs, and the deploy gate never change connectors.
Retired connectors
A connector that the active deployment no longer declares is retired. A deployment without a connectors/ folder retires every code connector in its environment. A retired connector is paused and keeps its URL, secrets, agent links, provider bindings, and run history. It doesn't count against the active connector limit and can't be resumed. Connic doesn't delete retired connectors; delete one from the dashboard when you no longer need it.
When a later deployment declares the file again with the same type, the connector comes back with its URL, secrets, and previous pause state. A rollback to a deployment that declared it restores that deployment's config and links, using the Variable values captured at that deploy.
Type changes and renames
name instead.Changing a file's type also retires the old connector and creates a new one.
Pause state and limits
New code connectors start active. This includes Kafka, SQS, and PostgreSQL connectors, which start paused when created in the dashboard. To hold off consuming in an environment, leave that environment out of environments until it is ready. Deploys never change the pause state of an existing connector; pause and resume it in the dashboard. The active connector limit still applies, and a new connector over the limit stays paused.
Phone numbers, senders, and bots
Two active connectors can't use the same phone number, messaging sender, or Telegram bot, even in different environments. A deploy that would cause this fails. A retired connector gives up its number, sender, or bot when another connector needs it, and takes it back when it returns.
Creating or updating a connector replaces provider settings that Connic didn't create, such as an existing Twilio incoming-call webhook, and writes the previous values to the connector logs. The Twilio Voice, Twilio Messaging, Telnyx Voice, Telnyx Messaging, and Telegram pages list what each one replaces.
Name rules
A code connector and a dashboard connector can't share a name in the same environment. A deploy that would create the clash fails. The dashboard, REST API, and Connic MCP refuse to create or rename a dashboard connector to a name that a code connector uses, including retired ones. connic lint reports two files that use the same name in the same environment.
When a connector change fails
Activation is all or nothing. If a provider call fails, for example because the Twilio API returns an error, nothing is activated and the previous deployment stays live.
To go live without the failing connectors, click Deploy anyway on the deployment page. It redeploys the commit and skips the connectors that fail. For a rollback, choose Activate anyway in the activate dialog, or call POST /v1/projects/{project_id}/deployments/{deployment_id}/activate?force=true. Skipped connectors keep their previous state, and the next activation tries them again.
Before a rollback, the activate dialog lists the connectors it would create, update, bring back, or retire.
In the dashboard
Code connectors show an In code badge. The dashboard disables editing, deleting, and linking agents for them, and the REST API and Connic MCP return 409. Pause and resume stay available. Retired connectors also show a Retired badge and can be deleted.
Validate with connic lint
connic lint checks connector files offline: their shape, types and modes, generated fields, ${NAME} syntax, whether linked agents and outbound source keys exist, and name clashes between files. Environment names, Connections, Bridges, Variables, and phone-number availability are checked when the deploy starts. connic deploy runs lint first and uploads connectors/ with the rest of the project.