Connecting Your APIs

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.

Our API Connection Tooling is low-code tooling designed to be used by developers and other technical users. We also have a code-based API Connection tool that allows you to create API Connections using javascript code for advanced use cases.

Understanding API Connections

API Connections are the bridge between your GenerativeAgent and your external APIs. They allow your agent to interact with your existing systems and services, just like a human agent would.

How API Connections Fit In

GenerativeAgent uses a hierarchical structure to organize its capabilities:

Tasks: High-level instructions that tell GenerativeAgent what to do. A task can have one or more functions.
Functions: Tools that help GenerativeAgent complete tasks. A function can point to a single API Connection.
API Connections: Configurations that enable Functions to interact with your APIs.

Core Components

Each API Connection consists of three main parts that work together:

API Source:
- Handles the technical details of calling your API
- Manages authentication and security
- Configures environment-specific settings (sandbox/production)
Request Interface:
- Defines what information GenerativeAgent can send
- Transforms GenerativeAgent’s requests into your API’s format
- Includes testing tools to verify the transformation
Response Interface:
- Controls what data GenerativeAgent receives
- Transforms the API response to a GenerativeAgent friendly format
- Includes testing tools to verify the transformation

Create an API Connection

To create an API Connection, you need to:

We have a code-based API Connection tool that allows you to create API Connections using javascript code. This is for advanced use cases such as where you need to merge multiple APIs into a single API Connection.

Access the API Integration Hub

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

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.

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.

Configure the API Source

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

Set up authentication methods
Configure environment settings
Define error handling rules
Add any required static headers

Set Up Request and Response Interfaces

Configure how GenerativeAgent interacts with your API:

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

Test and Validate

Before finalizing your API Connection:

Run test requests in the sandbox environment
Verify transformations work as expected
Check error handling behavior

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

Simplify Field Names

// Good - Clear and descriptive
{
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string"
    },
    "order_date": {
      "type": "string"
    }
  }
}

// Avoid - Cryptic or complex
{
  "type": "object", 
  "properties": {
    "cust_nm_001": {
      "type": "string"
    },
    "ord_dt_timestamp": {
      "type": "string"
    }
  }
}

Flatten Complex Structures

// Good - Flat structure
{
  "type": "object",
  "properties": {
    "shipping_street": {
      "type": "string"
    },
    "shipping_city": {
      "type": "string"
    },
    "shipping_country": {
      "type": "string"
    }
  }
}

// Avoid - Deep nesting
{
  "type": "object",
  "properties": {
    "shipping": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Add Clear Descriptions

{
  "properties": {
    "order_status": {
      "type": "string",
      "description": "Current status of the order (pending, shipped, delivered)",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}

Remove Optional Fields

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

Basic Field Mapping

{
  "headers": {
    "Content-Type": "application/json"
  },
  "pathParameters": {
    "userId": request.id
  },
  "queryParameters": {
    "include": "details,preferences"
  },
  "body": {
    "name": request.userName,
    "email": request.userEmail
  }
}

Data Formatting

{
  "body": {
    // Convert date to ISO format
    "timestamp": $toMillis(request.date),
    // Uppercase a value
    "region": $uppercase(request.country),
    // Join array values
    "tags": $join(request.categories, ",")
  }
}

Conditional Logic

{
  "body": {
    // Include field only if present
    "optional_field": $exists(request.someField) ? request.someField : undefined,
    // Transform based on condition
    "status": request.isActive = true ? "ACTIVE" : "INACTIVE"
  }
}

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

Test Various Scenarios

// Test 1: Minimal valid request
{
  "customerId": "123",
  "action": "view"
}

// Test 2: Full request with all fields
{
  "customerId": "123",
  "action": "update",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Validate Error Cases

Use Sandbox Environment

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

Focus on Essential Data

// Good - Only relevant fields
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890"
}

// Avoid - Including unnecessary details
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890",
  "internalId": "ord_123",
  "systemMetadata": { /* ... */ },
  "auditLog": [ /* ... */ ]
}

Use Clear Data Types

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "Current temperature in Celsius"
    },
    "isOpen": {
      "type": "boolean",
      "description": "Whether the store is currently open"
    },
    "lastUpdated": {
      "type": "string",
      "format": "date-time",
      "description": "When this information was last updated"
    }
  }
}

