Skip to content

Agent-Studio.md

Latest commit

 

History

History
4033 lines (2617 loc) · 74.4 KB

Agent-Studio.md

File metadata and controls

4033 lines (2617 loc) · 74.4 KB
Raw

Agent Studio API

Source: HighLevel API 2.0 Documentation Crawled: 2026-03-25

Table of Contents

Agent Studio Apis

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/agent-studio-apis

Skip to main content

Version: 1.0

Agent Studio APIs

Documentation for Agent Studio APIs

Authentication ​

  • HTTP: Bearer Auth
  • HTTP: Bearer Auth
  • HTTP: Bearer Auth
  • HTTP: Bearer Auth
  • HTTP: Bearer Auth

Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

| Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | | Bearer format: | JWT |

Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

| Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | | Bearer format: | JWT |

Use the Access Token generated with user type as Sub-Account.

| Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | | Bearer format: | JWT |

Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.

| Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | | Bearer format: | JWT |

Use the Access Token generated with user type as Agency.

| Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | | Bearer format: | JWT |

Agents

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/agents

Skip to main content

Documentation for Agent Studio APIs

📄️ Create Agent \ Creates a new agent with staging version. The agent will be created with an initial staging version that can later be promoted to production.📄️ List Agents \ Lists all active agents for the specified location. locationId is required parameter to ensure optimal performance. Supports pagination using limit and offset. Optionally filter by isPublished=true to return only agents with a published production version.📄️ Update Agent \ Updates a specific agent version by versionId. Supports updating nodes, edges, variables, and configuration.📄️ Update Agent Metadata \ Updates agent metadata such as name, description, and status.📄️ Delete Agent \ Deletes an agent and all its versions.📄️ Get Agent \ Gets a specific agent by its ID for the specified location with all its versions. Returns complete agent metadata and all non-deleted versions (draft, staging, production). locationId is required parameter. The agent must have active status.📄️ Promote to Production \ Promotes a draft version to production.📄️ Execute Agent \ Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified location. locationId is required in the request body.📄️ List Agents (Deprecated)\ **Deprecated endpoint - use GET /agent instead.**📄️ Get Agent (Deprecated)\ **Deprecated endpoint - use GET /agent/:agentId instead.**📄️ Execute Agent (Deprecated)\ **Deprecated endpoint - use POST /agent/:agentId/execute instead.**

Create Agent

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/create-agent

Skip to main content

Create Agent

POST https://services.leadconnectorhq.com/agent-studio/agent

Creates a new agent with staging version. The agent will be created with an initial staging version that can later be promoted to production.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Query Parameters

source string

Example: api

  • application/json

Body required

locationId stringrequired

Location ID

Example:C2QujeCh8ZnC7al2InWR

name string

Name of the agent

Example:Customer Support Agent

description string

Description of the agent

Example:AI agent specialized in handling customer inquiries and support tickets

agencyId string

Agency ID

Example:gjL2sFNXJfJYa3d2OYSN

authorId string

Author ID

Example:usr_abc123def456

authorName string

Author name

Example:John Doe

authorEmail string

Author email

Example:john@example.com

status stringrequired

Status of the agent

Possible values: [active, inactive, archived]

Example:active

version objectrequired

Version data for the agent including nodes, edges, and configuration

Example:{"versionName":"Version 1","description":"Initial version","nodes":[],"edges":[],"uiNodes":[],"uiEdges":[],"globalVariables":[],"inputVariables":[],"runtimeVariables":[],"scopes":[]}

nodes string[]

Nodes array (deprecated, prefer using version.nodes)

Example:[]

edges string[]

Edges array (deprecated, prefer using version.edges)

Example:[]

Responses ​

  • 201
  • 400
  • 401
  • 422
  • 500

Agent created successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent created successfully with staging version.

agent objectrequired

Created agent data with metadata

Example:{"agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","name":"Customer Support Agent","description":"AI agent specialized in handling customer inquiries and support tickets","locationId":"C2QujeCh8ZnC7al2InWR","agencyId":"gjL2sFNXJfJYa3d2OYSN","status":"active","authorId":"usr_abc123def456","folderId":"C2QujeCh8ZnC7al2InWR","folderName":null,"createdAt":"2024-02-27T10:30:00.000Z","updatedAt":"2024-02-27T10:30:00.000Z"}

versions arrayrequired

Created versions array (initial staging version)

Example:[{"versionId":"v1a2b3c4d5e6f7g8h9i0","agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","versionName":"Customer Support Agent v1","state":"staging","isPublished":false,"version":1,"createdAt":"2024-02-27T10:30:00.000Z"}]

{
  "success": true,
  "message": "Agent created successfully with staging version.",
  "agent": {
    "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",
    "name": "Customer Support Agent",
    "description": "AI agent specialized in handling customer inquiries and support tickets",
    "locationId": "C2QujeCh8ZnC7al2InWR",
    "agencyId": "gjL2sFNXJfJYa3d2OYSN",
    "status": "active",
    "authorId": "usr_abc123def456",
    "folderId": "C2QujeCh8ZnC7al2InWR",
    "folderName": null,
    "createdAt": "2024-02-27T10:30:00.000Z",
    "updatedAt": "2024-02-27T10:30:00.000Z"
  },
  "versions": [\
    {\
      "versionId": "v1a2b3c4d5e6f7g8h9i0",\
      "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",\
      "versionName": "Customer Support Agent v1",\
      "state": "staging",\
      "isPublished": false,\
      "version": 1,\
      "createdAt": "2024-02-27T10:30:00.000Z"\
    }\
  ]
}

Bad Request

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/agent' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "name": "Customer Support Agent",
  "description": "AI agent specialized in handling customer inquiries and support tickets",
  "agencyId": "gjL2sFNXJfJYa3d2OYSN",
  "authorId": "usr_abc123def456",
  "authorName": "John Doe",
  "authorEmail": "john@example.com",
  "status": "active",
  "version": {
    "versionName": "Version 1",
    "description": "Initial version",
    "nodes": [],
    "edges": [],
    "uiNodes": [],
    "uiEdges": [],
    "globalVariables": [],
    "inputVariables": [],
    "runtimeVariables": [],
    "scopes": []
  },
  "nodes": [],
  "edges": []
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "name": "Customer Support Agent",
  "description": "AI agent specialized in handling customer inquiries and support tickets",
  "agencyId": "gjL2sFNXJfJYa3d2OYSN",
  "authorId": "usr_abc123def456",
  "authorName": "John Doe",
  "authorEmail": "john@example.com",
  "status": "active",
  "version": {
    "versionName": "Version 1",
    "description": "Initial version",
    "nodes": [],
    "edges": [],
    "uiNodes": [],
    "uiEdges": [],
    "globalVariables": [],
    "inputVariables": [],
    "runtimeVariables": [],
    "scopes": []
  },
  "nodes": [],
  "edges": []
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Delete Agent

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/delete-agent

Skip to main content

Delete Agent

DELETE https://services.leadconnectorhq.com/agent-studio/agent/:agentId

Deletes an agent and all its versions.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

locationId stringrequired

Example: C2QujeCh8ZnC7al2InWR

source string

Example: api

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Agent deleted successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent deleted successfully

agentId string

Deleted agent ID

Example:p1q2r3s4t5u6v7w8x9y0z1a2

{
  "success": true,
  "message": "Agent deleted successfully",
  "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2"
}

Bad Request

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Agent not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L -X DELETE 'https://services.leadconnectorhq.com/agent-studio/agent/:agentId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

locationId — queryrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Execute Agent

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/execute-agent

Skip to main content

Execute Agent

POST https://services.leadconnectorhq.com/agent-studio/agent/:agentId/execute

Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified location. locationId is required in the request body.

Session Management:

  • For the first message in a new session, do not include the executionId in the request payload.
  • The API will return an executionId along with the agent response, which uniquely identifies this conversation session.
  • To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

source string

Example: api

  • application/json

Body required

message stringrequired

Message to send to the agent

Example:How can you help me with my marketing?

executionId string

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.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

inputVariables object

Input variables to pass to the agent. These should match the input variables defined in the agent configuration.

Example:{"customerName":"John Doe","orderNumber":"ORD-12345"}

versionId string

Published version ID to execute. If not provided, the latest published production version will be used.

Example:b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d

attachments object[]

Attachments for the message

Array [

type stringrequired

Type of attachment

Example:image

imageUrl stringrequired

URL of the image attachment

Example:https://example.com/image.png

]

locationId stringrequired

Location ID

Example:C2QujeCh8ZnC7al2InWR

contactId string

GHL Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

Example:cid_abc123def456

Responses ​

  • 200
  • 400
  • 401
  • 403
  • 404
  • 422
  • 500

Agent executed successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

executionId stringrequired

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.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

interactionId stringrequired

Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.

Example:m9n8o7p6q5r4s3t2u1v0w9x8

response stringrequired

Agent response text

Example:I can help you with various tasks...

type stringrequired

Response type

Example:text

nextExpectedInput stringrequired

Expected input type for next interaction

Example:text

goalCompletion booleanrequired

When end node is added in the graph, this will be true if the agent reached the end node in the graph

Example:false

executionStatus stringrequired

Execution status

Example:completed

flowSwitch booleanrequired

Whether flow was switched

Example:false

attachments arrayrequired

Response attachments

Example:[]

generativeOutputs arrayrequired

Generated outputs

Example:[]

{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}

Agent is not active or invalid request - locationId is required

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

User does not have required scopes to execute this agent

