For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Login
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
HomeDocsAPI ReferenceMCP ServerChat SDKsRelease Notes
  • Introduction
    • Overview
    • Authentication
    • Versioning
    • Limits
    • Pagination
    • Errors
    • Migrate to V2
    • Changelog
  • Knowledge
    • Overview
    • Sources
    • Articles
    • Tags
  • End Users
    • Overview
    • Getting started
    • Developer guide
  • Integrations
    • Overview
    • Getting started
      • GETList integrations
      • POSTCreate an integration
      • PATCHUpdate an integration
      • GETGet an installation
      • PATCHUpdate installation status
  • Conversations
    • Overview
    • Getting started
  • Webhooks
    • Overview
  • Data Compliance
    • Overview
  • Data Export
    • Overview
    • Getting started
    • Conversations
    • Messages
Login
LogoLogo
IntegrationsIntegrations

Create an integration

POST
https://example.ada.support/api/v2/platform-integrations/
POST
/api/v2/platform-integrations/
1import requests
2
3url = "https://example.ada.support/api/v2/platform-integrations/"
4
5payload = { "identifier_field_path": "credentials.knowledgeHubUrl" }
6headers = {
7    "Authorization": "Bearer <token>",
8    "Content-Type": "application/json"
9}
10
11response = requests.post(url, json=payload, headers=headers)
12
13print(response.json())
1{
2  "author": "Cool Shop",
3  "configuration_fields": {
4    "title": "Connect to Cool Shop Knowledge Hub",
5    "type": "object",
6    "description": "Complete this form to integrate your Knowledge Hub with your AI Agent",
7    "required": [
8      "credentials"
9    ],
10    "properties": {
11      "credentials": {
12        "type": "object",
13        "title": "My Knowledge Hub credentials",
14        "description": "The following information is found in your Cool Shop admin center",
15        "properties": {
16          "knowledgeHubUrl": {
17            "type": "string",
18            "title": "Knowledge Hub URL",
19            "description": "The URL of your Knowledge Hub"
20          },
21          "secretKey": {
22            "type": "string",
23            "title": "Secret key",
24            "description": "Find your Knowledge Hub secret key on the Knowledge Hub Management page",
25            "format": "password"
26          }
27        },
28        "required": [
29          "knowledgeHubUrl",
30          "secretKey"
31        ]
32      }
33    }
34  },
35  "contact": "help@coolshop.support",
36  "description": "Connect to Cool Shop Knowledge Hub to sync articles with your AI Agent's knowledge base",
37  "id": "5df263b7db5a7e6ea03fae9b",
38  "identifier_field_path": "credentials.knowledgeHubUrl",
39  "name": "Connect to Cool Shop Knowledge Hub",
40  "oauth_callback_url": "http://coolshop.com/",
41  "scopes": [
42    "articles:read",
43    "knowledge_sources:write"
44  ],
45  "status": "development",
46  "tags": [
47    "knowledge"
48  ],
49  "uninstallation_url": "http://coolshop.com/uninstall",
50  "call_to_action": "Connect to Cool Shop Knowledge Hub",
51  "client_secret": "a4a908jgf9a8gh9a",
52  "created": "2020-09-20T00:00:00+00:00",
53  "error_codes": {
54    "error_403": "Unauthorized",
55    "error_404": "Not Found"
56  },
57  "icon_url": "https://example.com/icon.png",
58  "updated": "2020-09-20T00:00:00+00:00"
59}

Create an integration. Integrations are created in development status by default.

Was this page helpful?
Previous

Update an integration

Next
Built with

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
identifier_field_pathstringRequired

JMESPath describing which of the fields in configuration_fields is the best human-friendly field to use to identify a specific installation (e.g., account name)

namestringRequired1-160 characters
The name of the integration
descriptionstringRequired>=1 character
A description of what the integration does and how to use it
authorstringRequired1-160 characters
The name of the integration developer
contactstringRequired>=1 character
The URL or email address where users of the integration can reach out for support
uninstallation_urlstringRequiredformat: "url">=1 character

The delete endpoint that initiates the uninstallation flow for the integration

oauth_callback_urlstringRequiredformat: "url">=1 character

The get endpoint that will be invoked after OAuth authorization

tagslist of enumsRequired
A list of tags that describe the type of integration
Allowed values:
scopeslist of stringsRequired
The list of OAuth token permissions the integration requests when installed
configuration_fieldsobjectRequired

A json-schema describing the settings fields that a user should be presented with when installing the integration

icon_urlstring or nullOptionalformat: "url">=1 character
The URL of the icon that should be displayed with your integration
call_to_actionstring or nullOptional>=1 character
The call to action text
error_codesobject or nullOptional
An object containing error codes and their corresponding error message the integration may return to the OAuth failure page to be displayed

Response

Platform integration created
authorstring1-160 characters
The name of the integration developer
configuration_fieldsobject

A json-schema describing the settings fields that a user should be presented with when installing the integration

contactstring>=1 character
The URL or email address where users of the integration can reach out for support
descriptionstring>=1 character
A description of what the integration does and how to use it
idstring
The unique identifier for the integration
identifier_field_pathstring

JMESPath describing which of the fields in configuration_fields is the best human-friendly field to use to identify a specific installation (e.g., account name)

namestring1-160 characters
The name of the integration
oauth_callback_urlstringformat: "url">=1 character

The get endpoint that will be invoked after OAuth authorization

scopeslist of strings
The list of OAuth token permissions the integration requests when installed
statusstring

The current state of the integration (development, approved, archived)

tagslist of enums
A list of tags that describe the type of integration
Allowed values:
uninstallation_urlstringformat: "url">=1 character

The delete endpoint that initiates the uninstallation flow for the integration

call_to_actionstring or null>=1 character
The call to action text
client_secretstringRead-only
The OAuth client secret for the integration
createdstringformat: "date-time"
The date the integration was created
error_codesobject or null
An object containing error codes and their corresponding error message the integration may return to the OAuth failure page to be displayed
icon_urlstring or nullformat: "url">=1 character
The URL of the icon that should be displayed with your integration
updatedstringformat: "date-time"
The date the integration was last updated

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error