How to Use Public APIs in GoHighLevel — Agent Studio

If you're running a digital marketing agency or managing multiple client accounts in GoHighLevel, you've probably felt the friction: you're stuck logging into HighLevel every time you need to run an AI agent. What if you could automate agent execution directly from your own software platform without touching the dashboard?

That's exactly what GoHighLevel's Public APIs for Agent Studio make possible. In this guide, I'll show you how to list, retrieve, and execute AI agents using secure OAuth authentication—so you can build seamless integrations that scale with your agency.

Whether you're building a custom client portal or automating workflows across your entire operation, understanding these APIs is a game-changer. Ready to unlock this potential? Get a free 30-day trial of GoHighLevel and start building with Agent Studio APIs today.

What Are Agent Studio Public APIs and Why Your Agency Needs Them

Agent Studio Public APIs are a set of endpoints that let you interact with AI agents built in GoHighLevel from outside the platform. Instead of requiring your clients or team members to log into HighLevel and manually trigger agents, you can call these APIs directly from your custom software.

Here's why this matters for your agency:

• Brand Control: Run HighLevel agents through your own white-labeled interface without ever showing the HighLevel dashboard
• Workflow Automation: Trigger agents automatically based on custom business logic in your systems
• Client Self-Service: Let clients execute agents from a portal you build without HighLevel access
• Integration Flexibility: Connect HighLevel agents to your existing tech stack seamlessly
• Scalability: Manage 50+ clients' agents from one central system without manual intervention

The Public APIs give you three primary capabilities: listing available agents, retrieving agent details, and executing agents with parameters. Each is secured with OAuth 2.0 authentication, which means your integrations stay protected and compliant.

Understanding the Three Core API Endpoints

GoHighLevel's Agent Studio exposes three main endpoints you need to understand. Let me break down what each does:

1. List Agents Endpoint

This endpoint returns all agents available in a specific location (sub-account). Use it when you need to display a dropdown menu or dashboard of available agents. The response includes agent ID, name, description, and status—everything you need to present options to users.

2. Get Agent Endpoint

Retrieve detailed information about a specific agent, including its input parameters, configuration, and execution requirements. This is essential before you execute an agent, because you need to know what inputs the agent expects. An agent might require a customer name and phone number, for example, and this endpoint tells you exactly what to collect.

3. Execute Agent Endpoint

This is the money endpoint—it actually runs the agent with the parameters you provide. Pass in the agent ID, location ID, and required input data, and the agent executes immediately. The response includes execution status and any output the agent generates.

Setting Up Secure OAuth Authentication

Every API call requires OAuth 2.0 authentication. This is GoHighLevel's way of ensuring only authorized applications can execute agents on your account.

Step 1: Create an OAuth Application

Log into your GoHighLevel account and navigate to Settings → Integrations → API Keys. Create a new OAuth application and record your Client ID and Client Secret. Never share your Client Secret—it's like your password.

Step 2: Request an Access Token

Your application exchanges the Client ID and Client Secret for an access token. This token is what you include in every API request. Access tokens typically expire after a set period (usually 1 hour), so your application needs to handle token refresh automatically.

Step 3: Include the Token in API Requests

Every API call includes an Authorization header with your access token:

Authorization: Bearer YOUR_ACCESS_TOKEN

The HighLevel npm SDK (@gohighlevel/api-client) handles this automatically if you're using their official client library. If you're building custom integrations, you'll need to manage token refresh manually or use a library that does it for you.

This is built into GoHighLevel. Try it free for 30 days →

Implementing List Agents and Get Agent Endpoints

Let's get practical. Here's how to implement these endpoints in your application.

List Agents Implementation

When you need to show a user which agents are available in their account, call the List Agents endpoint. The endpoint returns an array of agent objects. You can then populate a dropdown, table, or card-based UI with these agents.

Filter the response by agent status if you want to show only active agents. Exclude disabled or archived agents from user-facing interfaces to reduce confusion.

Get Agent Implementation

Once a user selects an agent, fetch its details using the Get Agent endpoint. This response tells you:

• What input fields are required
• Data types expected (string, number, email, etc.)
• Default values, if any
• Validation rules

Use this information to dynamically generate the form your user will fill out before execution. If an agent expects a phone number, show a phone input field. If it needs a date, show a date picker. This level of dynamic UI prevents execution errors and improves user experience.

Executing Agents Programmatically with Execute Agent API

This is where the magic happens. The Execute Agent endpoint takes the agent ID, location ID, and input parameters you collected, and runs the agent immediately.

The Execution Flow

First, validate all required parameters against the schema you retrieved from Get Agent. Don't send an incomplete request—it will fail and waste an API call.

Second, handle asynchronous execution. Agent execution might be instant (returns results immediately) or queued (returns a job ID for you to poll). Always implement polling logic if the response includes a job ID or execution status endpoint.

Third, gracefully handle errors. Network failures, invalid parameters, and agent timeouts all happen. Log these events and provide user feedback. Don't silently fail—tell the user what went wrong.

Example Response Handling

When an agent executes successfully, the API returns status, output data, and metadata. Store this execution record in your database so you have an audit trail. Your clients will want to see "Agent X ran on Date Y with Result Z."

Best Practices for Production Integrations

1. Manage Access Tokens Securely

Store your Client Secret in environment variables or a secure secrets manager—never hardcode it. Rotate tokens regularly and revoke old ones. If a token is ever exposed, revoke it immediately from the HighLevel dashboard.

2. Implement Rate Limiting

GoHighLevel has rate limits on API calls. Monitor your usage and implement request queuing on your side. If you're managing 100+ agents, you'll hit limits without proper throttling.

3. Log Everything

Create detailed logs of every API call: timestamp, agent ID, parameters sent, response received, execution time. When something breaks at 2 AM, these logs are your lifeline for debugging.

4. Validate User Permissions

Not every user should be able to execute every agent. Build permission checks into your application layer. Check that the authenticated user has rights to the location and agent before allowing execution.

5. Test with the Official SDK

Use the @gohighlevel/api-client npm package if you're building in JavaScript/Node. It handles OAuth, token refresh, and error handling automatically. This reduces bugs and maintenance overhead.