Agent not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/agent/:agentId/execute' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [\
    {\
      "type": "image",\
      "imageUrl": "https://example.com/image.png"\
    }\
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [\
    {\
      "type": "image",\
      "imageUrl": "https://example.com/image.png"\
    }\
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Execute Agent Deprecated

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/execute-agent-deprecated

Skip to main content

Execute Agent (Deprecated)

POST https://services.leadconnectorhq.com/agent-studio/public-api/agents/:agentId/execute

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecated endpoint - use POST /agent/:agentId/execute instead.

Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified location. locationId is required in the request body.

Session Management:

  • For the first message in a new session, do not include the executionId in the request payload.
  • The API will return an executionId along with the agent response, which uniquely identifies this conversation session.
  • To continue the conversation within the same session, include the executionId from the previous response in subsequent requests.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

source string

Example: api

  • application/json

Body required

message stringrequired

Message to send to the agent

Example:How can you help me with my marketing?

executionId string

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.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

inputVariables object

Input variables to pass to the agent. These should match the input variables defined in the agent configuration.

Example:{"customerName":"John Doe","orderNumber":"ORD-12345"}

versionId string

Published version ID to execute. If not provided, the latest published production version will be used.

Example:b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d

attachments object[]

Attachments for the message

Array [

type stringrequired

Type of attachment

Example:image

imageUrl stringrequired

URL of the image attachment

Example:https://example.com/image.png

]

locationId stringrequired

Location ID

Example:C2QujeCh8ZnC7al2InWR

contactId string

GHL Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

Example:cid_abc123def456

Responses ​

  • 200
  • 400
  • 401
  • 403
  • 404
  • 422
  • 500

Agent executed successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

executionId stringrequired

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.

Example:a1b2c3d4e5f6g7h8i9j0k1l2

interactionId stringrequired

Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId.

Example:m9n8o7p6q5r4s3t2u1v0w9x8

response stringrequired

Agent response text

Example:I can help you with various tasks...

type stringrequired

Response type

Example:text

nextExpectedInput stringrequired

Expected input type for next interaction

Example:text

goalCompletion booleanrequired

When end node is added in the graph, this will be true if the agent reached the end node in the graph

Example:false

executionStatus stringrequired

Execution status

Example:completed

flowSwitch booleanrequired

Whether flow was switched

Example:false

attachments arrayrequired

Response attachments

Example:[]

generativeOutputs arrayrequired

Generated outputs

Example:[]

{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}

Agent is not active or invalid request - locationId is required

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

User does not have required scopes to execute this agent

Agent not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/public-api/agents/:agentId/execute' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [\
    {\
      "type": "image",\
      "imageUrl": "https://example.com/image.png"\
    }\
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [\
    {\
      "type": "image",\
      "imageUrl": "https://example.com/image.png"\
    }\
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Get Agent By Id

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/get-agent-by-id

Skip to main content

Get Agent

GET https://services.leadconnectorhq.com/agent-studio/agent/:agentId

Gets a specific agent by its ID for the specified location with all its versions. Returns complete agent metadata and all non-deleted versions (draft, staging, production). locationId is required parameter. The agent must have active status.

Requirements

Scope(s)

agent-studio.readonly

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

locationId stringrequired

Example: C2QujeCh8ZnC7al2InWR

source string

Example: api

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Agent retrieved successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent retrieved successfully

agent objectrequired

Agent metadata with all active versions

Example:{"id":"d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd","agentId":"AgfS2JXWsSN8aXb5c4d2","name":"Customer Support Agent","description":"AI agent for customer support","isGhl":"false","agencyId":"5DP4iH6HLkQsiKESj6rh","locationId":"C2QujeCh8ZnC7al2InWR","productSlug":"agent_studio","productId":"agent_studio","authorId":"usr_123","status":"active","folderId":"vEoIigWSAw1BQA9DEchD","folderName":"Default Agents","createdAt":"2026-03-06T10:37:01.013Z","updatedAt":"2026-03-06T10:37:01.014Z","deleted":false,"productionVersion":{"versionId":"Ver1K8sSF2nC7al5InWz","versionName":"Content Creation Agent v1","isPublished":true,"inputVariables":[],"updatedAt":"2026-03-02T06:53:40.570Z"},"versions":[{"id":"3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3","versionId":"Ver1K8sSF2nC7al5InWz","agentId":"AgfS2JXWsSN8aXb5c4d2","agencyId":"5DP4iH6HLkQsiKESj6rh","locationId":"C2QujeCh8ZnC7al2InWR","versionName":"v1","description":"AI agent for customer support","state":"staging","isPublished":false,"scopes":[],"nodes":[],"edges":[],"uiNodes":[],"uiEdges":[],"globalVariables":[],"inputVariables":[],"runtimeVariables":[],"viewport":{"x":0,"y":0,"zoom":1},"globalConfig":{},"createdAt":"2026-03-06T10:37:01.079Z","updatedAt":"2026-03-06T10:37:01.079Z","deleted":false,"storedInBucket":true,"bucketFilePath":"agent-definitions/5DP4iH6HLkQsiKESj6rh/vEoIigWSAw1BQA9DEchD/d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd/3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3.json"}]}

traceId string

Request trace ID for debugging

Example:22dbda99-13d3-4b4d-a30e-c468334e2178

{
  "success": true,
  "message": "Agent retrieved successfully",
  "agent": {
    "id": "d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd",
    "agentId": "AgfS2JXWsSN8aXb5c4d2",
    "name": "Customer Support Agent",
    "description": "AI agent for customer support",
    "isGhl": "false",
    "agencyId": "5DP4iH6HLkQsiKESj6rh",
    "locationId": "C2QujeCh8ZnC7al2InWR",
    "productSlug": "agent_studio",
    "productId": "agent_studio",
    "authorId": "usr_123",
    "status": "active",
    "folderId": "vEoIigWSAw1BQA9DEchD",
    "folderName": "Default Agents",
    "createdAt": "2026-03-06T10:37:01.013Z",
    "updatedAt": "2026-03-06T10:37:01.014Z",
    "deleted": false,
    "productionVersion": {
      "versionId": "Ver1K8sSF2nC7al5InWz",
      "versionName": "Content Creation Agent v1",
      "isPublished": true,
      "inputVariables": [],
      "updatedAt": "2026-03-02T06:53:40.570Z"
    },
    "versions": [\
      {\
        "id": "3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3",\
        "versionId": "Ver1K8sSF2nC7al5InWz",\
        "agentId": "AgfS2JXWsSN8aXb5c4d2",\
        "agencyId": "5DP4iH6HLkQsiKESj6rh",\
        "locationId": "C2QujeCh8ZnC7al2InWR",\
        "versionName": "v1",\
        "description": "AI agent for customer support",\
        "state": "staging",\
        "isPublished": false,\
        "scopes": [],\
        "nodes": [],\
        "edges": [],\
        "uiNodes": [],\
        "uiEdges": [],\
        "globalVariables": [],\
        "inputVariables": [],\
        "runtimeVariables": [],\
        "viewport": {\
          "x": 0,\
          "y": 0,\
          "zoom": 1\
        },\
        "globalConfig": {},\
        "createdAt": "2026-03-06T10:37:01.079Z",\
        "updatedAt": "2026-03-06T10:37:01.079Z",\
        "deleted": false,\
        "storedInBucket": true,\
        "bucketFilePath": "agent-definitions/5DP4iH6HLkQsiKESj6rh/vEoIigWSAw1BQA9DEchD/d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd/3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3.json"\
      }\
    ]
  },
  "traceId": "22dbda99-13d3-4b4d-a30e-c468334e2178"
}

Bad Request - locationId is required

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Agent not found or not available

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.readonlyscheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/agent/:agentId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

locationId — queryrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Get Agent By Id Deprecated

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/get-agent-by-id-deprecated

Skip to main content

Get Agent (Deprecated)

GET https://services.leadconnectorhq.com/agent-studio/public-api/agents/:agentId

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecated endpoint - use GET /agent/:agentId instead.

Gets a specific agent by its ID for the specified location with all its versions. locationId is required parameter. The agent must have active status.

Requirements

Scope(s)

agent-studio.readonly

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

locationId stringrequired

Example: C2QujeCh8ZnC7al2InWR

source string

Example: api

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Agent retrieved successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent retrieved successfully

agent objectrequired

Agent metadata with all active versions

Example:{"id":"d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd","agentId":"AgfS2JXWsSN8aXb5c4d2","name":"Customer Support Agent","description":"AI agent for customer support","isGhl":"false","agencyId":"5DP4iH6HLkQsiKESj6rh","locationId":"C2QujeCh8ZnC7al2InWR","productSlug":"agent_studio","productId":"agent_studio","authorId":"usr_123","status":"active","folderId":"vEoIigWSAw1BQA9DEchD","folderName":"Default Agents","createdAt":"2026-03-06T10:37:01.013Z","updatedAt":"2026-03-06T10:37:01.014Z","deleted":false,"productionVersion":{"versionId":"Ver1K8sSF2nC7al5InWz","versionName":"Content Creation Agent v1","isPublished":true,"inputVariables":[],"updatedAt":"2026-03-02T06:53:40.570Z"},"versions":[{"id":"3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3","versionId":"Ver1K8sSF2nC7al5InWz","agentId":"AgfS2JXWsSN8aXb5c4d2","agencyId":"5DP4iH6HLkQsiKESj6rh","locationId":"C2QujeCh8ZnC7al2InWR","versionName":"v1","description":"AI agent for customer support","state":"staging","isPublished":false,"scopes":[],"nodes":[],"edges":[],"uiNodes":[],"uiEdges":[],"globalVariables":[],"inputVariables":[],"runtimeVariables":[],"viewport":{"x":0,"y":0,"zoom":1},"globalConfig":{},"createdAt":"2026-03-06T10:37:01.079Z","updatedAt":"2026-03-06T10:37:01.079Z","deleted":false,"storedInBucket":true,"bucketFilePath":"agent-definitions/5DP4iH6HLkQsiKESj6rh/vEoIigWSAw1BQA9DEchD/d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd/3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3.json"}]}

traceId string

Request trace ID for debugging

Example:22dbda99-13d3-4b4d-a30e-c468334e2178

{
  "success": true,
  "message": "Agent retrieved successfully",
  "agent": {
    "id": "d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd",
    "agentId": "AgfS2JXWsSN8aXb5c4d2",
    "name": "Customer Support Agent",
    "description": "AI agent for customer support",
    "isGhl": "false",
    "agencyId": "5DP4iH6HLkQsiKESj6rh",
    "locationId": "C2QujeCh8ZnC7al2InWR",
    "productSlug": "agent_studio",
    "productId": "agent_studio",
    "authorId": "usr_123",
    "status": "active",
    "folderId": "vEoIigWSAw1BQA9DEchD",
    "folderName": "Default Agents",
    "createdAt": "2026-03-06T10:37:01.013Z",
    "updatedAt": "2026-03-06T10:37:01.014Z",
    "deleted": false,
    "productionVersion": {
      "versionId": "Ver1K8sSF2nC7al5InWz",
      "versionName": "Content Creation Agent v1",
      "isPublished": true,
      "inputVariables": [],
      "updatedAt": "2026-03-02T06:53:40.570Z"
    },
    "versions": [\
      {\
        "id": "3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3",\
        "versionId": "Ver1K8sSF2nC7al5InWz",\
        "agentId": "AgfS2JXWsSN8aXb5c4d2",\
        "agencyId": "5DP4iH6HLkQsiKESj6rh",\
        "locationId": "C2QujeCh8ZnC7al2InWR",\
        "versionName": "v1",\
        "description": "AI agent for customer support",\
        "state": "staging",\
        "isPublished": false,\
        "scopes": [],\
        "nodes": [],\
        "edges": [],\
        "uiNodes": [],\
        "uiEdges": [],\
        "globalVariables": [],\
        "inputVariables": [],\
        "runtimeVariables": [],\
        "viewport": {\
          "x": 0,\
          "y": 0,\
          "zoom": 1\
        },\
        "globalConfig": {},\
        "createdAt": "2026-03-06T10:37:01.079Z",\
        "updatedAt": "2026-03-06T10:37:01.079Z",\
        "deleted": false,\
        "storedInBucket": true,\
        "bucketFilePath": "agent-definitions/5DP4iH6HLkQsiKESj6rh/vEoIigWSAw1BQA9DEchD/d6a6792d-0d50-4e8f-9c3b-ecd8096d0bdd/3f9d9ab7-5ca4-4e64-8472-eab9e77a0fe3.json"\
      }\
    ]
  },
  "traceId": "22dbda99-13d3-4b4d-a30e-c468334e2178"
}

Bad Request - locationId is required

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Agent not found or not available

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.readonlyscheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/public-api/agents/:agentId' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

locationId — queryrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Get Agents

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/get-agents

Skip to main content

List Agents

GET https://services.leadconnectorhq.com/agent-studio/agent

Lists all active agents for the specified location. locationId is required parameter to ensure optimal performance. Supports pagination using limit and offset. Optionally filter by isPublished=true to return only agents with a published production version.

Requirements

Scope(s)

agent-studio.readonly

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Query Parameters

locationId stringrequired

Example: C2QujeCh8ZnC7al2InWR

isPublished string

Optional filter to return only agents with a published production version

Example: true

limit stringrequired

Example: 20

offset stringrequired

Example: 0

source string

Example: api

Responses ​

  • 200
  • 400
  • 401
  • 422
  • 500

Agents retrieved successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agents retrieved successfully

agents object[]required

List of agents with metadata

Array [

agentId string

Agent ID

name string

Agent name

description string

Agent description

locationId string

Location ID

status string

Agent status (always "active")

createdAt string

Creation timestamp

updatedAt string

Last update timestamp

]

pagination objectrequired

Pagination metadata

total number

Total number of agents

limit number

Number of agents per page

offset number

Starting position

hasMore boolean

Whether more agents exist

