Create an AI Сopilot for your app
In this use case, we'll demonstrate how to integrate AI into your application. The easiest way to integrate data is through CSV file synchronization. Conduit creates a unique UI for your application, and the AI chat link obtained can be integrated as an iframe into the user interface of your product for each specific client.
You can find the repository here:
https://github.com/cndt-app/copilot_saas_demo/
The first step is to create a Company for your user. This is done by sending an HTTP POST request using the Link APP authorization token.
Example of creating a Company:
To begin, obtain the authorization token by visiting: https://app.getconduit.app/auth/link_app_token/
Then, send the following CURL request to create the Company:
Request Parameters:
{Link_APP_Token}: The Link APP authorization token obtained from the Conduit website.
{User_DB_ID}: The unique identifier of the user in your database. This identifier will be used as the id for the created Company.
name: The name of the Company, which will be displayed in Conduit.
page_enabled: A flag indicating whether the user can independently select data sources. Set to true to enable this feature.
Example Response:
Upon successful creation of the Company, the service will return the following response:
Response Field Descriptions:
id: The identifier of the created Company, corresponding to the provided User_DB_ID.
name: The name of the created Company.
created_at: The date and time when the Company was created in ISO 8601 format.
link_page: An object containing information about the Company's page.
url: The link to the Company's page where the user can select data sources.
enabled: The availability status of the page (enabled/disabled).
api_token: An object containing information about the API token for accessing the Company.
token: The Company-specific API token.
expires_at: The expiration time of the token in UNIX timestamp format.
Note: The token expires after 10 minutes.
After creating the Company and obtaining the access token, the next step is to upload a CSV file, which will be used by Copilot to create a chat.
To upload the file, you need to send an HTTP POST request to the following URL
Request Parameters:
{Company_Token}: The access token for the Company, obtained in the previous step.
file: The path to the CSV file you want to upload. In this example, the file orders.csv is used.
Example Response:
Upon successful file upload, the server will return an integer identifier for the uploaded file.
Response description
The returned value (12345 in this example) is a unique identifier for the uploaded file in the Conduit system. This identifier will be used in subsequent requests to reference this file.
Step 3: Metadata Description
In order for Copilot to use the uploaded file, it's necessary to provide a description of the metadata. This is done by sending an HTTP POST request.
Request Parameters:
- {file_id}: The ID of the file obtained in the upload step. Each uploaded file has a unique ID that can only be used once.
- name: The name of the file to be displayed in the interface, for example, "Orders."
- thousands_separator: The symbol used to separate thousands in numbers in the file. It can be a period (.) or a comma (,).
- decimal_separator: The symbol used to separate the decimal part in numbers. It can be a period (.) or a comma (,).
- read_from_line: The line number from which data reading starts. For example, if the first line contains headers, read_from_line should be set to 1.
- columns: Description of the columns in the file. Each column description includes:
- name: The column name, which should match the name in the CSV file.
- kind: The data type, which can be DIMENSION or METRIC.
- type: The data type in the column.
For DIMENSION, valid values are STRING, DATE, DATETIME, BOOL.
For METRIC, valid values are MONEY, DECIMAL, INTEGER, PERCENT.
- agg: The aggregation method for metrics.
For DIMENSION, the only valid value is UNIQ.
For METRIC, valid values are SUM, COUNT, AVERAGE, MAX, MIN, FIRST.
- is_enabled: If false, Copilot will not use this column.
- description: An optional field that can be used to provide additional information about the column to Copilot.
Example Response:
Upon successful saving of the file and its description, the server will return a unique identifier for the saved Spreadsheet.
Response Description:
The unique identifier of the saved Spreadsheet in the Conduit system. This identifier will be used in subsequent requests.
Once the Spreadsheet is saved, you can create a new Copilot chat. This is done by sending an HTTP POST request.
Request Parameters:
- name: The name of the new chat. This name will be displayed in the user interface.
- datasets: The list of datasets to be used in the chat. Each dataset is described by an object, which includes:
- type: The type of dataset. For Spreadsheet, the value should be "SPREADSHEET".
- id: The identifier of the Spreadsheet obtained after saving it.
Example Response:
Upon successful creation of the chat, the server will return the following JSON:
Response Field Descriptions:
- id: The unique identifier of the created chat in the Conduit system. This identifier can be used for further operations with the chat.
- name: The name of the created chat, matching the name specified in the request.
- url: The link to the chat's iframe. This link can be embedded in your product's user interface to provide users with direct access to the Copilot chat from your application.
To retrieve a list of all saved Spreadsheets available for the Company, you need to send an HTTP GET request.
Request Parameters:
In this case, no parameters are passed in the URL. You only need to provide the Company's authorization token in the request headers.
Company_Token: The access token for your company, which you used to authenticate previous requests.
Example Response:
The server's response is an array of objects, each corresponding to a saved Spreadsheet.
Description of Fields in the Response:
Each object in the array represents a separate Spreadsheet and contains the following fields:
- id: The unique identifier of the Spreadsheet in the Conduit system.
- name: The name of the Spreadsheet, as specified by the user during saving.
- created_at: The date and time when the Spreadsheet was created in ISO 8601 format.
- columns: An array of objects describing the columns of the Spreadsheet. Each column object includes:
- name: The name of the column as it was specified in the CSV file.
- kind: The type of the column - DIMENSION or METRIC.
- type: The data type in the column. For example, STRING, DATE, DATETIME, BOOL for DIMENSION, and MONEY, DECIMAL, INTEGER, PERCENT for METRIC.
- is_enabled: Indicates whether the column is used by Copilot.
To update a previously saved Spreadsheet in Conduit Copilot SaaS, you need to send an HTTP POST request to the appropriate endpoint.
Request Parameters:
- {spreadsheet_id}: The unique identifier of the Spreadsheet you want to update.
- file_id: (Optional) The ID of the new uploaded file. Leave this field empty if you don't need to update the file itself, or specify the new file ID.
- name: The new name for the Spreadsheet. This is used for display in the user interface.
- thousands_separator: The symbol used to separate thousands in numbers. It can be a period (.) or a comma (,).
- decimal_separator: The symbol used to separate the decimal part in numbers. It can be a period (.) or a comma (,).
- read_from_line: The line number from which data reading starts. Useful if new headers or notes are added at the beginning of the file.
- columns: An array describing the columns of the file. Each description includes:
- name: The name of the column, which should match the name in the CSV file.
- kind: The type of the column, which can be DIMENSION or METRIC.
- type: The data type in the column. For DIMENSION, valid types are STRING, DATE, DATETIME, BOOL. For METRIC, valid types are MONEY, DECIMAL, INTEGER, PERCENT.
- agg: The aggregation method for metrics. For DIMENSION, the only valid value is UNIQ. For METRIC, valid values are SUM, COUNT, AVERAGE, MAX, MIN, FIRST.
- is_enabled: If false, Copilot will not use this column.
- description: (Optional) A description of the column, which can be used to provide additional information to Copilot.
This request allows you to update the metadata and data structure of the Spreadsheet, and if necessary, the data file itself.
To get a list of all created Copilot chats for your company, you can send an HTTP GET request.
Request Parameters:
- {Company_Token}: The access token for your company, which you used to authenticate previous requests.
Example Response:
Upon successful execution of the request, the server will return a list of chats in JSON format:
Description of Response Fields:
- id: The unique identifier of the chat in the Conduit system. This identifier can be used for further operations with the chat.
- name: The name of the chat, specified during its creation. It is displayed in the user interface.
- url: The link to the chat's iframe. You can embed this link into your product's user interface to provide users with direct access to the Copilot chat from your application.
This list includes all chats created for your company and can be used for managing chats or integrating them into your application.
You can find the repository here:
https://github.com/cndt-app/copilot_saas_demo/
Step 1: Creating a Company
The first step is to create a Company for your user. This is done by sending an HTTP POST request using the Link APP authorization token.
Example of creating a Company:
To begin, obtain the authorization token by visiting: https://app.getconduit.app/auth/link_app_token/
Then, send the following CURL request to create the Company:
curl -X POST https://api.getconduit.app/link/company/ \\
-H "Authorization: Bearer {Link_APP_Token}" \\
-H "Content-Type: application/json" \\
-d '{ \\
"id": "{User_DB_ID}", \\
"name": "User's Company", \\
"page_enabled": true \\
}'Request Parameters:
{Link_APP_Token}: The Link APP authorization token obtained from the Conduit website.
{User_DB_ID}: The unique identifier of the user in your database. This identifier will be used as the id for the created Company.
name: The name of the Company, which will be displayed in Conduit.
page_enabled: A flag indicating whether the user can independently select data sources. Set to true to enable this feature.
Example Response:
Upon successful creation of the Company, the service will return the following response:
{
"id": "{User_DB_ID}",
"name": "User's Company",
"created_at": "2023-03-15T12:34:56Z",
"link_page": {
"url": "https://link.to/company_page",
"enabled": true
},
"api_token": {
"token": "company_specific_token",
"expires_at": 1678898400
}
}Response Field Descriptions:
id: The identifier of the created Company, corresponding to the provided User_DB_ID.
name: The name of the created Company.
created_at: The date and time when the Company was created in ISO 8601 format.
link_page: An object containing information about the Company's page.
url: The link to the Company's page where the user can select data sources.
enabled: The availability status of the page (enabled/disabled).
api_token: An object containing information about the API token for accessing the Company.
token: The Company-specific API token.
expires_at: The expiration time of the token in UNIX timestamp format.
Note: The token expires after 10 minutes.
Step 2: File Upload
After creating the Company and obtaining the access token, the next step is to upload a CSV file, which will be used by Copilot to create a chat.
To upload the file, you need to send an HTTP POST request to the following URL
curl -X POST https://api.getconduit.app/copilot_saas/spreadsheets/upload/ \\
-H "Authorization: Bearer {Company_Token}" \\
-F "file=@/path/to/orders.csv"Request Parameters:
{Company_Token}: The access token for the Company, obtained in the previous step.
file: The path to the CSV file you want to upload. In this example, the file orders.csv is used.
Example Response:
Upon successful file upload, the server will return an integer identifier for the uploaded file.
{
"file_id": 12345
}Response description
The returned value (12345 in this example) is a unique identifier for the uploaded file in the Conduit system. This identifier will be used in subsequent requests to reference this file.
Step 3: Metadata Description
In order for Copilot to use the uploaded file, it's necessary to provide a description of the metadata. This is done by sending an HTTP POST request.
curl -X POST https://api.getconduit.app/copilot_saas/spreadsheets/ \\
-H "Authorization: Bearer {Company_Token}" \\
-H "Content-Type: application/json" \\
-d '{ \\
"file_id": "{file_id}", \\
"name": "name", \\
"thousands_separator": ".", \\
"decimal_separator": ",", \\
"read_from_line": 1, \\
"columns": "columns" \\
}'Request Parameters:
- {file_id}: The ID of the file obtained in the upload step. Each uploaded file has a unique ID that can only be used once.
- name: The name of the file to be displayed in the interface, for example, "Orders."
- thousands_separator: The symbol used to separate thousands in numbers in the file. It can be a period (.) or a comma (,).
- decimal_separator: The symbol used to separate the decimal part in numbers. It can be a period (.) or a comma (,).
- read_from_line: The line number from which data reading starts. For example, if the first line contains headers, read_from_line should be set to 1.
- columns: Description of the columns in the file. Each column description includes:
- name: The column name, which should match the name in the CSV file.
- kind: The data type, which can be DIMENSION or METRIC.
- type: The data type in the column.
For DIMENSION, valid values are STRING, DATE, DATETIME, BOOL.
For METRIC, valid values are MONEY, DECIMAL, INTEGER, PERCENT.
- agg: The aggregation method for metrics.
For DIMENSION, the only valid value is UNIQ.
For METRIC, valid values are SUM, COUNT, AVERAGE, MAX, MIN, FIRST.
- is_enabled: If false, Copilot will not use this column.
- description: An optional field that can be used to provide additional information about the column to Copilot.
Example Response:
Upon successful saving of the file and its description, the server will return a unique identifier for the saved Spreadsheet.
{
"id": 67890
}Response Description:
The unique identifier of the saved Spreadsheet in the Conduit system. This identifier will be used in subsequent requests.
Step 4: Creating a New Copilot Chat
Once the Spreadsheet is saved, you can create a new Copilot chat. This is done by sending an HTTP POST request.
curl -X POST https://api.getconduit.app/copilot_saas/chats/ \\
-H "Authorization: Bearer {Company_Token}" \\
-H "Content-Type: application/json" \\
-d '{ \\
"name": "Chat Name", \\
"datasets": [ \\
{"type": "SPREADSHEET", "id": "{spreadsheet_id}"} \\
] \\
}'Request Parameters:
- name: The name of the new chat. This name will be displayed in the user interface.
- datasets: The list of datasets to be used in the chat. Each dataset is described by an object, which includes:
- type: The type of dataset. For Spreadsheet, the value should be "SPREADSHEET".
- id: The identifier of the Spreadsheet obtained after saving it.
Example Response:
Upon successful creation of the chat, the server will return the following JSON:
{
"id": 12345,
"name": "Chat Name",
"url": "https://link.to/chat/iframe"
}Response Field Descriptions:
- id: The unique identifier of the created chat in the Conduit system. This identifier can be used for further operations with the chat.
- name: The name of the created chat, matching the name specified in the request.
- url: The link to the chat's iframe. This link can be embedded in your product's user interface to provide users with direct access to the Copilot chat from your application.
Getting a List of Saved Spreadsheets
To retrieve a list of all saved Spreadsheets available for the Company, you need to send an HTTP GET request.
curl -X GET https://api.getconduit.app/copilot_saas/spreadsheets/ \\
-H "Authorization: Bearer {Company_Token}"Request Parameters:
In this case, no parameters are passed in the URL. You only need to provide the Company's authorization token in the request headers.
Company_Token: The access token for your company, which you used to authenticate previous requests.
Example Response:
The server's response is an array of objects, each corresponding to a saved Spreadsheet.
[
{
"id": 12345,
"name": "Orders",
"created_at": "2023-03-15T12:34:56Z",
"columns": [
{
"name": "Order ID",
"kind": "DIMENSION",
"type": "STRING",
"is_enabled": true
},
...
]
},
...
]Description of Fields in the Response:
Each object in the array represents a separate Spreadsheet and contains the following fields:
- id: The unique identifier of the Spreadsheet in the Conduit system.
- name: The name of the Spreadsheet, as specified by the user during saving.
- created_at: The date and time when the Spreadsheet was created in ISO 8601 format.
- columns: An array of objects describing the columns of the Spreadsheet. Each column object includes:
- name: The name of the column as it was specified in the CSV file.
- kind: The type of the column - DIMENSION or METRIC.
- type: The data type in the column. For example, STRING, DATE, DATETIME, BOOL for DIMENSION, and MONEY, DECIMAL, INTEGER, PERCENT for METRIC.
- is_enabled: Indicates whether the column is used by Copilot.
Updating a Saved Spreadsheet
To update a previously saved Spreadsheet in Conduit Copilot SaaS, you need to send an HTTP POST request to the appropriate endpoint.
curl -X POST https://api.getconduit.app/copilot_saas/spreadsheets/{spreadsheet_id}/ \\
-H "Authorization: Bearer {Company_Token}" \\
-H "Content-Type: application/json" \\
-d '{ \\
"file_id": "optional_new_file_id", \\
"name": "Updated Spreadsheet Name", \\
"thousands_separator": ".", \\
"decimal_separator": ",", \\
"read_from_line": 2, \\
"columns": "[{column_description}]" \\
}'Request Parameters:
- {spreadsheet_id}: The unique identifier of the Spreadsheet you want to update.
- file_id: (Optional) The ID of the new uploaded file. Leave this field empty if you don't need to update the file itself, or specify the new file ID.
- name: The new name for the Spreadsheet. This is used for display in the user interface.
- thousands_separator: The symbol used to separate thousands in numbers. It can be a period (.) or a comma (,).
- decimal_separator: The symbol used to separate the decimal part in numbers. It can be a period (.) or a comma (,).
- read_from_line: The line number from which data reading starts. Useful if new headers or notes are added at the beginning of the file.
- columns: An array describing the columns of the file. Each description includes:
- name: The name of the column, which should match the name in the CSV file.
- kind: The type of the column, which can be DIMENSION or METRIC.
- type: The data type in the column. For DIMENSION, valid types are STRING, DATE, DATETIME, BOOL. For METRIC, valid types are MONEY, DECIMAL, INTEGER, PERCENT.
- agg: The aggregation method for metrics. For DIMENSION, the only valid value is UNIQ. For METRIC, valid values are SUM, COUNT, AVERAGE, MAX, MIN, FIRST.
- is_enabled: If false, Copilot will not use this column.
- description: (Optional) A description of the column, which can be used to provide additional information to Copilot.
This request allows you to update the metadata and data structure of the Spreadsheet, and if necessary, the data file itself.
Retrieving Chat List
To get a list of all created Copilot chats for your company, you can send an HTTP GET request.
curl -X GET https://api.getconduit.app/copilot_saas/chats/ \\
-H "Authorization: Bearer {Company_Token}"Request Parameters:
- {Company_Token}: The access token for your company, which you used to authenticate previous requests.
Example Response:
Upon successful execution of the request, the server will return a list of chats in JSON format:
[
{
"id": 12345,
"name": "Chat Name 1",
"url": "https://link.to/chat1/iframe"
},
{
"id": 67890,
"name": "Chat Name 2",
"url": "https://link.to/chat2/iframe"
}
// Or more chats
]Description of Response Fields:
- id: The unique identifier of the chat in the Conduit system. This identifier can be used for further operations with the chat.
- name: The name of the chat, specified during its creation. It is displayed in the user interface.
- url: The link to the chat's iframe. You can embed this link into your product's user interface to provide users with direct access to the Copilot chat from your application.
This list includes all chats created for your company and can be used for managing chats or integrating them into your application.
Updated on: 02/04/2024
Thank you!