Connectors API
A connector plugs Fibric into a system you already run, software or hardware, and advertises its capabilities by intent over MCP. This page documents installing a connector from the marketplace, listing and inspecting installed connectors, running a connection test, and uninstalling. What a connector is conceptually is covered in Connectors.
Shared conventions, including authentication, pagination, the Idempotency-Key header, and the error envelope, are defined in the API overview. Error codes are catalogued in Errors.
The connector object
An installed connector is an instance of a marketplace listing, bound to your tenant with its own credentials. The instance id (prefix cn_) is distinct from the listing id, which names the marketplace entry it was installed from, for example cn-magento.
Unique identifier of this installed instance, prefixed cn_.
Always connector.
The marketplace listing this instance was installed from, for example cn-magento, cn-kustomer, or cn-amazon-connect. Browse listings in the marketplace.
Instance label within the tenant, for example magento-us-store. Defaults to the listing id when omitted at install.
saas or hardware. Set by the listing.
Always mcp. Every connector is an MCP server; the kernel hardcodes no vendor.
Capabilities this instance fulfills, in noun.verb form. Operators bind to these names, never to the connector directly.
The tools the connector exposes over MCP: name and side_effect. Side-effecting tools are the ones the executor gates behind the trust policy and idempotency keys.
Auth summary: type (api_key, oauth2, or basic) and a masked hint. Secrets are write-only; they are never returned by any read.
connected, pending_auth, or error. A connector in error keeps its configuration; fix credentials and re-test.
RFC 3339 timestamp of installation.
Last successful sense from the source system. null before the first sync.
{
"id": "cn_7d2f4a",
"object": "connector",
"listing": "cn-magento",
"name": "magento-us-store",
"kind": "saas",
"transport": "mcp",
"capabilities": ["order.read", "order.hold", "order.notify"],
"tools": [
{ "name": "order.read", "side_effect": false },
{ "name": "order.hold", "side_effect": true },
{ "name": "order.notify", "side_effect": true }
],
"auth": { "type": "api_key", "hint": "mg_****41" },
"status": "connected",
"created_at": "2026-06-18T10:02:00Z",
"last_synced_at": "2026-07-02T14:59:40Z"
}List installed connectors
connectors:readReturns the tenant's installed connector instances, newest first, cursor-paginated. This lists what you have installed, not the marketplace catalog.
Only connectors that fulfill this capability, for example order.hold.
Filter by saas or hardware.
Filter by connected, pending_auth, or error.
Page size, 1–100. Defaults to 20.
Pagination cursor from a previous response's next_cursor.
curl "https://api.fibric.io/v1/connectors?capability=order.hold" \
-H "Authorization: Bearer $FIBRIC_KEY"{
"object": "list",
"data": [
{
"id": "cn_7d2f4a",
"object": "connector",
"listing": "cn-magento",
"name": "magento-us-store",
"kind": "saas",
"capabilities": ["order.read", "order.hold", "order.notify"],
"status": "connected"
}
],
"has_more": false,
"next_cursor": null
}Install a connector
connectors:writeInstalls a marketplace listing into the tenant with its auth configuration. Listings marked live in the marketplace, currently cn-kustomer, cn-magento, and cn-amazon-connect, install immediately. Early-access listings return 422 listing_early_access; they are provisioned with your team during onboarding rather than self-served.
For api_key and basic auth the connector connects on install. For oauth2 the response is pending_auth with an authorize_url; the connector becomes connected after the authorization dance completes.
The marketplace listing id, for example cn-magento. An id that is not in the catalog fails with 404 not_found.
Credentials for the source system. Shape depends on the listing's auth type: {"type":"api_key","key":"…"}, {"type":"basic","username":"…","password":"…"}, or {"type":"oauth2"} to begin the authorization flow. Stored in the tenant vault, write-only.
Instance label, unique within the tenant. Required if you install the same listing twice, for example two Magento stores.
Listing-specific settings, for example a store base URL or an Amazon Connect instance id. The listing's marketplace page documents its keys.
curl -X POST https://api.fibric.io/v1/connectors \
-H "Authorization: Bearer $FIBRIC_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: install-magento-us-store" \
-d '{
"listing": "cn-magento",
"name": "magento-us-store",
"auth": { "type": "api_key", "key": "mg_live_9f4c2e8b1a41" },
"config": { "base_url": "https://store.acme.com" }
}'{
"id": "cn_7d2f4a",
"object": "connector",
"listing": "cn-magento",
"name": "magento-us-store",
"kind": "saas",
"transport": "mcp",
"capabilities": ["order.read", "order.hold", "order.notify"],
"auth": { "type": "api_key", "hint": "mg_****41" },
"status": "connected",
"created_at": "2026-07-02T15:20:00Z",
"last_synced_at": null
}Error cases:
| Status | Code | When |
|---|---|---|
400 | missing_parameter | listing or auth is absent. |
400 | invalid_parameter | auth.type does not match the listing's declared auth, or a required config key is missing. |
404 | not_found | No marketplace listing with this id. |
409 | state_conflict | An instance with this name already exists in the tenant. |
422 | listing_early_access | The listing is early access and not yet self-serve. Request access and it is provisioned during onboarding. |
422 | auth_failed | The source system rejected the supplied credentials. Nothing was installed. |
The platform is free during early access. Premium connectors are priced from $29 per source per month and operator packs from $49 per operator per month; installing a priced listing states the price in the marketplace and on the install response. Nothing is charged silently.
Retrieve a connector
connectors:readReturns the full connector object, including its tools and health. Secrets are never included.
The installed instance id, for example cn_7d2f4a.
curl https://api.fibric.io/v1/connectors/cn_7d2f4a \
-H "Authorization: Bearer $FIBRIC_KEY"Returns the connector object. A cross-tenant id reads as 404 not_found.
Test a connector
connectors:writeRuns a connection test against the real source. Read tools execute for real; side-effecting tools dry-run only, validating auth and reachability without writing anything. This mirrors fibric connector test in the CLI. A failing test moves the connector to error and reports which tool failed and why.
The installed instance to test.
Optional subset of tool names to test. Omit to test every tool the connector exposes.
curl -X POST https://api.fibric.io/v1/connectors/cn_7d2f4a/test \
-H "Authorization: Bearer $FIBRIC_KEY" \
-H "Content-Type: application/json" \
-d '{ "tools": ["order.read", "order.hold"] }'{
"object": "connector_test",
"connector_id": "cn_7d2f4a",
"status": "passed",
"results": [
{ "tool": "order.read", "mode": "live", "ok": true, "latency_ms": 184 },
{ "tool": "order.hold", "mode": "dry_run", "ok": true, "latency_ms": 211 }
],
"tested_at": "2026-07-02T15:22:31Z"
}Error cases:
| Status | Code | When |
|---|---|---|
400 | invalid_parameter | A name in tools is not a tool this connector exposes. |
404 | not_found | No connector with this id exists for the tenant. |
409 | state_conflict | The connector is pending_auth; complete authorization first. |
502 | connector_upstream_error | The source system was unreachable. The connector moves to error; the body carries the upstream detail. |
Uninstall a connector
connectors:writeRemoves the instance and purges its credentials from the vault. Events it already ingested and receipts that reference it are kept; the audit trail is never thinned by an uninstall. If any active operator depends on a capability only this connector fulfills, the request fails with 409 connector_in_use and the body lists the dependent operators; pause them or bind the capability to another connector first.
The installed instance to remove.
curl -X DELETE https://api.fibric.io/v1/connectors/cn_7d2f4a \
-H "Authorization: Bearer $FIBRIC_KEY"{
"id": "cn_7d2f4a",
"object": "connector",
"deleted": true
}{
"error": {
"type": "conflict_error",
"code": "connector_in_use",
"message": "order.hold is fulfilled only by cn_7d2f4a; operators op_8f2a1c depend on it.",
"doc_url": "https://fibric.io/docs/errors#connector_in_use",
"request_id": "req_2c8d90f1"
}
}Because operators bind to capabilities and not to connectors, replacing one source with another is: install the new connector, confirm it fulfills the same capabilities, uninstall the old one. No operator changes. See Capabilities.