List employees in the Upservice account.

Args: params (ListEmployeesInput): - limit (Optional[int]): Page size, 1-100 (default 25) - offset (Optional[int]): Items to skip for pagination (default 0)

Returns: str: JSON array/object of employees as returned by the Upservice API (fields typically include id, first_name, last_name, email, position, department).

Error Handling: Returns "Error: ..." with an actionable message on failure (see error codes below).

List projects in the Upservice account.

Args: params (ListProjectsInput): limit (1-100, default 25), offset (default 0), status, tags_condition, tags_ids

Returns: str: JSON list of projects (id, title, managers, members, completed, etc.)

Create a new project in Upservice.

Args: params (CreateProjectInput): - title (str): Project title - managers (List[int]): Employee IDs to assign as project managers - members (List[int]): Employee IDs to assign as project members - extra_fields (Optional[dict]): Extra raw JSON fields to merge into the body

Returns: str: JSON of the created project record.

Retrieve a single project by ID.

Args: params (ProjectIdInput): project_id (int)

Returns: str: JSON of the project record, or "Error: Resource not found (404)" if it doesn't exist.

Update an existing project's fields (e.g. title).

Args: params (UpdateProjectInput): project_id (int), title (optional str), extra_fields (optional dict)

Returns: str: JSON of the updated project record.

Permanently delete a project. This is a destructive operation and cannot be undone.

Args: params (ProjectIdInput): project_id (int)

Returns: str: JSON confirmation, or "Error: ..." on failure.

Replace the full set of managers for a project.

Note: this REPLACES the existing manager list, it does not append to it.

Args: params (SetProjectEmployeesInput): project_id (int), employees (List[int], the new full manager list)

Returns: str: JSON confirmation/updated manager list.

Replace the full set of members/guests for a project.

Note: this REPLACES the existing membership list, it does not append to it.

Args: params (SetProjectEmployeesInput): project_id (int), employees (List[int], the new full member list)

Returns: str: JSON confirmation/updated member list.

Mark a project as completed.

Args: params (ProjectIdInput): project_id (int)

Returns: str: JSON of the updated project record.

List sprints, optionally filtered by project.

Args: params (ListSprintsInput): limit, offset, project (optional list of IDs), status (optional list), is_lag (optional bool)

Returns: str: JSON list of sprints.

Create a new sprint under a project.

Args: params (CreateSprintInput): title, project (int), date_start (YYYY-MM-DD), date_end (YYYY-MM-DD), extra_fields (optional dict)

Returns: str: JSON of the created sprint.

Retrieve a single sprint by ID.

Args: params (SprintIdInput): sprint_id (int)

Returns: str: JSON of the sprint record.

Update a sprint's title or dates.

Args: params (UpdateSprintInput): sprint_id (int), title/date_start/date_end (all optional), extra_fields (optional dict)

Returns: str: JSON of the updated sprint.

Permanently delete a sprint. This is a destructive operation.

Args: params (SprintIdInput): sprint_id (int)

Returns: str: JSON confirmation, or "Error: ..." on failure.

Mark a sprint as completed.

Args: params (SprintIdInput): sprint_id (int)

Returns: str: JSON of the updated sprint.

Activate a sprint (start it).

Args: params (SprintIdInput): sprint_id (int)

Returns: str: JSON of the updated sprint.

Add one or more existing tasks to a sprint.

Args: params (AddTasksToSprintInput): sprint_id (int), tasks (List[int] of task IDs)

Returns: str: JSON list of task IDs now in the sprint.

List tags defined in the Upservice account, optionally filtered by a search query.

Args: params (ListTagsInput): limit, offset, query (optional str)

Returns: str: JSON list of tags (id, name, color, type).

Create a new tag definition.

Args: params (CreateTagInput): name (str), color (optional str), type (optional: text|number|address|date|richard)

Returns: str: JSON of the created tag, including its UUID.

Update an existing tag's name or color.

Args: params (UpdateTagInput): tag_id (UUID str), name (optional), color (optional)

Returns: str: JSON of the updated tag.

Permanently delete a tag definition (removing it from all entities it was applied to).

Args: params (UpdateTagInput): only tag_id is used (UUID str)

Returns: str: JSON confirmation, or "Error: ..." on failure.

Assign (attach) a tag to an entity such as a task, chat, asset, contact, or attachment.

Args: params (AssignTagInput): tag_id (UUID), entity_id (UUID or int), entity_type (enum)

Returns: str: JSON confirmation of the assignment.

Remove (detach) a tag from an entity.

Args: params (AssignTagInput): tag_id (UUID), entity_id (UUID or int), entity_type (enum)

Returns: str: JSON confirmation, or "Error: ..." on failure.

List/search tasks with optional filters for kind, project, author, responsible, date ranges, and tags.

CONFIRMED LIMITATION (verified against the live API, not just the OpenAPI spec): this endpoint has no status/status_in/is_completed/completed/query filter. Passing any of those as extra query params is silently ignored server-side (no error, no effect on results) — status filtering must be done client-side on the returned status field. There is no workaround on the Upservice API today; this has been reported to Upservice as a feature request. Until it lands, narrow results with date_end_gte/date_end_lte (due-date range) plus project/author/responsible BEFORE paginating and filtering by status client-side — e.g. for "open overdue tasks", pass date_end_lte=<now, ISO 8601> together with project/responsible to get a small candidate set, then drop any whose status is completed/cancelled/rejected/deleted. Do not call this with only author (or no filters) and try to page through everything — accounts can have 100k+ tasks and completed_at/date filters are the only server-side way to keep that bounded.

Args: params (ListTasksInput): limit, offset, kind, project, author, responsible, created_at_gte/lte, completed_at_gte/lte, date_start_gte/lte, date_end_gte/lte, tags_ids, tags_condition (all optional except pagination defaults)

Returns: str: JSON list of tasks matching the filters.

Create a new task (or meeting/agreement/ticket, depending on kind).

Args: params (CreateTaskInput): title, kind, description, project, sprint, responsible, responsible_departments, estimation (minutes), date_start, date_end, file_list, mentions, extra_fields

Returns: str: JSON of the created task record, including its ID.

Examples: - "Create a task 'Fix login bug' in project 42, due 2026-08-01" -> title="Fix login bug", project=42, date_end="2026-08-01T00:00:00Z" - "Create a task and mention Ivan (employee_id 115768) in the description" -> description="cc {{115768}}", mentions=[{"employee_id": 115768, "display_name": "Ivan Ivanov"}]

Retrieve full details for a single task by ID.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON of the task record.

Partially update a task's fields (title, description, dates, responsible, etc).

Only fields you provide are changed; omitted fields are left unchanged.

Args: params (UpdateTaskInput): task_id (int) plus any fields to change, mentions (for description), and extra_fields for anything not explicitly modeled

Returns: str: JSON of the updated task record.

Permanently delete a task. This is a destructive operation and cannot be undone.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON confirmation, or "Error: ..." on failure.

List file attachments on a task.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON list of attachments (id, filename, url, etc. - use upservice_get_file_url for a fresh download link).

Change a task's status (e.g. mark as completed, cancelled, in progress).

Args: params (UpdateTaskStatusInput): task_id (int), status (enum), reason (optional str, needed for cancel/reject)

Returns: str: JSON of the updated task.

Set the planned-effort estimate for a task, in minutes.

Args: params (UpdateTaskEstimationInput): task_id (int), estimation (int, minutes)

Returns: str: JSON of the updated task.

Log actual effort (worklog) spent on a task, in minutes.

Args: params (UpdateTaskWorklogInput): task_id (int), value (int, minutes of actual effort)

Returns: str: JSON of the updated task/worklog.

Advance an agreement/approval workflow step on a task: progress it, approve it, or reject it.

Args: params (AgreementActionInput): task_id (int), action (progress|approved|rejected), rejection_reason (required if action='rejected'), date_end (optional, used with 'progress')

Returns: str: JSON of the updated agreement state.

List the approval/agreement steps and their statuses for a task.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON list of agreement steps.

List the co-responsible employees assigned to a task.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON list of co-responsible employees.

Get the agreement sheet (approval status and attachments) for a task.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON with status and attachments for the agreement.

Get the acquaintance sheet (who has read/acknowledged) for a task of kind 'acquaintance'.

Args: params (TaskIdInput): task_id (int)

Returns: str: JSON with acknowledgement status per employee.

List custom directories (reference catalogs, e.g. assets, contacts) defined in the account.

Note: this endpoint has no pagination in the Upservice API; it returns all matching directories.

Args: params (ListDirectoriesInput): parent, search, id, manager (all optional)

Returns: str: JSON list of directories.

Create a new custom directory (reference catalog).

Args: params (CreateDirectoryInput): title, manager_id (int), parent_id (optional int)

Returns: str: JSON of the created directory.

Retrieve a single directory by ID.

Args: params (DirectoryIdInput): directory_id (int)

Returns: str: JSON of the directory record.

Update a directory's title or manager.

Args: params (UpdateDirectoryInput): directory_id (int), title (optional), manager_id (optional)

Returns: str: JSON of the updated directory.

Permanently delete a directory (and, depending on account settings, its records). Destructive operation.

Args: params (DirectoryIdInput): directory_id (int)

Returns: str: JSON confirmation, or "Error: ..." on failure.

List records within directories, optionally filtered to one or more directories.

Args: params (ListDirectoryRecordsInput): limit, offset, category, responsible, creator, search, id, tags_ids, tags_condition, date_end_gte/lte, is_subscribed (all optional)

Returns: str: JSON list of directory records.

Create a new record within a directory (e.g. an asset or contact entry).

Args: params (CreateDirectoryRecordInput): title, category (directory ID), responsible (employee ID), description (optional), inventory_number (optional), extra_fields (optional dict)

Returns: str: JSON of the created record.

Retrieve a single directory record by ID.

Args: params (RecordIdInput): record_id (int)

Returns: str: JSON of the record.

Partially update a directory record's fields.

Only fields you explicitly pass are sent — an omitted field is left unchanged, while an explicit null (e.g. responsible=null) is sent as-is and clears that field server-side.

Args: params (UpdateDirectoryRecordInput): record_id (int) plus any fields to change, extra_fields for the rest

Returns: str: JSON of the updated record.

Permanently delete a directory record. Destructive operation.

Args: params (RecordIdInput): record_id (int)

Returns: str: JSON confirmation, or "Error: ..." on failure.

List the entities (tasks, orders, projects, etc.) linked/related to a directory record.

Args: params (RecordIdInput): record_id (int)

Returns: str: JSON list of related entities, grouped by relation type.

Add or remove multiple links between a directory record and other entities (tasks, projects, orders, etc.) in one call.

Args: params (BulkUpdateRelationsInput): record_id (int), relations (list of {rel_type, relation_ids, is_delete})

Returns: str: JSON confirmation of the applied relation changes.

Load messages from one or more Upservice chat rooms.

Args: params (ListChatMessagesInput): chat_uuids (required list), channel_id (required), limit, offset, thread_ids, language, sender_id, message_kind (all optional)

Returns: str: JSON list of messages.

Get messages for a specific chat room within a specific channel.

Args: params (GetChatMessagesInput): channel_unique_identifier (str), room_uuid (str), limit, offset

Returns: str: JSON list of messages in that room.

Create a new external/inbound message (e.g. from an external channel integration).

Args: params (SendMessageInput): content (str), message_id (optional UUID str), mentions (optional)

Returns: str: JSON of the created message.

Create a new message directly in a channel (not tied to a specific chat room).

Args: params (SendChannelMessageInput): channel_unique_identifier (str), content (str), message_id, first_name, last_name, email, phone, mentions (all optional), extra_fields (optional dict)

Returns: str: JSON of the created message.

Send a message into a specific chat room within a channel.

Args: params (SendChatMessageInput): channel_id (str), room_uuid (str), content (str), message_id (optional), mentions (optional)

Returns: str: JSON of the sent message.

Get a fresh, time-limited download URL for a file/attachment.

Args: params (FileIdInput): file_id (str)

Returns: str: JSON containing the file's download URL.

Upload a local file to Upservice (e.g. to attach it to a task via its returned file ID).

Args: params (UploadFileInput): file_path (absolute local path)

Returns: str: JSON of the uploaded file record, including its ID.

Upload a local file to an external channel in Upservice.

Args: params (UploadFileToChannelInput): channel_unique_identifier (str), file_path (absolute local path)

Returns: str: JSON of the uploaded file record, including its ID.

Get a fresh, time-limited download URL for a file/attachment scoped to an external channel.

Args: params (ChannelFileIdInput): channel_unique_identifier (str), file_id (str)

Returns: str: JSON containing the file's download URL.