Standardize Formats

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

Basic Data Mapping

Date and Time Formatting

{
  // Convert ISO timestamp to readable format
  "orderDate": $fromMillis($toMillis(clientApiCall.data.created_at), 
                          "[FNn], [MNn] [D1o], [Y]"),
  
  // Format time in 12-hour clock
  "deliveryTime": $fromMillis($toMillis(clientApiCall.data.delivery_eta), 
                             "[h]:[m01] [P]")
}

Complex Data Processing

{
  // Calculate order summary
  "orderSummary": {
    "totalItems": $sum(clientApiCall.data.items[*].quantity),
    "uniqueItems": $count(clientApiCall.data.items),
    "hasGiftItems": $exists(clientApiCall.data.items[type="GIFT"])
  },
  
  // Format address components
  "deliveryAddress": $join([
    clientApiCall.data.address.street,
    clientApiCall.data.address.city,
    clientApiCall.data.address.state,
    clientApiCall.data.address.zip
  ], ", ")
}

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

Test Different Response Types

Validate Data Formatting

Edge Cases

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:

Navigate to API Integration Hub > API Specs
Click on the relevant API Spec.
Click on the “Parameters” tab and flag
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.

Update Passenger Name (Simple mapping)

This example demonstrates configuring an API connection for updating a passenger’s name on a flight booking.

API Endpoint

PUT /flight/[flightId]/passenger/[passengerId]
{
  "name": {
    "first": [Passenger FirstName],
    "last": [Passenger LastName]
  }
}

API Response

{
  "id": "pax-12345",
  "flightId": "XZ2468",
  "updatedAt": "2024-10-04T14:30:00Z",
  "passenger": {
    "id": "PSGR-56789",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "seatAssignment": "14A",
    "checkedIn": true,
    "frequentFlyerNumber": "FF123456"
  },
  "status": "confirmed",
  "specialRequests": ["wheelchair", "vegetarian_meal"],
  "baggage": {
    "checkedBags": 1,
    "carryOn": 1
  }
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "externalCustomerId": {"type": "string"},
    "passengerFirstName": {"type": "string"},
    "passengerLastName": {"type": "string"},
    "flightId": {"type": "string"}
  },
  "required": ["externalCustomerId", "passengerFirstName", "passengerLastName", "flightId"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightId": request.flightId,
    "passengerId": request.externalCustomerId
  },
  "queryParameters": {},
  "body": {
    "name": {
      "first": request.passengerFirstName,
      "last": request.passengerLastName
    }
  }
}

Sample Test Request:

{
  "externalCustomerId": "CUST123",
  "passengerFirstName": "Johnson",
  "passengerLastName": "Doe",
  "flightId": "XZ2468"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the name update was successful"
    }
  },
  "required": ["success"]
}

Response Transformation:

{
  "success": $exists(clientApiCall.data.id) and 
             $exists(clientApiCall.data.passenger.name.first) and 
             $exists(clientApiCall.data.passenger.name.last) and 
             clientApiCall.data.status = "confirmed"
}

Sample Test Response:

{
  "clientApiCall": {
    "data": {
      "id": "pax-12345",
      "flightId": "XZ2468",
      "updatedAt": "2024-10-04T14:30:00Z",
      "passenger": {
        "id": "PSGR-56789",
        "name": {
          "first": "John",
          "last": "Doe"
        },
        "seatAssignment": "14A",
        "checkedIn": true,
        "frequentFlyerNumber": "FF123456"
      },
      "status": "confirmed",
      "specialRequests": ["wheelchair", "vegetarian_meal"],
      "baggage": {
        "checkedBags": 1,
        "carryOn": 1
      }
    }
  }
}

Lookup Flight Status (Complex mapping)

This example shows how to simplify a complex flight status API response by removing unnecessary fields and flattening nested structures.

API Endpoint

GET /flights/[flightNumber]/status

API Response

{
  "flightDetails": {
    "flightNumber": "AA123",
    "route": {
      "origin": {
        "code": "SFO",
        "terminal": "2",
        "gate": "A12",
        "weather": { /* complex weather object */ }
      },
      "destination": {
        "code": "JFK",
        "terminal": "4",
        "gate": "B34",
        "weather": { /* complex weather object */ }
      }
    },
    "schedule": {
      "departure": {
        "scheduled": "2024-03-15T10:30:00Z",
        "estimated": "2024-03-15T10:45:00Z",
        "actual": null
      },
      "arrival": {
        "scheduled": "2024-03-15T19:30:00Z",
        "estimated": "2024-03-15T19:45:00Z",
        "actual": null
      }
    },
    "status": "DELAYED",
    "aircraft": { /* aircraft details */ }
  }
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "flightNumber": {
      "type": "string",
      "description": "The flight number to look up"
    }
  },
  "required": ["flightNumber"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightNumber": request.flightNumber
  },
  "queryParameters": {},
  "body": {}
}

Sample Test Request:

{
  "flightNumber": "AA123"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "flight_number": { 
      "type": "string",
      "description": "The flight number"
    },
    "flight_status": { 
      "type": "string",
      "description": "Current status of the flight"
    },
    "origin_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for origin"
    },
    "destination_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for destination"
    },
    "scheduled_departure_time": { 
      "type": "string",
      "description": "Scheduled departure time"
    },
    "scheduled_arrival_time": { 
      "type": "string",
      "description": "Scheduled arrival time"
    },
    "is_flight_delayed": { 
      "type": "boolean",
      "description": "Whether the flight is delayed"
    }
  }
}

Response Transformation:

{
  "flight_number": clientApiCall.data.flightDetails.flightNumber,
  "flight_status": clientApiCall.data.flightDetails.status,
  "origin_airport_code": clientApiCall.data.flightDetails.route.origin.code,
  "destination_airport_code": clientApiCall.data.flightDetails.route.destination.code,
  "scheduled_departure_time": clientApiCall.data.flightDetails.schedule.departure.estimated,
  "scheduled_arrival_time": clientApiCall.data.flightDetails.schedule.arrival.estimated,
  "is_flight_delayed": clientApiCall.data.flightDetails.status = "DELAYED"
}

Appointment Lookup (Date Formatting)

This example demonstrates date formatting and complex object transformation for an appointment lookup API.

API Endpoint

GET /appointments/[appointmentId]

API Response

{
  "id": "apt_123",
  "type": "DENTAL_CLEANING",
  "startTime": "2024-03-15T14:30:00Z",
  "endTime": "2024-03-15T15:30:00Z",
  "provider": "Dr. Sarah Smith",
  "location": "Downtown Medical Center",
  "patient": {
    "id": "pat_456",
    "name": "John Doe",
    "dateOfBirth": "1985-06-15",
    "contactInfo": {
      "email": "john.doe@email.com",
      "phone": "+1-555-0123"
    }
  },
  "status": "confirmed",
  "notes": "Regular cleaning and check-up",
  "insuranceVerified": true,
  "lastUpdated": "2024-03-01T10:15:00Z"
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "appointmentId": {
      "type": "string",
      "description": "The ID of the appointment to look up"
    }
  },
  "required": ["appointmentId"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "appointmentId": request.appointmentId
  },
  "queryParameters": {},
  "body": {}
}

Sample Test Request:

{
  "appointmentId": "apt_123"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "appointmentType": { 
      "type": "string",
      "description": "The type of appointment in a readable format"
    },
    "date": { 
      "type": "string",
      "description": "The appointment date in a friendly format"
    },
    "startTime": { 
      "type": "string",
      "description": "The appointment start time in 12-hour format"
    },
    "doctor": { 
      "type": "string",
      "description": "The healthcare provider's name"
    },
    "clinic": { 
      "type": "string",
      "description": "The location where the appointment will take place"
    },
    "status": {
      "type": "string",
      "description": "The current status of the appointment"
    },
    "patientName": {
      "type": "string",
      "description": "The name of the patient"
    }
  },
  "required": ["appointmentType", "date", "startTime", "doctor", "clinic", "status", "patientName"]
}

Response Transformation:

{
  /* Convert appointment type from UPPER_SNAKE_CASE to readable format */
  "appointmentType": $replace(clientApiCall.data.type, "_", " ") ~> $lowercase(),
  
  /* Format date as "Friday, March 15th, 2024" */
  "date": $fromMillis($toMillis(clientApiCall.data.startTime), "[FNn], [MNn] [D1o], [Y]"),
  
  /* Format start time as "2:30 PM" */
  "startTime": $fromMillis($toMillis(clientApiCall.data.startTime), "[h]:[m01] [P]"),
              
  /* Map provider and location directly */
  "doctor": clientApiCall.data.provider,
  "clinic": clientApiCall.data.location,
  
  /* Map status and patient name */
  "status": clientApiCall.data.status,
  "patientName": clientApiCall.data.patient.name
}

Sample Transformed Response:

{
  "appointmentType": "dental cleaning",
  "date": "Friday, March 15th, 2024",
  "startTime": "2:30 PM",
  "doctor": "Dr. Sarah Smith",
  "clinic": "Downtown Medical Center",
  "status": "confirmed",
  "patientName": "John Doe"
}

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:

Previewer

Integrating GenerativeAgent

Connecting Your Knowledge Base

On this page

Understanding API Connections
How API Connections Fit In
Core Components
Create an API Connection
Request Interface
Request Schema
Request Transformation
Request Testing
Response Interface
Response Schema
Response Transformation
Response Testing
Redaction
API Versioning
API Connection Logs
Default API Spec Settings
Examples
Next Steps

Understanding API Connections

API Connections are the bridge between your GenerativeAgent and your external APIs. They allow your agent to interact with your existing systems and services, just like a human agent would.

How API Connections Fit In

GenerativeAgent uses a hierarchical structure to organize its capabilities:

Tasks: High-level instructions that tell GenerativeAgent what to do. A task can have one or more functions.
Functions: Tools that help GenerativeAgent complete tasks. A function can point to a single API Connection.
API Connections: Configurations that enable Functions to interact with your APIs.

Core Components

Each API Connection consists of three main parts that work together:

API Source:
- Handles the technical details of calling your API
- Manages authentication and security
- Configures environment-specific settings (sandbox/production)
Request Interface:
- Defines what information GenerativeAgent can send
- Transforms GenerativeAgent’s requests into your API’s format
- Includes testing tools to verify the transformation
Response Interface:
- Controls what data GenerativeAgent receives
- Transforms the API response to a GenerativeAgent friendly format
- Includes testing tools to verify the transformation

Create an API Connection

To create an API Connection, you need to:

Access the API Integration Hub

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

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.

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.

Configure the API Source

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

Set up authentication methods
Configure environment settings
Define error handling rules
Add any required static headers

Set Up Request and Response Interfaces

Configure how GenerativeAgent interacts with your API:

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

Test and Validate

Before finalizing your API Connection:

Run test requests in the sandbox environment
Verify transformations work as expected
Check error handling behavior

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

Simplify Field Names

// Good - Clear and descriptive
{
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string"
    },
    "order_date": {
      "type": "string"
    }
  }
}

// Avoid - Cryptic or complex
{
  "type": "object", 
  "properties": {
    "cust_nm_001": {
      "type": "string"
    },
    "ord_dt_timestamp": {
      "type": "string"
    }
  }
}

Flatten Complex Structures

// Good - Flat structure
{
  "type": "object",
  "properties": {
    "shipping_street": {
      "type": "string"
    },
    "shipping_city": {
      "type": "string"
    },
    "shipping_country": {
      "type": "string"
    }
  }
}

// Avoid - Deep nesting
{
  "type": "object",
  "properties": {
    "shipping": {
      "type": "object",
      "properties": {
        "address": {
          "type": "object",
          "properties": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Add Clear Descriptions

{
  "properties": {
    "order_status": {
      "type": "string",
      "description": "Current status of the order (pending, shipped, delivered)",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}

Remove Optional Fields

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

Basic Field Mapping

{
  "headers": {
    "Content-Type": "application/json"
  },
  "pathParameters": {
    "userId": request.id
  },
  "queryParameters": {
    "include": "details,preferences"
  },
  "body": {
    "name": request.userName,
    "email": request.userEmail
  }
}

Data Formatting

{
  "body": {
    // Convert date to ISO format
    "timestamp": $toMillis(request.date),
    // Uppercase a value
    "region": $uppercase(request.country),
    // Join array values
    "tags": $join(request.categories, ",")
  }
}

Conditional Logic

{
  "body": {
    // Include field only if present
    "optional_field": $exists(request.someField) ? request.someField : undefined,
    // Transform based on condition
    "status": request.isActive = true ? "ACTIVE" : "INACTIVE"
  }
}

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

Test Various Scenarios

// Test 1: Minimal valid request
{
  "customerId": "123",
  "action": "view"
}

// Test 2: Full request with all fields
{
  "customerId": "123",
  "action": "update",
  "data": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Validate Error Cases

Use Sandbox Environment

Response Interface

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

Focus on Essential Data

// Good - Only relevant fields
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890"
}

// Avoid - Including unnecessary details
{
  "orderStatus": "shipped",
  "estimatedDelivery": "2024-03-20",
  "trackingNumber": "1Z999AA1234567890",
  "internalId": "ord_123",
  "systemMetadata": { /* ... */ },
  "auditLog": [ /* ... */ ]
}

Use Clear Data Types

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "Current temperature in Celsius"
    },
    "isOpen": {
      "type": "boolean",
      "description": "Whether the store is currently open"
    },
    "lastUpdated": {
      "type": "string",
      "format": "date-time",
      "description": "When this information was last updated"
    }
  }
}

Standardize Formats

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

Basic Data Mapping

Date and Time Formatting

{
  // Convert ISO timestamp to readable format
  "orderDate": $fromMillis($toMillis(clientApiCall.data.created_at), 
                          "[FNn], [MNn] [D1o], [Y]"),
  
  // Format time in 12-hour clock
  "deliveryTime": $fromMillis($toMillis(clientApiCall.data.delivery_eta), 
                             "[h]:[m01] [P]")
}

Complex Data Processing

{
  // Calculate order summary
  "orderSummary": {
    "totalItems": $sum(clientApiCall.data.items[*].quantity),
    "uniqueItems": $count(clientApiCall.data.items),
    "hasGiftItems": $exists(clientApiCall.data.items[type="GIFT"])
  },
  
  // Format address components
  "deliveryAddress": $join([
    clientApiCall.data.address.street,
    clientApiCall.data.address.city,
    clientApiCall.data.address.state,
    clientApiCall.data.address.zip
  ], ", ")
}

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

Test Different Response Types

Validate Data Formatting

Edge Cases

Redaction

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

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

Navigate to API Integration Hub > API Specs
Click on the relevant API Spec.
Click on the “Parameters” tab and flag
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 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.

Update Passenger Name (Simple mapping)

This example demonstrates configuring an API connection for updating a passenger’s name on a flight booking.

API Endpoint

PUT /flight/[flightId]/passenger/[passengerId]
{
  "name": {
    "first": [Passenger FirstName],
    "last": [Passenger LastName]
  }
}

API Response

{
  "id": "pax-12345",
  "flightId": "XZ2468",
  "updatedAt": "2024-10-04T14:30:00Z",
  "passenger": {
    "id": "PSGR-56789",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "seatAssignment": "14A",
    "checkedIn": true,
    "frequentFlyerNumber": "FF123456"
  },
  "status": "confirmed",
  "specialRequests": ["wheelchair", "vegetarian_meal"],
  "baggage": {
    "checkedBags": 1,
    "carryOn": 1
  }
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "externalCustomerId": {"type": "string"},
    "passengerFirstName": {"type": "string"},
    "passengerLastName": {"type": "string"},
    "flightId": {"type": "string"}
  },
  "required": ["externalCustomerId", "passengerFirstName", "passengerLastName", "flightId"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightId": request.flightId,
    "passengerId": request.externalCustomerId
  },
  "queryParameters": {},
  "body": {
    "name": {
      "first": request.passengerFirstName,
      "last": request.passengerLastName
    }
  }
}

Sample Test Request:

{
  "externalCustomerId": "CUST123",
  "passengerFirstName": "Johnson",
  "passengerLastName": "Doe",
  "flightId": "XZ2468"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the name update was successful"
    }
  },
  "required": ["success"]
}

Response Transformation:

{
  "success": $exists(clientApiCall.data.id) and 
             $exists(clientApiCall.data.passenger.name.first) and 
             $exists(clientApiCall.data.passenger.name.last) and 
             clientApiCall.data.status = "confirmed"
}

Sample Test Response:

{
  "clientApiCall": {
    "data": {
      "id": "pax-12345",
      "flightId": "XZ2468",
      "updatedAt": "2024-10-04T14:30:00Z",
      "passenger": {
        "id": "PSGR-56789",
        "name": {
          "first": "John",
          "last": "Doe"
        },
        "seatAssignment": "14A",
        "checkedIn": true,
        "frequentFlyerNumber": "FF123456"
      },
      "status": "confirmed",
      "specialRequests": ["wheelchair", "vegetarian_meal"],
      "baggage": {
        "checkedBags": 1,
        "carryOn": 1
      }
    }
  }
}

Lookup Flight Status (Complex mapping)

This example shows how to simplify a complex flight status API response by removing unnecessary fields and flattening nested structures.

API Endpoint

GET /flights/[flightNumber]/status

API Response

{
  "flightDetails": {
    "flightNumber": "AA123",
    "route": {
      "origin": {
        "code": "SFO",
        "terminal": "2",
        "gate": "A12",
        "weather": { /* complex weather object */ }
      },
      "destination": {
        "code": "JFK",
        "terminal": "4",
        "gate": "B34",
        "weather": { /* complex weather object */ }
      }
    },
    "schedule": {
      "departure": {
        "scheduled": "2024-03-15T10:30:00Z",
        "estimated": "2024-03-15T10:45:00Z",
        "actual": null
      },
      "arrival": {
        "scheduled": "2024-03-15T19:30:00Z",
        "estimated": "2024-03-15T19:45:00Z",
        "actual": null
      }
    },
    "status": "DELAYED",
    "aircraft": { /* aircraft details */ }
  }
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "flightNumber": {
      "type": "string",
      "description": "The flight number to look up"
    }
  },
  "required": ["flightNumber"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightNumber": request.flightNumber
  },
  "queryParameters": {},
  "body": {}
}

Sample Test Request:

{
  "flightNumber": "AA123"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "flight_number": { 
      "type": "string",
      "description": "The flight number"
    },
    "flight_status": { 
      "type": "string",
      "description": "Current status of the flight"
    },
    "origin_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for origin"
    },
    "destination_airport_code": { 
      "type": "string",
      "description": "Three-letter airport code for destination"
    },
    "scheduled_departure_time": { 
      "type": "string",
      "description": "Scheduled departure time"
    },
    "scheduled_arrival_time": { 
      "type": "string",
      "description": "Scheduled arrival time"
    },
    "is_flight_delayed": { 
      "type": "boolean",
      "description": "Whether the flight is delayed"
    }
  }
}

Response Transformation:

{
  "flight_number": clientApiCall.data.flightDetails.flightNumber,
  "flight_status": clientApiCall.data.flightDetails.status,
  "origin_airport_code": clientApiCall.data.flightDetails.route.origin.code,
  "destination_airport_code": clientApiCall.data.flightDetails.route.destination.code,
  "scheduled_departure_time": clientApiCall.data.flightDetails.schedule.departure.estimated,
  "scheduled_arrival_time": clientApiCall.data.flightDetails.schedule.arrival.estimated,
  "is_flight_delayed": clientApiCall.data.flightDetails.status = "DELAYED"
}

Appointment Lookup (Date Formatting)

This example demonstrates date formatting and complex object transformation for an appointment lookup API.

API Endpoint

GET /appointments/[appointmentId]

API Response

{
  "id": "apt_123",
  "type": "DENTAL_CLEANING",
  "startTime": "2024-03-15T14:30:00Z",
  "endTime": "2024-03-15T15:30:00Z",
  "provider": "Dr. Sarah Smith",
  "location": "Downtown Medical Center",
  "patient": {
    "id": "pat_456",
    "name": "John Doe",
    "dateOfBirth": "1985-06-15",
    "contactInfo": {
      "email": "john.doe@email.com",
      "phone": "+1-555-0123"
    }
  },
  "status": "confirmed",
  "notes": "Regular cleaning and check-up",
  "insuranceVerified": true,
  "lastUpdated": "2024-03-01T10:15:00Z"
}

Request Configuration

Request Schema:

