Add or import APIs

In addition to the various integrations supported by Yellow.ai, you can seamlessly integrate any third-party APIs with your AI-agent. This comprehensive guide provides step-by-step instructions on connecting your AI-agent to external APIs, enabling real-time data storage and retrieval for creating a personalized user experience.

Add a new API

There are two ways by which you can add API:

• Add API manually
• Import APIs

Add API manually

1. Go to Automation > API > + Add new API.

   

2. In the pop-up screen, specify the API name, HTTP Method, and the request URL along with the query parameters.

   

3. Click Add new API to save the details.

Add request components for APIs

To use an API, you need to include parameters for requesting information, incorporate headers to notify the third party about the data being sent, and add a body when transmitting data to the API. Our platform also provides the option to modify settings related to an API.

Add query params

API parameters are essential components used when making requests to an API. They serve as specific instructions or information that you include with your request, helping the API understand and fulfill your requirements accurately.

To add params:

1. On the API details page, under PARAMS, click + Add Params

   

2. Enter params in key-value pairs and click Add.

   

Below are examples of key-value pairs for static and dynamic parameters: Static parameter:

• Key: botId
• Value: x766543323dwe_34

Dynamic parameter:

• Key: city
• Value: {{{city}}} In these examples: The botId key has a static value (it remains constant). The "city" key has a dynamic value represented as {{{city}}}, indicating that the value will be dynamically replaced with the actual value of the "city" parameter during runtime.

Add request headers

Headers in API requests are additional pieces of information sent alongside the main request.

To add headers:

1. On the API details page, under HEADERS click + Add headers

   

2. Enter headers in key-value pairs and click Add. For example, if you have are authenticating an API, set the Key as Authorization and the Value as the API key.

   

Add body

The body in an API is the main content of the request containing data or information that should be sent to the third-party server. For POST, PUT, or DELETE methods, you can add request body under the Body section.

note

Multipart/form-data is not supported.

To add a body:

1. On the API details page, under BODY, choose the format of the request body. The supported formats are x-www-form-urlencoded, JSON, XML, GRAPHQL, form-data and raw.

2. For JSON, XML, GRAPHQLform-data or raw body, type or paste the request body the available box.

   

   For other formats, click + Add body and provide body params in key-value pairs.

   

To send dynamic data over body use "{{{value}}}".

note

• You can pass the access key or auth token in the way that the API is designed. You could pass it in the request URL, body, or headers. You can ignore this for APIs where no authentication is required.

Configuration

You can modify the API settings for optimal performance and security. This lets you manage timeout, retry strategies, and SSL enforcement, enhancing your control over communication for a more resilient and secure API integration.

Configuration	Description
Timeout	Maximum time allowed for API response
Retry on failure (5xx)	Number of attempts to retry in case of server errors
Follow redirect(s)	Determines if API should automatically follow redirects
Encoding	Method used to encode data (e.g., JSON, XML)
Use strictSSL	Enforces strict SSL certificate validation. You might not get response if this is enabled and there is some problem with SSL certificate.
API alerts on	Events triggering alerts (e.g., errors, high traffic)
Default message on invoking API	Default response or action when API is invoked
API failure message (4/5xx code)	Message displayed upon API failure with specific codes
enableMutualTLS	Enables mutual TLS authentication for enhanced security

note

The Configure environment option is disabled in the Live/Production environment.

Import APIs (CURL/JSON)

If you have a CURL script, JSON file, or collection URL, you can conveniently import it to yellow.ai.

1. Go to Automation > API.

2. Click the arrow icon next to API management and select Import .

   

Import API from CURL

1. In Type, choose Curl .

   

2. In API name enter a unique name for the API. Use alpha-numeric characters without space.

   

3. In Import curl, copy past the CURL script and click Import.

4. The imported API will be available under API Management.

   

Import API(s) from a JSON file

If you have one or more APIs, save your collection in a JSON file and import them as mentioned in the following steps:

1. Choose Type as Collection or JSON depending on the file you want to import

2. Drag & drop the file in Import JSON or use the Upload file button to upload the file.

   

3. Click Import.

4. The imported API will be available under API Management.

   

Configure environment variables

Streamline API configuration across environments by using the Configure Environment Variable option. Instead of manually inputting endpoint or parameter values for each environment, this option allows you to define and manage values uniquely for each environment.

To add environment variables:

1. Go to Automation > API > Configure environment.

   

2. Enter the key, for example endpoint and enter the respective values for each environment. Click Save.

   

3. Include the key in API URL in the following format: {{{env.variablename}}} for example, {{{env.endpoint}}}

   

4. Choose the environment and click Send to test the API. A 2xx response indicates that the API works successfully.

   

Test the API

To verify the proper functioning of the added API, input all API details and select the SEND button adjacent to the API. A sample response will be visible if the API works properly.

Confirm the expected functionality of the API and click Save to save the API settings.

note

• API response has a size limit of 250kb. You will get an error if the response exceeds the limit.

• Before testing the API, choose the respective environment from the drop-down.

  

Configure MTLS authentication

MTLS, or Mutual Transport Layer Security, is an essential part of keeping APIs safe and secure. It works by verifying the identity of both the client and server, ensuring that messages exchanged between them are authentic and haven't been tampered with.

This method establishes a trusted communication channel, safeguarding sensitive information from unauthorized access or modifications during transmission. Additionally, MTLS enhances the overall security posture of applications and systems by providing robust encryption and authentication mechanisms.

Prerequisites

To configure MTLS, you'll need specific information from the system where the API is hosted. Here's what you'll need:

1. Domain: The domain name of the system hosting the API.
2. Certificate: A digital certificate used for encryption and authentication. This should be provided in the file format with the ".cert" extension.
3. Key: The private key associated with the certificate, used for encryption and decryption. It should be provided in the file format with the ".key" extension.
4. Certificate Authority (CA): The entity that issues and verifies the digital certificates. You'll need information about the Certificate Authority responsible for issuing the certificate used by the API.

Configuring MTLS authentication

Only Super Admin can add a new certificate.

note

Developer, Admin and Super admin roles can view this feature but only the Super Admin can make changes such as add a new certificate, delete the existing certificate, etc. Only the Super Admin can view the key.

Here are the steps to configure MTLS authentication:

1. Gather the required information mentioned above: Domain, Certificate, Key, and Certificate Authority.

2. Navigate to the AI-agent environment where you want to configure MTLS.

3. On the cloud platform, go to Automation, then API.

4. On the right side, you'll see a lock icon labeled "Configure MTLS authentication." Click on it.

   

5. Enter the Domain name.

6. Upload the Certificate file.

7. Upload the Key file.

8. Upload the Certificate Authority file.

9. Click on Save to apply the configuration.

   

Troubleshooting errors when saving certificate

If you encounter any errors while saving the certificate, follow these steps:

1. Open the Inspect tool of your browser.
2. Navigate to the network tab.
3. Try saving the details again.
4. Look for the name saveApiCertificates and click on it.
5. If you see an error message like host is invalid, check the host entry URL. If it starts directly with the domain (e.g., app.yellow.ai), try adding "https://" or "http://" before the domain (e.g., https://app.yellow.ai). This should resolve the issue.

{
    "success": true,
    "message": "Success",
    "data": {
        "inserted": [],
        "updated": [],
        "invalid": [
            {
                "host": "apihmo-mtls.brb.com.br",
                "error": "Error: Host is invalid\n    at /app/dist/controllers/apiCertificates.js:83:27\n    at step (/app/dist/controllers/apiCertificates.js:33:23)\n    at Object.next (/app/dist/controllers/apiCertificates.js:14:53)\n    at /app/dist/controllers/apiCertificates.js:8:71\n    at new Promise (<anonymous>)\n    at __awaiter (/app/dist/controllers/apiCertificates.js:4:12)\n    at validateCertData (/app/dist/controllers/apiCertificates.js:71:49)\n    at /app/dist/controllers/apiCertificates.js:164:42\n    at step (/app/dist/controllers/apiCertificates.js:33:23)\n    at Object.next (/app/dist/controllers/apiCertificates.js:14:53)\n    at /app/dist/controllers/apiCertificates.js:8:71\n    at new Promise (<anonymous>)\n    at __awaiter (/app/dist/controllers/apiCertificates.js:4:12)\n    at processCertificates (/app/dist/controllers/apiCertificates.js:146:12)\n    at /app/dist/controllers/apiCertificates.js:215:42\n    at step (/app/dist/controllers/apiCertificates.js:33:23)"
            }
        ]
    }
}

• If you encounter any other error, such as "Certificate is invalid", please* check it internally and provide the correct certificate.

Export APIs

Exporting APIs involves capturing their configuration settings, allowing for seamless sharing, backup, or replication. Follow these steps to export APIs:

1. Go to Automation > API.

2. Click the arrow icon next to API management and select Export .

   

3. Select the APIs to be exported, you can also select Select all APIs at the left bottom to select all the APIs in one go

   

4. Click Export.

Troubleshooting

API is not working, or the module is not showing any response

• Disabling Use Strict SSL can sometimes resolve connectivity issues, especially if there are problems with SSL certificates. Ensure that you're aware of the security implications before making changes to SSL settings.

API works in Postman and API management but gives a blank response when tested in Node.

• Check your dynamic environment variables. Ensure you pass the variables in triple braces - {{{env.variable}}}.

  In Postman, it would be in double braces - {{env.name}}.

• For cRUL requests, instead of creating the API separately, import the cURL request to prevent errors in the cloud.

API working correctly in Postman but returns a 403 error when integrated into the Automation API section

The issue may stem from region-specific URLs being blocked. This could be because the region specific URLs are gettings bloxked, it is recommended to Whitelist your region specific URL. For instance, https://r1.cloud.yellow.ai.