SourceSync.ai LogoBY SiteGPT.ai

SiteGPT.ai

Connections API

The Connections API lets you manage connections to external services like Notion, Google Drive, Dropbox, Box, OneDrive, SharePoint, and Confluence. All connectors support automatic connection reuse through external identifiers.

POST/v1/connections

Create Connection

Automatic Connection Reuse: When creating connections, if the same user has previously authorized your integration, SourceSync will automatically reuse the existing connection based on the user's external identifier (externalId). This prevents duplicate connections and maintains consistency across different tenants and applications. This behavior applies to all supported connectors.

Create a new connection to an external service.

You can send an optional X-Tenant-ID header for multitenancy within a namespace (docs).

Authorization

  • Name
    Authorization*
    Type
    string
    Description
    Bearer token authentication. Include your API key as Bearer your_api_key
  • Name
    Accept*
    Type
    string
    Description
    application/json

Request Body

  • Name
    namespaceId*
    Type
    string
    Description
    Unique identifier of the namespace where the connection will be created
  • Name
    name*
    Type
    string
    Description
    Name for the connection
  • Name
    connector*
    Type
    enum<string>
    Description
    Type of the connector
    Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE
  • Name
    clientRedirectUrl
    Type
    string(optional)
    Description
    URL to redirect the client to, after the connection is created. If not provided, the client will be redirected to SourceSync connector page.

Request

POST
/v1/connections
curl -X POST https://api.sourcesync.ai/v1/connections \
  -H "Authorization: Bearer ${SOURCE_SYNC_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123",
    "name": "My Google Drive",
    "connector": "GOOGLE_DRIVE",
    "clientRedirectUrl": "https://example.com/ragaas/google-drive/success"
  }'


Response Body

  • Name
    success*
    Type
    boolean
    Description
    Indicates whether the request is successful or not. This is always true for success responses.
  • Name
    message*
    Type
    string
    Description
    Human readable message mentioning the result of the request
  • Name
    data*
    Type
    object
    Description
    Data returned from the API.
    • Name
      connection*
      Type
      object
      Description
      Created connection details
      • Name
        id*
        Type
        string
        Description
        Unique identifier for the connection
    • Name
      authorizationUrl*
      Type
      string
      Description
      URL to authorize the connection

Response

POST
/v1/connections
{
  "success": true,
  "message": "Please visit the authorization URL to connect your Google Drive account",
  "data": {
    "connection": {
      "id": "conn_abc123"
    },
    "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?..."
  }
}
GET/v1/connections

List Connections

List all connections of a connector for a specific namespace.

You can send an optional X-Tenant-ID header for multitenancy within a namespace (docs).

Authorization

  • Name
    Authorization*
    Type
    string
    Description
    Bearer token authentication. Include your API key as Bearer your_api_key
  • Name
    Accept*
    Type
    string
    Description
    application/json

Query Parameters

  • Name
    namespaceId*
    Type
    string
    Description
    Unique identifier of the namespace
  • Name
    connector
    Type
    enum<string>(optional)
    Description
    Filter connections by connector
    Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE

Request

GET
/v1/connections
curl -X GET 'https://api.sourcesync.ai/v1/connections?namespaceId=ns_123&connector=NOTION' \
  -H "Authorization: Bearer ${SOURCE_SYNC_API_KEY}"


Response Body

  • Name
    success*
    Type
    boolean
    Description
    Indicates whether the request is successful or not. This is always true for success responses.
  • Name
    message*
    Type
    string
    Description
    Human readable message mentioning the result of the request
  • Name
    data*
    Type
    object
    Description
    Data returned from the API.
    • Name
      connections*
      Type
      array<object>
      Description
      List of connections in the organization
      • Name
        id*
        Type
        string
        Description
        Unique identifier for the connection
      • Name
        name*
        Type
        string
        Description
        Name of the connection
      • Name
        connector*
        Type
        enum<string>
        Description
        Type of the connector
        Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE
      • Name
        status*
        Type
        enum<string>
        Description
        Current status of the connection
        Available options: PENDING, ACTIVE, FAILED, REVOKED
      • Name
        statusReason
        Type
        string(optional)
        Description
        Reason for the connection status
      • Name
        config*
        Type
        object
        Description
        Connection configuration
        • Name
          authType*
          Type
          enum<string>
          Description
          Type of the authentication used for the connection
          Available options: OAUTH2
        • Name
          credentials*
          Type
          object
          Description
          Credentials for the connection
          • Name
            accessToken*
            Type
            string
            Description
            Access token for the connection
          • Name
            refreshToken
            Type
            string(optional)
            Description
            Refresh token for the connection
      • Name
        clientRedirectUrl
        Type
        string(optional)
        Description
        URL to redirect the client to, after the connection is created
      • Name
        namespace*
        Type
        object
        Description
        Details of the namespace the connection belongs to
        • Name
          identifier*
          Type
          string
          Description
          Unique identifier of the namespace
      • Name
        organization*
        Type
        object
        Description
        Details of the organization the connection belongs to
        • Name
          id*
          Type
          string
          Description
          Unique identifier for the organization
      • Name
        createdAt*
        Type
        object
        Description
        Timestamp when the connection was created
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp
      • Name
        updatedAt*
        Type
        object
        Description
        Timestamp when the connection was last updated
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp

Response

GET
/v1/connections
{
  "success": true,
  "message": "Fetched all the connections successfully",
  "data": {
    "connections": [
      {
        "id": "conn_abc123",
        "name": "My Notion Workspace",
        "connector": "NOTION",
        "status": "ACTIVE",
        "statusReason": null,
        "config": {
          "authType": "OAUTH2",
          "credentials": {
            "accessToken": "access_token_123",
            "refreshToken": null
          }
        },
        "externalId": "NOTION|[email protected]|bb78832e-c4c4-4602-929d-e80865f9cfa5",
        "clientRedirectUrl": "https://example.com/ragaas/notion/success",
        "namespace": {
          "identifier": "ns_123"
        },
        "organization": {
          "id": "org_123"
        },
        "createdAt": {
          "isoString": "2024-01-01T00:00:00Z"
        },
        "updatedAt": {
          "isoString": "2024-01-01T00:00:00Z"
        }
      }
    ]
  }
}
GET/v1/connections/:connectionId

Get Connection

Get the status of a connection.

You can send an optional X-Tenant-ID header for multitenancy within a namespace (docs).

Authorization

  • Name
    Authorization*
    Type
    string
    Description
    Bearer token authentication. Include your API key as Bearer your_api_key
  • Name
    Accept*
    Type
    string
    Description
    application/json

Path Parameters

  • Name
    connectionId*
    Type
    string
    Description
    ID of the connection

Query Parameters

  • Name
    namespaceId*
    Type
    string
    Description
    Unique identifier of the namespace

Request

GET
/v1/connections/:connectionId
curl -X GET https://api.sourcesync.ai/v1/connections/conn_abc123?namespaceId=ns_123 \
  -H "Authorization: Bearer ${SOURCE_SYNC_API_KEY}"


Response Body

  • Name
    success*
    Type
    boolean
    Description
    Indicates whether the request is successful or not. This is always true for success responses.
  • Name
    message*
    Type
    string
    Description
    Human readable message mentioning the result of the request
  • Name
    data*
    Type
    object
    Description
    Data returned from the API.
    • Name
      connection*
      Type
      object
      Description
      Details of the connection
      • Name
        id*
        Type
        string
        Description
        Unique identifier for the connection
      • Name
        name*
        Type
        string
        Description
        Name of the connection
      • Name
        connector*
        Type
        enum<string>
        Description
        Type of the connector
        Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE
      • Name
        status*
        Type
        enum<string>
        Description
        Current status of the connection
        Available options: PENDING, ACTIVE, FAILED, REVOKED
      • Name
        statusReason
        Type
        string(optional)
        Description
        Reason for the connection status
      • Name
        config*
        Type
        object
        Description
        Connection configuration
        • Name
          authType*
          Type
          enum<string>
          Description
          Type of the authentication used for the connection
          Available options: OAUTH2
        • Name
          credentials*
          Type
          object
          Description
          Credentials for the connection
          • Name
            accessToken*
            Type
            string
            Description
            Access token for the connection
          • Name
            refreshToken
            Type
            string(optional)
            Description
            Refresh token for the connection
      • Name
        clientRedirectUrl
        Type
        string(optional)
        Description
        URL to redirect the client to, after the connection is created
      • Name
        namespace*
        Type
        object
        Description
        Details of the namespace the connection belongs to
        • Name
          identifier*
          Type
          string
          Description
          Unique identifier of the namespace
      • Name
        organization*
        Type
        object
        Description
        Details of the organization the connection belongs to
        • Name
          id*
          Type
          string
          Description
          Unique identifier for the organization
      • Name
        createdAt*
        Type
        object
        Description
        Timestamp when the connection was created
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp
      • Name
        updatedAt*
        Type
        object
        Description
        Timestamp when the connection was last updated
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp

Response

GET
/v1/connections/:connectionId
{
  "success": true,
  "message": "Fetched the connection successfully",
  "data": {
    "connection": {
      "id": "conn_abc123",
      "name": "My Notion Workspace",
      "connector": "NOTION",
      "status": "ACTIVE",
      "statusReason": null,
      "config": {
        "authType": "OAUTH2",
        "credentials": {
          "accessToken": "access_token_123",
          "refreshToken": null
        }
      },
      "externalId": "NOTION|[email protected]|bb78832e-c4c4-4602-929d-e80865f9cfa5",
      "clientRedirectUrl": "https://example.com/ragaas/notion/success",
      "namespace": {
        "identifier": "ns_123"
      },
      "organization": {
        "id": "org_123"
      },
      "createdAt": {
        "isoString": "2024-01-01T00:00:00Z"
      },
      "updatedAt": {
        "isoString": "2024-01-01T00:00:00Z"
      }
    }
  }
}
PATCH/v1/connections/:connectionId

Update Connection

Update the connection or/and modify the selected pages for the connection.

You can send an optional X-Tenant-ID header for multitenancy within a namespace (docs).

Authorization

  • Name
    Authorization*
    Type
    string
    Description
    Bearer token authentication. Include your API key as Bearer your_api_key
  • Name
    Accept*
    Type
    string
    Description
    application/json

Path Parameters

  • Name
    connectionId*
    Type
    string
    Description
    ID of the connection

Request Body

  • Name
    namespaceId*
    Type
    string
    Description
    Unique identifier of the namespace where the connection will be updated
  • Name
    name
    Type
    string(optional)
    Description
    Name for the connection
  • Name
    clientRedirectUrl
    Type
    string(optional)
    Description
    URL to redirect the client to, after the connection is created

Request

PATCH
/v1/connections/:connectionId
curl -X PATCH https://api.sourcesync.ai/v1/connections/conn_abc123 \
  -H "Authorization: Bearer ${SOURCE_SYNC_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123",
    "name": "My Notion Workspace",
    "clientRedirectUrl": "https://example.com/ragaas/notion/success"
  }'


Response Body

  • Name
    success*
    Type
    boolean
    Description
    Indicates whether the request is successful or not. This is always true for success responses.
  • Name
    message*
    Type
    string
    Description
    Human readable message mentioning the result of the request
  • Name
    data*
    Type
    object
    Description
    Data returned from the API.
    • Name
      authorizationUrl*
      Type
      string
      Description
      URL to re-authorize the connection and modify selected pages for the connection
    • Name
      connection*
      Type
      object
      Description
      Details of the updated connection
      • Name
        id*
        Type
        string
        Description
        Unique identifier for the connection
      • Name
        name*
        Type
        string
        Description
        Name of the connection
      • Name
        connector*
        Type
        enum<string>
        Description
        Type of the connector
        Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE
      • Name
        status*
        Type
        enum<string>
        Description
        Current status of the connection
        Available options: PENDING, ACTIVE, FAILED, REVOKED
      • Name
        statusReason
        Type
        string(optional)
        Description
        Reason for the connection status
      • Name
        config*
        Type
        object
        Description
        Connection configuration
        • Name
          authType*
          Type
          enum<string>
          Description
          Type of the authentication used for the connection
          Available options: OAUTH2
        • Name
          credentials*
          Type
          object
          Description
          Credentials for the connection
          • Name
            accessToken*
            Type
            string
            Description
            Access token for the connection
          • Name
            refreshToken
            Type
            string(optional)
            Description
            Refresh token for the connection
      • Name
        clientRedirectUrl
        Type
        string(optional)
        Description
        URL to redirect the client to, after the connection is created
      • Name
        namespace*
        Type
        object
        Description
        Details of the namespace the connection belongs to
        • Name
          identifier*
          Type
          string
          Description
          Unique identifier of the namespace
      • Name
        organization*
        Type
        object
        Description
        Details of the organization the connection belongs to
        • Name
          id*
          Type
          string
          Description
          Unique identifier for the organization
      • Name
        createdAt*
        Type
        object
        Description
        Timestamp when the connection was created
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp
      • Name
        updatedAt*
        Type
        object
        Description
        Timestamp when the connection was last updated
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp

Response

PATCH
/v1/connections/:connectionId
{
  "success": true,
  "message": "Please visit the authorization URL to modify the selected pages for this connection",
  "data": {
    "authorizationUrl": "https://api.notion.com/v1/oauth/authorize?..."
    "connection": {
      "id": "conn_abc123",
      "name": "My Notion Workspace",
      "connector": "NOTION",
      "status": "ACTIVE",
      "statusReason": null,
      "config": {
        "authType": "OAUTH2",
        "credentials": {
          "accessToken": "access_token_123",
          "refreshToken": null
        }
      },
      "externalId": "NOTION|[email protected]|bb78832e-c4c4-4602-929d-e80865f9cfa5",
      "clientRedirectUrl": "https://example.com/ragaas/notion/success",
      "namespace": {
        "identifier": "ns_123"
      },
      "organization": {
        "id": "org_123"
      },
      "createdAt": {
        "isoString": "2024-01-01T00:00:00Z"
      },
      "updatedAt": {
        "isoString": "2024-01-01T00:00:00Z"
      }
    }
  }
}
POST/v1/connections/:connectionId/revoke

Revoke Connection

Revoke the connection.

You can send an optional X-Tenant-ID header for multitenancy within a namespace (docs).

Authorization

  • Name
    Authorization*
    Type
    string
    Description
    Bearer token authentication. Include your API key as Bearer your_api_key
  • Name
    Accept*
    Type
    string
    Description
    application/json

Path Parameters

  • Name
    connectionId*
    Type
    string
    Description
    ID of the connection

Request Body

  • Name
    namespaceId*
    Type
    string
    Description
    Unique identifier of the namespace

Request

POST
/v1/connections/:connectionId/revoke
curl -X POST https://api.sourcesync.ai/v1/connections/conn_abc123/revoke \
  -H "Authorization: Bearer ${SOURCE_SYNC_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "namespaceId": "ns_123"
  }'


Response Body

  • Name
    success*
    Type
    boolean
    Description
    Indicates whether the request is successful or not. This is always true for success responses.
  • Name
    message*
    Type
    string
    Description
    Human readable message mentioning the result of the request
  • Name
    data*
    Type
    object
    Description
    Data returned from the API.
    • Name
      connection*
      Type
      object
      Description
      Details of the revoked connection
      • Name
        id*
        Type
        string
        Description
        Unique identifier for the connection
      • Name
        name*
        Type
        string
        Description
        Name of the connection
      • Name
        connector*
        Type
        enum<string>
        Description
        Type of the connector
        Available options: NOTION, GOOGLE_DRIVE, DROPBOX, ONEDRIVE, BOX, CONFLUENCE
      • Name
        status*
        Type
        enum<string>
        Description
        Current status of the connection
        Available options: PENDING, ACTIVE, FAILED, REVOKED
      • Name
        statusReason
        Type
        string(optional)
        Description
        Reason for the connection status
      • Name
        config*
        Type
        object
        Description
        Connection configuration
        • Name
          authType*
          Type
          enum<string>
          Description
          Type of the authentication used for the connection
          Available options: OAUTH2
        • Name
          credentials*
          Type
          object
          Description
          Credentials for the connection
          • Name
            accessToken*
            Type
            string
            Description
            Access token for the connection
          • Name
            refreshToken
            Type
            string(optional)
            Description
            Refresh token for the connection
      • Name
        clientRedirectUrl
        Type
        string(optional)
        Description
        URL to redirect the client to, after the connection is created
      • Name
        namespace*
        Type
        object
        Description
        Details of the namespace the connection belongs to
        • Name
          identifier*
          Type
          string
          Description
          Unique identifier of the namespace
      • Name
        organization*
        Type
        object
        Description
        Details of the organization the connection belongs to
        • Name
          id*
          Type
          string
          Description
          Unique identifier for the organization
      • Name
        createdAt*
        Type
        object
        Description
        Timestamp when the connection was created
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp
      • Name
        updatedAt*
        Type
        object
        Description
        Timestamp when the connection was last updated
        • Name
          isoString*
          Type
          string
          Description
          ISO 8601 formatted timestamp

Response

POST
/v1/connections/:connectionId/revoke
{
  "success": true,
  "message": "The connection has been revoked successfully",
  "data": {
    "connection": {
      "id": "conn_abc123",
      "name": "My Notion Workspace",
      "connector": "NOTION",
      "status": "REVOKED",
      "statusReason": "The connection was revoked by the user",
      "config": {
        "authType": "OAUTH2",
        "credentials": null,
      },
      "clientRedirectUrl": null,
      "namespace": {
        "identifier": "ns_123"
      },
      "organization": {
        "id": "org_123"
      },
      "createdAt": {
        "isoString": "2024-01-01T00:00:00Z"
      },
      "updatedAt": {
        "isoString": "2024-01-01T00:00:00Z"
      }
    }
  }
}

Connection Status

  • Name
    PENDING*
    Type
    string
    Description

    Connection created but not yet authorized

  • Name
    ACTIVE*
    Type
    string
    Description

    Connection authorized and ready to use

  • Name
    FAILED*
    Type
    string
    Description

    Connection authorization failed

  • Name
    REVOKED*
    Type
    string
    Description

    Connection access was revoked

Connection Credentials

For OAuth2 connections, the credentials object contains:

  • Name
    accessToken*
    Type
    string
    Description

    The OAuth access token for API requests

  • Name
    refreshToken
    Type
    string | null(optional)
    Description

    The OAuth refresh token (null for Notion since tokens don't expire)

  • Name
    accessTokenExpiresAt
    Type
    number | null(optional)
    Description

    Token expiration timestamp (Infinity for Notion tokens that don't expire)

  • Name
    refreshTokenExpiresAt
    Type
    number | null(optional)
    Description

    Refresh token expiration timestamp (null for Notion)

Connection Properties

In addition to credentials, connections may include these properties:

  • Name
    externalId
    Type
    string(optional)
    Description

    External identifier used for connection management and isolation between different users. Format varies by connector:

Error Codes

  • Name
    INVALID_REQUEST
    Description

    Missing or invalid request parameters

  • Name
    NAMESPACE_NOT_FOUND
    Description

    Specified namespace does not exist

  • Name
    CONNECTION_NOT_FOUND
    Description

    Specified connection does not exist

  • Name
    CREATE_CONNECTION_FAILED
    Description

    Failed to create connection

  • Name
    FETCH_CONNECTIONS_FAILED
    Description

    Failed to fetch connections