{
  "type": "object",
  "properties": {
    "appointmentId": {
      "type": "string",
      "description": "The ID of the appointment to look up"
    }
  },
  "required": ["appointmentId"]
}

Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "appointmentId": request.appointmentId
  },
  "queryParameters": {},
  "body": {}
}

Sample Test Request:

{
  "appointmentId": "apt_123"
}

Response Configuration

Response Schema:

{
  "type": "object",
  "properties": {
    "appointmentType": { 
      "type": "string",
      "description": "The type of appointment in a readable format"
    },
    "date": { 
      "type": "string",
      "description": "The appointment date in a friendly format"
    },
    "startTime": { 
      "type": "string",
      "description": "The appointment start time in 12-hour format"
    },
    "doctor": { 
      "type": "string",
      "description": "The healthcare provider's name"
    },
    "clinic": { 
      "type": "string",
      "description": "The location where the appointment will take place"
    },
    "status": {
      "type": "string",
      "description": "The current status of the appointment"
    },
    "patientName": {
      "type": "string",
      "description": "The name of the patient"
    }
  },
  "required": ["appointmentType", "date", "startTime", "doctor", "clinic", "status", "patientName"]
}

Response Transformation:

{
  /* Convert appointment type from UPPER_SNAKE_CASE to readable format */
  "appointmentType": $replace(clientApiCall.data.type, "_", " ") ~> $lowercase(),
  
  /* Format date as "Friday, March 15th, 2024" */
  "date": $fromMillis($toMillis(clientApiCall.data.startTime), "[FNn], [MNn] [D1o], [Y]"),
  
  /* Format start time as "2:30 PM" */
  "startTime": $fromMillis($toMillis(clientApiCall.data.startTime), "[h]:[m01] [P]"),
              
  /* Map provider and location directly */
  "doctor": clientApiCall.data.provider,
  "clinic": clientApiCall.data.location,
  
  /* Map status and patient name */
  "status": clientApiCall.data.status,
  "patientName": clientApiCall.data.patient.name
}

Sample Transformed Response:

{
  "appointmentType": "dental cleaning",
  "date": "Friday, March 15th, 2024",
  "startTime": "2:30 PM",
  "doctor": "Dr. Sarah Smith",
  "clinic": "Downtown Medical Center",
  "status": "confirmed",
  "patientName": "John Doe"
}

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:

Previewer

Integrating GenerativeAgent

Connecting Your Knowledge Base

On this page

Understanding API Connections
How API Connections Fit In
Core Components
Create an API Connection
Request Interface
Request Schema
Request Transformation
Request Testing
Response Interface
Response Schema
Response Transformation
Response Testing
Redaction
API Versioning
API Connection Logs
Default API Spec Settings
Examples
Next Steps

​Understanding API Connections

​How API Connections Fit In

​Core Components

​Create an API Connection

​Request Interface

​Request Schema

​Request Transformation

​Request Testing

​Response Interface

​Response Schema

​Response Transformation

​Response Testing

​Redaction

​API Versioning

​API Connection Logs

​Default API Spec Settings

​Examples

​Next Steps

Previewer

Integrating GenerativeAgent

Connecting Your Knowledge Base

Changelog

​Understanding API Connections

​How API Connections Fit In

​Core Components

​Create an API Connection

​Request Interface

​Request Schema

​Request Transformation

​Request Testing

​Response Interface

​Response Schema

​Response Transformation

​Response Testing

​Redaction

​API Versioning

​API Connection Logs

​Default API Spec Settings

​Examples

​Next Steps

Previewer

Integrating GenerativeAgent

Connecting Your Knowledge Base

Understanding API Connections

How API Connections Fit In

Core Components

Create an API Connection

Request Interface

Request Schema

Request Transformation

Request Testing

Response Interface

Response Schema

Response Transformation

Response Testing

Redaction

API Versioning

API Connection Logs

Default API Spec Settings

Examples

Next Steps

Understanding API Connections

How API Connections Fit In

Core Components

Create an API Connection

Request Interface

Request Schema

Request Transformation

Request Testing

Response Interface

Response Schema

Response Transformation

Response Testing

Redaction

API Versioning

API Connection Logs

Default API Spec Settings

Examples

Next Steps