# External API

### Working with External APIs in eMOBIQ AI

{% embed url="<https://www.youtube.com/watch?v=EpdeGfuKEeA>" %}

eMOBIQ AI enables seamless integration with external APIs, allowing your application to communicate with third-party systems, databases, or services. This functionality empowers developers and system integrators to extend the capabilities of their applications by connecting to external data sources and executing custom logic.

***

### 1. Creating a New API Connection

Let's begin integrating an external API into your eMOBIQ AI environment:

#### Step-by-Step Instructions:

1. **Add a New API**
   * Select `External API` as the backend connection

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-57ac3271454d0dd12ba31cdfc92ab735888db602%2Fimage%20(9).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

1. **Adding a new API**
   * Click on `+ Add a new API`
   * Provide a **meaningful name** and **description** for the API connection. These will help identify the purpose and function of the API within your application
   * Click `Save` to proceed

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-cd3b2c0afb2ac4f3098f36ac3c6c6ef129fc3f98%2FScreenRecording2025-06-16at5.22.35PM-ezgif.com-speed.gif?alt=media" alt="" width="563"><figcaption></figcaption></figure>

1. **Configure Domain Settings**
   * Click on `+ Add Domain`
   * Enter the **Base URL** (also known as the root endpoint) that links eMOBIQ AI to the target external API

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-782ef0a381b0ae9748cc73a7e6f92191c4546693%2Fimage%20(2)%20(1)%20(1)%20(1).png?alt=media" alt="" width="563"><figcaption><p>This URL serves as the foundation for all API requests made from your application to the external service</p></figcaption></figure>

***

### 2. Authentication Setup

Authentication ensures secure access to external APIs. eMOBIQ AI supports five common authentication methods:

{% hint style="info" %}
*If you're unsure which authentication method to use, consult the documentation for the API you're integrating with or reach out to the service provider of the API for guidance*
{% endhint %}

{% stepper %}
{% step %}
**Selecting Authentication Type**

Select the appropriate **authentication type** based on the external API's requirements

**Supported Authentication Types:**

1. Basic Auth
2. API Key
3. Bearer Token
4. JWT Bearer
5. [OAuth 2.0](https://docs.emobiq.com/emobiq-ai/readme/external-api/oauth-2.0)
   {% endstep %}

{% step %}
**Authentication Credentials**

Depending on the type of authentication your API requires, you’ll need to provide the appropriate credentials. Here’s what to enter for each authentication type:

{% tabs %}
{% tab title="Basic Auth" %}

* Enter your Username and Password
* The system will automatically encode these into a `Base64` string and include it in the request headers
  {% endtab %}

{% tab title="API Key" %}

* Specify the **Header Name** (e.g., `x-api-key`) and the **Key Value**
* This adds a static key-value pair to the request headers and is commonly used for lightweight service authentication
  {% endtab %}

{% tab title="Bearer Token" %}

* Enter the **Token** string that will be used as the Bearer credential
* This token is typically obtained from an authentication server and will be included in the `Authorization` header like this: `Bearer <your_token>`
  {% endtab %}

{% tab title="JWT Bearer" %}

* Enter the JWT (JSON Web Token) you want to use for authentication
* The JWT is usually generated by an identity provider or authentication service and must be valid at the time of the request
* Some systems also allow you to generate or refresh tokens dynamically using pre-request scripts or custom logic
  {% endtab %}

{% tab title="OAuth 2.0" %}

* **Client ID**: The public identifier for your application
* **Client Secret**: The private key used to authenticate your app (optional depending on the grant type)
* **Token Endpoint**: The URL where the system can request an access token
* You may also select the appropriate **Grant Type** (e.g., Authorization Code, Client Credentials) and configure additional settings if needed
* Ensure to refresh your access tokens when required:

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-49196b48c9c92bb082a05a8c9b82307b36ef1ed2%2FAccess%20Token.png?alt=media" alt=""><figcaption><p>Clicking on <code>Get new Access Token</code>,<br>ensures that the connection remains authenticated and ready for use</p></figcaption></figure>
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Authentication Instructions**

After configuring your API authentication method, you can define Authentication Instructions — this tells the AI how to use the credentials when generating the app. This effectively creates a more accurate end result and helps to save cost during the app generation process.

Auth Instructions allows you to:

* Specify how authentication should be applied in requests (e.g., which headers, tokens, or query params to include)
* Customise the behaviour of each API depending on the level of control you need
* Help the AI correctly authorise requests to secured endpoints, without manual adjustments
* While this step is optional, providing clear authentication instructions improves reliability and reduces ambiguity in how the AI should structure API calls
  {% endstep %}
  {% endstepper %}

{% hint style="success" %}
*Best Practice: Use authentication instructions to align your API call structure with the external service’s expected format (especially useful for APIs with non-standard auth headers or dynamic tokens)*
{% endhint %}

***

### 3. Defining API Functions

Once the domain and authentication are configured, you can define specific functions (or endpoints) to interact with the external API

#### Create a New Function:

1. **Function Details**

{% tabs %}
{% tab title="Method" %}
Supported HTTP methods include `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`

<div align="left"><figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-f4611ea825e94147286e8efc635ed19ada0c3f5b%2Fimage%20(3)%20(1)%20(1)%20(1).png?alt=media" alt="" width="351"><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Name" %}
A descriptive name for the function
{% endtab %}

