Skip to main content
A Provider is a system that your company uses, such as GitHub, Jira, Slack, Linear, or Workday. A Provider connection brings the data of one Provider into your Workspace. Parable syncs that data into the Provider Pool, where you query it with SQL.
Parable reads data from your Providers. It does not write to your systems.

The model

Every Provider connection has two parts. Parable ships a Provider Plugin, and your Workspace configures a Provider connection from it. The Provider Plugin is the same for every Workspace. The Provider connection belongs to your Workspace. Examples on these pages use three variables. $PARABLE_API_URL is the base URL of the Workspace API. $PARABLE_API_TOKEN is your token. $PARABLE_WORKSPACE is your Workspace slug, such as acme-corp.

Browse the Provider directory

The directory needs no sign-in. Search it for a Provider:
List the connection methods of one Provider. A leaf method (isLeaf: true) carries the connectorId, the authentication strategies that you can use, and the ingestionConfigSchema:

Browse by function

The directory also lists one entry for each Provider product, with no setup details:
Each entry has connectorId, name, description, logo, releaseStage, and groupingIds, the connection methods of the product. variants describes each of those connection methods with its own connectorId, name, description, logo, releaseStage and groupingPath. When you send X-Tenant, priority says whether your Workspace marks the Provider required or suggested, on the entry and on each variant. Categories group Providers by business function, such as engineering or finance:
Each category has slug, label, sortOrder, parent, and connectorIds. The list is flat. Build the tree from parent.id, and match connectorIds to the connectorId of each directory entry. A category with isLegacy: true stays in the list for earlier selections.

Availability

Each leaf method says how far Parable has released its plugin: connectorReleaseStatus decides what your Workspace can do:
  • Before authorized. Parable refuses a connection or a credential save (WA-CN-005).
  • authorized. You can create the connection, save credentials, and check them. No sync starts, and Parable refuses a change of ingestion settings. When the plugin reaches executable, save the credentials again or check them to start the first sync.
  • executable and later. A valid credential save starts the first sync.
  • deprecated. Parable refuses a new connection or a credential save (WA-CN-006).
A Provider that Parable has not released to your Workspace answers like a Provider that does not exist.

Connection names in the Provider Pool

Most Providers serve every connection under one Provider Pool schema, the Provider’s own name, such as providers.github. A Provider whose poolNamespace is connection, such as a database Provider, serves each connection under a name that you choose. Send it as catalogSlug when you connect, for example fusion. The tables of that connection then serve as providers.fusion.{table}. When you send no catalogSlug, Parable uses the connection name, normalized: Fusion Parable serves as providers.fusion_parable. The connect form in the app sends only the name.
  • Use lowercase letters, digits, and single underscores. Start with a letter.
  • You cannot change the name later. Plot SQL names the tables by it.
  • Parable refuses the connection when:
    • the Provider needs a name and you sent neither a catalogSlug nor a connection name that normalizes to one (WA-CN-007).
    • another live connection in the Workspace uses the name (WA-CN-008).
    • a Provider or a Pool family, such as identity, already serves under the name (WA-CN-009).
    • the Provider serves every connection under its own name and you sent a name (WA-CN-010).
When you remove a connection, its name is free again. A Provider whose poolNamespace is connection must read its data on a schedule. Parable does not collect data that such a Provider sends, because it cannot tell which connection sent it.

Providers that send data

Most plugins read the Provider on a schedule. Some Providers send their data to Parable instead, such as webhooks and telemetry exporters. A leaf method of such a Provider has integrationClass: streaming, a protocolType such as webhook or otlp, and supportedInboundAuthStrategies, the ways that Parable can verify its senders. See Providers that send data.

Read your connections

List the Provider connections in your Workspace:
Each item has the nested Provider Plugin in connector. In this list, connector.taps is empty. Add ?includeTaps=true to get every Tap with its schema. That makes the response much larger. To read the full plugin of one connection, read that connection:
To check only whether the data of each connection is current, list the connection freshness. It has no Provider Plugin, so the response stays small:
  • Each item has the connection’s connectionStatus, connectionStatusMessage, lastSyncAt, and lastSyncStatus, the same values as in the full list. A Provider that sends data also has lastDataReceivedAt.
  • A page holds at most limit connections, newest first: 50 by default, 100 at most. It stops before 40,000 characters, but it always holds one connection.
  • Send nextOffset back as offset for the next page. The last page has no nextOffset.

What your Workspace controls

  • Which Providers are connected, with which strategy and credentials. The API never returns a secret value. A secret field comes back as an empty string.
  • Which Taps run. A new connection starts with the plugin’s default Taps. Other Taps are opt-in. See Taps.
  • Sync health. Each connection reports these fields:
You do not choose pagination or sync mode. The Provider Plugin sets them for each Tap, so that Parable reads the Provider correctly. You can read them, but you cannot change them. How a sync reads a Provider explains each field.

Rate limits

Each Provider Plugin limits how fast Parable calls the Provider. A plugin sets one of two kinds of limit:
  • A fixed limit. It sets requests per second, concurrent requests, and retry rules.
  • A Provider budget. It follows the quota that the Provider publishes and the rate-limit headers that it returns.
A Tap can set its own limit. You cannot change these limits. They explain why a large first sync takes time.

Request a Provider

If the directory does not list a system that you use, request it:
A request does not create a Provider connection. Read your requests and their status with GET /api/connector-requests/connector-requests. You can also request a Provider from Providers in the Workspace app.
Setup guides for each Provider (OAuth apps, API keys, and scopes) are in the Provider Plugin guides.