Skip to main content
The APIs tab lets you define external HTTP APIs directly in Agent Studio and reference and include them when you are 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 the APIs tab is 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. 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

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

​
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. Supported auth types include:
  • No auth
  • Header-based auth (for example, API keys)
  • Other configured mechanisms depending on deployment
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()
For examples of API calls in context, see: