Create Agent

Endpoint used to create an agent.

curl --request POST \
  --url https://chat.api.toolzz.com.br/api/v1/bot \
  --header 'Authorization: Bearer TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '
    {
    "name": "<string>",
    "description": "<string>",
    "tags": "<string>",
    "prompt": "<string>",
    "iconFileId": "uuid",
    "model": "<string>",
    "credentialId": "uuid",
    "safeMode": false,
    "messagesLimit": 123,
    "charactersLimit": 123,
    "genAIOrganization": "<string>",
    "analyticsCredentialId": "uuid",
    "whatsappCredentialId": "uuid",
    "instagramCredentialId": "uuid",
    "messengerCredentialId": "uuid",
    "unityId": "uuid",
    "hasAnalytics": true,
    "hasMonetization": true,
    "hasVoice": true,
    "hasPlugins": true,
    "hasTools": true,
    "hasMulti": true,
    "hasWhatsapp": true,
    "hasInstagram": true,
    "hasMessenger": true,
    "temperature": 123,
    "topP": 123,
    "presencePenalty": 123,
    "frequencyPenalty": 123,
    "tools": [
        {
            "type": "<string>",
            "description": "<string>"
        }
    ],
    "topK": 123,
    "messagesQuery": 123,
    "coin": "<string>",
    "price": 123,
    "timeTest": 123,
    "recurring": "<string>",
    "monetizationCredentialId": "uuid",
    "featuredProduct": true,
    "folder": [
        {
            "id": "uuid"
        }
    ]
}
'

Response Example

