Trigger Connection Runs

Use the Workspace API to start a run for a saved Connection. The API uses the OAuth 2.0 client credentials flow.

Create an API client

An organization owner or admin can create credentials in Workspace Settings > Integrations > Workspace API Clients. Each client is limited to the workspace where it was created.

Copy the client ID and client secret when the client is created. The client secret is shown only once.

Get an access token

Exchange the client credentials for an access token:

curl --request POST \
  'https://studio.precog.cloud/api/public/v1/oauth/token' \
  --user '<client-id>:<client-secret>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials'

A successful request returns:

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "connections:runs:create"
}

The access token expires after one hour and can trigger runs only in the API client's workspace.

Trigger a Connection run

You need these UUIDs:

• workspaceId: the workspace where the API client and Connection exist
• connectionId: the saved Connection ID, not its Precog pipeline ID

Send an empty POST request with the access token:

ACCESS_TOKEN='<access-token>'
WORKSPACE_ID='<workspace-id>'
CONNECTION_ID='<connection-id>'

curl --request POST \
  "https://studio.precog.cloud/api/public/v1/workspaces/${WORKSPACE_ID}/connections/${CONNECTION_ID}/runs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Do not send a request body.

Accepted response

A successfully accepted request returns 202 Accepted:

{
  "connectionId": "<connection-id>",
  "status": "accepted"
}

This response means Precog accepted the Connection for execution. It does not mean that the run has completed successfully.

Errors

Token endpoint errors:

Connection-run endpoint errors: