> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiployees.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Създаване на инструмент за време на повикване

> Създаване на нов инструмент за време на повикване

Този endpoint ви позволява да създадете нов инструмент за време на повикване, който може да бъде използван от вашите AI асистенти за взаимодействие с външни API по време на повиквания.

### Параметри в тялото на заявката

<ParamField body="name" type="string" required>
  Име на инструмента - трябва да съдържа само малки букви и долни черти, и да започва с буква (например, `get_weather`, `book_appointment`)
</ParamField>

<ParamField body="description" type="string" required>
  Подробно обяснение кога и как AI трябва да използва този инструмент (максимум 255 символа)
</ParamField>

<ParamField body="endpoint" type="string" required>
  Валиден URL на API endpoint за извикване
</ParamField>

<ParamField body="method" type="string" required>
  HTTP метод: `GET`, `POST`, `PUT`, `PATCH`, или `DELETE`
</ParamField>

<ParamField body="timeout" type="integer" optional>
  Timeout на заявката в секунди (1-30, по подразбиране: 10)
</ParamField>

<ParamField body="headers" type="array" optional>
  HTTP headers за изпращане с заявката

  <Expandable title="свойства на headers">
    <ParamField body="name" type="string" required>
      Име на header
    </ParamField>

    <ParamField body="value" type="string" required>
      Стойност на header
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="schema" type="array" optional>
  Параметри, които AI ще извлече от разговора и ще изпрати до endpoint

  <Expandable title="свойства на schema">
    <ParamField body="name" type="string" required>
      Име на параметър (2-32 символа, трябва да започва с буква, може да съдържа букви и долни черти)
    </ParamField>

    <ParamField body="type" type="string" required>
      Тип на параметър: `string`, `number`, или `boolean`
    </ParamField>

    <ParamField body="description" type="string" required>
      Описание за да помогне на AI да разбере как да извлече този параметър (3-255 символа)
    </ParamField>
  </Expandable>
</ParamField>

### Полета в отговора

<ResponseField name="message" type="string">
  Съобщение за успех
</ResponseField>

<ResponseField name="data" type="object">
  Обектът на създадения инструмент

  <Expandable title="свойства на data">
    <ResponseField name="id" type="integer">
      Уникалният идентификатор на инструмента
    </ResponseField>

    <ResponseField name="name" type="string">
      Името на инструмента
    </ResponseField>

    <ResponseField name="description" type="string">
      Описание на инструмента
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      URL на API endpoint
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP метод
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Timeout на заявката в секунди
    </ResponseField>

    <ResponseField name="headers" type="array">
      HTTP headers
    </ResponseField>

    <ResponseField name="schema" type="array">
      Схема на параметрите
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Tool created successfully",
    "data": {
      "id": 1,
      "name": "check_order_status",
      "description": "Use this tool to check the status of a customer's order.",
      "endpoint": "https://api.yourstore.com/orders/status",
      "method": "GET",
      "timeout": 10,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer sk_..."
        }
      ],
      "schema": [
        {
          "name": "order_id",
          "type": "string",
          "description": "The customer's order ID"
        },
        {
          "name": "order_number",
          "type": "number",
          "description": "The numeric order number"
        },
        {
          "name": "priority_order",
          "type": "boolean",
          "description": "Whether this is a priority order"
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T12:00:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The name field must contain only lowercase letters and underscores, and start with a letter.",
    "errors": {
      "name": [
        "Tool name must contain only lowercase letters and underscores, and start with a letter."
      ]
    }
  }
  ```

  ```json 422 Plan Limit Reached theme={null}
  {
    "message": "You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools."
  }
  ```
</ResponseExample>

### Прикачване на инструменти към асистенти

След създаването на инструмент, трябва да го прикачите към асистент за да го използвате по време на повиквания. Инструментите се управляват чрез Assistant API:

* **[Създаване на асистент](/api-reference/assistants/create-assistant)** - Използвайте параметъра `tool_ids` за да прикачите инструменти при създаване на асистент
* **[Актуализиране на асистент](/api-reference/assistants/update-assistant)** - Използвайте параметъра `tool_ids` за да добавите, премахнете или заместите инструменти на съществуващ асистент