{% tab title="Path" %}
The relative path of the API endpoint (e.g., `/api/v1/users`)
{% endtab %}
{% endtabs %}

2. **Request Configuration**

{% tabs %}
{% tab title="Params" %}
Query parameters appended to the URL

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-b94ad746a1db9f5d335d9560f691c66c3436476f%2Fimage%20(4)%20(1)%20(1)%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Headers" %}
Metadata sent with the request (e.g., content type, authorization headers)

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-a4e0c156523e3472fdbab99d168d01ddff68dc63%2Fimage%20(5)%20(1)%20(1)%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Body" %}
Data sent in the body of the request, particularly useful for `POST`, `PUT`, and `PATCH` methods

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-12159d3df4e5ed9f9052b3863b341d44d75939fb%2Fimage%20(6)%20(1)%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Instructions" %}
Describe how the AI should interpret and utilize this function. Think of this as a functional specification for the AI engine to understand how to execute or reference this API during runtime

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-2822a7a806112e933a85657930dd970168148d93%2Fimage%20(7)%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

***

### 4. Testing the API

Before integrating the API into your application, it’s essential to verify that it works correctly

{% stepper %}
{% step %}
**Test**

Use the `Test` button to send a request to the external API

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-63387c75011f342a7f8057b0ab9263a1b767b1b1%2FUntitled%20design%20(5).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Return Message**

A successful test will return a `200` or `201` status code, indicating that the connection and function execution was successful. Otherwise, try resolving the errors that appear

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-325c3faa3cca5813a25aa0444439d01d12a08c60%2Fimage%20(6).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Examination**

Examine the returned data to ensure it matches expectations and contains the necessary fields for downstream processing
{% endstep %}
{% endstepper %}

***

### 5. Refining the API Response

Sometimes, not all data returned by an API is required by your application. You can edit the response to improve performance and clarity.

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-7b16759c181c84668c1aa66d3822e798cdcd2b24%2FResponse.png?alt=media" alt=""><figcaption></figcaption></figure>

Editing the response can either be done through a checklist **(Formatted)** or through the text editor **(Raw)**

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-6970e9171dd1a697eecee3f863a88ff146c5a025%2FEdit_Response.png?alt=media" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Edit or Remove Unnecessary Fields" %}
If certain fields aren’t used, click **Edit** to remove them to ensure the AI doesn't use it, this is essential in helping the project be generated quicker and ensuring that only usable API information is available when creating the app
{% endtab %}

{% tab title="Edit the Response" %}

* Use the edit function to filter or transform the JSON structure returned by the API
* Select or deselect via the checkboxes
* This helps simplify complex responses and align them with the format expected by your frontend components or internal logic
  {% endtab %}
  {% endtabs %}

***

### 6. Importing APIs Using Schemas

For larger or more structured integrations, eMOBIQ AI supports importing API definitions using schema files

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-97afa849d606322e68865afbd8f4886e51c5ead0%2F1%20(4).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

{% tabs %}
{% tab title="(1) Import via Schema File" %}
Upload a schema file (such as OpenAPI 3.0 Schema) that describes the API endpoints and data structures
{% endtab %}

{% tab title="(2) Manual Schema Entry" %}

* Fill out the schema form manually to define the API structure directly in the platform and click generate

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-64b79ccee5f478a906a9b088b251c7c75a7bcac7%2F1%20(1)%20(1).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

* Functions will be populated according to the schema

<figure><img src="https://1183608340-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsUDFGj32EEDxm4CJ43yZ%2Fuploads%2Fgit-blob-0b14d4521ee0ea94fda60e00bfd97bbe62899d9d%2Fimage%20(9)%20(1).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

* This approach is ideal for APIs that don't provide downloadable schema files but still need formal documentation
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
***Note**: Using schemas help streamline the integration process, ensuring consistency and reducing manual configuration errors*
{% endhint %}

***

### Conclusion

By leveraging the robust API management features of eMOBIQ AI, you can securely and efficiently integrate external services into your applications. Whether you're retrieving data, submitting forms, or triggering backend processes, eMOBIQ AI provides a flexible and scalable framework for building intelligent, connected systems.