# Connections

> Read the provider catalog and redacted project connection metadata while live connector operations remain unavailable.

Canonical guide: <https://api.blackpearl.com/docs/connectors>

Raw Markdown: <https://api.blackpearl.com/docs/raw/connectors.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

Connectors is a Preview inventory surface, not a finished integration runtime. The catalog describes provider manifests and credential fields. Connections are encrypted, project-scoped configuration records created and rotated by organization administrators in the Console. The public API is read-only.

There are currently no public operations that verify a provider credential, read provider records, write provider records, execute a sync, send a message, receive a webhook, or complete an OAuth callback. Catalog entries report verification as `unavailable`, and many are not bound to any executor. Do not treat a configured Connection as proof that a provider is reachable, authorized, funded, or operational.

## Read the catalog

Preview operation `connector_catalog_list_v1_connectors_get` returns `GET /v1/connectors`. Each entry describes a stable provider key, version, display metadata, credential field names, capabilities, limits, provenance, and verification mode. It never returns credential values.

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/connectors" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
```

Treat declared capabilities as reviewed inventory only. A future adapter must have its own execution, authorization, rate-limit, retry, audit, and data-rights review before a capability can become operational.

## Read configured connections

Preview operation `connection_list_v1_connections_get` returns redacted `GET /v1/connections` rows for the API key's project. A row identifies the provider, display label, status, catalog version, credential revision, configured field names, and timestamps. Secret values, ciphertext, key IDs, OAuth tokens, and raw verification responses are never returned.

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/connections" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
```

The Console stores provider credential documents encrypted with a dedicated rotation keyring. Provider secrets are distinct from the Blackpearl bearer key and must never appear in public Job inputs, URLs, free-text reasons, metadata, logs, or Outcome payloads.

Because the surface is Preview, response fields and provider inventory can change incompatibly. Pin only opaque connection IDs when testing a Preview capability, and design a safe fallback when the associated executor is unavailable.