Skip to main content

Agents

API endpoints related to managing Agents. Agents are AI-powered virtual representatives that handle conversations with your customers using the knowledge and personality you define. Agents are linked to an Organization.

Note: These endpoints require an API key scoped to the organization in the path. Requests made with an API key that belongs to a different organization return 401 Unauthorized.

Get Agents​

Retrieves all agents for a given organization.

GET /v1/organizations/{organizationId}/agents

Path Parameters:

  • organizationId (string, required): The unique identifier of the organization.

Headers:

  • x-api-key (string, required): Your API key for authentication.

Response:

  • 200 OK: Agents retrieved successfully. 
    {
      "message": "Successfully retrieved organization agents",
      "data": [
        {
          "id": "agent_123abc",
          "name": "Sales Representative",
          "knowledgeBase": [
            {
              "id": "kb_123abc",
              "name": "Product Knowledge",
              "url": "https://example.com/kb/products",
              "usageMode": "auto"
            }
          ],
          "firstMessage": "Thanks for calling Example Solutions Inc., how may I assist you today?",
          "specificQuestions": ["What are your business hours? What services do you offer?"],
          "maxDurationSeconds": 300,
          "isOverviewTrainingEnabled": true,
          "voiceId": "cjVigY5qzO86Huf0OWal",
          "shouldTakeMessage": false,
          "createdAt": 1698407100000,
          "updatedAt": 1698407100000
        }
      ]
    }
  • 400 Bad Request: Invalid or expired API key.
  • 404 Not Found: Organization not found.

Try it yourself​

GET/v1/organizations/{organizationId}/agents
Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/agents

Get Agent By ID​

Retrieves details for a specific agent.

GET /v1/organizations/{organizationId}/agents/{agentId}

Path Parameters:

  • organizationId (string, required): The unique identifier of the organization.
  • agentId (string, required): The unique identifier of the agent.

Headers:

  • x-api-key (string, required): Your API key for authentication.

Response:

  • 200 OK: Agent details retrieved successfully. 
    {
      "message": "Successfully retrieved organization agent",
      "data": {
        "id": "agent_123abc",
        "name": "Sales Representative",
        "knowledgeBase": [
          {
            "id": "kb_123abc",
            "name": "Product Knowledge",
            "url": "https://example.com/kb/products",
            "usageMode": "auto"
          }
        ],
        "firstMessage": "Thanks for calling Example Solutions Inc., how may I assist you today?",
        "specificQuestions": ["What are your business hours? What services do you offer?"],
        "maxDurationSeconds": 300,
        "isOverviewTrainingEnabled": true,
        "voiceId": "cjVigY5qzO86Huf0OWal",
        "shouldTakeMessage": false,
        "createdAt": 1698407100000,
        "updatedAt": 1698407100000
      }
    }
  • 400 Bad Request: Invalid or expired API key.
  • 404 Not Found: Agent or organization not found.

Try it yourself​

GET/v1/organizations/{organizationId}/agents/{agentId}
Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/agents/{agentId}

Update Agent​

Updates details for an existing agent within a specific organization.

PATCH /v1/organizations/{organizationId}/agents/{agentId}

Path Parameters:

  • organizationId (string, required): The unique identifier of the organization the agent belongs to.
  • agentId (string, required): The unique identifier of the agent to update.

Headers:

  • Content-Type (string, required): Must be set to application/json.
  • x-api-key (string, required): Your API key for authentication.

Request Body:

{
  "name": "Updated Sales Representative",
  "knowledgeBase": [
    {
      "id": "kb_123abc",
      "name": "Product Knowledge",
      "url": "https://example.com/kb/products"
    }
  ],
  "firstMessage": "Thanks for calling Example Solutions Inc., how may I assist you today?",
  "specificQuestions": "What are your business hours? What services do you offer?",
  "maxDurationSeconds": 300,
  "isOverviewTrainingEnabled": true,
  "voiceId": "cjVigY5qzO86Huf0OWal"
}

Field Notes:

  • All fields are optional — include only what you want to change.
  • knowledgeBase (array, optional): Replaces the agent's knowledge base list wholesale. Every entry requires id, name, and url, and every id must reference an existing knowledge base document.
  • specificQuestions (string or array of strings, optional): Replaces the question list. A legacy free-form string is preserved as a single array entry; pass an array for individual questions or [] to clear the list. Responses return the stored array.
  • maxDurationSeconds (number, optional): Positive integer.

Response:

  • 200 OK: Agent updated successfully. 
    {
      "message": "Successfully updated organization agent",
      "data": {
        "id": "agent_123abc",
        "name": "Updated Sales Representative",
        "knowledgeBase": [
          {
            "id": "kb_123abc",
            "name": "Product Knowledge",
            "url": "https://example.com/kb/products",
            "usageMode": "auto"
          }
        ],
        "firstMessage": "Thanks for calling Example Solutions Inc., how may I assist you today?",
        "specificQuestions": ["What are your business hours? What services do you offer?"],
        "maxDurationSeconds": 300,
        "isOverviewTrainingEnabled": true,
        "voiceId": "cjVigY5qzO86Huf0OWal",
        "shouldTakeMessage": false,
        "createdAt": 1697000000000,
        "updatedAt": 1698405000000
      }
    }
  • 400 Bad Request: Invalid input data, invalid API key, or one or more knowledgeBase ids do not reference an existing knowledge base document.
  • 404 Not Found: Organization or Agent with the specified IDs not found.

Try it yourself​

PATCH/v1/organizations/{organizationId}/agents/{agentId}
Request URL: https://api.askbenny.ca/v1/organizations/{organizationId}/agents/{agentId}