{
  "success": true,
  "message": "Agents retrieved successfully",
  "agents": [\
    {\
      "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",\
      "name": "Marketing Assistant",\
      "description": "AI agent specialized in marketing strategy and content creation",\
      "locationId": "C2QujeCh8ZnC7al2InWR",\
      "status": "active",\
      "createdAt": "2024-01-15T10:30:00.000Z",\
      "updatedAt": "2024-02-20T14:45:00.000Z"\
    },\
    {\
      "agentId": "b3c4d5e6f7g8h9i0j1k2l3m4",\
      "name": "Customer Support Bot",\
      "description": "AI agent for handling customer inquiries and support tickets",\
      "locationId": "C2QujeCh8ZnC7al2InWR",\
      "status": "active",\
      "createdAt": "2024-01-10T09:15:00.000Z",\
      "updatedAt": "2024-02-18T16:20:00.000Z"\
    }\
  ],
  "pagination": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Bad Request - locationId is required

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.readonlyscheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/agent' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

locationId — queryrequired

limit — queryrequired

offset — queryrequired

Version — headerrequired

---2021-04-15

Show optional parameters

isPublished — query

source — query

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Get Agents Deprecated

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/get-agents-deprecated

Skip to main content

List Agents (Deprecated)

GET https://services.leadconnectorhq.com/agent-studio/public-api/agents

deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

Deprecated endpoint - use GET /agent instead.

Lists all active agents that have a published production version for the specified location. locationId is required parameter. Supports pagination using limit and offset.

Requirements

Scope(s)

agent-studio.readonly

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Query Parameters

locationId stringrequired

Example: C2QujeCh8ZnC7al2InWR

limit stringrequired

Example: 20

offset stringrequired

Example: 0

source string

Example: api

Responses ​

  • 200
  • 400
  • 401
  • 422
  • 500

Agents retrieved successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agents retrieved successfully

agents object[]required

List of agents with metadata

Array [

agentId string

Agent ID

name string

Agent name

description string

Agent description

locationId string

Location ID

status string

Agent status (always "active")

createdAt string

Creation timestamp

updatedAt string

Last update timestamp

]

pagination objectrequired

Pagination metadata

total number

Total number of agents

limit number

Number of agents per page

offset number

Starting position

hasMore boolean

Whether more agents exist

{
  "success": true,
  "message": "Agents retrieved successfully",
  "agents": [\
    {\
      "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",\
      "name": "Marketing Assistant",\
      "description": "AI agent specialized in marketing strategy and content creation",\
      "locationId": "C2QujeCh8ZnC7al2InWR",\
      "status": "active",\
      "createdAt": "2024-01-15T10:30:00.000Z",\
      "updatedAt": "2024-02-20T14:45:00.000Z"\
    },\
    {\
      "agentId": "b3c4d5e6f7g8h9i0j1k2l3m4",\
      "name": "Customer Support Bot",\
      "description": "AI agent for handling customer inquiries and support tickets",\
      "locationId": "C2QujeCh8ZnC7al2InWR",\
      "status": "active",\
      "createdAt": "2024-01-10T09:15:00.000Z",\
      "updatedAt": "2024-02-18T16:20:00.000Z"\
    }\
  ],
  "pagination": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Bad Request - locationId is required

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.readonlyscheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/public-api/agents' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

locationId — queryrequired

limit — queryrequired

offset — queryrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Promote And Publish

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/promote-and-publish

Skip to main content

Promote to Production

POST https://services.leadconnectorhq.com/agent-studio/agent/versions/:versionId/publish

Promotes a draft version to production.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

versionId stringrequired

Example: v1a2b3c4d5e6f7g8h9i0

Query Parameters

source string

Example: api

  • application/json

Body required

locationId stringrequired

Location ID for authorization

Example:C2QujeCh8ZnC7al2InWR

userId string

User ID performing the promotion action

Example:usr_abc123def456

userName string

User name performing the promotion action

Example:John Doe

userEmail string

User email performing the promotion action

Example:john.doe@example.com

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Version promoted and published successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Draft published to production successfully. New draft version created for future edits.

data objectrequired

Result data with production and new draft version details

Example:{"productionVersion":{"versionId":"v1a2b3c4d5e6f7g8h9i0","agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","versionName":"Customer Support Agent v2","state":"prod","isPublished":true,"version":2,"publishedAt":"2024-02-27T12:00:00.000Z","publishedBy":"usr_abc123def456","publishedByName":"John Doe","publishedByEmail":"john.doe@example.com"},"newDraftVersion":{"versionId":"v2b3c4d5e6f7g8h9i0j1","agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","versionName":"Customer Support Agent v3","state":"draft","isPublished":false,"version":3,"createdAt":"2024-02-27T12:00:00.000Z"}}

{
  "success": true,
  "message": "Draft published to production successfully. New draft version created for future edits.",
  "data": {
    "productionVersion": {
      "versionId": "v1a2b3c4d5e6f7g8h9i0",
      "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",
      "versionName": "Customer Support Agent v2",
      "state": "prod",
      "isPublished": true,
      "version": 2,
      "publishedAt": "2024-02-27T12:00:00.000Z",
      "publishedBy": "usr_abc123def456",
      "publishedByName": "John Doe",
      "publishedByEmail": "john.doe@example.com"
    },
    "newDraftVersion": {
      "versionId": "v2b3c4d5e6f7g8h9i0j1",
      "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",
      "versionName": "Customer Support Agent v3",
      "state": "draft",
      "isPublished": false,
      "version": 3,
      "createdAt": "2024-02-27T12:00:00.000Z"
    }
  }
}

Bad Request - Only draft versions can be promoted

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Version not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L 'https://services.leadconnectorhq.com/agent-studio/agent/versions/:versionId/publish' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "userId": "usr_abc123def456",
  "userName": "John Doe",
  "userEmail": "john.doe@example.com"
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

versionId — pathrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "userId": "usr_abc123def456",
  "userName": "John Doe",
  "userEmail": "john.doe@example.com"
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Update Agent Metadata

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/update-agent-metadata

Skip to main content

Update Agent Metadata

PATCH https://services.leadconnectorhq.com/agent-studio/agent/:agentId

Updates agent metadata such as name, description, and status.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

agentId stringrequired

Example: p1q2r3s4t5u6v7w8x9y0z1a2

Query Parameters

source string

Example: api

  • application/json

Body required

locationId stringrequired

Location ID for authorization (cannot be updated)

Example:C2QujeCh8ZnC7al2InWR

name string

Name of the agent

Example:Updated Customer Support Agent

description string

Description of the agent

Example:Updated AI agent with enhanced customer support capabilities

status string

Status of the agent

Possible values: [active, inactive, archived]

Example:active

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Agent metadata updated successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent updated successfully

data objectrequired

Updated agent or version data

Example:{"agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","versionId":"v1a2b3c4d5e6f7g8h9i0","name":"Updated Customer Support Agent","description":"Updated AI agent with enhanced customer support capabilities","status":"active","updatedAt":"2024-02-27T11:45:00.000Z"}

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",
    "versionId": "v1a2b3c4d5e6f7g8h9i0",
    "name": "Updated Customer Support Agent",
    "description": "Updated AI agent with enhanced customer support capabilities",
    "status": "active",
    "updatedAt": "2024-02-27T11:45:00.000Z"
  }
}

