Connections

Get Available Connections

get

List all available connections that can be configured.

Returns a list of available connection types with their configuration parameters.

Responses
200

Successful Response

application/json
get
/connections/available
GET /connections/available HTTP/1.1
Host: api.stack-ai.com
Accept: */*
200

Successful Response

[
  {
    "connection_type_id": "text",
    "provider_id": "text",
    "name": "text",
    "description": "text",
    "labels": [
      "text"
    ],
    "params": [
      {
        "label": "text",
        "type": "string",
        "placeholder": "text",
        "default": 1,
        "help": "text",
        "url": "text",
        "required": true,
        "name": "text"
      }
    ],
    "minimum_plan": "text",
    "color": "#A3A3A3",
    "is_marketing_stunt": false,
    "connection_type": "credentials"
  }
]

Get Connections

get

List all available connections for the user in his current organization.

Authorizations
OAuth2passwordRequired
Token URL:
Query parameters
connection_providerany ofOptional
stringOptional
or
nullOptional
limitintegerOptionalDefault: 1000
offsetintegerOptionalDefault: 0
Responses
200

Successful Response

application/json
get
/connections
GET /connections HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "connection_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_by": {
      "avatar_url": "text",
      "full_name": "text",
      "has_completed_onboarding": true,
      "last_signed_in": "text",
      "updated_at": "text",
      "id": "text",
      "email": "text"
    },
    "created_at": "2025-11-10T10:49:18.436394+00:00",
    "updated_by": {
      "avatar_url": "text",
      "full_name": "text",
      "has_completed_onboarding": true,
      "last_signed_in": "text",
      "updated_at": "text",
      "id": "text",
      "email": "text"
    },
    "updated_at": "2025-11-10T10:49:18.436438+00:00",
    "name": "Unnamed connection",
    "org_id": "text",
    "provider_id": "text",
    "connection_type_id": "text",
    "connection_provider_data": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Create Connection

post

Create a new connection. The connection will be created in the user's current organization.

Authorizations
OAuth2passwordRequired
Token URL:
Body

Request model for creating/updating a connection.

namestringOptionalDefault: Unnamed connection
provider_idstringRequired
connection_type_idstringRequired
connection_provider_dataobject · BaseConnectionDataModelRequired

Base data model for all connections.

Responses
post
/connections
POST /connections HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "Unnamed connection",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {}
}
{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Connection By Id

get
Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
refresh_oauth_tokensbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
get
/connections/{connection_id}
GET /connections/{connection_id} HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update Connection

put

Update the connection with the given id.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Body

Request model for creating/updating a connection.

namestringOptionalDefault: Unnamed connection
provider_idstringRequired
connection_type_idstringRequired
connection_provider_dataobject · BaseConnectionDataModelRequired

Base data model for all connections.

Responses
200

Successful Response

application/json
put
/connections/{connection_id}
PUT /connections/{connection_id} HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "Unnamed connection",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {}
}
{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Delete Connection

delete

Delete a connection given its ID.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Responses
delete
/connections/{connection_id}
DELETE /connections/{connection_id} HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Patch Connection

patch

Patch a connection to update specific fields like name.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Body

Request model for partially updating a connection (e.g., renaming).

namestringRequired

New name for the connection

Responses
200

Successful Response

application/json
patch
/connections/{connection_id}
PATCH /connections/{connection_id} HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}
{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Connection Health

get

Check the health of a connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Responses
200

Successful Response

application/json
get
/connections/{connection_id}/health
GET /connections/{connection_id}/health HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Oauth Url

post

Return the OAuth URL for a connection provider.

Authorizations
OAuth2passwordRequired
Token URL:
Body

Request model for creating/updating a connection.

namestringOptionalDefault: Unnamed connection
provider_idstringRequired
connection_type_idstringRequired
connection_provider_dataobject · BaseConnectionDataModelRequired

Base data model for all connections.

Responses
200

Successful Response

application/json
Responsestring
post
/connections/oauth/start
POST /connections/oauth/start HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "Unnamed connection",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {}
}
text

Create Connection From Callback

post

Create a new connection from an OAuth callback.

This endpoint is used to create a new connection for providers that use the OAuth protocol. The OAuth flow is initialized by the stack frontend, where the user is redirected to the provider's authorization page. Once the user authorizes the application, they are redirected back to the stack frontend with a code parameter. This code is then sent to this endpoint, which uses it to create a new connection for said provider completing the OAuth flow.

Authorizations
OAuth2passwordRequired
Token URL:
Query parameters
codestringRequired
Body

Request model for creating/updating a connection.

namestringOptionalDefault: Unnamed connection
provider_idstringRequired
connection_type_idstringRequired
connection_provider_dataobject · BaseConnectionDataModelRequired

Base data model for all connections.

Responses
post
/connections/oauth/callback
POST /connections/oauth/callback?code=text HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "Unnamed connection",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {}
}
{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Update Connection From Callback

put

Update an existing connection from an OAuth callback.

Mirrors the creation flow but updates the specified connection with new OAuth credentials. Path chosen for consistency with POST /oauth/callback and REST semantics.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
codestringRequired
Body

Request model for creating/updating a connection.

namestringOptionalDefault: Unnamed connection
provider_idstringRequired
connection_type_idstringRequired
connection_provider_dataobject · BaseConnectionDataModelRequired

Base data model for all connections.

Responses
200

Successful Response

application/json
put
/connections/oauth/callback/{connection_id}
PUT /connections/oauth/callback/{connection_id}?code=text HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 108

{
  "name": "Unnamed connection",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {}
}
{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "created_at": "2025-11-10T10:49:18.436394+00:00",
  "updated_by": {
    "avatar_url": "text",
    "full_name": "text",
    "has_completed_onboarding": true,
    "last_signed_in": "text",
    "updated_at": "text",
    "id": "text",
    "email": "text"
  },
  "updated_at": "2025-11-10T10:49:18.436438+00:00",
  "name": "Unnamed connection",
  "org_id": "text",
  "provider_id": "text",
  "connection_type_id": "text",
  "connection_provider_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Connection Resources

get

Get the resources associated with a connection.

This endpoint returns the information for the selected resource in the connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
resource_idsstring[]Optional
refresh_oauth_tokensbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
get
/connections/{connection_id}/resources
GET /connections/{connection_id}/resources HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": {
    "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-11-28T01:31:40.235Z",
    "modified_at": "2025-11-28T01:31:40.235Z",
    "indexed_at": "2025-11-28T01:31:40.235Z",
    "inode_type": "file",
    "resource_id": "text",
    "inode_path": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "dataloader_metadata": {
      "^[^\\t\\n\\r\\f\\v]+$": null
    },
    "user_metadata": {
      "^[^\\t\\n\\r\\f\\v]+$": null
    },
    "inode_id": "123e4567-e89b-12d3-a456-426614174000",
    "content_hash": "text",
    "content_mime": "text",
    "size": 1,
    "status": "resource",
    "supabase_signed_url": "text"
  }
}

Get Children Resources

get

Get the children of a resource associated with a connection.

This endpoint can be used to navigate the resources in the connection. If no resource_id is provided, it will return the list of resources at the root of the connection. If a resource_id is provided, it will return the children of that resource. If the resource_id corresponds to a file, an empty list will be returned.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
resource_idany ofOptional
stringOptional
or
nullOptional
cursorany ofOptional

Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.

Example: ZXhhbXBsZV9jdXJzb3I=
stringOptional
or
nullOptional
page_sizeinteger · min: 1 · max: 1000Optional

Number of items to be returned in the page.

Default: 50
refresh_oauth_tokensbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
get
/connections/{connection_id}/resources/children
GET /connections/{connection_id}/resources/children HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Search Connection Resources

get

Search for resources in the connection that match the query.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
querystringRequired

Search query string

cursorany ofOptional

Optional identifier for the page that should be returned. If it is not provided, the first page will be returned.

Example: ZXhhbXBsZV9jdXJzb3I=
stringOptional
or
nullOptional
page_sizeinteger · min: 1 · max: 1000Optional

Number of items to be returned in the page.

Default: 50
refresh_oauth_tokensbooleanOptionalDefault: false
Responses
200

Successful Response

application/json
get
/connections/{connection_id}/resources/search
GET /connections/{connection_id}/resources/search?query=text HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Paginated Connections

get

List all available connections for the user in his current organization.

Supports dynamic field__operator filters.

Authorizations
OAuth2passwordRequired
Token URL:
Query parameters
limitintegerOptionalDefault: 10
offsetintegerOptionalDefault: 0
sort_bystring · enumOptionalDefault: created_atPossible values:
sort_dirstring · enumOptionalDefault: descPossible values:
Responses
200

Successful Response

application/json
get
/api/v1/connections
GET /api/v1/connections HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status_code": 200,
  "response_code": "text",
  "meta": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "data": [
    {
      "connection_id": "123e4567-e89b-12d3-a456-426614174000",
      "created_by": {
        "avatar_url": "text",
        "full_name": "text",
        "has_completed_onboarding": true,
        "last_signed_in": "text",
        "updated_at": "text",
        "id": "text",
        "email": "text"
      },
      "created_at": "2025-11-10T10:49:18.436394+00:00",
      "updated_by": {
        "avatar_url": "text",
        "full_name": "text",
        "has_completed_onboarding": true,
        "last_signed_in": "text",
        "updated_at": "text",
        "id": "text",
        "email": "text"
      },
      "updated_at": "2025-11-10T10:49:18.436438+00:00",
      "name": "Unnamed connection",
      "org_id": "text",
      "provider_id": "text",
      "connection_type_id": "text",
      "connection_provider_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "offset": 0,
  "limit": 50,
  "total": 0
}

Get Connection Rbac

get

Get the RBA info for a connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Responses
200

Successful Response

application/json
get
/api/v1/connections/{connection_id}/rbac
GET /api/v1/connections/{connection_id}/rbac HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "org_level_role": "text",
  "user_roles": {
    "ANY_ADDITIONAL_PROPERTY": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  },
  "group_roles": {
    "ANY_ADDITIONAL_PROPERTY": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  },
  "current_user_effective_role": "text"
}

Update Connection Rbac

put

Update the RBAC info for a connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Body
subject_typestring · enumRequired

RBAC subject types for access control.

Possible values:
rolestringRequired
subject_idstring · uuidRequired
Responses
200

Successful Response

application/json
Responseany
put
/api/v1/connections/{connection_id}/rbac
PUT /api/v1/connections/{connection_id}/rbac HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "subject_type": "user",
  "role": "text",
  "subject_id": "123e4567-e89b-12d3-a456-426614174000"
}
No content

Delete Connection Rbac

delete

Delete RBA info for the connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Query parameters
subject_typestring · enumRequired

RBAC subject types for access control.

Possible values:
subject_idstring · uuidRequired
Responses
delete
/api/v1/connections/{connection_id}/rbac
DELETE /api/v1/connections/{connection_id}/rbac?subject_type=user&subject_id=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Update Connection Organization Role

patch

Update the organization-level role for a connection.

Authorizations
OAuth2passwordRequired
Token URL:
Path parameters
connection_idstring · uuidRequired
Body

Request model for updating connection organization-level role.

roleany ofRequired

Organization-level role for the connection. Set to null to remove org-level access.

stringOptional
or
nullOptional
Responses
200

Successful Response

application/json
Responseany
patch
/api/v1/connections/{connection_id}/organization-role
PATCH /api/v1/connections/{connection_id}/organization-role HTTP/1.1
Host: api.stack-ai.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "role": "text"
}
No content
PreviousFoldersNextDocuments

Last updated

Was this helpful?