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

nullOptional

limitintegerOptionalDefault: 1000

offsetintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

422

Validation Error

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

201

Successful Response

application/json

422

Validation Error

application/json

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

422

Validation Error

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

422

Validation Error

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

204

Successful Response

422

Validation Error

application/json

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

422

Validation Error

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

422

Validation Error

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

422

Validation Error

application/json

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

201

Successful Response

application/json

422

Validation Error

application/json

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

422

Validation Error

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

422

Validation Error

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-12-18T15:26:48.293Z",
    "modified_at": "2025-12-18T15:26:48.293Z",
    "indexed_at": "2025-12-18T15:26:48.293Z",
    "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

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

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

422

Validation Error

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

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

422

Validation Error

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

422

Validation Error

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

422

Validation Error

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

422

Validation Error

application/json

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

204

Successful Response

422

Validation Error

application/json

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

nullOptional

Responses

200

Successful Response

application/json

Responseany

422

Validation Error

application/json

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

PreviousFolders NextDocuments

Last updated 1 month ago

Was this helpful?