# Connections

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

Canonical guide: <https://engine.neraperla.com/docs/connectors>

Raw Markdown: <https://engine.neraperla.com/docs/raw/connectors.md>

OpenAPI: <https://engine.neraperla.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 owners and administrators in the Console. The public API is read-only.

Plainly: catalog entries are not yet verifiable or consumable. No operation — public API or Console — can verify a provider credential, read provider records, write provider records, execute a sync, send a message, receive a webhook, or complete an OAuth callback; the Console's connection verify action returns "not implemented" for every provider. Catalog entries report verification as `unavailable`, and no public operation is bound to an executor. The one Console-only exception is the [CRM Schema preview](https://engine.neraperla.com/docs/crm-schema), which can read HubSpot or Salesforce schema metadata — never records — through a privately configured adapter; it does not make any catalog entry verifiable or consumable. Do not treat a configured Connection as proof that a provider is reachable, authorized, funded, or operational, and do not build a workflow that depends on a listed provider becoming consumable.

## 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 request's project: a project key's own project, or the project a company-level key names with the `Blackpearl-Project` header (or its default 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.
