Skip to main content
This walkthrough checks that your token works. Then it lists the Provider connections in your Workspace and reads the Workspace’s data catalog. All three calls only read. A Parable token works for each one. An MCP token works too, while the Workspace allows external agents. A SQL token does not. See Authentication to get a token. Set these variables first:
1

Check who you are

GET /api/users/me returns your membership in the Workspace. It needs no role. Every member can call it.
Response (shortened)
A 200 with your own record means that authentication works. A 401 means that the token is wrong, revoked, or expired.
2

List your Provider connections

GET /api/vendors/tenant-connector-instances lists each Provider connection in the Workspace, such as GitHub, Jira, or Slack. Each item has a connectionStatus, such as idle, sync_failed, or credential_error, and a connectionStatusMessage that explains it. The call needs a role that can view Provider connections.
Use this call to add a sync-health check to your own monitoring.
3

Read your data catalog

GET /api/v2/catalog lists the tables and views that your Workspace can query from its Provider data, with their columns. The call needs a role that can read the data catalog. With an MCP token, the catalog lists only the tables that the token’s owner can query.
Parable Data Engine explains how to query these tables with SQL.
A 403 means that your roles do not allow the call in this Workspace.

The response envelope

Every successful response wraps its payload in the same envelope. Every response, successful or not, also has an X-Request-ID header with the same ID. You can send your own X-Request-ID on a request, and Parable uses it.

Pages of results

Most lists return every item in one response. The lists that page do it in one of two ways. Offset and limit. Send limit and offset as query parameters. When data is an object, it repeats limit and offset and has the page in items and the full count in total. When data is an array, read the next page until a page holds fewer items than limit.
Cursor. The response has a nextCursor in data. Send it back as cursor to read the next page. When nextCursor is empty or absent, there are no more pages. Plot data (POST /api/parable/authoring/primaries/{rootRefId}/plots/data) and a listing from POST /api/provider-pool/search page this way.

Errors

An error response has the content type application/problem+json (RFC 9457). Its body has these members:
Response (403)
Use code, not detail, in code that handles an error. The API reference lists the statuses.

Next steps

API reference

Every operation, with parameters, response shapes, and SDK samples.

Connectors

Provider connections, Taps, and how data reaches your Workspace.