{
  "id": "uuid",
  "name": "<string>",
  "prompt": "<string>",
  "metaprompt": "<string>",
  "description": "<string>",
  "folders": [
    {
      "id": "uuid",
      "botId": "uuid",
      "folderId": "uuid",
      "kbId": "uuid",
      "kbFolder": {
        "isRoot": false,
        "id": "uuid",
        "institutionId": "uuid",
        "name": "<string>",
        "knowLedgeBaseId": "uuid"
      }
    }
  ],
  "plugins": [
    {
      "status": true,
      "id": "uuid",
      "botId": "uuid",
      "pluginId": "uuid",
      "plugin": {
        "status": true,
        "isActivated": true,
        "id": "uuid",
        "name": "<string>",
        "iconFileId": "uuid",
        "description": "<string>",
        "code": "<string>",
        "institutionId": "uuid",
        "userId": "uuid",
        "unityId": "uuid",
        "color": "<string>",
        "createdAt": "<string>",
        "type": "<string>",
        "googleCalendarPlugin": [
          {
            "id": "uuid",
            "googleId": "<string>",
            "calendarId": "<string>",
            "timezone": "<string>",
            "pluginId": "uuid",
            "notificationType": null,
            "notificationDelayMs": 123,
            "createdAt": "<string>",
            "updatedAt": "<string>",
            "googleUser": {
              "name": "<string>",
              "given_name": "<string>",
              "family_name": "<string>",
              "picture": "<string>",
              "email": "<string>",
              "hd": "<string>"
            },
            "googleToken": "<string>"
          }
        ]
      }
    }
  ],
  "botGenAI": [
    {
      "isDefault": true,
      "messagesLimit": 123,
      "charactersLimit": 123,
      "temperature": 123,
      "topP": 123,
      "frequencyPenalty": 123,
      "presencePenalty": 123,
      "topK": 123,
      "messagesQuery": 123,
      "id": "uuid",
      "botId": "uuid",
      "credentialId": "uuid",
      "analyticsCredentialId": "uuid",
      "model": "<string>",
      "credential": {
        "status": false,
        "id": "uuid",
        "name": "<string>",
        "userId": "uuid",
        "unityId": "uuid",
        "integrationId": "uuid",
        "secretId": "uuid",
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "virtualKey": "<string>",
        "integration": {
          "status": true,
          "id": "uuid",
          "name": "<string>",
          "type": "<string>",
          "iconId": "uuid",
          "slug": "<string>",
          "icon": {
            "id": "uuid",
            "institutionId": "uuid",
            "url": "<string>",
            "extension": "<string>",
            "size": 123
          }
        }
      }
    }
  ],
  "IconFile": {
    "id": "uuid",
    "institutionId": "uuid",
    "type": "<string>",
    "fileName": "<string>",
    "url": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "extension": "<string>",
    "size": 123
  },
  "tags": [
    "<string>"
  ],
  "unityId": "uuid",
  "institutionId": "uuid",
  "isActivated": true,
  "botMonetization": {
    "credentialId": "uuid",
    "price": 123,
    "timeTest": 123,
    "featuredProduct": false,
    "id": "uuid",
    "coin": "<string>",
    "recurring": "<string>",
    "credential": {
      "status": false,
      "id": "uuid",
      "name": "<string>",
      "userId": "uuid",
      "unityId": "uuid",
      "integrationId": "uuid",
      "secretId": "uuid"
    }
  },
  "botVoiceConfig": [
    {
      "visualType": "<string>",
      "language": "<string>",
      "primaryColor": "<string>",
      "buttonColor": "<string>",
      "theme": "<string>",
      "textTitle": "<string>",
      "textDescription": "<string>",
      "waitTime": 123,
      "callTime": 123,
      "id": "uuid",
      "botId": "uuid",
      "voiceId": "<string>",
      "voiceCredentialId": "uuid",
      "visualIconId": "uuid",
      "insertedLabsId": "<string>",
      "voiceModel": "<string>",
      "visualIcon": {
        "id": "uuid",
        "institutionId": "uuid",
        "fileName": "<string>",
        "url": "<string>",
        "size": 123
      },
      "voiceCredential": {
        "id": "uuid",
        "name": "<string>",
        "userId": "uuid",
        "unityId": "uuid",
        "integrationId": "uuid",
        "secretId": "uuid"
      }
    }
  ],
  "botMultiAgents": [
    {
      "id": "uuid",
      "botId": "uuid",
      "promptFlow": "<string>",
      "agentIds": [
        "uuid"
      ],
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ]
  "favorites": [],
  "botFallBack": []
}

---

Request description

Access Token

Parameter	Type	Description	Required
Authorization	String	Access token (“Bearer” must be before the token)	Yes

Body Parameters

Parameter	Type	Description	Required
unityId	UUID	Organizational unit identifier.	Yes
name	String	Bot identification name.	Yes
description	String	Brief description of the agent’s purpose.	Yes
tags	String	Tags for categorization (e.g., #agent).	No
prompt	String	System Prompt with instructions and AI personality.	Yes
iconFileId	UUID	Icon image file identifier.	No
model	String	Language model to be used (e.g., gpt-4o).	Yes
credentialId	UUID	ID of the integration credential with the AI provider.	Yes
safeMode	Boolean	Enables or disables content security filters.	No
messagesLimit	Number	Message limit per interaction.	No
charactersLimit	Number	Character limit per response sent.	No
hasAnalytics	Boolean	Enables the use of Toolzz Analytics.	No
hasMonetization	Boolean	Enables billing and subscription functions.	No
hasVoice	Boolean	Enables voice interaction functionality.	No
hasPlugins	Boolean	Allows the use of external plugins.	No
hasTools	Boolean	Allows the use of internal tools (Scraping, etc.).	No
temperature	Number	Level of creativity/randomness (0.0 to 1.0).	No
topP	Number	Core sampling control.	No
presencePenalty	Number	Penalty for repeating topics.	No
frequencyPenalty	Number	Penalty for repeating words.	No
topK	Number	Vocabulary limit for the K most probable words.	No
messagesQuery	Number	Number of contextual messages per query.	No
tools	Array	List of objects containing type and description of the tools.	No
coin	String	Currency code for monetization (e.g., brl).	No
price	Number	Value charged for bot use.	No
recurring	String	Billing recurrence period (e.g., month).	No
monetizationCredentialId	UUID	ID of the payment provider credential (e.g., Stripe).	No
featuredProduct	Boolean	Defines if the bot appears as a featured product.	No
folder	Array	List of objects with the id (UUID) of knowledge folders.	No

---

Response description

Key	Type	Description	Required
id	UUID	Unique identifier of the created Bot.	Yes
name	String	Bot name returned by the system.	Yes
prompt	String	Behavior and personality instructions (System Prompt).	Yes
metaprompt	String	System control instructions and AI limitations.	Yes
description	String	Brief description of the Bot’s functions.	Yes
isActivated	Boolean	Bot activation status (true/false).	Yes
unityId	UUID	Linked organizational unit identifier.	Yes
institutionId	UUID	Owning institution identifier.	Yes
fallbackPhrase	String	Safety phrase sent when the AI does not find an answer.	No
folders	Array	List of linked folders and knowledge bases (RAG).	Yes
plugins	Array	Active integration plugins (e.g., Google Calendar).	Yes
botGenAI	Array	Generative model settings (temperature, tokens, etc.).	Yes
IconFile	Object	Metadata and URL of the Bot’s icon image.	Yes
tags	Array	List of search tags associated with the Bot.	No
botMonetization	Object	Pricing rules, currency, and recurrence.	No
botVoiceConfig	Array	Voice settings, audio widget colors, and provider.	No
botMultiAgents	Array	Flow and transition rules between different agents.	No
botFallBack	Array	List of agents configured for automatic overflow.	No
favorites	Array	List of identifiers of users who favorited the Bot.	No

---

Security

To access this endpoint, it is necessary to send a valid access token through the authorization header (Authorization) of the request. Additionally, the API is protected by other security measures to safeguard user data.

To access your access token, follow these steps:

1. Log in to the ToolzzAI platform
2. Click on “Settings”
3. Click on “Access Token”
4. Copy the access token