Bad Request

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Agent not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L -X PATCH 'https://services.leadconnectorhq.com/agent-studio/agent/:agentId' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "name": "Updated Customer Support Agent",
  "description": "Updated AI agent with enhanced customer support capabilities",
  "status": "active"
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

agentId — pathrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "name": "Updated Customer Support Agent",
  "description": "Updated AI agent with enhanced customer support capabilities",
  "status": "active"
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!

Update Agent Version

Source: https://marketplace.gohighlevel.com/docs/ghl/agent-studio/update-agent-version

Skip to main content

Update Agent

PATCH https://services.leadconnectorhq.com/agent-studio/agent/versions/:versionId

Updates a specific agent version by versionId. Supports updating nodes, edges, variables, and configuration.

Requirements

Scope(s)

agent-studio.write

Auth Method(s)

OAuth Access Token``Private Integration Token

Token Type(s)

Sub-Account Token

Request ​

Header Parameters

Version stringrequired

Possible values: [2021-04-15]

API Version

Path Parameters

versionId stringrequired

Example: v1a2b3c4d5e6f7g8h9i0

Query Parameters

source string

Example: api

  • application/json

Body required

locationId stringrequired

Location ID for authorization

Example:C2QujeCh8ZnC7al2InWR

versionName string

Version name

Example:Customer Support Agent v2

description string

Description of the version

Example:Updated version with improved customer handling logic

nodes object[]

Complete array of nodes for the agent workflow. Provide all nodes including unchanged ones.

Example:[{"nodeId":"node_1","nodeName":"Start","type":"start","isStartNode":true},{"nodeId":"node_2","nodeName":"LLM Node","type":"llm","nodeConfig":{"prompt":"How can I help you?","llmProvider":"openai","llmModel":"gpt-4"}}]

edges object[]

Complete array of edges connecting the nodes. Provide all edges including unchanged ones.

Example:[{"startNode":"node_1","endNode":"node_2"}]

globalVariables object[]

Global variables accessible throughout the agent workflow

Example:[{"key":"apiKey","type":"string","value":"your-api-key"}]

inputVariables object[]

Input variables required from user at execution time

Example:[{"key":"customerName","type":"string","description":"Customer name for personalization"}]

runtimeVariables object[]

Runtime variables generated during agent execution

Example:[{"key":"sessionId","type":"string","description":"Current session identifier"}]

globalConfig object

Global configuration including prompts and settings

Example:{"globalPrompt":{"currentPrompt":"You are a helpful customer support assistant.","history":[]}}

userId string

User ID performing the update

Example:usr_abc123def456

userName string

User name performing the update

Example:John Doe

Responses ​

  • 200
  • 400
  • 401
  • 404
  • 422
  • 500

Version updated successfully

  • application/json

  • Schema

  • Example (auto)

Schema

success booleanrequired

Success status

Example:true

message stringrequired

Response message

