HighLevel: Agent studio schemas

← Agent studio operations · All schemas

Create Agent — agent Studio create Agent — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
agencyId	string	Optional	Agency ID
authorEmail	string	Optional	Author email
authorId	string	Optional	Author ID
authorName	string	Optional	Author name
description	string	Optional	Description of the agent
edges	array	Optional	Edges array (deprecated, prefer using version.edges)
edges[]	string	Each item
locationId	string	Required within parent	Location ID
name	string	Optional	Name of the agent
nodes	array	Optional	Nodes array (deprecated, prefer using version.nodes)
nodes[]	string	Each item
status	string	Required within parent	Status of the agent One of: active, inactive, archived
version	object	Required within parent	Version data for the agent including nodes, edges, and configuration

Create Agent — agent Studio create Agent — response body

Field	Type	Presence	Description and constraints
$	object	Root
agent	object	Required within parent	Created agent data with metadata
message	string	Required within parent	Response message
success	boolean	Required within parent	Success status
versions	array	Required within parent	Created versions array (initial staging version)

Delete Agent — agent Studio delete Agent — response body

Field	Type	Presence	Description and constraints
$	object	Root
agentId	string	Optional	Deleted agent ID
message	string	Required within parent	Response message
success	boolean	Required within parent	Success status

Execute Agent — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
attachments	array	Optional	Attachments for the message
attachments[]	Model	Each item	Expand Execute Agent — request body — body attachments item
contactId	string	Optional	Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.
executionId	string	Optional	Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages.
inputVariables	object	Optional	Input variables to pass to the agent. These should match the input variables defined in the agent configuration.
locationId	string	Required within parent	Location ID
message	string	Required within parent	Message to send to the agent
versionId	string	Optional	Published version ID to execute. If not provided, the latest published production version will be used.

Referenced models: Execute Agent — request body — body attachments item

Execute Agent — request body — body attachments item

Field	Type	Presence	Description and constraints
$	object	Root
imageUrl	string	Required within parent	URL of the image attachment
type	string	Required within parent	Type of attachment

Execute Agent — response body

Field	Type	Presence	Description and constraints
$	object	Root
attachments	array	Required within parent	Response attachments
executionId	string	Required within parent	Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation.
executionStatus	string	Required within parent	Execution status
flowSwitch	boolean	Required within parent	Whether flow was switched
generativeOutputs	array	Required within parent	Generated outputs
goalCompletion	boolean	Required within parent	When end node is added in the graph, this will be true if the agent reached the end node in the graph
interactionId	string	Required within parent	Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.
nextExpectedInput	string	Required within parent	Expected input type for next interaction
response	string	Required within parent	Agent response text
success	boolean	Required within parent	Success status
type	string	Required within parent	Response type

Get Agent (Deprecated) — response body

Field	Type	Presence	Description and constraints
$	object	Root
agent	object	Required within parent	Agent metadata with all active versions
message	string	Required within parent	Response message
success	boolean	Required within parent	Success status
traceId	string	Optional	Request trace ID for debugging

List Agents (Deprecated) — response body

Field	Type	Presence	Description and constraints
$	object	Root
agents	array	Required within parent	List of agents with metadata
agents[]	object	Each item
agents[].agentId	string	Optional	Agent ID
agents[].createdAt	string	Optional	Creation timestamp
agents[].description	string	Optional	Agent description
agents[].locationId	string	Optional	Location ID
agents[].name	string	Optional	Agent name
agents[].status	string	Optional	Agent status (always "active")
agents[].updatedAt	string	Optional	Last update timestamp
message	string	Required within parent	Response message
pagination	object	Required within parent	Pagination metadata
pagination.hasMore	boolean	Optional	Whether more agents exist
pagination.limit	JSON	Optional
pagination.limit (anyOf 1)	number	Alternative	Number of agents per page
pagination.limit (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pagination.offset	JSON	Optional
pagination.offset (anyOf 1)	number	Alternative	Starting position
pagination.offset (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pagination.total	JSON	Optional
pagination.total (anyOf 1)	number	Alternative	Total number of agents
pagination.total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
success	boolean	Required within parent	Success status

Promote to Production — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
locationId	string	Required within parent	Location ID for authorization
userEmail	string	Optional	User email performing the promotion action
userId	string	Optional	User ID performing the promotion action
userName	string	Optional	User name performing the promotion action

Promote to Production — response body

Field	Type	Presence	Description and constraints
$	object	Root
data	object	Required within parent	Result data with production and new draft version details
message	string	Required within parent	Response message
success	boolean	Required within parent	Success status

Update Agent Metadata — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	Description of the agent
locationId	string	Required within parent	Location ID for authorization (cannot be updated)
name	string	Optional	Name of the agent
status	string	Optional	Status of the agent One of: active, inactive, archived

Update Agent Metadata — response body

Field	Type	Presence	Description and constraints
$	object	Root
data	object	Required within parent	Updated agent or version data
message	string	Required within parent	Response message
success	boolean	Required within parent	Success status

Update Agent — agent Studio update Agent Version — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	Description of the version
edges	array	Optional	Complete array of edges connecting the nodes. Provide all edges including unchanged ones.
edges[]	object	Each item
globalConfig	object	Optional	Global configuration including prompts and settings
globalVariables	array	Optional	Global variables accessible throughout the agent workflow
globalVariables[]	object	Each item
inputVariables	array	Optional	Input variables required from user at execution time
inputVariables[]	object	Each item
locationId	string	Required within parent	Location ID for authorization
nodes	array	Optional	Complete array of nodes for the agent workflow. Provide all nodes including unchanged ones.
nodes[]	object	Each item
runtimeVariables	array	Optional	Runtime variables generated during agent execution
runtimeVariables[]	object	Each item
userId	string	Optional	User ID performing the update
userName	string	Optional	User name performing the update
versionName	string	Optional	Version name