Manage Component Connections

Manage Component Connections via API

List Connections

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

export INSTILL_API_TOKEN=********

curl -X GET 'http://localhost:8080/v1beta/namespaces/NAMESPACE_ID/connections' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $INSTILL_API_TOKEN"

from instill.clients import init_pipeline_client

pipeline = init_pipeline_client(api_token="INSTILL_API_TOKEN", url="http://localhost:8080")
pipeline.list_connections(namespace_id="NAMESPACE_ID")
pipeline.close()

Get Connection

This endpoint allows for getting a connection associated with a specific namespace.

export INSTILL_API_TOKEN=********

curl -X GET 'http://localhost:8080/v1beta/namespaces/NAMESPACE_ID/connections/CONNECTION_ID'
\
--header "Content-Type: application/json" \
--header "Authorization: Bearer $INSTILL_API_TOKEN"

from instill.clients import init_pipeline_client

pipeline = init_pipeline_client(api_token="INSTILL_API_TOKEN", url="http://localhost:8080")
pipeline.get_connection(namespace_id="NAMESPACE_ID", connection_id="CONNECTION_ID")
pipeline.close()

Update Connection

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

export INSTILL_API_TOKEN=********

curl -X PATCH
'http://localhost:8080/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": {}
}'

from instill.clients import init_pipeline_client

pipeline = init_pipeline_client(api_token="INSTILL_API_TOKEN", url="http://localhost:8080")
pipeline.update_connection(
  namespace_id="NAMESPACE_ID",
  connection_id="CONNECTION_ID",
  integration_id="openai",
  is_oauth=False,
)
pipeline.close()

Delete Connection

This endpoint enables the deletion of a specified connection.

export INSTILL_API_TOKEN=********

curl -X DELETE
'http://localhost:8080/v1beta/namespaces/NAMESPACE_ID/connections/CONNECTION_ID' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $INSTILL_API_TOKEN"

from instill.clients import init_pipeline_client

pipeline = init_pipeline_client(api_token="INSTILL_API_TOKEN", url="http://localhost:8080")
pipeline.delete_connection(
  namespace_id="NAMESPACE_ID", connection_id="CONNECTION_ID"
)
pipeline.close()

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

Component 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 Component Connections via Console

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