Help Center

Overview

The Agent Studio Public API allows your external applications to interact with your AI agents programmatically. You can list, retrieve details for, and execute your production-ready agents directly from your own software, without needing to log into the CRM dashboard. All communication is handled through secure HTTP requests that require proper authentication.

Key Capabilities

By using the Public API, you can integrate the power of your AI agents into a variety of other systems. This enables you to embed agent functionality into mobile applications, other software platforms, or internal tools. You can also trigger agents from external automation services or run them within your own environment to meet specific data privacy requirements. The API returns structured JSON data, making it easy for your systems to process the results.

Available API Endpoints

The Public API provides several endpoints for managing and interacting with your agents.

List Agents

This endpoint retrieves a list of all active agents for a specified location.

Method: GET
Endpoint: /agent-studio/public-api/agents
Required Parameter: locationId (as a query parameter)
Optional Parameters: limit, offset (for pagination)

This is useful for populating a selection menu in your application with available agents.

Get Agent Details

Use this endpoint to fetch the complete metadata for a specific agent.

Method: GET
Endpoint: /agent-studio/public-api/agents/{agentId}
Required Parameter: locationId (as a query parameter)

The response includes details such as the agent's name, status, configured tools, variables, and its current lifecycle stage.

Execute an Agent

This endpoint runs an agent and returns its full output.

Method: POST
Endpoint: /agent-studio/public-api/agents/{agentId}/execute
Request Body: A JSON object containing the locationId and an input object (e.g., a prompt). An optional executionId can be included to continue a conversation thread.

The first call to execute an agent will return an executionId in the response. You can use this ID in subsequent calls to maintain the context of a multi-turn conversation with the agent.

Authentication

All requests to the Public API must be authenticated. There are two primary methods for obtaining an access token.

OAuth 2.0

You can use the standard OAuth 2.0 authorization code flow. After creating an OAuth application in your CRM's developer settings, you will exchange an authorization code for an access token. This token must be included in the Authorization header of your API requests as a Bearer token.

Private Integration Token (PIT)

For server-to-server integrations, a Private Integration Token offers a simpler alternative to OAuth. You can generate a PIT in the Developer Settings, scoping it to a specific sub-account. This token is used in the Authorization header just like an OAuth token.

Getting Started

Follow these steps to begin using the Agent Studio Public API.

Ensure Agent Studio is enabled for your sub-account and that you have at least one agent published to the "Production" stage.
Navigate to Settings > Developer in your CRM dashboard.
Create either an OAuth application or a Private Integration.
For OAuth, note your Client ID and Client Secret. For a Private Integration, copy the generated PIT value.
If using OAuth, follow the standard flow to obtain an access token. Securely store this token and refresh it as needed.
Test your connection by calling the List Agents endpoint with your authentication token and locationId.
Use the returned agentId to make a test call to the Execute Agent endpoint.

Frequently Asked Questions

Are there rate limits?
Yes. Each sub-account is limited to 300 requests per minute across all Agent Studio API endpoints.

Can I stream agent responses?
No, streaming partial responses is not currently supported. The Execute Agent endpoint returns the complete output in a single JSON response.

Using the Agent Studio Public API