Reference preview

These pages describe Fibric’s target architecture. Public CLI, API, SDK, and sandbox access are not available. Examples do not establish deployed capabilities.

Reference

Connectors API

This page specifies a proposed connector-management API. No public self-serve install, test, or uninstall path exists today. Five listings are evidenced through live BearScope product paths; the other 43 are managed early access.

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.

idstring

Unique identifier of this installed instance, prefixed cn_.

objectstring

Always connector.

listingstring

The marketplace listing this instance was installed from, for example cn-magento, cn-kustomer, or cn-amazon-connect. Browse listings in the marketplace.

namestring

Instance label within the tenant, for example magento-us-store. Defaults to the listing id when omitted at install.

kindstring

saas or hardware. Set by the listing.

transportstring

Always mcp. Every connector is an MCP server; the kernel hardcodes no vendor.

capabilitiesstring[]

Capabilities this instance fulfills, in noun.verb form. Operators bind to these names, never to the connector directly.

toolsobject[]

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.

authobject

Auth summary: type (api_key, oauth2, or basic) and a masked hint. Secrets are write-only; they are never returned by any read.

statusstring

connected, pending_auth, or error. A connector in error keeps its configuration; fix credentials and re-test.

created_atstring

RFC 3339 timestamp of installation.

last_synced_atstring or null

Last successful sense from the source system. null before the first sync.

json · the connector object

{
  "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"
}

GET

List installed connectors#

GET/v1/connectorsscope connectors:read

Returns the tenant's installed connector instances, newest first, cursor-paginated. This lists what you have installed, not the marketplace catalog.

capabilitystring · query

Only connectors that fulfill this capability, for example order.hold.

kindstring · query

Filter by saas or hardware.

statusstring · query

Filter by connected, pending_auth, or error.

limitinteger · query

Page size, 1–100. Defaults to 20.

cursorstring · query

Pagination cursor from a previous response's next_cursor.

curl

curl "https://api.fibric.io/v1/connectors?capability=order.hold" \
  -H "Authorization: Bearer $FIBRIC_KEY"

200 OK Response

json

{
  "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
}

POST

Install a connector#

POST/v1/connectorsscope connectors:write

This target operation illustrates connector installation. No public self-serve install endpoint exists. Kustomer, Magento, and Amazon Connect are evidenced through live BearScope product paths; all catalog provisioning is managed and deployment-specific.

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.

listingrequiredstring · body

The marketplace listing id, for example cn-magento. An id that is not in the catalog fails with 404 not_found.

authrequiredobject · body

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.

namestring · body

Instance label, unique within the tenant. Required if you install the same listing twice, for example two Magento stores.

configobject · body

Listing-specific settings, for example a store base URL or an Amazon Connect instance id. The listing's marketplace page documents its keys.

curl

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" }
  }'

201 Created Response

json

{
  "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 reference listing is managed early access and not self-serve. Request a managed review.
`422`	`auth_failed`	The source system rejected the supplied credentials. Nothing was installed.

Premium listings and billing

No public checkout or free developer tier is available. Marketplace prices are indicative planning assumptions only; managed scope and contractual rates are confirmed before deployment on the pricing page path.

GET

Retrieve a connector#

GET/v1/connectors/{connector_id}scope connectors:read

Returns the full connector object, including its tools and health. Secrets are never included.

connector_idrequiredstring · path

The installed instance id, for example cn_7d2f4a.

curl

curl https://api.fibric.io/v1/connectors/cn_7d2f4a \
  -H "Authorization: Bearer $FIBRIC_KEY"

200 OK Response

Returns the connector object. A cross-tenant id reads as 404 not_found.

POST

Test a connector#

POST/v1/connectors/{connector_id}/testscope connectors:write

Runs 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.

connector_idrequiredstring · path

The installed instance to test.

toolsstring[] · body

Optional subset of tool names to test. Omit to test every tool the connector exposes.

curl

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"] }'

200 OK Response

json

{
  "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.

DELETE

Uninstall a connector#

DELETE/v1/connectors/{connector_id}scope connectors:write

Removes 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.

connector_idrequiredstring · path

The installed instance to remove.

curl

curl -X DELETE https://api.fibric.io/v1/connectors/cn_7d2f4a \
  -H "Authorization: Bearer $FIBRIC_KEY"

200 OK Response

json

{
  "id": "cn_7d2f4a",
  "object": "connector",
  "deleted": true
}

409 Conflict When operators depend on it

json

{
  "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://www.fibric.io/docs/errors#connector_in_use",
    "request_id": "req_2c8d90f1"
  }
}

Swapping vendors is configuration, not a rewrite

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.