Example:Agent updated successfully

data objectrequired

Updated agent or version data

Example:{"agentId":"p1q2r3s4t5u6v7w8x9y0z1a2","versionId":"v1a2b3c4d5e6f7g8h9i0","name":"Updated Customer Support Agent","description":"Updated AI agent with enhanced customer support capabilities","status":"active","updatedAt":"2024-02-27T11:45:00.000Z"}

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "agentId": "p1q2r3s4t5u6v7w8x9y0z1a2",
    "versionId": "v1a2b3c4d5e6f7g8h9i0",
    "name": "Updated Customer Support Agent",
    "description": "Updated AI agent with enhanced customer support capabilities",
    "status": "active",
    "updatedAt": "2024-02-27T11:45:00.000Z"
  }
}

Bad Request

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:400

message string

Example:Bad Request

{
  "statusCode": 400,
  "message": "Bad Request"
}

Unauthorized

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:401

message string

Example:Invalid token: access token is invalid

error string

Example:Unauthorized

{
  "statusCode": 401,
  "message": "Invalid token: access token is invalid",
  "error": "Unauthorized"
}

Version not found

Unprocessable Entity

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:422

message string[]

Example:["Unprocessable Entity"]

error string

Example:Unprocessable Entity

{
  "statusCode": 422,
  "message": [\
    "Unprocessable Entity"\
  ],
  "error": "Unprocessable Entity"
}

Internal Server Error

  • application/json

  • Schema

  • Example (auto)

Schema

statusCode number

Example:500

message string

Example:Internal Server Error

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Authorization: Authorization

name: Authorizationtype: httpscopes: agent-studio.writescheme: bearerbearerFormat: JWTin: headerdescription: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

  • curl

  • nodejs

  • python

  • php

  • java

  • go

  • ruby

  • powershell

  • CURL

curl -L -X PATCH 'https://services.leadconnectorhq.com/agent-studio/agent/versions/:versionId' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "versionName": "Customer Support Agent v2",
  "description": "Updated version with improved customer handling logic",
  "nodes": [\
    {\
      "nodeId": "node_1",\
      "nodeName": "Start",\
      "type": "start",\
      "isStartNode": true\
    },\
    {\
      "nodeId": "node_2",\
      "nodeName": "LLM Node",\
      "type": "llm",\
      "nodeConfig": {\
        "prompt": "How can I help you?",\
        "llmProvider": "openai",\
        "llmModel": "gpt-4"\
      }\
    }\
  ],
  "edges": [\
    {\
      "startNode": "node_1",\
      "endNode": "node_2"\
    }\
  ],
  "globalVariables": [\
    {\
      "key": "apiKey",\
      "type": "string",\
      "value": "your-api-key"\
    }\
  ],
  "inputVariables": [\
    {\
      "key": "customerName",\
      "type": "string",\
      "description": "Customer name for personalization"\
    }\
  ],
  "runtimeVariables": [\
    {\
      "key": "sessionId",\
      "type": "string",\
      "description": "Current session identifier"\
    }\
  ],
  "globalConfig": {
    "globalPrompt": {
      "currentPrompt": "You are a helpful customer support assistant.",
      "history": []
    }
  },
  "userId": "usr_abc123def456",
  "userName": "John Doe"
}'

Request Collapse all

Base URL

Edit

https://services.leadconnectorhq.com

Auth

Bearer Token

Parameters

versionId — pathrequired

Version — headerrequired

---2021-04-15

Show optional parameters

source — query

Body required

{
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "versionName": "Customer Support Agent v2",
  "description": "Updated version with improved customer handling logic",
  "nodes": [\
    {\
      "nodeId": "node_1",\
      "nodeName": "Start",\
      "type": "start",\
      "isStartNode": true\
    },\
    {\
      "nodeId": "node_2",\
      "nodeName": "LLM Node",\
      "type": "llm",\
      "nodeConfig": {\
        "prompt": "How can I help you?",\
        "llmProvider": "openai",\
        "llmModel": "gpt-4"\
      }\
    }\
  ],
  "edges": [\
    {\
      "startNode": "node_1",\
      "endNode": "node_2"\
    }\
  ],
  "globalVariables": [\
    {\
      "key": "apiKey",\
      "type": "string",\
      "value": "your-api-key"\
    }\
  ],
  "inputVariables": [\
    {\
      "key": "customerName",\
      "type": "string",\
      "description": "Customer name for personalization"\
    }\
  ],
  "runtimeVariables": [\
    {\
      "key": "sessionId",\
      "type": "string",\
      "description": "Current session identifier"\
    }\
  ],
  "globalConfig": {
    "globalPrompt": {
      "currentPrompt": "You are a helpful customer support assistant.",
      "history": []
    }
  },
  "userId": "usr_abc123def456",
  "userName": "John Doe"
}

Send API Request

ResponseClear

Click the Send API Request button above and see the response here!