GenerativeAgent can call your APIs to get data or perform actions through API Connections. These connections allow GenerativeAgent to handle complex tasks like looking up account information or booking flights.

Our API Connection tooling lets you transform your existing APIs into LLM-friendly interfaces that GenerativeAgent can use effectively. Unlike other providers that require you to create new simplified APIs specifically for LLM use, ASAPP’s approach lets you leverage your current infrastructure without additional development work.

Typically, a developer or other technical user will create API Connections. If you need help, reach out to your ASAPP team.

Understanding API Connections

An API connection consists of three core components:

  1. API Source:

    • Defines how to call your API
    • Handles authentication, headers, and error responses
    • Configures environment-specific settings (sandbox/production)
  2. Request Interface:

    • Specifies what GenerativeAgent sees and can request
    • Transforms GenerativeAgent’s requests into your API format
    • Provides testing capabilities for validation
  3. Response Interface:

    • Controls what data GenerativeAgent receives back
    • Transforms API responses into LLM-friendly formats
    • Supports data formatting and simplification

Create an API Connections

To create an API Connection, you need to:

1

Access the API Integration Hub

  1. Navigate to API Integration Hub in your dashboard
  2. Select the API Connections tab
  3. Click the Create Connection button
2

Select or Upload Your API Specification

Every API Connection requires an OpenAPI specification that defines your API endpoints and structure.

  • Choose an existing API spec from your previously uploaded API Specs, or
  • Upload a new OpenAPI specification file

We support any API that uses JSON for requests and responses.

3

Configure Basic Details

Provide the essential information for your connection:

  • Name: A descriptive name for the API Connection
  • Description: Brief explanation of the connection’s purpose
  • Endpoint: Select the specific API endpoint from your specification

Only endpoints with JSON request and response bodies are supported.

4

Configure the API Source

After creation, you’ll be taken to the API Source configuration page. Here you’ll need to:

  1. Set up authentication methods
  2. Configure environment settings
  3. Define error handling rules
  4. Add any required static headers
5

Set Up Request and Response Interfaces

Configure how GenerativeAgent interacts with your API:

  1. Define the Request Interface:
    • Specify the schema GenerativeAgent will use
    • Create request transformations
    • Test with sample requests
  2. Configure the Response Interface:
    • Define the response schema
    • Set up response transformations
    • Validate with sample responses
6

Test and Validate

Before finalizing your API Connection:

  1. Run test requests in the sandbox environment
  2. Verify transformations work as expected
  3. Check error handling behavior
7

Link to Functions

Once your API Connection is configured and tested, you can reference it in a Function to enable GenerativeAgent to use the API.

Request Interface

The Request Interface defines how GenerativeAgent interacts with your API. It consists of three key components that work together to enable effective API communication.

  • Request Schema: The schema of the data that GenerativeAgent can send to your API.
  • Request Transformation: The transformation that will apply to the data before sending it to your API.
  • Testing Interface: The interface that allows you to test the request transformation with different inputs.

Request Schema

The Request Schema specifies the structure of data that GenerativeAgent can send to your API. This schema should be designed for optimal LLM interaction.

This schema is NOT the schema of the API. This is the schema of that is shown to GenerativeAgent.

Best Practices for Schema Design

When first created, the Request Schema is a 1-1 mapping to the underlying API spec.

Request Transformation

The Request Transformation converts GenerativeAgent’s request into the format your API expects. This is done using JSONata expressions.

When first created, the Request Transformation is a 1-1 mapping to the underlying API spec.

Common Transformation Patterns

Request Testing

Thoroughly test your request transformations to ensure GenerativeAgent can send the correct data to your API.

The API Connection can not be saved until the request transformation has a successful test.

Testing Best Practices

Response Interface

The Response Interface determines how API responses are processed and presented to GenerativeAgent. A well-designed response interface makes it easier for GenerativeAgent to understand and use the API’s data effectively.

There are three main components to the response interface:

  • Response Schema: The JSON schema for the data returned to GenerativeAgent from the API.
  • Response Transformation: A JSONata transformation where the API response is transformed into the response given to GenerativeAgent.
  • Test Response: The testing panel to test the response transformation with different API responses and see the output.

Response Schema

The Response Schema defines the structure of data that GenerativeAgent will receive. Focus on creating clear, simple schemas that are optimized for LLM processing.

The Response Schema is NOT the schema of the underlying API. This is the schema of what is returned to GenerativeAgent.

Schema Design Principles

When first created, the Response Schema is a 1-1 mapping to the underlying API spec.

Response Transformation

Transform complex API responses into GenerativeAgent-friendly formats using JSONata. The goal is to simplify and standardize the data.

The Transformation’s input is the raw API response. The output is the data that GenerativeAgent will receive and must match the Response Schema.

When first created, the Response Transformation is a 1-1 mapping to the underlying API spec.

Transformation Examples

Response Testing

Thoroughly test your response transformations to ensure GenerativeAgent receives well-formatted, useful data.

The API Connection can not be saved until the response transformation has a successful test.

Use API Mock Users to save response from your server to use them in the response testing.

Testing Strategies

Redaction

You have the option to redact fields in the request or response from API Connection Logs or Conversation Explorer.

You can redact fields the internal request and response, by adding x-redact to a field in the Request Schema or Response Schema. You will need to save the API connection to apply the changes. This will redact the fields in the Conversation Explorer as well.

You can redact fields in the raw API request and response, by flagging the fields in the relevant API Spec:

  1. Navigate to API Integration Hub > API Specs
  2. Click on the relevant API Spec.
  3. Click on the “Parameters” tab and flag
  4. Per endpoint, click the fields you want to redact.

Redacting the Spec will redact the fields within the API Connection Log.

API Versioning

Every update to an API Connection requires a version change. This is to ensure that no change can be made to an API connection that impacts a live function.

If you make a change to an API connection, the Function that references that API connection will need to be explicitly updated to point to the new version.

API Connection Logs

We log all requests and responses for API connections. This allows you to see the raw requests and responses, and the transformations that were applied.

Use the logs to debug and understand how API connections are working.

Logs are available in API Integration Hub > API Connection Logs.

Default API Spec Settings

You can set default information in an API spec. These default settings are used as a template for newly created API connections, copying those settings for all API connections created for that API spec.

You can set the following defaults:

  • Headers
  • Sandbox Settings:
    • Base URL
    • Authentication Method
  • Production Settings:
    • Base URL
    • Authentication Method

You can make further changes to API connections as necessary.

You can also change the defaults and it will not change existing API connections, though the new defaults will be used on any new connections made with that Spec.

Examples

Here are some examples of how to configure API connections for different scenarios.

Next Steps

Now that you’ve configured your API connections, GenerativeAgent can interact with your APIs just like a live agent. Here are some helpful resources for next steps: