Integrations | Documentation

Integrations allow users to set up components that connect with external services.

#Connection Object

All the APIs in Connection Endpoints follow a consistent structure for request and response bodies. Below are the key fields:

id: The connection's unique identifier.
uid: The immutable UID of the connection.
namespaceId: The namespace ID owning the connection.
method: Acceptable values are METHOD_DICTIONARY and METHOD_OAUTH.
setup: The connection details.

For additional details, please refer to the API reference.

Example Connection Object:

{
  "uid": "011477fa-9215-4d0a-b0ea-7101398f786f",
  "id": "openai",
  "namespaceId": "test",
  "integrationId": "openai",
  "integrationTitle": "OpenAI",
  "method": "METHOD_DICTIONARY",
  "setup": {
      "api-key": "key",
      "organization": "my-org"
  },
  "scopes": [],
  "view": "VIEW_FULL",
  "createTime": "2024-10-01T07:55:03.697377Z",
  "updateTime": "2024-10-01T07:55:03.697377Z"
}

#Manage Connections via API

#List Connections

This endpoint returns a paginated list of connections associated with a specific namespace.

cURL

Python

export INSTILL_API_TOKEN=********
curl -X GET 'https://api.instill.tech/v1beta/namespaces/NAMESPACE_ID/connections' \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $INSTILL_API_TOKEN"

#Create Connection

cURL

Python

export INSTILL_API_TOKEN=********
curl -X POST 'https://api.instill.tech/v1beta/namespaces/NAMESPACE_ID/connections' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $INSTILL_API_TOKEN" \
  --data '{
    "id": "CONNECTION_ID",
    "integrationId": "openai"
    "method": "METHOD_DICTIONARY",
    "setup": {}
  }'

#Get Connection

This endpoint allows for getting a connection.

cURL

Python

export INSTILL_API_TOKEN=********
curl -X GET 'https://api.instill.tech/v1beta/namespaces/NAMESPACE_ID/connections/CONNECTION_ID' \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $INSTILL_API_TOKEN"

#Update Connection

This endpoint allows for updating a connection with a new setup.

cURL

Python

export INSTILL_API_TOKEN=********
curl -X PATCH 'https://api.instill.tech/v1beta/namespaces/NAMESPACE_ID/connections/CONNECTION_ID' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $INSTILL_API_TOKEN" \
  --data '{
    "integrationId": "openai"
    "method": "METHOD_DICTIONARY",
    "setup": {}
  }'

#Delete Connection

This endpoint enables the deletion of a specified connection.

cURL

Python

export INSTILL_API_TOKEN=********
curl -X DELETE 'https://api.instill.tech/v1beta/namespaces/NAMESPACE_ID/connections/CONNECTION_ID' \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $INSTILL_API_TOKEN"

The NAMESPACE_ID and CONNECTION_ID path parameter must be replaced by the connection owner's ID (namespace) and the connection ID.

#Manage Connections via Console

You can store the connection settings to such services from the Console > Settings > Integrations page.

Explore integrations and create connections from the settings page

#Creating a connection

The Connected section shows the connections already created, grouped by application. You can explore the supported integrations and create a new connection through the Connect button.

Add new connections through the "Connect" button

#Connecting through OAuth 2.0

If an integration supports OAuth 2.0 to connect with the 3rd party service (e.g., GitHub, Slack), you won't need to fill the connection details. The connection flow will be as simple as authorizing the Instill AI application to interact with that vendor on your behalf.

If you're using Instill Cloud, you don't need to worry about configuring applications on 3rd party vendors. On community-edition deployments, you can follow the vendor's instructions to connect via OAuth, which will typically involve creating an application on that service. In order to integrate your Instill AI deployment with a vendor via OAuth, you'll need to copy your app's client ID and client secret and set them as environment variables on instill-core.

If your deployment isn't configured to support OAuth, you'll still be able to create connections. In this case, you'll need to fill a form with the connection details, which you'll need to fetch from the vendor's site.

#Referencing a Connection

component:
  sql-0:
    type: sql
    input:
      table-name: weights
      update-data: ${variable.new-weights}
    setup: ${connection.service-1-dev}
    task: TASK_UPDATE

Connections offer several benefits over in-component setup declarations:

Making pipeline recipes more compact.
Centralizing credential management in a single page.
Connecting with 3rd party services via OAuth 2.0.

Reference a connection from the pipeline editor