Skip to main content
This page covers custom API integrations configured in the APIs tab in Agent Studio. For PolyAI’s public APIs (Chat, Conversations, Handoff, etc.), see the API Reference. For pre-built third-party integrations (e.g., OpenTable, Salesforce, Zendesk), contact your PolyAI account manager to enable them via the Integrations tab.
The APIs tab (under Configure in the Agent Studio sidebar) lets you define external HTTP APIs and reference them when building functions and flows. api-tab It provides:
  • A shared, inspectable API definition
  • Environment-specific base URLs
  • A consistent calling interface inside conv.api
This page explains what the APIs tab does and how to call defined APIs from your agent.

​
What API integrations are for

Use the APIs tab when you want your agent to:
  • Fetch or send data to an external system
  • Call internal services (CRM, ticketing, booking, payments)
  • Avoid maintaining potentially weighty custom HTTP logic in functions
Typical use cases:
  • Look up a ticket, booking, or account
  • Create or update a record
  • Trigger downstream systems from a flow

​
How API definitions work

An API definition consists of:
  1. A named API
  2. Environment-specific base URLs
  3. One or more operations

​
API name

The API name becomes the namespace under conv.api.
Use snake_case for API names and operation names (e.g., my_service, get_contact).
Example:
  • API name: salesforce
  • Runtime access: conv.api.salesforce

​
Base URL and environments

Each API supports separate configuration for:
  • Draft / Sandbox
  • Pre-release
  • Live
This allows you to:
  • Test against staging services
  • Promote safely without changing code
  • Keep flows identical across environments
At runtime, the agent automatically uses the base URL for the active environment.

​
Operations

Each operation represents a single HTTP endpoint. You define:
  • Method (GET, POST, PUT, DELETE, etc.)
  • Operation name
  • Resource path
Example resource path: /tickets/{ticket_id} Path variables are automatically exposed as arguments when calling the operation.

​
Referencing APIs while you are building an agent

api-tab-runtime All defined APIs are available inside functions under the conv.api object. The structure is: 
conv.api.<api_name>.<operation_name>(...)
Example: 
response = conv.api.salesforce.get_contact("123")

​
What gets returned from an API call

Calling an operation returns a requests.Response-like object (a standard Python HTTP response object). This means you can:
  • Check response.status_code
  • Access response.text
  • Call response.json() to parse JSON responses
  • Call conv.log_api_response(response) to log the response for debugging in Conversation Review

​
Debugging with conv.log_api_response()

Use conv.log_api_response(response) to log API responses so they appear in Conversation Review. This is useful when troubleshooting failed or unexpected API calls. 
response = conv.api.salesforce.get_contact("123")
conv.log_api_response(response)

​
Example: reading JSON from a response

Assume your API returns the following JSON: 
{
  "id": "123",
  "status": "active",
  "email": "customer@example.com"
}
You would handle it like this inside a function: 
response = conv.api.salesforce.get_contact("123")

data = response.json()
status = data["status"]
email = data["email"]
You can then use those values to decide what to return to the agent.

​
Error handling

Always check the response status before processing data. Non-200 responses may indicate the API call failed or the resource was not found. 
response = conv.api.salesforce.get_contact("123")
conv.log_api_response(response)

if response.status_code == 200:
    data = response.json()
    return {"content": f"The account status is {data['status']}."}
else:
    return {"content": "I wasn't able to retrieve the account details. Please try again later."}
You can also use response.raise_for_status() to raise an exception on non-2xx responses: 
response = conv.api.salesforce.get_contact("123")
conv.log_api_response(response)

try:
    response.raise_for_status()
    data = response.json()
    return {"content": f"The account status is {data['status']}."}
except Exception:
    return {"content": "Something went wrong while fetching your account details."}

​
Returning values from your function

After calling an API and processing the response, your function must return a dictionary. There are two common patterns:

​
1. Return natural language content

Use this when you want the LLM to continue the conversation naturally: 
return {"content": f"The account is currently {status}."}

​
2. Return a programmatic utterance

Use this when you want to return a fully controlled response: 
return {"utterance": "Your account is active and ready to use."}
In most cases:
  • "content" lets the model incorporate your result into a broader response.
  • "utterance" returns a fixed, deterministic reply.

​
Path variables

You can pass path variables as positional or keyword arguments. Examples: 
response = conv.api.salesforce.get_contact("123")
Or: 
response = conv.api.salesforce.get_contact(contact_id="123")

​
Query parameters, body, and headers

Operations accept arbitrary keyword arguments at call time. You can pass:
  • Query parameters
  • JSON bodies
  • Custom headers
Example: 
response = conv.api.stripe.create_payment(
    amount=100,
    params={"expand": "customer"},
    json={"amount": 100, "currency": "usd"},
    headers={"X-Custom-Header": "value"}
)
This behaves similarly to a thin wrapper around a standard HTTP client.

​
Authentication

Authentication is configured at the API level.
Authentication configuration is not branch-specific. If you edit auth settings on any branch, the change applies globally — including to the main branch. Take care when modifying auth configuration.
Supported authentication types:
  • No auth — No authentication required.
  • API key — A key sent in a header or query parameter.
  • Basic auth — Username and password encoded in the Authorization header.
  • OAuth 2.0 — Token-based authentication with automatic token management.
  • Bearer token — A token sent in the Authorization header.
Auth configuration covers three aspects:
  1. Type — The authentication method (API key, bearer token, basic auth, OAuth 2.0, etc.)
  2. Location — Where credentials are sent (header, query parameter, or cookie)
  3. Secret value — The credential itself, managed securely by Agent Studio
Auth credentials are handled by Agent Studio and are not embedded in flows or functions.

​
Summary

The APIs tab provides:
  • Centralized API configuration
  • Environment-aware routing
  • A simple runtime interface with conv.api
  • A requests.Response-like return object that you process with response.json()
  • Debugging support via conv.log_api_response()
For examples of API calls in context, see:
Last modified on March 31, 2026