> For the complete documentation index, see [llms.txt](https://docs.emobiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.emobiq.com/emobiq-ai/readme/external-api.md).

# 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.

***

### Choosing Your Integration Mode

eMOBIQ AI offers three ways to register an external API. Pick the one that matches your use case before starting:

| Mode                                                                       | Best for                                                 | Setup style                                                 |
| -------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| **Standard External API** (this page)                                      | Any third-party REST API that needs accuracy and testing | Endpoint-by-endpoint configuration in a Postman-like editor |
| [**EZ-Connect**](/emobiq-ai/readme/external-api/ez-connect.md)             | Non-technical users, prototypes, throwaway demos         | Paste plain-text or natural-language API documentation      |
| [**Business Connect**](/emobiq-ai/readme/external-api/business-connect.md) | ERP integrations (Acumatica, Dynamics 365, Sage)         | Authenticate with ERP credentials and bulk-import endpoints |

{% hint style="info" %}
*The rest of this page covers the **Standard External API** flow — the most flexible option, with full control over endpoints, authentication, testing, and response shaping.*
{% endhint %}

***

### 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="/files/PwivQC0SA4YrROivCdtq" 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="/files/hBRS1j6ZqIINxcLonVGz" 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="/files/cqocNcFePwsiVnCKKzLg" 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](/emobiq-ai/readme/external-api/oauth-2.0.md)
   {% 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
* Select the appropriate **Grant Type** from the options below and fill in the required fields

**Supported Grant Types:**

| Grant Type                       | Best for                                                                                                 |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Password Credentials**         | First-party trusted apps that collect the user's username and password directly                          |
| **Client Credentials**           | Machine-to-machine or backend services accessing their own resources (no user involved)                  |
| **Authorization Code**           | Web apps accessing user data with explicit consent (e.g., Google, Microsoft, Salesforce)                 |
| **Authorization Code with PKCE** | Use when your OAuth provider requires PKCE — adds a cryptographic challenge to prevent code interception |

**Authorization Code** — requires:

* Authorization URL, Access Token URL, Client ID, Client Secret, and Callback (Redirect) URL
* eMOBIQ AI acts as a confidential client; the token exchange happens server-to-server

**Authorization Code with PKCE** — requires:

* Authorization URL, Access Token URL, Client ID, and Callback URL
* Choose **SHA-256** (recommended) or **Plain** as the PKCE mode
* Client Secret is not required and is often omitted

For full details on all grant types, see the [OAuth 2.0 guide](/emobiq-ai/readme/external-api/oauth-2.0.md).

* Ensure to refresh your access tokens when required:

<figure><img src="/files/0au38BuEqE9zBnBrj7jh" 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="/files/I7CyFdyxbVfCptEEIDC0" 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="/files/4i4liCOC2fc3uoqnkeyn" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

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

<figure><img src="/files/hGqwS1gVh9inmYucbZ1Y" 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="/files/c8mYmzgn7q0oP0HC6miP" 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="/files/KW5sjMyfngTcQBqy507U" 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="/files/o0lJKweXZg9iXxzl1kgj" 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="/files/hfhorkKnwA9NGj10gxs3" 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="/files/2WwaxB1PZQ2exSArKSrt" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/RoJCxKpIGHOkTdtrPQJJ" 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="/files/5ZDSHhIVTyQXdc9cp3x3" 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="/files/XnfVLLipYO8Xzaoin0Zo" alt="" width="563"><figcaption></figcaption></figure>

* Functions will be populated according to the schema

<figure><img src="/files/ZWk0I9Xz4p0uDCuYndTx" 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 %}

***

### 7. Manage Cookies

<figure><img src="/files/h0mc3GJbTOjbDcIJILX7" alt=""><figcaption></figcaption></figure>

When calling external APIs — particularly those that use OAuth or session-based authentication — the API provider may set cookies as part of the authentication handshake, or require certain cookies to be present before allowing a request through. The **Manage Cookies** panel gives you visibility into those cookies and lets you manually add any that are missing.

{% hint style="info" %}
Cookies are managed entirely within your own browser — they stay on your device and are never transmitted to eMOBIQ servers. Because of this, cookies are browser-specific: switching to a different browser means you'll need to re-add them there.
{% endhint %}

The panel is split into two sections:

| Panel               | Description                                                                                                                                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Domain (left)**   | Lists all domains that have cookies in your current browser session, grouped by the API provider domain (e.g., `login.microsoftonline.com`, `github.com`). A search bar lets you filter by domain name. Each domain shows a count of how many cookies it holds. |
| **Cookies (right)** | Displays the **Key** and **Value** of every cookie set by the selected domain. An **Add** form at the bottom lets you manually inject cookies for that domain.                                                                                                  |

**Viewing cookies by domain**

1. Open the **Manage Cookies** panel
2. Use the **Search domain** bar to filter, or scroll to find the API provider domain
3. Click a domain — its cookies appear in the right panel as a Key / Value list

**Adding a cookie**

1. Select the target domain from the left panel
2. Scroll to the **Add** section at the bottom of the right panel
3. Enter the cookie **Key** and **Value** and confirm — the cookie will be sent with subsequent API calls to that domain

***

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.emobiq.com/emobiq-ai/readme/external-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.