Bot API rules and limits

Access rules

• The bot API is available only to users with role BOT
• Authorization uses Authorization: Bearer <token>
• If the token is valid but the user is not BOT, the API returns 403 Bot token required
• If the user is missing, the API returns 401 User not found
• If the token is invalid, the API returns 401 Invalid token
• If the token is expired, the API returns 401 Token has expired

The bot works only within the user's existing form access scope.
Create checks access by form_id.
Read and update check access by task.form_id.

Additional access rule:

• one bot can have access to at most 2 forms
• if it needs access to more forms, create another bot, issue a separate token, and grant that bot access to the required forms

Supported field types

• TextField
• TextareaField
• NumberField
• ChoiceField
• DateField
• DueDateField
• PhoneField
• EmailField
• FormField
• TableField

Notes:

• PATCH /bot/tasks/{task_id}/items/{form_field_id} updates a single item, so TableField is not updated through this endpoint
• Table child items support only: TextField, NumberField, ChoiceField, EmailField, PhoneField, DateField, DueDateField, FormField
• TextareaField is not allowed inside tables
• FilesField and TimeTrackerField are not currently supported and return 400 Unsupported field type for bot create: ...

Payload and file limits

• JSON payload:
  • create task: 128 KB
  • update item: 32 KB
• Upload file size:
  • 20 MB per file

If the JSON body is too large, the API returns 413 Payload too large. Max size is ... bytes.
If a file is too large, upload returns 400 File too large. Up to 20MB allowed.

Maximum counts

• participants_ids <= 5
• task_items <= 50
• files <= 10
• table rows <= 100
• row items <= 15

Typical validation errors include:

• participants_ids limit exceeded: 5
• task_items limit exceeded: 50
• files limit exceeded: 10
• table rows limit exceeded for field {form_field_id}: 100
• table row items limit exceeded: 15

Rate limits

• create: 30/min
• update item: 120/min
• upload: 10/min
• read: 300/min

When exceeded, the API returns 429 Rate limit exceeded. Retry after {seconds} seconds.

If the business needs higher throughput, the current implementation is better served by creating a second bot user and using a separate token.

Data validation

• TextField, EmailField, PhoneField, FormField: string up to 1 KB, null bytes are removed
• TextareaField: string up to 30 KB, null bytes are removed
• ChoiceField: only list or null
• NumberField: number or numeric string, normalized to DECIMAL(15,5), rounded to 5 digits
• DateField / DueDateField: must be a valid ISO datetime string

Validation messages include:

• value must be a string
• value must be a list or null
• choice values must contain only strings or null
• invalid numeric value: ...
• numeric value exceeds DECIMAL(15,5) max: 9999999999.99999
• value must be an ISO datetime string
• invalid datetime value: ...

Responsible users

For forms with steps:

• responsible_ids is required
• a bot user cannot be responsible
• only active non-BOT users with access to the form are accepted
• if no valid responsible users remain, the API returns 400 Responsible users are invalid for this form

For forms without steps, separate assignments are not required.

Common errors

• 403 Form access not found
• 400 responsible_ids is required for forms with steps
• 400 Responsible users are invalid for this form
• 400 Bot already has access to 2 forms. Create another bot or remove access from another form.
• 404 Form not found
• 404 Task not found
• 400 Form field {id} not found
• 404 Form field not found
• 400 Field {id} type mismatch: expected ..., got ...
• 400 Table child field {id} not found
• 400 Files not found: [...]
• 400 File extension is not allowed: ...
• 400 Invalid file content type for .ext: ...