Voice AI and Conversation AI are separate products in HighLevel's API, each with its own scopes and its own request parameters. The errors below are the ones that come from treating them as one, plus the version header that decides which documentation page applies to your call.
Match each scope to the call
Request scopes by the call your integration actually makes. This is the map we work from.
- Create a Voice AI agent: voice-ai-agents.write.
- Create an action on a Voice AI agent: voice-ai-agent-goals.write.
- List Voice AI agents: voice-ai-agents.readonly.
- Read Voice AI call logs: voice-ai-dashboard.readonly. This one comes from our own build notes; HighLevel's scope table didn't load when we checked, so confirm it there.
- Search Conversation AI agents: conversation-ai.readonly.
Ask for voice-ai-agents.write and voice-ai-agent-goals.write by name. voice-ai.write doesn't exist.
Listing Voice AI agents
The Voice AI list call has three rules, all in HighLevel's List Agents schema. It needs locationId. Its pageSize takes a value from 1 to 50. And its pages are numbered from 1, not 0.
Our notes from September 2026 filed the page-size limit under undocumented quirks, after the list returned a 422 above 50. The current schema states the limit, so treat it as a rule. To page through a large account, ask for 50 at a time and step the page number up from 1.
Searching Conversation AI agents
Conversation AI search is a different shape. HighLevel documents startAfter, limit and a query for the agent name, matched in lowercase, so lowercase the text before you send it.
Don't copy the Voice AI parameters across. In our builds in September 2026, adding locationId to this search returned a 422 saying the property locationId should not exist. We haven't reproduced that since, but locationId isn't among the documented search parameters either, so leave it out.
Which Version header to send
HighLevel's API docs come in versions, and the header follows the version you're reading. The current unversioned pages for Conversation AI search and the Voice AI list show Version: v3. Older pinned pages, and older notes of ours, use 2021-04-15.
Neither header fits every endpoint by default. Set the version per call in your code, match it to the documentation page you built that call from, and note which page that was. HighLevel has changed this before, so check the current page when a call that used to work starts failing.
Rather have it set up for you?
We'd build your chat and voice agents in HighLevel along with the API calls that manage them, starting with a 30-minute 1:1 with Rob.
When a call fails, check in this order
Most errors on these endpoints trace back to one of four things.
- The scope. Is it the exact scope for this call, not a shorthand or a neighboring product's scope?
- The product. Are you sending Voice AI parameters to a Conversation AI endpoint, or the reverse?
- The limits. For the Voice AI list: locationId present, pageSize 50 or lower, page starting at 1.
- The version. Does the Version header match the doc page this call was written from?