` nodes with a `fileId` attribute (UUID) and `filename`. Images are **not** inlined as base64 in this API response.\n\n**Downloading embedded binaries for display or AI vision:** Use HTTP GET on the Leadtime **web application** origin (not the Public API base path): `/api/files/public/{fileId}`. Optional resized images: `/api/files/public/{fileId}/{maxWidth}` (and height if supported). The same `/api/files/public/...` pattern appears in other API responses (e.g. workspace upload, logos). Integrations and agents should parse `fileId` from the HTML, then fetch those URLs when they need to read image or file content.","operationId":"TasksController_getTaskDetails","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}}],"responses":{"200":{"description":"Task details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailsResponseDto"}}}},"400":{"description":"Invalid identifier format (not UUID and not numeric)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get task details by UUID or shortNumber","tags":["tasks","common-lists"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates an existing task with partial data. Only provided fields will be updated, allowing you to modify specific properties without affecting others. The identifier can be either a UUID or a numeric short number (with or without # prefix). When updating the description, HTML or Markdown format is accepted and will be converted to the internal editor format. Changing the task type automatically updates the status if needed. Changing the project cascades to subtasks and time logs. Description mentions trigger notifications to mentioned users. Requires Tasks.editAnyTitleAndDescription permission. Organization members can only update tasks with guestAccess enabled.","operationId":"TasksController_patchTask","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or short number (e.g., \"550e8400-e29b-41d4-a716-446655440000\" or \"123\" or \"#123\")","schema":{"example":"123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchTaskDto"}}}},"responses":{"200":{"description":"Task updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailsResponseDto"}}}},"400":{"description":"Invalid request data or validation error"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Access denied: No project access or permission denied"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update a task","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a task by its UUID or numeric shortNumber identifier. The task is marked as deleted but remains in the database for historical purposes. Access is controlled by Tasks.delete permission and project access. Billed tasks cannot be deleted to maintain billing integrity. Parent/subtask relationships are handled automatically - removing a parent task does not delete its subtasks, but removes the parent-child relationship. Organization members can only delete tasks with guestAccess enabled.","operationId":"TasksController_deleteTask","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid identifier format (not UUID and not numeric) or task is billed"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Access denied: No Tasks.delete permission, no project access, or OrganizationMember accessing non-guest task"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete task by UUID or shortNumber","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/tasks/{identifier}/duplicate":{"post":{"description":"Creates a copy of an existing task in the same project. The duplicated task keeps the source task configuration such as type, status, description, priority, assignee, accountable person, tags, custom fields, guest access, and task products. The new task title gets a ` (Copy)` suffix. Accepts either a UUID or a numeric short number (with or without `#` prefix). Organization members can only duplicate tasks with guest access enabled.","operationId":"TasksController_duplicateTask","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or short number (e.g., \"550e8400-e29b-41d4-a716-446655440000\" or \"123\" or \"#123\")","schema":{"example":"123","type":"string"}}],"responses":{"201":{"description":"Task duplicated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailsResponseDto"}}}},"400":{"description":"Invalid identifier format (not UUID and not numeric)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Access denied: Missing Tasks.create permission, no project access, or OrganizationMember accessing a non-guest task"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Duplicate a task","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/tasks/{identifier}/comments":{"post":{"description":"Creates a new comment on a task. Comments are used for ongoing communication between participants and can be marked as internal (visible only to team members) or public (visible to guest users). The comment body accepts HTML or Markdown format and will be converted to the internal editor format. You can optionally update the task assignee, change the status, or log time in the same request. Mentions in comments (using @username) trigger notifications to mentioned users. Access is controlled by Tasks.addComments permission, project permissions, and guest access settings. Organization members can only comment on tasks with guestAccess enabled.","operationId":"TasksController_addComment","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTaskCommentDto"}}}},"responses":{"201":{"description":"Comment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCommentResponseDto"}}}},"400":{"description":"Invalid identifier format or validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add comment to task","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/tasks/{identifier}/comments/{commentId}":{"patch":{"description":"Updates the body of an existing task comment. Only the comment author can edit their own comment - this ensures comment integrity and prevents unauthorized modifications. The task identifier can be either a UUID or a numeric shortNumber. The comment body can be provided in HTML or Markdown format and will be converted to the internal editor format. The updated comment retains its original creation timestamp, author, and guest access settings.","operationId":"TasksController_updateTaskComment","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}},{"name":"commentId","required":true,"in":"path","description":"Comment UUID","schema":{"example":"aa0e8400-e29b-41d4-a716-446655440005","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskCommentDto"}}}},"responses":{"200":{"description":"Comment updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCommentResponseDto"}}}},"400":{"description":"Invalid identifier format, invalid comment data, or task not editable"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Not comment author, no project access, or OrganizationMember accessing non-guest task"},"404":{"description":"Task or comment not found, or comment already deleted"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update task comment","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a task comment. The comment is marked as deleted but remains in the database for historical purposes. Comment authors can always delete their own comments. Users with Tasks.deleteAnyComment permission can delete any comment, allowing moderators to remove inappropriate content. The task identifier can be either a UUID or a numeric shortNumber. Access is controlled by project permissions and guest access settings.","operationId":"TasksController_deleteTaskComment","parameters":[{"name":"identifier","required":true,"in":"path","description":"Task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}},{"name":"commentId","required":true,"in":"path","description":"Comment UUID","schema":{"example":"aa0e8400-e29b-41d4-a716-446655440005","type":"string"}}],"responses":{"200":{"description":"Comment deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid identifier format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Not comment author and no Tasks.deleteAnyComment permission, no project access, or OrganizationMember accessing non-guest task"},"404":{"description":"Task or comment not found, or comment already deleted"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete task comment","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/tasks/{identifier}/subtasks":{"post":{"description":"Adds an existing task as a subtask to the specified parent task. Subtasks allow you to break down complex tasks into smaller, more manageable units with clear assignments and better tracking. Each subtask works like its own ticket with its own description, assignee, priority, and status. The parent task identifier can be either a UUID or a numeric shortNumber. The subtask must exist and be accessible to the user. Requires Tasks.editAnyTitleAndDescription permission.","operationId":"TasksController_addSubtask","parameters":[{"name":"identifier","required":true,"in":"path","description":"Parent task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSubtaskDto"}}}},"responses":{"200":{"description":"Subtask added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailsResponseDto"}}}},"400":{"description":"Invalid identifier format or validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Access denied: No access to project or task not editable"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add a subtask to a task","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/tasks/{identifier}/subtasks/{subtaskId}":{"delete":{"description":"Removes the parent-child relationship between a task and its subtask by setting the subtask parentTaskId to null. The subtask itself is not deleted - it becomes a standalone task again. This is useful when reorganizing task hierarchies or when a subtask needs to be promoted to a main task. The parent task identifier can be either a UUID or a numeric shortNumber. The subtaskId must be a valid UUID. Requires Tasks.editAnyTitleAndDescription permission.","operationId":"TasksController_removeSubtask","parameters":[{"name":"identifier","required":true,"in":"path","description":"Parent task UUID or numeric shortNumber","schema":{"example":"550e8400-e29b-41d4-a716-446655440000 or 123","type":"string"}},{"name":"subtaskId","required":true,"in":"path","description":"Subtask UUID to remove","schema":{"example":"550e8400-e29b-41d4-a716-446655440001","type":"string"}}],"responses":{"200":{"description":"Subtask removed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDetailsResponseDto"}}}},"400":{"description":"Invalid identifier format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Access denied: No access to project or task not editable"},"404":{"description":"Task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Remove a subtask from a task","tags":["tasks","common-lists"],"x-required-scopes":["api:write"]}},"/projects/{id}/billing-settings":{"get":{"description":"**What are Project Billing Settings?**\nProject billing settings define how invoices are created and structured for a specific project. These settings control invoice formatting, billing rules, default recipients, and support contingent (retainer) configurations.\n\n**What data is returned:**\n- **Invoice structure settings**: Whether to combine support and subscription invoices or split them separately\n- **Billing rules**: Whether bug tasks are billable\n- **Default invoice recipient**: The contact person from the customer organization who receives invoices\n- **Support contingent (retainer) configuration**: Monthly hour packages at fixed prices for recurring support/maintenance services\n- **Billing version snapshots**: Project versions used as the basis for invoicing (Single projects only)\n\n**Support Contingents (Retainers):**\nSupport contingents allow you to allocate monthly hour packages at a fixed price. They are perfect for recurring support, maintenance, or service tasks and get suggested automatically in invoice review. Unused hours can optionally be carried over to subsequent months.\n\n**Billing Versions:**\nFor Single projects, you can select which project version snapshot will be used as the basis for billing. This includes components, manual items, and products as agreed in that version. You can also optionally select a separate subscription billing version for products with recurring payments.\n\n**Permission requirements:**\nRequires Projects.seeAnyProject permission to view billing settings.","operationId":"ProjectBillingSettingsController_getBillingSettings","parameters":[{"name":"id","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Project billing settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProjectBillingSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found or user does not have access"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project billing settings","tags":["projects","project-settings","billing"],"x-required-scopes":["api:read"]},"patch":{"description":"**How to update billing settings:**\nThis endpoint allows partial updates to project billing settings. Only the fields you provide will be updated; all other fields remain unchanged. The endpoint automatically merges your partial update with the current settings.\n\n**Invoice structure options:**\n- **allowMixedBilling (true)**: Combined invoices - bill support efforts (by booked hours) and subscriptions on a single invoice\n- **allowMixedBilling (false)**: Split invoices - support invoices are generated separately from subscription invoices\n\n**Billing rules:**\n- **bugsAreBillable**: Set whether time spent on tasks with \"Bug\" activity can be billed to the customer\n\n**Default invoice recipient:**\n- **invoiceContactId**: Select a contact person from the customer organization (OrganizationMember ID). This person will be auto-filled when creating invoices, but can be changed during invoice creation. Set to null to remove the default recipient.\n\n**Billing version snapshots (Single projects only):**\n- **billingProjectSnapshotId**: Select which project version will be used as the basis for billing. Includes components, manual items, and products as agreed in that version.\n- **productsBillingProjectSnapshotId**: Optionally select a separate version for billing subscriptions independently of the project scope. If empty, the main billing version is used automatically.\n\n**Permission requirements:**\nRequires both Projects.edit AND Invoices.manage permissions to update billing settings.","operationId":"ProjectBillingSettingsController_updateBillingSettings","parameters":[{"name":"id","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectBillingSettingsDto"}}}},"responses":{"200":{"description":"Project billing settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid input - validation errors or missing required conditional fields"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Projects.edit or Invoices.manage permission"},"404":{"description":"Project not found or user does not have access"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update project billing settings","tags":["projects","project-settings","billing"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/component-details/{id}":{"get":{"description":"Returns full details of a component from a project component tree including all nested children and metadata. \n\n**What are Project Components?**\nProject components are reusable project templates that standardize recurring project types. They connect requirements management, cost calculation, and execution in one unified workflow. Each component contains items (Epics, Work Packages, Todo Lists, Test Suites) that define the project structure.\n\n**Project Components vs Library Components:**\n- **Project Components** (this endpoint): Belong to a specific project, contain live data (answers to questions, test case evaluations, todo completion status), and can be connected to tasks in the task management system.\n- **Library Components**: Workspace-wide reusable templates (projectId is null) that serve as blueprints. They can be imported into projects to create project component instances.\n\n**Response Format:**\nAll ProseMirror editor content (description, internalNote) is automatically converted to HTML format for easy consumption. The response includes the complete hierarchical structure with all nested items and their metadata.\n\n**Access Control:**\nOnly project components that belong to the specified project (component.projectId equals projectId) are accessible through this endpoint.","operationId":"ProjectComponentsController_getComponentDetails","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentDetailsResponseDto"}}}},"400":{"description":"Invalid projectId or component id format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions or no access to project"},"404":{"description":"Component not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project component details","tags":["projects","components","questions"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/components/tree":{"get":{"description":"Returns the complete hierarchical tree structure of components and their items for a specific project. Only non-deleted components and items are included in the response.\n\n**Component Tree Structure:**\nThe project tree organizes work into a clear hierarchy:\n- **Components**: Top-level containers that group related work packages. Examples include \"Website Development\", \"CRM Onboarding\", or \"E-commerce Setup\". Each component represents a major deliverable or project phase.\n- **Items**: Building blocks within components. Each item can be one of four types:\n - **Epic**: Major sections or phases that group related work packages around a common theme (e.g., \"Technical Implementation\", \"Design & Development\")\n - **Work Package**: Self-contained, clearly defined tasks that deliver tangible results (e.g., \"Set up hosting\", \"Design homepage layout\"). Work packages can have timeframes, questions, todos, and test cases.\n - **Todo List**: Checklists of sub-steps or checkpoints perfect for recurring processes, quality control, or project preparation (e.g., \"Kickoff Checklist\", \"Quality Control\")\n - **Test Suite**: Formal acceptance tests for project results. Contains multiple test cases with steps and expected results (e.g., \"Contact Form Tests\", \"SEO Review\")\n\n**Nesting and Relationships:**\nItems can be nested to any depth, allowing for complex project structures. Each Work Package can contain Questions (to capture customer requirements), Todos (checklist items that can be checked off), and Test Cases (individual test steps within a Test Suite).\n\n**Use Cases:**\nThis endpoint is ideal for displaying the complete project structure in a tree view, understanding project organization, and navigating the component hierarchy.","operationId":"ProjectComponentsController_getProjectTree","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Project component tree retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentLibraryTreeResponseDto"}}}},"400":{"description":"Invalid project ID format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get component tree for a specific project","tags":["projects","components","questions"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/components/item-details/{id}":{"get":{"description":"Returns complete details of a component item from a project component tree including all test cases, todos, questions, conditions, and nested children.\n\n**What are Component Items?**\nItems are the building blocks within components that structure the project work. Each item can be one of four types:\n- **Epic**: Major sections or phases that group related work packages around a common theme (e.g., \"Technical Implementation\", \"Design & Development\"). Epics help track project progress at a strategic level.\n- **Work Package**: Self-contained, clearly defined tasks that deliver tangible results (e.g., \"Set up hosting\", \"Design homepage\"). Work packages can have timeframes, questions, todos, and test cases attached.\n- **Todo List**: Checklists of sub-steps or checkpoints perfect for recurring processes, quality control, or project preparation (e.g., \"Kickoff Checklist\", \"Quality Control\"). Each todo item can be checked off individually.\n- **Test Suite**: Formal acceptance tests for project results (e.g., \"Contact Form Tests\", \"SEO Review\"). Contains multiple test cases with steps and expected results. The project is considered finished when all test cases pass.\n\n**Attached Resources:**\nEach item can have various resources attached:\n- **Questions**: Capture customer-specific requirements or project details in a structured way (e.g., \"Do you need e-commerce functionality?\"). Answers can automatically affect effort calculation and pricing.\n- **Todos**: Checklist items within a Work Package or Todo List. Each todo can be checked off individually, supports comments, and tracks completion status with timestamps.\n- **Test Cases**: Individual test steps within a Test Suite. Each test case has steps, expected results, and can be evaluated as Passed, Failed, or PassedWithReservations.\n- **Conditions**: Rules that control when items are visible or active based on answers, todo completion, or test case status.\n\n**Response Format:**\nAll ProseMirror editor content (description, internalNote, question descriptions, test case steps, etc.) is automatically converted to HTML format. The response includes the complete item structure with all nested children, making it easy to display the full item hierarchy.\n\n**Access Control:**\nOnly project component items that belong to components in the specified project (component.projectId equals projectId) are accessible through this endpoint.","operationId":"ProjectComponentsController_getProjectComponentItemDetails","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component item UUID","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentItemDetailsResponseDto"}}}},"400":{"description":"Invalid projectId or id UUID format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to view component item details or access to project denied"},"404":{"description":"Component item not found, is deleted, or does not belong to the specified project"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project component item details","tags":["projects","components","questions"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/components":{"post":{"description":"Creates a new project component (reusable project template) with name, description, icon, tags, and internal notes.\n\n**What are Project Components?**\nProject components are reusable project templates that standardize recurring project types. They serve as blueprints for planning, pricing, and executing similar projects consistently. Components connect requirements management, cost calculation, and execution in one unified workflow.\n\n**After Creating a Component:**\nOnce created, you can add items (Epics, Work Packages, Todo Lists, Test Suites) to define the project structure. You can also add questions to capture customer requirements, todos for checklists, and test cases for acceptance testing.\n\n**Component Placement:**\nThe component is automatically appended to the end of the project component list. You can reorder components later using the sort endpoint.\n\n**Content Format:**\nDescription and internal note fields accept HTML or Markdown input and are automatically converted to the internal IDoc format for storage. When retrieved, this content is converted back to HTML for easy consumption.\n\n**Side Effects:**\nCreating a component automatically triggers project configuration change tracking, marking the project as having been modified.","operationId":"ProjectComponentsController_createComponent","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectComponentDto"}}}},"responses":{"201":{"description":"Component created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectComponentResponseDto"}}}},"400":{"description":"Invalid request: missing required fields or invalid UUID format for tags"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to create components or access to project denied"},"404":{"description":"Project not found or not accessible"},"422":{"description":"Editor content conversion errors"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new component in a project","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/import-from-library":{"post":{"description":"Imports one or more reusable component templates from the workspace component library into the specified project.\n\n**Component Library vs Project Components:**\nThe component system operates in two contexts:\n- **Library Components**: Workspace-wide reusable templates (projectId is null). These are blueprints with no live data - questions are defined but not answered, todos are not checked, test cases are not evaluated. Library components serve as templates that can be reused across multiple projects.\n- **Project Components**: Live instances in projects (projectId is set). These contain actual project data - questions can be answered, todos can be checked off, test cases can be evaluated, and items can be connected to tasks in the task management system.\n\n**What Gets Imported:**\nWhen you import a library component, the complete component structure is duplicated into the project, including:\n- All items (Epics, Work Packages, Todo Lists, Test Suites) with their complete hierarchy and nesting\n- All questions with their options and configurations (answers are initialized as empty/unanswered)\n- All todos with their descriptions (completion status is initialized as not done)\n- All test cases with steps and expected results (evaluations are initialized as not tested)\n- All conditions with their logic (automatically updated to reference the new item/question/todo/test case IDs in the project)\n\n**Automatic Processing:**\nAfter import, the system automatically:\n- Recalculates all conditions to ensure they reference the correct items in the project\n- Recalculates timeframes based on work packages and their configurations\n- Adds the imported components to the end of the project component list\n- Marks the project configuration as changed\n\n**Use Case:**\nThis endpoint is perfect for standardizing project setup. Create reusable templates in the library once, then import them into new projects to get a consistent starting structure that can be customized per project.","operationId":"ProjectComponentsController_importFromLibrary","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportComponentsFromLibraryDto"}}}},"responses":{"201":{"description":"Components imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportComponentsFromLibraryResponseDto"}}}},"400":{"description":"Invalid request: empty componentIds array or invalid UUID format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to import components or access to project denied"},"404":{"description":"Project not found or component not found in library"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Import components from library into project","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/todos":{"post":{"description":"Creates a new todo checklist item within a project component item. Todos are actionable checklist items that help track progress and ensure nothing is missed.\n\n**What are Todos?**\nTodos are checklist items used to track actionable tasks within component items. They are perfect for:\n- Recurring processes (tests, approvals, installation steps)\n- Quality control checkpoints\n- Project preparation steps\n- Final checks before go-live\n- Kickoff checklists\n- Review and approval workflows\n\n**Todo Features:**\nEach todo can be:\n- Checked off individually to track completion\n- Commented on to add notes or context\n- Tracked with completion status (isDone), who completed it (doneBy), and when (doneUpdatedAt)\n\n**Where Todos Can Be Attached:**\nTodos can be attached to Work Packages or Todo List items. When attached to a Todo List, they become sub-items in a checklist. When attached to a Work Package, they serve as actionable steps within that work package.\n\n**Content Format:**\nThe description field accepts HTML or Markdown format and is automatically converted to IDoc format for storage. When retrieved, it is converted back to HTML for easy consumption.\n\n**Automatic Processing:**\nAfter creating a todo, the system automatically:\n- Calculates sort order as max(sort) + 1 for todos in the same item, positioning it at the end\n- Recalculates all conditions that depend on todo completion status\n- Updates timeframes if conditions changed\n- Marks the project configuration as changed\n\n**Use Case:**\nCreate todos to break down work packages into actionable steps, create quality checklists, or define approval workflows. Todos can also be used in conditions to control when other items are visible or active.","operationId":"ProjectComponentsController_createTodo","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTodoDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodoOperationResponseDto"}}}},"400":{"description":"Invalid request: invalid UUID format, missing required fields, or invalid content"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Component item not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new todo (checklist item) for a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/items/{itemId}/todos/{todoId}":{"patch":{"description":"Updates title and/or description of an existing todo item within a project component item. Only provided fields are updated (partial update). Description accepts HTML or Markdown format and is converted to IDoc for storage. Only todos belonging to component items in the specified project are accessible.","operationId":"ProjectComponentsController_updateTodo","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}},{"name":"todoId","required":true,"in":"path","description":"Todo UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440011","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTodoDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodoOperationResponseDto"}}}},"400":{"description":"Invalid request: no fields provided for update or invalid UUID format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components"},"404":{"description":"Todo not found or does not belong to the specified item in the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update an existing todo","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/todos/{id}":{"delete":{"description":"Deletes a todo item from a project component item (soft delete - sets deletedAt timestamp). Todos are checklist items within component items (epics, features, tasks) that can be marked as complete and have comments. This endpoint validates that the todo exists and belongs to a component item in the specified project. The service automatically triggers condition cleanup (removes conditions targeting the deleted todo), recalculates conditions if needed, and marks the project configuration as changed.","operationId":"ProjectComponentsController_deleteTodo","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}},{"name":"id","required":true,"in":"path","description":"Todo UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440011","type":"string"}}],"responses":{"200":{"description":"Todo deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid projectId, itemId, or todo id format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or no access to project"},"404":{"description":"Todo not found, component item not found, or item does not belong to the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete (soft delete) a todo from a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/testcases/{id}":{"delete":{"description":"Deletes a test case from a project component item (soft delete - sets deletedAt timestamp). Test cases are used to define test scenarios with steps and expected results for component items. This endpoint validates that the test case exists and belongs to a component item in the specified project. The service automatically triggers condition cleanup, recalculation, and timeframe updates.","operationId":"ProjectComponentsController_deleteTestCase","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}},{"name":"id","required":true,"in":"path","description":"Test case UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440010","type":"string"}}],"responses":{"200":{"description":"Test case deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid projectId, itemId, or testCaseId format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to delete test cases or no access to project"},"404":{"description":"Project not found, component item not found, or test case not found in the specified item"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete (soft delete) a test case","tags":["projects","components","questions"],"x-required-scopes":["api:write"]},"patch":{"description":"Partially updates an existing test case for a component item within a project. Only provided fields will be updated. Editor content (description, steps, expectedResult) accepts HTML or Markdown input when provided.","operationId":"ProjectComponentsController_updateTestCase","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440010","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}},{"name":"id","required":true,"in":"path","description":"Test case UUID","schema":{"example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTestCaseDto"}}}},"responses":{"200":{"description":"Test case updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentTestCaseDto"}}}},"400":{"description":"Invalid request: validation errors or test case does not belong to project"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project, item, or test case not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update an existing test case","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/questions":{"post":{"description":"Creates a new question for a component item within a project component. Questions capture customer-specific requirements or project details in a structured way, making work packages flexible and reusable.\n\n**What are Questions?**\nQuestions are form fields attached to component items (typically Work Packages) that help capture customer requirements or project details. They make work packages flexible and reusable by allowing later individualization in projects. When customers answer questions, the answers can automatically affect effort calculation and pricing.\n\n**Question Types:**\nEach question can have one of eight types, each suited for different data collection needs:\n- **ShortText**: Single-line text input for names, titles, keywords, or short answers\n- **Editor**: Formatted multi-line text for descriptions, detailed explanations, or free text answers\n- **Checkbox**: Yes/No selection or multiple checkbox options. Answers can impact effort calculation if options have extraHours configured\n- **Radio**: Single choice from multiple predefined options. Answers can impact effort calculation if options have extraHours configured\n- **Files**: Upload files such as logos, documents, graphics, or reference materials\n- **Datepicker**: Select a date for deadlines, delivery dates, or scheduling\n- **Multiplier**: Dynamic calculation based on quantity. For example, \"How many pages?\" with a duration per page. The system calculates: Answer (quantity) Γ Duration per element = Total additional effort\n- **Person**: Select one or more people from the project team or clients\n\n**Key Features:**\n- **Automatic Effort Calculation**: Answers to Checkbox, Radio, and Multiplier questions can automatically affect the project effort and pricing\n- **Conditional Visibility**: Questions can have conditions that control when they are shown (e.g., only show if another question was answered a certain way)\n- **Flexible Options**: Checkbox and Radio questions support multiple options, each with optional extraHours that affect effort calculation\n\n**Validation Rules:**\nFor Checkbox and Radio question types, at least one option must be provided in the options array. The description field accepts HTML or Markdown input and is automatically converted to IDoc format for storage.\n\n**Automatic Processing:**\nAfter creating a question, the system automatically:\n- Assigns a sort order (max existing sort + 1) to position the question in the list\n- Recalculates all conditions to ensure dependent items are shown/hidden correctly\n- Updates timeframes if the question affects effort calculation\n- Triggers summary generation if needed\n\n**Use Case:**\nUse questions to create dynamic, customer-specific project configurations. For example, ask \"Do you need e-commerce functionality?\" and automatically add extra work packages or adjust pricing based on the answer.","operationId":"ProjectComponentsController_createQuestion","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectQuestionDto"}}}},"responses":{"201":{"description":"Question created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"e57dc37b-7693-4d06-b49c-17084b773aff","description":"ID of the created question"}}}}}},"400":{"description":"Invalid request: options array must have at least 1 item for Checkbox/Radio types, or invalid UUID/description format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found, item not found, or item does not belong to a component in the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new question for a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/questions/{id}":{"patch":{"description":"Updates only the provided fields of an existing question for a component item within a project. Questions support multiple types (ShortText, Editor, Checkbox, Radio, Files, Datepicker, Multiplier, Person). For Checkbox/Radio types, options must be provided if type is being updated to one of these types. The description field accepts HTML or Markdown input and is stored in IDoc format. Options management: options with id are updated, options without id are created, options removed from array are deleted. Conditions management: conditions with id are updated, conditions without id are created, conditions removed from array are deleted. This endpoint automatically recalculates conditions, updates timeframes, and triggers summary generation.","operationId":"ProjectComponentsController_updateQuestion","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Question UUID","schema":{"example":"f47dc37b-7693-4d06-b49c-17084b773baa","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectQuestionDto"}}}},"responses":{"200":{"description":"Question updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"f47dc37b-7693-4d06-b49c-17084b773baa","description":"ID of the updated question"}}}}}},"400":{"description":"Invalid request: options array must have at least 1 item for Checkbox/Radio types when type is updated, or invalid UUID/description format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found, item not found, question not found, or question does not belong to an item in the project"},"422":{"description":"Editor content conversion errors"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update an existing question","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/questions/sort":{"post":{"description":"Reorders questions within a component item by providing a new sort order array of question IDs. The sort order determines the display order of questions in the UI and affects condition evaluation order. All questions for the item must be included in the newSortOrder array.","operationId":"ProjectComponentsController_sortProjectQuestions","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortProjectQuestionsDto"}}}},"responses":{"200":{"description":"Questions reordered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid UUID format or failed to sort questions"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Item not found or does not belong to a component in the project, or question IDs not found in the item"},"422":{"description":"Incomplete sort order: not all questions for the item are included in newSortOrder"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder questions within a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/questions/{id}/answer":{"post":{"description":"Submits an answer to a question within a project component item. This endpoint allows users to provide answers to questions that capture customer requirements or project details.\n\n**Question Types and Answer Formats:**\nQuestions can have different types, and each type requires a specific answer format. Only provide the answer field(s) relevant to the question type:\n- **ShortText**: Provide shortTextAnswer (string)\n- **Editor**: Provide editorAnswer (HTML or Markdown string)\n- **Checkbox**: Provide selectedOptions (array of option IDs for multiple selections)\n- **Radio**: Provide selectedOption (single option ID string)\n- **Files**: Provide fileUrls (array of file URL strings)\n- **Datepicker**: Provide dateAnswer (ISO 8601 date string)\n- **Multiplier**: Provide multiplierAnswer (number)\n- **Person**: Provide selectedPersonId (array of person IDs)\n\n**Automatic Processing:**\nWhen you submit an answer, the system automatically:\n- Tracks who answered (answeredBy is set to the current user)\n- Records when the answer was provided (answeredAt timestamp)\n- Calculates the isAnswered flag based on whether a valid answer was provided\n- Updates option selections for Checkbox/Radio types (marks options as selected)\n- Recalculates project conditions to show/hide dependent items based on the answer\n- Updates effort calculations if the question affects pricing (for Checkbox/Radio/Multiplier types)\n- Updates timeframes if effort changed\n\n**Permissions:**\nThis endpoint uses the processComponentsQuestions permission, which is more permissive than manageComponents. This allows users to answer questions and participate in project configuration without requiring full component edit access.","operationId":"ProjectComponentsController_answerQuestion","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component Item UUID","schema":{"example":"d47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Question UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerProjectQuestionDto"}}}},"responses":{"200":{"description":"Question answered successfully"},"400":{"description":"Invalid request: invalid UUID format, invalid date format, or invalid option IDs"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions (processComponentsQuestions) or access to project denied"},"404":{"description":"Question not found or question does not belong to the component item in the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Answer a question in a project component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/questions/{questionId}":{"delete":{"description":"Soft deletes a question from a component item within a project. The question must exist and belong to the specified component item in the project. This operation automatically cleans up invalid condition targets, recalculates conditions, updates component item timeframes, and marks the project configuration as changed.","operationId":"ProjectComponentsController_deleteQuestion","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}},{"name":"questionId","required":true,"in":"path","description":"Question UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"responses":{"200":{"description":"Question deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid project ID, item ID, or question ID format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Question not found, item not found, or item does not belong to the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete a question from a project component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/items/{itemId}/testcases":{"post":{"description":"Creates a new test case for a component item within a project. Test cases document formal review and approval criteria for project results.\n\n**What are Test Cases?**\nTest cases are individual test steps within a Test Suite. They document formal review and approval criteria for project results, ensuring that all delivered work meets the agreed requirements. Test cases are part of the acceptance testing process.\n\n**Test Case Structure:**\nEach test case consists of four main parts:\n- **Title**: Short, clear title that describes what is being tested (e.g., \"Check confirmation email destination\", \"Validate form input fields\")\n- **Description**: Explains what is being tested and why it matters. Provides context for the test.\n- **Steps**: Step-by-step instructions for running the test. Should be clear and reproducible (e.g., \"1. Navigate to login page 2. Enter credentials 3. Click login button\")\n- **Expected Result**: Describes the expected or correct system behavior when the test is run successfully (e.g., \"User is successfully logged in and redirected to dashboard\")\n\n**Test Case Evaluation:**\nAfter a test case is created, it can be evaluated later using the evaluate endpoint. Test cases can be marked as:\n- **Passed**: Test completed successfully and met all expected results\n- **Failed**: Test did not meet the expected result or revealed issues\n- **PassedWithReservations**: Test passed but with notes or concerns that should be documented\n\n**Project Completion:**\nThe project is considered finished when all test cases within all Test Suites have been passed successfully. This ensures quality and formal acceptance before project completion.\n\n**Content Format:**\nAll editor content fields (description, steps, expectedResult) accept HTML or Markdown input and are automatically converted to IDoc format for storage. When retrieved, they are converted back to HTML for easy consumption.\n\n**Use Case:**\nCreate test cases to define formal acceptance criteria for project deliverables. This ensures consistent quality standards and provides clear documentation of what was tested and approved.","operationId":"ProjectComponentsController_createTestCase","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440010","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID. Items are the building blocks within components (Epics, Work Packages, Todo Lists, Test Suites).","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestCaseDto"}}}},"responses":{"201":{"description":"Test case created successfully. Returns the ID of the created test case.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440010"}}}}}},"400":{"description":"Invalid request: validation errors or item does not belong to project"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project or item not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new test case (acceptance test step) for a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/testcases/{id}/evaluate":{"post":{"description":"Mark a test case as passed or failed with optional comment. Uses Projects.processComponentsTestCases permission, allowing test evaluation without full component management access. Automatically sets testedBy and testedAt fields. Updates project configuration flag and recalculates conditions.","operationId":"ProjectComponentsController_evaluateTestCase","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440001","type":"string"}},{"name":"id","required":true,"in":"path","description":"Test case ID","schema":{"example":"550e8400-e29b-41d4-a716-446655440002","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateTestCaseDto"}}}},"responses":{"200":{"description":"Test case evaluation saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentTestCaseDto"}}}},"400":{"description":"Invalid request data or test case does not belong to component in project"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User does not have permission to evaluate test cases"},"404":{"description":"Test case not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Evaluate a test case","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/tree/sort":{"post":{"description":"Allows reordering components and items at the same level, reparenting items to different components or parent items, and moving items between components (automatically updates componentId for all descendants). Automatically handles side-effects including conditions recalculation, configurationChanged flag updates, summary generation checks, and timeframe updates.","operationId":"ProjectComponentsController_saveComponentsSort","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveComponentsSortDto"}}}},"responses":{"200":{"description":"Tree structure updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Products sort updated successfully"}}}}}},"400":{"description":"Invalid request format, invalid UUIDs, or invalid type values"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found or component/item not found in project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Move/reorder items in project component tree","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/tasks/generate":{"post":{"description":"Generate tasks from a component item and its children. The endpoint recursively processes items (two levels deep), skips Epic items, and only creates tasks for items that don't already have associated tasks. Can be used with either a Component ID or a ComponentItem ID.","operationId":"ProjectComponentsController_generateTasksFromItems","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTasksFromItemsDto"}}}},"responses":{"200":{"description":"Tasks generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTasksFromItemsResponseDto"}}}},"400":{"description":"Invalid request: invalid projectId, itemId format, or itemType value. Items may already be generating."},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found, item not found, or item does not belong to the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Generate tasks from a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/tasks/disconnect":{"post":{"description":"Disconnect a component item from its associated task(s). Optionally, the associated task(s) can be deleted after disconnection by setting deleteTask to true. All tasks connected to the item via entityUniqueId will be disconnected. If no tasks are connected to the item, a 404 error will be returned.","operationId":"ProjectComponentsController_disconnectItemFromTask","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"itemId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectItemFromTaskDto"}}}},"responses":{"200":{"description":"Item successfully disconnected from task(s)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid request: invalid projectId or itemId format, or validation error in request body"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found, item not found, item does not belong to the project, or no tasks are connected to the item"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Disconnect a component item from its associated task(s)","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/{id}":{"patch":{"description":"Updates only the provided fields of an existing component in a project. The description and internalNote fields accept HTML or Markdown and will be converted to the internal format. Updating a component triggers project configuration change tracking.","operationId":"ProjectComponentsController_patchComponent","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectComponentDto"}}}},"responses":{"200":{"description":"Component updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectComponentResponseDto"}}}},"400":{"description":"Invalid request: invalid UUID format for component ID, project ID, or tag IDs"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Component not found, component does not belong to project, or project not accessible"},"422":{"description":"Editor content conversion errors"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update a project component","tags":["projects","components","questions"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a component by setting the deletedAt timestamp. The component is marked as deleted but not permanently removed from the database. Automatically cleans up invalid condition targets, recalculates project conditions, updates project configurationChanged flag, and updates timeframes.","operationId":"ProjectComponentsController_deleteComponent","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"responses":{"200":{"description":"Component deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid component ID or project ID format (not valid UUID)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Component not found, component does not belong to project, component already deleted, or project not accessible"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete (soft delete) a component in a project","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/todos/{id}/toggle":{"post":{"description":"Toggles the completion status of a todo item within a project component item. Updates the isDone status, sets doneBy to the current user, and updates doneUpdatedAt timestamp. This endpoint uses the processComponentsTodos permission, allowing users to toggle todo completion without requiring full component management permissions. After toggling, the system recalculates conditions and marks the project configuration as changed.","operationId":"ProjectComponentsController_toggleTodo","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID (the item that contains the todo)","schema":{"example":"b58dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Todo UUID","schema":{"example":"c69dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleTodoDto"}}}},"responses":{"200":{"description":"Todo completion status toggled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid UUID format or missing isDone field"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions or no access to project"},"404":{"description":"Todo not found or does not belong to a component item in the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Toggle todo completion status","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/todos/sort":{"post":{"description":"Reorders todos within a component item by providing a new sort order array. The sort order determines the display order of todos in the UI and affects condition evaluation order. All todos in the newSortOrder array must belong to the specified item. This operation automatically recalculates conditions if needed and marks the project configuration as changed.","operationId":"ProjectComponentsController_sortTodos","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortTodosDto"}}}},"responses":{"200":{"description":"Todos successfully reordered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid projectId, itemId, or todo IDs in sort order"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions or no access to project"},"404":{"description":"Item not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Sort todos within an item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/testcases/sort":{"post":{"description":"Reorders test cases within a component item by providing a new sort order array. The sort order determines the display order of test cases in the UI and affects condition evaluation order. All test case IDs in the array must belong to the specified item.","operationId":"ProjectComponentsController_sortTestCases","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortTestCasesDto"}}}},"responses":{"200":{"description":"Test cases successfully sorted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid projectId, itemId, or test case IDs format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions or no access to project"},"404":{"description":"Project or item not found, or item does not belong to the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Sort test cases within a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/{id}/export":{"post":{"description":"Exports a project component to the workspace library, making it available for reuse across all projects. The exported component includes all nested data (items, questions, todos, test cases, conditions) with ID references automatically updated. The component is placed at the end of the library with an optional custom name. Requires both Projects.manageComponents and ProjectComponentsLibrary.edit permissions.","operationId":"ProjectComponentsController_exportComponentToLibrary","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component UUID to export","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportComponentToLibraryDto"}}}},"responses":{"201":{"description":"Component exported to library successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportComponentToLibraryResponseDto"}}}},"400":{"description":"Invalid projectId or component id format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or edit library, or no access to project"},"404":{"description":"Component not found, deleted, or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Export a project component to the library","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{id}":{"patch":{"description":"Updates only the provided fields of an existing component item (epic, feature, task) in a project. The description and internalNote fields accept HTML or Markdown and will be converted to the internal format. When the conditions array is provided, it completely replaces existing conditions. Conditions with id are updated, conditions without id are created, and conditions not in the array are deleted. Updating an item triggers automatic side effects including condition recalculation, project configuration change tracking, and timeframe updates.","operationId":"ProjectComponentsController_patchItem","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component item UUID","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchComponentItemDto"}}}},"responses":{"200":{"description":"Item updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"3047983b-d798-4aff-8dd4-628cf1900703"}}}}}},"400":{"description":"Invalid request: invalid UUID format for item ID, project ID, component ID, tag IDs, or invalid type/timeFrame combination"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Item not found, item does not belong to project component, component not found, or parent item not found"},"422":{"description":"Editor content conversion errors"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update a component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a component item (epic, feature, task) in a project component. The item will be marked as deleted but not permanently removed. Automatically cleans up invalid condition targets and recalculates project conditions.","operationId":"ProjectComponentsController_deleteItem","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component item UUID","schema":{"example":"3047983b-d798-4aff-8dd4-628cf1900703","type":"string"}}],"responses":{"200":{"description":"Item deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid projectId or item id format"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Item not found or does not belong to a component in the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/tasks/connect":{"post":{"description":"Connects a component item (epic, feature, or task) to an existing task in the task management system. If the item already has a task connection, it will be disconnected first before establishing the new connection. Component tags are automatically merged into the task's tags. To disconnect an item from a task without connecting to a new one, pass null or omit the taskId in the request body.","operationId":"ProjectComponentsController_connectItemToTask","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component item UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectItemToTaskDto"}}}},"responses":{"200":{"description":"Item connected/disconnected successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid request: invalid UUID format for projectId, itemId, or taskId"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Project not found, item not found, item does not belong to project, or task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Connect component item to task","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items/{itemId}/todos/{id}/comment":{"post":{"description":"Adds or updates a comment on a todo item within a project component item. Todos are checklist items that can be marked as complete and have comments. The comment content is provided in HTML or Markdown format and converted to internal IDoc format. Uses the processComponentsTodos permission, allowing users to comment on todos without full component edit access. The system automatically recalculates project conditions and sets the project configurationChanged flag after adding a comment.","operationId":"ProjectComponentsController_addTodoComment","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Component Item UUID","schema":{"example":"d47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Todo UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTodoCommentDto"}}}},"responses":{"200":{"description":"Comment added successfully"},"400":{"description":"Invalid request: invalid UUID format or missing todoComment field"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions (processComponentsTodos) or access to project denied"},"404":{"description":"Todo not found or todo does not belong to the component item in the project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add a comment to a todo in a project component item","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/{id}/duplicate":{"post":{"description":"Creates a copy of an existing component including all nested data (items, questions, todos, test cases, and conditions). The duplicated component is automatically named with \"(Copy)\" suffix and placed immediately after the original component in the sort order. Condition references are automatically updated to point to the new duplicated items. Triggers project configuration change tracking and recalculates conditions and timeframes.","operationId":"ProjectComponentsController_duplicateComponent","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component UUID to duplicate","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"responses":{"201":{"description":"Component duplicated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateComponentResponseDto"}}}},"400":{"description":"Invalid component ID format (not a valid UUID)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or no access to project"},"404":{"description":"Component not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Duplicate a component within the same project","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/components/{id}/recalculate-estimates":{"post":{"description":"Recalculates time estimates for all items (epics and non-epics) within a project component. This includes:\n- Recalculating individual item estimates based on timeFrame and question multipliers/extra hours\n- Recalculating epic estimates by summing their children's estimates\n- Updating the component's totalTimeFrame\n- Respecting visibility conditions (items with invalid conditions are excluded)\n\nItems are processed bottom-up (children first, then parents) to ensure accurate calculations. Only components that belong to the specified project can be recalculated through this endpoint.","operationId":"ProjectComponentsController_recalculateComponentEstimates","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"a47dc37b-7693-4d06-b49c-17084b773aff","type":"string"}},{"name":"id","required":true,"in":"path","description":"Component UUID","schema":{"example":"e57dc37b-7693-4d06-b49c-17084b773aff","type":"string"}}],"responses":{"200":{"description":"Estimates recalculated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid projectId or component ID format (not a valid UUID)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or no access to project"},"404":{"description":"Component not found or does not belong to the specified project"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Recalculate all estimates for a project component","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/items":{"post":{"description":"Creates a new component item within a project component. Items are the building blocks that structure project work.\n\n**What are Component Items?**\nItems are the building blocks within components that organize and structure project work. Each item can be one of four types:\n\n1. **Epic**: Major sections or phases that group related work packages around a common theme or goal\n - Example: \"Technical Implementation\", \"Design & Development\", \"Project Kickoff & Preparation\"\n - Can contain Work Packages, Todo Lists, or Test Suites\n - Can nest other Epics to create complex hierarchies (arbitrary nesting depth)\n - Helps track project progress at a strategic level\n - TimeFrame is not required for Epics\n\n2. **Work Package**: Self-contained, clearly defined tasks that deliver tangible results\n - Example: \"Set up domain and hosting\", \"Design homepage layout\", \"Configure CMS\"\n - Can have timeframes/estimates (required field)\n - Can contain Questions (to capture customer requirements), Todos (checklist items), and Test Cases (acceptance test steps)\n - Can nest other Work Packages for complex tasks\n - Acts as a draft before creating tickets in the task management system\n\n3. **Todo List**: Checklists of sub-steps or checkpoints\n - Example: \"Kickoff Checklist\", \"Quality Control Checklist\", \"Go-live Approval\"\n - Perfect for recurring processes (tests, approvals, installation steps)\n - Each todo item within the list can be checked off individually\n - TimeFrame is required (estimated time to complete the checklist)\n\n4. **Test Suite**: Formal acceptance tests for project results\n - Example: \"Contact Form Tests\", \"Responsive Design Check\", \"SEO Review\"\n - Contains multiple test cases with steps and expected results\n - Project is considered finished when all test cases within all Test Suites pass\n - TimeFrame is required (estimated time to run all tests)\n\n**Item Placement:**\nItems can be created at the root level of a component or nested under parent items (Epics or other Work Packages). This allows for flexible project structures that match your workflow.\n\n**Content Format:**\nThe description and internalNote fields accept HTML or Markdown input and are automatically converted to the internal IDoc format for storage. When retrieved, they are converted back to HTML for easy consumption.\n\n**Validation Rules:**\nTimeFrame is required for all item types except Epic. The timeframe represents the estimated effort in hours for completing the item.","operationId":"ProjectComponentsController_createItem","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project UUID","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateComponentItemDto"}}}},"responses":{"201":{"description":"Component item created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateComponentItemResponseDto"}}}},"400":{"description":"Invalid request: invalid UUID format, missing required fields, or validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions to manage components or access to project denied"},"404":{"description":"Component not found or does not belong to the specified project"},"422":{"description":"Editor content conversion errors"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new component item (Epic, Work Package, Todo List, or Test Suite)","tags":["projects","components","questions"],"x-required-scopes":["api:write"]}},"/projects/documentation":{"get":{"description":"Project documentation allows you to capture, structure, and share project-related knowledge directly in the project context. This helps keep important information like technical notes, repeated questions, and project-specific details organized and accessible.\n\nRetrieves a paginated grid of project documentation with filtering and sorting capabilities. Quick search available on: title. Filterable fields: id, projectId, projectName, title, userId, createdAt, updatedAt, sort. Sortable fields: id, projectId, projectName, title, userId, createdAt, updatedAt, sort.\n\n**Features:**\n- View all documentation articles across the workspace or filter by specific project\n- Each article includes title, author, and last update timestamp\n- Articles can be sorted and filtered using grid parameters\n\n**Use cases:**\n- Document project setup procedures and access credentials\n- Capture technical quirks and troubleshooting steps\n- Share project-specific notes and guidelines\n- Keep track of important decisions and context","operationId":"ProjectDocumentationController_listProjectDocumentation","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: title","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Documentation ID\n- **projectId** (set): Project ID\n- **projectName** (string): Project name\n- **title** (string): Documentation title\n- **userId** (string): Author user ID\n- **createdAt** (date): Creation timestamp\n- **updatedAt** (date): Last update timestamp\n- **sort** (number): Sort order\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Documentation ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (set): Project ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **projectName** (string): Project name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **title** (string): Documentation title (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **userId** (string): Author user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **updatedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **sort** (number): Sort order (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Documentation ID\n- **projectId**: Project ID\n- **projectName**: Project name\n- **title**: Documentation title\n- **userId**: Author user ID\n- **createdAt**: Creation timestamp\n- **updatedAt**: Last update timestamp\n- **sort**: Sort order\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** sort (asc)","schema":{"example":"[{\"field\":\"sort\",\"direction\":\"asc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, projectId, projectName, title, userId, createdAt, updatedAt, sort","schema":{"example":"id,projectId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of project documentation articles"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List project documentation articles","tags":["projects","project-documentation","projects"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new project documentation article to capture and share project-related knowledge.\n\n**What to include:**\n- Clear, descriptive title that helps team members find the article quickly\n- Rich text content with formatting, headings, lists, and links\n- Project-specific information like access credentials, technical notes, or procedures\n\n**Content format:**\n- Accepts HTML or Markdown input\n- Content is automatically converted to internal ProseMirror format for storage\n- Supports rich text formatting including headings, lists, tables, and code blocks\n- When retrieved via GET endpoint, content is returned as HTML\n\n**Permissions:**\n- Requires \"createDocumentation\" permission for the project\n- Article is automatically associated with the authenticated user as the author","operationId":"ProjectDocumentationController_createProjectDocumentation","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectDocumentationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentationResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"projectId":["Project ID is required"],"title":["Title is required"],"content":["Content is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new project documentation article","tags":["projects","project-documentation","projects"],"x-required-scopes":["api:write"]}},"/projects/documentation/{id}":{"get":{"description":"Retrieves complete details of a specific project documentation article, including the full formatted content.\n\n**Returns:**\n- Article ID, project ID, and title\n- Full article content in HTML format (converted from internal ProseMirror format)\n- Author information (user ID who created the article)\n- Creation and last update timestamps\n\nThe content field contains HTML that can be directly rendered in a browser or HTML viewer. The content supports basic text formatting including headings, paragraphs, bold, italic, links, and lists.","operationId":"ProjectDocumentationController_getProjectDocumentationDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project documentation article details","tags":["projects","project-documentation","projects"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates specific fields of an existing project documentation article. Only provided fields will be updated; all other fields remain unchanged.\n\n**Update behavior:**\n- All fields are optional - only include fields you want to update\n- If content is provided, it replaces the entire article content\n- If projectId is provided, the article is moved to the specified project\n- If title is provided, only the title is updated\n\n**Content format:**\n- Accepts HTML or Markdown input (same as create endpoint)\n- Content is converted to internal format and stored\n- Supports rich text formatting including headings, lists, tables, and code blocks\n\n**Permissions:**\n- Requires \"manageDocumentation\" permission for the project\n- Original author information is preserved","operationId":"ProjectDocumentationController_patchProjectDocumentation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectDocumentationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentationResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update a project documentation article","tags":["projects","project-documentation","projects"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a project documentation article. The article is marked as deleted and will no longer appear in list queries, but it is not permanently removed from the database.\n\n**Deletion behavior:**\n- Article is marked with a deletedAt timestamp\n- Article will not appear in GET list queries\n- Article details can still be retrieved directly by ID if needed\n- Data is preserved for potential recovery or audit purposes\n\n**Permissions:**\n- Requires \"manageDocumentation\" permission for the project","operationId":"ProjectDocumentationController_deleteProjectDocumentation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete a project documentation article","tags":["projects","project-documentation","projects"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/documents/contact-persons":{"get":{"description":"**What are contact persons?**\nContact persons are users who appear as the addressed recipient in project documents. They represent the client or stakeholder who will receive and review the document.\n\n**How contact persons are determined:**\n- For external projects (projects linked to an organization): Returns all members of the linked organization\n- For internal projects: Returns all employees in the workspace\n\n**What is returned:**\nA list of users with their ID, full name, position/title, and avatar. This list is used when creating or updating documents to select who should be listed as the contact person in the document header and recipient fields.\n\n**Use cases:**\n- Populate dropdown/select fields when creating documents\n- Display available contacts when editing document properties\n- Ensure only valid contacts are assigned to documents","operationId":"ProjectDocumentsController_getContactPersons","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Contact persons retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectDocumentUserResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get available contact persons for document creation","tags":["projects","documents"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/documents":{"get":{"description":"**What are project documents?**\nProject documents are structured documents (estimates, specifications, contracts) that are automatically generated from project data. They are based on saved project versions (snapshots) and can include dynamic content, variables, and conditional sections.\n\n**Document types:**\n- **Estimate**: Commercial proposals summarizing project services, quantities, discounts, and costs\n- **Specification**: Detailed requirement documents describing what must be delivered\n- **Custom Editor**: Free-form documents like contracts, NDAs, or custom agreements\n\n**What is returned:**\nA paginated grid/list of all documents for the specified project, including:\n- Document title, type, and status\n- Associated project version (snapshot)\n- Contact person assigned to the document\n- Creation date\n- All fields can be filtered, sorted, and paginated\n\n**Document statuses:**\n- Draft: Initial version, not yet finalized\n- Waiting for Approval: Sent to client for review\n- Final: Ready for signing\n- Accepted: Approved by client\n- Rejected: Declined by client\n- Parked: Temporarily set aside\n\n**Important notes:**\n- Documents are always linked to a specific project version for traceability\n- Only documents from the current workspace are returned\n- Requires permission to view projects in the workspace\n\nRetrieves a paginated grid of documents with filtering and sorting capabilities. Quick search available on: title. Filterable fields: id, title, type, status, contactUserId, snapshotId, createdAt. Sortable fields: id, title, type, status, contactUserId, snapshotId, createdAt.","operationId":"ProjectDocumentsController_listDocuments","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: title","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Document ID\n- **title** (string): Document title\n- **type** (set): Document type (Estimate, Specification, CustomEditor)\n- **status** (set): Document status (Draft, Final, WaitingForApproval, etc.)\n- **contactUserId** (string): Contact person user ID\n- **snapshotId** (string): Project snapshot ID\n- **createdAt** (date): Document creation timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Document ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **title** (string): Document title (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Document type (Estimate, Specification, CustomEditor) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **status** (set): Document status (Draft, Final, WaitingForApproval, etc.) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **contactUserId** (string): Contact person user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **snapshotId** (string): Project snapshot ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Document creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Document ID\n- **title**: Document title\n- **type**: Document type (Estimate, Specification, CustomEditor)\n- **status**: Document status (Draft, Final, WaitingForApproval, etc.)\n- **contactUserId**: Contact person user ID\n- **snapshotId**: Project snapshot ID\n- **createdAt**: Document creation timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, title, type, status, contactUserId, snapshotId, createdAt","schema":{"example":"id,title","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of project documents"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List documents for a project","tags":["projects","documents"],"x-required-scopes":["api:read"]},"post":{"description":"**What are project documents?**\nProject documents are structured documents automatically generated from project data. They can be estimates, specifications, or custom documents (contracts, NDAs, etc.) that pull in project, organization, and company data through variables.\n\n**Document creation workflow:**\n1. **Select project version**: Documents must be linked to a saved project version (snapshot) for traceability. Use GET /projects/:id/versions to get available versions.\n2. **Choose document type**: Estimate (commercial proposal), Specification (requirements), or CustomEditor (free-form document)\n3. **Set basic properties**: Title, description, status (usually starts as Draft)\n4. **Assign contact person**: Select from available contacts (use GET /projects/:id/documents/contact-persons)\n5. **Configure layout**: Enable table of contents, title page, indication mode (marks as non-binding estimate)\n6. **Set heading style**: Controls automatic numbering of headings (important for legal documents)\n7. **Add custom variables**: If using a template with custom variables, provide values for each variable\n\n**Content format:**\n- Description and customEditorContent accept HTML or Markdown\n- Content is automatically converted to internal IDoc format for storage\n- When retrieved, content is converted back to HTML for display\n- Supports rich formatting: headings, lists, tables, links, etc.\n\n**Custom variables:**\nIf your document template includes custom variables, provide them in the customVariables array:\n- Each variable needs: name, type, and value (matching the type)\n- Types: Text, LongText, Number, Boolean, Date, Select, MultiSelect\n- For Select/MultiSelect: provide options array and select value(s)\n- Required variables must have values provided\n\n**Validation:**\n- Project version must exist and belong to the project\n- Contact person must be available for this project type\n- All required custom variables must have values\n- Document type and status must be valid enum values\n\n**What is returned:**\nThe created document with all fields, including converted HTML content and custom variable values.\n\n**Use cases:**\n- Create new estimate for client approval\n- Generate specification document from project requirements\n- Create custom contract or agreement document\n- Automate document generation from project data","operationId":"ProjectDocumentsController_createDocument","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectDocumentDto"}}}},"responses":{"201":{"description":"Document created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentResponseDto"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Permission denied"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create new document","tags":["projects","documents"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/documents/{id}":{"get":{"description":"**What is returned:**\nComplete details for a specific project document, including all metadata, content, and configuration.\n\n**Content format:**\n- Description and custom editor content are returned as HTML (converted from internal IDoc format)\n- This allows direct display in web browsers or further HTML processing\n- Original formatting, headings, lists, and tables are preserved\n\n**Custom variables:**\nIf the document uses custom variables (defined in templates), all variable definitions and their current values are included:\n- Variable name, type, and description\n- Current value (formatted according to variable type)\n- Available options (for Select/MultiSelect types)\n- Required flag indicating if value must be provided\n\n**Document configuration:**\n- Layout options: table of contents, title page, indication mode\n- Heading style: controls how headings are numbered (normal, sequential, sequential from level 2, sequential with paragraph signs)\n- Type and status: document category and workflow state\n- Project version binding: which project snapshot this document is based on\n\n**Use cases:**\n- Display document in a viewer/editor interface\n- Show document metadata and properties\n- Edit document content and variables\n- Export document to DOCX format\n- Track document status and history","operationId":"ProjectDocumentsController_getDocument","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Document retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Document not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get document details","tags":["projects","documents"],"x-required-scopes":["api:read"]},"patch":{"description":"**How partial updates work:**\nOnly fields provided in the request body will be updated. All other fields remain unchanged. This allows flexible updates without needing to send the entire document.\n\n**Content updates:**\n- If description or customEditorContent is provided, it replaces the existing content\n- If set to null or empty string, the content is cleared\n- If omitted, existing content is preserved\n- Content accepts HTML or Markdown and is converted to internal format\n\n**Custom variables:**\n- If customVariables array is provided, it completely replaces all existing custom variables\n- If omitted, existing custom variables are preserved\n- To update individual variables, include all variables (updated and unchanged) in the array\n\n**Validation:**\n- Project version (if provided) must exist and belong to the project\n- Contact person (if provided) must be available for this project type\n- All provided custom variables must have valid values matching their types\n\n**Common update scenarios:**\n- Change document status (e.g., Draft β Waiting for Approval)\n- Update document title or description\n- Modify custom variable values\n- Change contact person assignment\n- Update layout options (table of contents, title page, etc.)\n- Switch to a different project version\n\n**What is returned:**\nThe updated document with all fields, including converted HTML content and custom variable values.","operationId":"ProjectDocumentsController_updateDocument","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectDocumentDto"}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectDocumentResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Document not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update document","tags":["projects","documents"],"x-required-scopes":["api:write"]},"delete":{"description":"**How deletion works:**\nThis endpoint performs a soft delete - the document is marked as deleted but not permanently removed from the database. This preserves data integrity and allows for audit trails.\n\n**What happens:**\n- Document is marked with deletedAt timestamp\n- Document no longer appears in list queries (GET /projects/:id/documents)\n- Document details cannot be retrieved (returns 404)\n- Historical data is preserved for compliance and auditing\n\n**Validation:**\n- Document must exist and belong to the specified project\n- Document must belong to the current workspace\n- Requires permission to manage documents\n\n**Use cases:**\n- Remove documents that are no longer needed\n- Clean up draft documents\n- Archive outdated versions\n- Maintain data retention policies\n\n**Note:** This is a permanent operation. There is no undo functionality. If you need to restore a deleted document, contact support.","operationId":"ProjectDocumentsController_deleteDocument","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Document ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Document deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Document not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete document","tags":["projects","documents"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/documents/preview-offer-number/{snapshotId}":{"get":{"description":"Generates a preview formatted offer number that will be assigned when the document is created. This is used for UI display purposes only. Requires snapshotId to format with correct version.","operationId":"ProjectDocumentsController_getPreviewOfferNumber","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"type":"string"}},{"name":"snapshotId","required":true,"in":"path","description":"Snapshot ID for version information","schema":{"type":"string"}}],"responses":{"200":{"description":"Preview formatted offer number","content":{"application/json":{"schema":{"type":"object","properties":{"formattedOfferNumber":{"type":"string","example":"WKM-1-v2-27012026-1"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get preview formatted offer number for new document","tags":["projects","documents"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/interim-payments":{"get":{"description":"Returns all interim payments (partial payments, advance payments, prepayments) for the specified project.\n\n**What are Interim Payments?**\nInterim payments are payments made before the final project invoice is completed. They help maintain cash flow during long-running projects, split large invoices into manageable parts, and track incoming payments according to agreed payment schedules.\n\n**Typical use cases:**\n- Contractually agreed down payment at project start\n- Installment after milestone approval\n- Security payment before development start\n\n**What is returned:**\n- All interim payments for the project, sorted by their sort order\n- Each payment includes: title, description (as HTML), amount, billing status, creation date, and sort order\n- The description field is automatically converted from internal IDoc format to HTML for API responses\n\n**Important:**\n- Only non-deleted payments are returned\n- Payments marked as billed (isBilled: true) are still included in the list\n- Requires Projects.seeAnyProject permission","operationId":"ProjectInterimPaymentsController_listInterimPayments","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Interim payments retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectInterimPaymentResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List project interim payments","tags":["projects","project-settings","billing","interim-payments"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new interim payment (partial payment, advance payment, prepayment) in the specified project.\n\n**How it works:**\n- The new payment is added to the project with the provided title, description, and amount\n- Sort order is automatically set to the maximum existing sort order plus 1 (appears at the end of the list)\n- The payment is initially marked as not billed (isBilled: false)\n- Description can be provided as HTML or Markdown and is automatically converted to internal IDoc format\n\n**Required fields:**\n- **title**: Short label for the payment (e.g., \"Prepayment\", \"50% Deposit\", \"Milestone 1\")\n- **amount**: Payment amount (must be positive, minimum 0.01)\n\n**Optional fields:**\n- **description**: Detailed notes about the payment (e.g., \"Client paid β¬1,000 upfront\"). Can be provided as HTML or Markdown format\n\n**What happens after creation:**\n- The payment becomes available for billing in the invoicing system\n- When used in an invoice, it is automatically deducted from the final invoice amount\n- The payment can be reordered using the sort endpoint\n\n**Validation:**\n- Amount must be a positive number (minimum 0.01)\n- Title cannot be empty\n- Project must exist and be accessible\n\n**Permissions:** Requires Projects.edit permission","operationId":"ProjectInterimPaymentsController_createInterimPayment","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectInterimPaymentDto"}}}},"responses":{"201":{"description":"Interim payment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create interim payment","tags":["projects","project-settings","billing","interim-payments"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/interim-payments/{id}":{"patch":{"description":"Updates only the provided fields of an existing interim payment. Fields not included in the request remain unchanged.\n\n**How partial updates work:**\n- Only fields included in the request body are updated\n- Omitted fields retain their current values\n- Description can be updated with new HTML or Markdown content\n- Sort order is not changed (use the sort endpoint to reorder payments)\n\n**Updatable fields:**\n- **title**: Update the payment label\n- **description**: Update payment notes (HTML or Markdown format)\n- **amount**: Change the payment amount (must be positive, minimum 0.01)\n\n**Important restrictions:**\n- Cannot update the isBilled status (this is managed automatically by the invoicing system)\n- Cannot change the project ID (payment is tied to the project)\n- Cannot update creation date or user ID\n\n**Validation:**\n- If amount is provided, it must be a positive number (minimum 0.01)\n- If title is provided, it cannot be empty\n- Payment must exist and belong to the specified project\n\n**Permissions:** Requires Projects.edit permission","operationId":"ProjectInterimPaymentsController_patchInterimPayment","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectInterimPaymentDto"}}}},"responses":{"200":{"description":"Interim payment updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Interim payment not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update interim payment","tags":["projects","project-settings","billing","interim-payments"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft-deletes an interim payment by marking it as deleted. The payment is not permanently removed from the database.\n\n**How deletion works:**\n- The payment is marked with a deletedAt timestamp\n- Deleted payments no longer appear in list queries\n- The payment is not permanently removed (soft delete)\n- Historical data and billing records remain intact\n\n**Important considerations:**\n- If the payment has already been billed (isBilled: true), deletion may affect invoice calculations\n- Consider the impact on invoicing before deleting billed payments\n- Deleted payments can be filtered out from API responses\n\n**Permissions:** Requires Projects.edit permission","operationId":"ProjectInterimPaymentsController_deleteInterimPayment","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Interim payment deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Interim payment not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete interim payment","tags":["projects","project-settings","billing","interim-payments"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/interim-payments/sort":{"post":{"description":"Updates the sort order of interim payments by providing a new ordered list of payment IDs.\n\n**How reordering works:**\n- Provide an array of payment IDs in the desired display order\n- The first ID in the array gets sort order 0, the second gets 1, and so on\n- Payments not included in the array retain their current sort order\n- This affects the order in which payments appear in list responses\n\n**Example:**\nTo display payments in order: Payment A, Payment C, Payment B\nSend: { \"paymentIds\": [\"id-of-A\", \"id-of-C\", \"id-of-B\"] }\n\n**Validation:**\n- All payment IDs must be valid UUIDs\n- All payment IDs must belong to the specified project\n- Array cannot be empty\n\n**Use cases:**\n- Organize payments chronologically (e.g., first payment, second payment, final payment)\n- Group related payments together\n- Prioritize certain payments in the display\n\n**Permissions:** Requires Projects.edit permission","operationId":"ProjectInterimPaymentsController_sortInterimPayments","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortInterimPaymentsDto"}}}},"responses":{"200":{"description":"Interim payments reordered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder interim payments","tags":["projects","project-settings","billing","interim-payments"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/manual-positions":{"get":{"description":"**What are Manual Positions?**\nManual positions are extra costs that do not come from the product catalog. They are used to bill for external costs, third-party services, flat fees, and other expenses that fall outside the automatic system logic. Typical examples include printing costs, translation services, license fees, travel expenses, or one-time flat rates.\n\nManual positions are part of the project planning process and will appear in project quotes and invoices. They can be categorized, discounted, and reordered as needed.\n\n**What this endpoint returns:**\n- All active manual positions for the specified project\n- Positions are sorted by their sort order (ascending)\n- Only current positions are returned (snapshot positions are excluded)\n- Descriptions are returned as HTML (converted from internal IDoc format)\n\n**Permission requirements:**\n- Requires read access to the project\n- Requires api:read scope\n\n**Use cases:**\n- Display manual positions in project planning interface\n- Show billable items that will appear in quotes and invoices\n- Review project cost breakdown before creating offers","operationId":"ProjectManualPositionsController_listManualPositions","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManualPositionResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all manual positions for a project","tags":["projects"],"x-required-scopes":["api:read"]},"post":{"description":"**What this endpoint does:**\nCreates a new manual position (billable item) for a project. Manual positions represent extra costs that are not automatically tracked by the system, such as external services, third-party expenses, or one-time fees.\n\n**How it works:**\n- The position is added to the project's current planning\n- Sort order is automatically assigned (new positions are added at the end)\n- Description can be provided as HTML or Markdown (automatically converted to internal format)\n- The position can optionally be assigned to a category for better organization\n- Once created, the position will appear in project quotes and invoices\n\n**Description format:**\n- Accepts HTML or Markdown format\n- The system automatically detects the format and converts it to internal IDoc format\n- Empty descriptions are allowed (will be stored as empty IDoc)\n- In responses, descriptions are always returned as HTML\n\n**Validation rules:**\n- Name is required and must not be empty\n- Price must be a number greater than or equal to 0\n- Category ID must be a valid UUID if provided\n- Project must exist and user must have access\n\n**Permission requirements:**\n- Requires Projects.manageManualPositions permission\n- Requires api:write scope\n- Requires read access to the project\n\n**Use cases:**\n- Add external costs like printing or translation services\n- Record one-time fees that are not in the product catalog\n- Include retroactive charges or corrections to existing offers\n- Add services that happened outside the operational project structure","operationId":"ProjectManualPositionsController_createManualPosition","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateManualPositionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualPositionResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new manual position","tags":["projects"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/manual-positions/{id}":{"patch":{"description":"**What this endpoint does:**\nUpdates an existing manual position. Supports partial updates - you only need to provide the fields you want to change.\n\n**How partial updates work:**\n- Only provided fields are updated\n- Fields not included in the request remain unchanged\n- To remove a category, set categoryId to null\n- Description can be updated with new HTML or Markdown content\n\n**Description updates:**\n- If description is provided, it will be converted from HTML/Markdown to internal IDoc format\n- If description is not provided, the existing description remains unchanged\n- Empty descriptions are allowed\n\n**Validation rules:**\n- Position must exist and belong to the specified project\n- Name must not be empty if provided\n- Price must be greater than or equal to 0 if provided\n- Category ID must be a valid UUID if provided (or null to remove)\n- Project must exist and user must have access\n\n**Permission requirements:**\n- Requires Projects.manageManualPositions permission\n- Requires api:write scope\n- Requires read access to the project\n\n**Use cases:**\n- Correct pricing or descriptions\n- Update position details before creating quotes\n- Reassign positions to different categories\n- Modify positions based on client feedback","operationId":"ProjectManualPositionsController_updateManualPosition","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchManualPositionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManualPositionResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update an existing manual position","tags":["projects"],"x-required-scopes":["api:write"]},"delete":{"description":"**What this endpoint does:**\nSoft deletes a manual position by setting the deletedAt timestamp. The position is not permanently removed from the database but is hidden from normal queries and will not appear in project quotes or invoices.\n\n**How soft deletion works:**\n- The position is marked as deleted with a timestamp\n- It remains in the database for historical reference\n- Deleted positions are excluded from list queries\n- The position can be referenced in historical project snapshots\n\n**Validation rules:**\n- Position must exist and belong to the specified project\n- Project must exist and user must have access\n\n**Permission requirements:**\n- Requires Projects.manageManualPositions permission\n- Requires api:write scope\n- Requires read access to the project\n\n**Use cases:**\n- Remove positions that are no longer needed\n- Clean up project planning before finalizing quotes\n- Remove incorrectly added positions","operationId":"ProjectManualPositionsController_deleteManualPosition","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete a manual position","tags":["projects"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/manual-positions/sort":{"post":{"description":"**What this endpoint does:**\nUpdates the sort order of manual positions within a project. The order determines how positions appear in project planning views, quotes, and invoices.\n\n**How reordering works:**\n- Provide an array of position IDs in the desired display order\n- The first ID in the array will have sort order 0, the second will have sort order 1, and so on\n- All positions must belong to the specified project\n- Positions not included in the array will maintain their current sort order (but may appear after the reordered positions)\n\n**Validation rules:**\n- All position IDs must be valid UUIDs\n- All positions must belong to the specified project\n- Project must exist and user must have access\n- Duplicate IDs are not allowed\n\n**Permission requirements:**\n- Requires Projects.manageManualPositions permission\n- Requires api:write scope\n- Requires read access to the project\n\n**Use cases:**\n- Organize positions by importance or category\n- Group related positions together\n- Control the order in which positions appear in quotes and invoices\n- Improve readability of project planning overview","operationId":"ProjectManualPositionsController_sortManualPositions","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortManualPositionsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder manual positions","tags":["projects"],"x-required-scopes":["api:write"]}},"/projects/journal":{"get":{"description":"Retrieves a paginated grid of project journal entries with filtering and sorting capabilities. Filterable fields: id, projectId, createdAt, createdBy, mood, reminder. Sortable fields: id, projectId, createdAt, createdBy, mood, reminder.\n\n**What are Project Journals?**\nProject journals are chronological records of important project events, observations, feedback, risks, and internal notes. They act as a timeline-based memory for projects, helping stakeholders track developments, assess communication, and prevent knowledge loss.\n\n**What is returned:**\n- Journal entry identification (ID, projectId)\n- Content (body as HTML, mood indicator)\n- Metadata (createdAt, createdBy, lastUpdated)\n- Optional reminder date for follow-ups\n\n**Journal Entry Features:**\n- **Mood indicators**: Sad (negative reactions, problems), Neutral (factual observations), Happy (positive feedback, wins)\n- **Rich text content**: Supports formatted text with paragraphs, highlighting, and structuring\n- **Reminder function**: Optional date-based reminders for follow-ups or review points\n\n**Filtering and search:**\n- Filter by projectId to view entries for a specific project\n- Filter by mood, creation date, creator, or reminder date\n- Sort by any sortable field (default: createdAt descending)\n- Server-side pagination for large journal lists\n\n**Permissions:**\nAutomatically filters journal entries based on user permissions. Users without Projects.seeAnyProject permission will only see journal entries for projects they have access to.","operationId":"ProjectsJournalController_listProjectJournals","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Journal entry ID\n- **projectId** (string): Project ID\n- **createdAt** (date): Journal entry creation timestamp\n- **createdBy** (string): Creator user ID\n- **mood** (set): Journal entry mood\n- **reminder** (date): Reminder date\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Journal entry ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Journal entry creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **createdBy** (string): Creator user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **mood** (set): Journal entry mood (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **reminder** (date): Reminder date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Journal entry ID\n- **projectId**: Project ID\n- **createdAt**: Journal entry creation timestamp\n- **createdBy**: Creator user ID\n- **mood**: Journal entry mood\n- **reminder**: Reminder date\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, projectId, createdAt, createdBy, mood, reminder, body","schema":{"example":"id,projectId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of project journal entries"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List project journal entries","tags":["projects","journal","projects"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new project journal entry to document important project events, observations, feedback, or notes.\n\n**What to include:**\n- **projectId** (required): The UUID of the project this entry belongs to\n- **body** (required): The journal entry content in HTML or Markdown format. Supports rich text formatting including paragraphs, headings, highlighting, and lists\n- **mood** (optional): Mood indicator - Sad (problems/escalations), Neutral (factual), or Happy (wins/progress). Defaults to Neutral if not provided\n- **reminder** (optional): ISO 8601 date string for setting a reminder about this entry\n\n**Common use cases:**\n- Documenting customer feedback or complaints\n- Recording internal findings and observations\n- Capturing important conversations or decisions\n- Noting risks or opportunities\n- Tracking project mood and sentiment over time\n\n**Validation:**\n- The projectId must exist and be accessible to the authenticated user\n- Body content cannot be empty\n- Reminder date must be a valid ISO 8601 date string\n\n**What is returned:**\nThe complete created journal entry with all fields populated, including the body converted to HTML format.","operationId":"ProjectsJournalController_createProjectJournal","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectJournalResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"projectId":["Project ID is required"],"body":["Body content is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create project journal entry","tags":["projects","journal","projects"],"x-required-scopes":["api:write"]}},"/projects/journal/{id}":{"get":{"description":"Returns complete details for a specific project journal entry, including the full formatted content.\n\n**What is returned:**\n- Journal entry identification (ID, projectId)\n- Complete body content converted to HTML format with all formatting preserved\n- Mood indicator (Sad, Neutral, or Happy)\n- Creation metadata (createdAt, createdBy)\n- Last update timestamp (lastUpdated)\n- Optional reminder date (null if not set)\n\n**Use cases:**\n- Displaying a full journal entry in detail view\n- Editing an existing entry (use this to get current values before updating)\n- Retrieving formatted content for display in external systems\n\n**Note:** Returns 404 if the journal entry does not exist, has been deleted, or is not a project journal entry.","operationId":"ProjectsJournalController_getProjectJournalDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project journal entry details","tags":["projects","journal","projects"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates one or more fields of an existing project journal entry. Only provided fields will be updated; all other fields remain unchanged.\n\n**What can be updated:**\n- **projectId**: Move the entry to a different project (must be accessible to user)\n- **body**: Update the journal entry content (HTML or Markdown format)\n- **mood**: Change the mood indicator (Sad, Neutral, or Happy)\n- **reminder**: Update or set a reminder date (ISO 8601 format). Set to null to clear an existing reminder\n\n**Update behavior:**\n- All fields are optional - only include fields you want to change\n- If a field is not provided, its current value is preserved\n- For reminder: provide a date string to set/update, or null to clear\n- The lastUpdated timestamp is automatically updated when any field changes\n\n**Validation:**\n- If projectId is provided, it must exist and be accessible to the authenticated user\n- Body content cannot be empty if provided\n- Reminder date must be a valid ISO 8601 date string if provided\n\n**What is returned:**\nThe complete updated journal entry with all fields, including the body converted to HTML format.","operationId":"ProjectsJournalController_patchProjectJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectJournalResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update project journal entry","tags":["projects","journal","projects"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a project journal entry. The entry is marked as deleted and will no longer appear in list queries, but it is not permanently removed from the database.\n\n**Deletion behavior:**\n- The entry is marked with a deletedAt timestamp\n- Deleted entries do not appear in the list endpoint results\n- The entry data remains in the database for audit purposes\n- This operation cannot be undone through the API\n\n**Note:** Returns 404 if the journal entry does not exist, has already been deleted, or is not a project journal entry.","operationId":"ProjectsJournalController_deleteProjectJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete project journal entry","tags":["projects","journal","projects"],"x-required-scopes":["api:write"]}},"/projects/uploads":{"get":{"description":"Retrieves a paginated grid of project uploads with filtering and sorting capabilities. Quick search available on: fileName, description. Filterable fields: id, projectId, fileId, fileName, description, categoryId, mimeType, fileSize, userId, updatedAt. Sortable fields: id, projectId, fileId, fileName, description, categoryId, mimeType, fileSize, userId, updatedAt.\n\n**What are Project Uploads?**\nProject uploads allow you to centrally manage project-related files within Leadtime. This feature provides organized storage for documents like contracts, offers, technical specifications, or internal notes directly within project context, eliminating the need to search through external folders.\n\n**What is returned:**\n- Upload identification (ID, project ID, file ID)\n- File information (filename, MIME type, file size in bytes)\n- Organization details (description, category ID)\n- User information (user ID who created or last updated the upload)\n- Timestamps (creation and last update dates)\n\n**Filtering and search:**\n- Quick search across file name and description fields\n- Advanced filtering by project ID, category, file type, user, and more\n- Sorting by any sortable field (default: updatedAt descending)\n- Server-side pagination for large upload lists\n\n**Access control:**\nThis endpoint automatically filters uploads based on project access permissions:\n- Users with Projects.seeAnyProject permission see all uploads across all projects\n- Other users see only uploads from projects they have access to\n- Optional filtering by projectId via grid filters allows focusing on specific projects\n\n**Note:** This endpoint requires the Projects.manageUploads permission.","operationId":"ProjectUploadsController_listProjectUploads","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: fileName, description","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Upload ID\n- **projectId** (set): Project ID\n- **fileId** (string): File ID\n- **fileName** (string): File name\n- **description** (string): Upload description\n- **categoryId** (set): Category ID\n- **mimeType** (string): MIME type\n- **fileSize** (number): File size in bytes\n- **userId** (set): User ID who created the upload\n- **updatedAt** (date): Last update timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Upload ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (set): Project ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **fileId** (string): File ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **fileName** (string): File name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **description** (string): Upload description (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **categoryId** (set): Category ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **mimeType** (string): MIME type (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **fileSize** (number): File size in bytes (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **userId** (set): User ID who created the upload (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **updatedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Upload ID\n- **projectId**: Project ID\n- **fileId**: File ID\n- **fileName**: File name\n- **description**: Upload description\n- **categoryId**: Category ID\n- **mimeType**: MIME type\n- **fileSize**: File size in bytes\n- **userId**: User ID who created the upload\n- **updatedAt**: Last update timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** updatedAt (desc)","schema":{"example":"[{\"field\":\"updatedAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, projectId, fileId, fileName, description, categoryId, mimeType, fileSize, userId, updatedAt","schema":{"example":"id,projectId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of project uploads"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List project uploads","tags":["projects","uploads","projects"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new project upload record, linking an uploaded file to a project.\n\n**How to upload files:**\n1. First, upload the file using POST /workspace/upload to obtain a fileId\n2. Then use that fileId in this endpoint to create the project upload record\n\n**Required fields:**\n- projectId: The project to attach the upload to (must exist and user must have access)\n- fileId: The file ID from the workspace upload endpoint (must exist in workspace)\n\n**Optional fields:**\n- description: Free text field for classifying the content (e.g., \"Signed contract 10/28/2025\", \"Kickoff protocol\")\n- categoryId: Thematic classification for organizing uploads (e.g., Contract, Offer, Documentation)\n\n**Validation:**\n- Project must exist and belong to the workspace\n- User must have access to the project\n- File must exist and belong to the workspace\n- Category must exist and belong to the workspace (if provided)\n\n**What is returned:**\nComplete upload details including file metadata, timestamps, and user information.\n\n**Note:** This endpoint requires the Projects.manageUploads permission.","operationId":"ProjectUploadsController_createProjectUpload","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectUploadDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUploadResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"projectId":["Project ID is required"],"fileId":["File ID is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create project upload","tags":["projects","uploads","projects"],"x-required-scopes":["api:write"]}},"/projects/uploads/{id}":{"get":{"description":"Retrieves complete details for a specific project upload, including all file metadata and organization information.\n\n**What is returned:**\n- Upload identification (ID, project ID, file ID)\n- File metadata (filename, MIME type, file size in bytes)\n- Organization details (description, category ID)\n- User information (user ID who created the upload)\n- Timestamps (creation and last update dates in ISO 8601 format)\n\n**Note:** This endpoint requires the Projects.manageUploads permission. Only uploads from projects the user has access to can be retrieved.","operationId":"ProjectUploadsController_getProjectUploadDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUploadResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project upload details","tags":["projects","uploads","projects"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates specific fields of an existing project upload. Only provided fields are updated; all fields are optional.\n\n**What can be updated:**\n- projectId: Change which project the upload belongs to (must exist and user must have access)\n- description: Update the description text (set to null to clear)\n- categoryId: Change or remove the category (set to null to remove category assignment)\n\n**Note:** The file itself cannot be changed. To replace a file, delete the upload and create a new one.\n\n**Validation:**\n- Upload must exist and belong to the workspace\n- If projectId is provided, project must exist and user must have access\n- If categoryId is provided, category must exist and belong to the workspace\n\n**What is returned:**\nComplete updated upload details including all current field values.\n\n**Note:** This endpoint requires the Projects.manageUploads permission.","operationId":"ProjectUploadsController_patchProjectUpload","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectUploadDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUploadResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update project upload","tags":["projects","uploads","projects"],"x-required-scopes":["api:write"]},"delete":{"description":"Removes a project upload from the project. This performs a soft delete, meaning the upload is marked as deleted but not permanently removed from the database. The file itself remains in the workspace file storage.\n\n**What happens:**\n- The upload record is marked as deleted (deletedAt timestamp is set)\n- The upload no longer appears in project upload lists\n- The underlying file remains in workspace storage\n\n**Validation:**\n- Upload must exist and belong to the workspace\n- User must have access to the project containing the upload\n\n**Note:** This endpoint requires the Projects.manageUploads permission.","operationId":"ProjectUploadsController_deleteProjectUpload","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete project upload","tags":["projects","uploads","projects"],"x-required-scopes":["api:write"]}},"/projects/{id}/document-settings":{"get":{"description":"Returns document settings for a specific project including current values and inherited defaults from organization/workspace hierarchy.\n\n**What are Project Document Settings?**\nProject document settings control formatting options and contact information for automatically generated documents such as proposals, contracts, requirement specifications, and other project documents. These settings can override organization/workspace defaults on a per-project basis, allowing you to customize document appearance and structure for specific projects.\n\n**Settings Overview:**\n- **Title Page**: Controls whether generated documents include a title page\n- **Table of Contents**: Determines if an automatically generated table of contents is embedded (especially helpful for long documents)\n- **Heading Style**: Controls the numbering and formatting of headings (Normal, Sequential, SequentialFromSecondLevel, SequentialWithParagraphs)\n- **Default Contact Person**: Sets the contact person automatically when creating new documents (useful for recurring offer processes and automated preambles)\n\n**Inheritance System:**\nSettings support a three-level inheritance hierarchy:\n1. **Project-level settings**: Project-specific overrides (null = inherit from organization)\n2. **Organization-level defaults**: Organization-specific defaults (null = inherit from workspace)\n3. **Workspace-level defaults**: Global workspace defaults\n\nThe response includes both current project values and the inherited defaults from the organization/workspace hierarchy. Null values in current settings indicate that the project inherits from organization/workspace defaults. The \"*Default\" fields show what values are inherited when project settings are null.","operationId":"ProjectDocumentSettingsController_getDocumentSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetProjectDocumentSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project document settings","tags":["projects","project-settings"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates document settings for a specific project. All fields are optional - only provided fields will be updated.\n\n**What are Project Document Settings?**\nProject document settings control formatting options and contact information for automatically generated documents such as proposals, contracts, requirement specifications, and other project documents. These settings can override organization/workspace defaults on a per-project basis.\n\n**Settings You Can Update:**\n- **projectDocumentTitlePage**: Enable/disable title page for generated documents (null = use organization standard)\n- **projectDocumentEnableToc**: Enable/disable table of contents in generated documents (null = use organization standard)\n- **projectDocumentHeadingStyle**: Set heading numbering style (null = use organization standard)\n - Normal: No numbering\n - Sequential: Numbering from level 1\n - SequentialFromSecondLevel: Numbering from level 2\n - SequentialWithParagraphs: Numbering with symbol prefix (e.g., Β§)\n- **projectDocumentDefaultContactUserId**: Set default contact person UUID for new documents (null = use organization standard or no default)\n\n**Inheritance Behavior:**\nSetting any field to null enables inheritance from organization/workspace defaults. This allows you to override organization settings for specific projects or revert to using organization standards.\n\n**Use Cases:**\n- Customize document formatting for specific project types\n- Set project-specific contact persons for recurring offer processes\n- Override organization defaults when needed\n- Revert to organization standards by setting fields to null","operationId":"ProjectDocumentSettingsController_updateDocumentSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectDocumentSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update project document settings","tags":["projects","project-settings"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/subscription-billings":{"get":{"description":"**What are Project Subscription Billings?**\nProject Subscription Billings allow you to manage recurring fees and charges for projects. This feature is ideal for SaaS subscriptions, maintenance contracts, support packages, or any recurring billing arrangement. The system automatically generates billing rows based on your date range and frequency settings, which can then be included in invoices.\n\n**What data is returned:**\n- All active subscription billing items for the specified project\n- Items are sorted by their sort order (display order)\n- Each item includes date range, payment type, price, frequency, and configuration details\n\n**Payment types supported:**\n- **fixed**: Fixed monthly fee (e.g., $500/month support package)\n- **perUnit**: Variable pricing based on units (e.g., per user, per license)\n- **oneTime**: One-time charge within the subscription period\n\n**Use cases:**\n- Retrieve all recurring billing items for a project\n- Display subscription information in project dashboards\n- Generate reports on recurring revenue\n- Audit subscription configurations","operationId":"ProjectSubscriptionBillingsController_listSubscriptionBillings","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription billings retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSubscriptionBillingResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found or access denied"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List project subscription billings","tags":["projects","project-settings","billing","subscriptions"],"x-required-scopes":["api:read"]},"post":{"description":"**What this endpoint does:**\nCreates a new recurring subscription billing item for a project. The system automatically generates billing rows for each billing period based on your date range and frequency settings. These rows can later be included in invoices.\n\n**How it works:**\n1. Specify the date range (fromDate to toDate) for when the subscription is active\n2. Set the frequency (1-12 months) to determine billing intervals:\n - 1 = monthly billing\n - 3 = quarterly billing\n - 6 = semi-annual billing\n - 12 = yearly billing\n3. Choose the payment type:\n - **fixed**: Fixed amount per period (e.g., $500/month)\n - **perUnit**: Variable pricing (e.g., $50 per user per month)\n - **oneTime**: One-time charge (requires quantity field)\n4. The system automatically:\n - Calculates sort order (display position)\n - Generates billing rows for each period within the date range\n - Creates date keys for invoice matching\n\n**Validation rules:**\n- fromDate must be before or equal to toDate\n- Price must be positive\n- Frequency must be between 1 and 12 months\n- Quantity is required for oneTime payment type\n\n**Permissions required:**\n- Projects.edit: Ability to edit project settings\n- Invoices.manage: Ability to manage invoice configurations\n\n**Example use cases:**\n- Set up monthly support package subscription\n- Configure quarterly maintenance contract\n- Add yearly license renewal\n- Create variable pricing based on usage","operationId":"ProjectSubscriptionBillingsController_createSubscriptionBilling","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectSubscriptionBillingDto"}}}},"responses":{"201":{"description":"Subscription billing created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid date range, frequency, or other validation error"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions (requires Projects.edit and Invoices.manage)"},"404":{"description":"Project not found or access denied"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create project subscription billing","tags":["projects","project-settings","billing","subscriptions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/subscription-billings/{id}":{"patch":{"description":"**What this endpoint does:**\nPartially updates an existing subscription billing item. You can update any combination of fields without providing all values. The system automatically regenerates billing rows if the date range or frequency changes.\n\n**How updates work:**\n- Only provide the fields you want to change (all fields are optional)\n- If you update fromDate, toDate, or frequency, the system will:\n - Delete unbilled billing rows\n - Regenerate billing rows based on new date range and frequency\n - Preserve already billed rows (they are not affected)\n- Other fields (price, title, payment type) update immediately without regenerating rows\n\n**Important notes:**\n- If updating both fromDate and toDate, ensure fromDate is before or equal to toDate\n- Changing frequency will affect all future billing periods\n- Already billed rows remain unchanged\n- Sort order is preserved unless explicitly changed\n\n**Permissions required:**\n- Projects.edit: Ability to edit project settings\n- Invoices.manage: Ability to manage invoice configurations\n\n**Example use cases:**\n- Extend subscription end date\n- Change billing frequency (e.g., from monthly to quarterly)\n- Update subscription price\n- Modify subscription title or description\n- Change payment type","operationId":"ProjectSubscriptionBillingsController_updateSubscriptionBilling","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectSubscriptionBillingDto"}}}},"responses":{"200":{"description":"Subscription billing updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid date range, frequency, or other validation error"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions (requires Projects.edit and Invoices.manage)"},"404":{"description":"Project or subscription billing not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update project subscription billing","tags":["projects","project-settings","billing","subscriptions"],"x-required-scopes":["api:write"]},"delete":{"description":"**What this endpoint does:**\nSoft deletes a subscription billing item. The item is marked as deleted and will no longer appear in listings or be included in future invoice generation. However, the data is retained in the database for historical records and audit purposes.\n\n**What happens when deleted:**\n- The subscription billing item is marked with a deletedAt timestamp\n- It disappears from all active listings and queries\n- Already billed rows remain unchanged (historical invoices are not affected)\n- Unbilled billing rows are effectively cancelled\n- The item can be restored if needed (though not through this API)\n\n**Permissions required:**\n- Projects.edit: Ability to edit project settings\n- Invoices.manage: Ability to manage invoice configurations\n\n**Use cases:**\n- Cancel an active subscription\n- Remove a subscription that is no longer needed\n- Clean up test or incorrect subscription entries","operationId":"ProjectSubscriptionBillingsController_deleteSubscriptionBilling","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription billing deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions (requires Projects.edit and Invoices.manage)"},"404":{"description":"Project or subscription billing not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete project subscription billing","tags":["projects","project-settings","billing","subscriptions"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/subscription-billings/products-from-snapshot":{"get":{"description":"**What this endpoint does:**\nReturns products from the current billing snapshot for Single type projects. These products represent what will be used for invoice generation and show how invoice rows will be formed.\n\n**What data is returned:**\n- Products from the billing snapshot (productsBillingProjectSnapshotId or billingProjectSnapshotId)\n- Only for Single type projects\n- Products are sorted by their sort order\n- Includes product details: name, prices, quantities, active dates, etc.\n\n**Use cases:**\n- Display products that will be used for billing\n- Preview how invoice rows will be formed\n- Show read-only product information for subscription billing","operationId":"ProjectSubscriptionBillingsController_getProductsFromBillingSnapshot","parameters":[{"name":"projectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Products retrieved successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found or access denied"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get products from billing snapshot","tags":["projects","project-settings","billing","subscriptions"],"x-required-scopes":["api:read"]}},"/projects/{projectId}/products":{"get":{"description":"Returns an array of product summary objects for a project. Products are sorted by sort field (ascending) and only non-deleted products are returned.\n\nProducts in Leadtime are standardized services or items from the product catalog that have been imported into a project. They can represent one-time purchases, subscriptions, or quantity-based services. Each product includes pricing information, quantity, active date ranges, and calculated final prices based on selected variants and options.\n\nThe response includes:\n- Product identification (id, name, finalName)\n- Category and logo information\n- Quantity and pricing (fixed, subscription, per-unit)\n- Final calculated prices (includes variant and option adjustments)\n- Active date range (activeFrom, activeTo, isActive flag)","operationId":"ProjectProductsController_listProducts","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Products retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectProductResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Project does not exist"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all products in a project","tags":["projects","products"],"x-required-scopes":["api:read"]},"post":{"description":"Imports a standardized product from the product catalog into a project. The product is copied into the project, allowing project-specific configuration without affecting the original catalog entry.\n\n**How it works:**\n1. Select a product from the catalog by providing its productId\n2. Set the quantity for this product in the project\n3. Optionally select an active variant (e.g., Standard, Pro, Enterprise)\n4. Select any required options and optional add-ons\n\n**Product Isolation:**\nWhen imported, the product becomes a copy within the project. Any subsequent changes to the product in this project do not affect the original catalog entry. This ensures historical accuracy for quotes and invoices.\n\n**Pricing:**\nThe final price is calculated based on:\n- Base product pricing (fixed, subscription, or per-unit)\n- Selected variant pricing adjustments\n- Selected option value extra pricing\n- Quantity multiplier\n\n**Required fields:**\n- productId: UUID of the catalog product to import\n- quantity: Minimum 1\n- options: Array of option selections (can be empty array)\n\n**Optional fields:**\n- activeVariantId: UUID of the variant to activate\n\nReturns the ID of the newly created product in the project.","operationId":"ProjectProductsController_importProductToProject","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportProductToProjectDto"}}}},"responses":{"201":{"description":"Product imported successfully","schema":{"example":{"success":true,"id":"550e8400-e29b-41d4-a716-446655440000"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad Request - Invalid input or validation error"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Catalog product or project does not exist"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Import product from catalog","tags":["projects","products"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/products/{productId}":{"get":{"description":"Returns full product details including variants, options, and HTML-formatted description.\n\nThis endpoint provides complete information about a product in a project, including:\n\n**Product Information:**\n- Basic details (name, description as HTML, category, logo)\n- Pricing structure (fixed price, subscription price, per-unit price)\n- Price calculation details (unit name, frequency, final calculated prices)\n- Quantity and active date ranges\n\n**Variants:**\n- All available product variants (e.g., Standard, Pro, Enterprise)\n- Each variant includes its own pricing and HTML-formatted description\n- Active variant status and sort order\n\n**Options:**\n- All available product options (add-ons or configuration choices)\n- Option values with extra pricing adjustments\n- Required/multiple selection settings\n\nThe description and variant descriptions are returned as HTML, converted from the internal document format.","operationId":"ProjectProductsController_getProductDetails","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","description":"Product ID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Product details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectProductDetailsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Product or project does not exist"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get product details","tags":["projects","products"],"x-required-scopes":["api:read"]},"delete":{"description":"Soft deletes a product from a project by setting the deletedAt timestamp. The product is not permanently removed, but is hidden from product lists and excluded from calculations.\n\n**Soft Delete Behavior:**\n- Product is marked as deleted with a timestamp\n- Product no longer appears in list endpoints\n- Product is excluded from price calculations\n- Historical data is preserved for audit purposes\n\n**Note:** This only removes the product from the project. The original catalog product remains unchanged.","operationId":"ProjectProductsController_deleteProduct","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","description":"Product ID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Product deleted successfully","schema":{"example":{"success":true}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Product or project does not exist"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete product from project","tags":["projects","products"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/products/{productId}/settings":{"post":{"description":"Updates only product configuration settings without modifying product details. This endpoint is designed for quick updates to how a product is used in a project, without changing the product itself.\n\n**What gets updated:**\n- quantity: How many units of this product are in the project\n- activeVariantId: Which variant is currently active (e.g., Standard vs Pro)\n- options: Which option values are selected (e.g., color, add-ons)\n\n**What does not get updated:**\n- Product name, description, category, or logo\n- Base pricing (priceFixed, priceSubscription, pricePerUnit)\n- Variant definitions or option definitions\n- Active date ranges\n\n**Use cases:**\n- Customer changes their mind about variant selection\n- Adjusting quantity after initial import\n- Adding or removing optional add-ons\n- Quick configuration changes without full product edit\n\n**Pricing Impact:**\nChanging quantity, variant, or options will affect the final calculated prices, but the base product pricing structure remains unchanged.","operationId":"ProjectProductsController_updateProductSettings","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","description":"Product ID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSettingsDto"}}}},"responses":{"200":{"description":"Product settings updated successfully","schema":{"example":{"success":true}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad Request - Invalid input or validation error"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Product or project does not exist"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update product settings","tags":["projects","products"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/products/{productId}/duplicate":{"post":{"description":"Creates a copy of an existing product within the same project. Useful when you need the same product multiple times with different configurations or for different time periods.\n\n**What gets duplicated:**\n- All product details (name, description, category, logo)\n- All pricing information\n- All variants and their configurations\n- All options and option values\n- Current quantity and settings\n\n**Use cases:**\n- Same product with different active date ranges\n- Same product with different variant/option selections\n- Multiple instances of a product in one project\n\nReturns the ID of the newly created duplicate product.","operationId":"ProjectProductsController_duplicateProduct","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}},{"name":"productId","required":true,"in":"path","description":"Product ID to duplicate","schema":{"format":"uuid","type":"string"}}],"responses":{"201":{"description":"Product duplicated successfully","schema":{"example":{"success":true,"id":"550e8400-e29b-41d4-a716-446655440001"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Product or project does not exist"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Duplicate product","tags":["projects","products"],"x-required-scopes":["api:write"]}},"/projects/{projectId}/products/sort":{"post":{"description":"Updates the sort order for multiple products in a project. Products are displayed in the order specified by the provided array of product IDs.\n\n**How it works:**\n1. Provide an array of product IDs in the desired display order\n2. The first ID in the array will have the lowest sort value\n3. Subsequent IDs receive incrementally higher sort values\n4. Products not included in the array retain their current sort order\n\n**Requirements:**\n- All product IDs must belong to the specified project\n- All product IDs must be valid UUIDs\n- Array must contain at least one product ID\n\n**Use cases:**\n- Reorganizing product list for better presentation\n- Grouping related products together\n- Prioritizing important products at the top","operationId":"ProjectProductsController_reorderProducts","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSortDto"}}}},"responses":{"200":{"description":"Products reordered successfully","schema":{"example":{"success":true}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad Request - Invalid input"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient permissions or no project access"},"404":{"description":"Not Found - Project does not exist"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder products","tags":["projects","products"],"x-required-scopes":["api:write"]}},"/projects/{id}/versions":{"get":{"description":"Returns a list of all saved project versions (snapshots) with their details.\n\n**What are Project Versions?**\nProject versions freeze the current state of a project configuration at a specific point in time. They capture the complete project state including:\n- Project tree structure with dynamically activated work packages\n- Products including variants, prices, and discounts\n- Answered form questions and their effects\n- Manually added items\n- All configuration changes\n\nVersions ensure that offered, negotiated, and contracted content remains traceable. They serve as the basis for quotes, specifications, and billing documents.\n\n**What is returned:**\n- **id**: Unique version identifier (UUID)\n- **title**: Version title/name\n- **semverVersion**: Semantic version string (e.g., \"1.2.3\")\n- **branchId**: Branch identifier for version tracking\n- **parentId**: Parent version ID (null for first version)\n- **createdAt**: ISO 8601 timestamp when version was created\n- **createdBy**: User ID who created the version\n- **description**: HTML-formatted version description\n- **isCurrent**: Whether this is the current active version for the project\n\n**Use cases:**\n- View version history to see how project evolved\n- Select a version when creating quotes or specifications\n- Compare different project states\n- Restore to a previous version if needed","operationId":"ProjectVersionsController_listVersions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of project versions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectVersionDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all versions for a project","tags":["projects","versions"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new version (snapshot) of the current project configuration state.\n\n**What gets saved:**\nThe version captures the complete project state at the time of creation:\n- Project tree structure with all components and work packages\n- Products including variants, prices, and discounts\n- Answered form questions and their effects\n- Manually added items\n- All configuration changes\n\n**How to use:**\n1. Make changes to your project configuration\n2. Call this endpoint with a descriptive title\n3. Optionally provide a description in HTML or Markdown format\n4. The version is created and becomes the current active version\n\n**Best practices:**\n- Create versions after filling out questionnaires or making structural changes\n- Create a version before sending out offers\n- Use clear, descriptive version titles\n- Create variants when customers want to compare alternatives\n\n**Required permissions:** Projects.manageSnapshots permission is required to create versions.","operationId":"ProjectVersionsController_createVersion","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectVersionDto"}}}},"responses":{"200":{"description":"Created version with description as HTML","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectVersionDto"}}}},"400":{"description":"Invalid input"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new project version","tags":["projects","versions"],"x-required-scopes":["api:write"]}},"/projects/{id}/versions/{versionId}":{"get":{"description":"Returns complete details for a specific project version, including estimate data.\n\n**What is returned:**\n- All standard version fields (id, title, semverVersion, branchId, parentId, createdAt, createdBy, description, isCurrent)\n- **estimateData**: Complete estimate data including:\n - Products with variants, prices, and discounts\n - Components with nested structure\n - Manual positions\n - Pricing breakdowns (fixed, subscriptions, per-unit)\n\n**Use cases:**\n- View detailed version information\n- Access estimate data for a specific version\n- Compare estimate data between versions\n- Use version data for generating documents or reports","operationId":"ProjectVersionsController_getVersionDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Version details with estimate data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectVersionDetailsDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Version or project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get version details","tags":["projects","versions"],"x-required-scopes":["api:read"]}},"/projects/{id}/versions/{versionId}/restore":{"post":{"description":"Restores the project configuration to the state of a previously saved version. This is a destructive operation that replaces the current project state.\n\n**What happens:**\n- The current project configuration is replaced with the selected version\n- All current components, products, and manual positions are removed\n- The project state is restored to exactly match the saved version\n- The restored version becomes the current active version\n\n**Warning:**\nThis operation cannot be undone. All unsaved changes will be lost. Make sure to create a new version of the current state before restoring if you want to preserve it.\n\n**Use cases:**\n- Rollback to a previous version after unwanted changes\n- Restore a project variant for comparison\n- Revert to a stable configuration\n\n**Required permissions:** Projects.manageSnapshots permission is required to restore versions.","operationId":"ProjectVersionsController_restoreVersion","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Version restored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Version or project not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Restore project to a previous version","tags":["projects","versions"],"x-required-scopes":["api:write"]}},"/projects/{id}/configuration-state":{"get":{"description":"Returns the current state of the project configuration, including version information and change tracking.\n\n**What is returned:**\n- **lastConfigurationSnapshot**: Information about the last saved version (id, version, createdAt, title)\n- **configurationChanged**: Whether the project configuration has changed since the last version was saved\n- **configurationChangedAt**: ISO 8601 timestamp when configuration last changed (null if unchanged)\n- **productCount**: Number of products in the project\n- **componentCount**: Number of components in the project\n- **manualPositionCount**: Number of manual positions in the project\n- **discountCount**: Number of discounts applied\n- **snapshotCount**: Total number of versions saved for the project\n- **documentCount**: Number of documents associated with the project\n\n**Use cases:**\n- Check if there are unsaved changes (configurationChanged flag)\n- Get overview of project contents\n- Determine if a new version should be created\n- View version history count","operationId":"ProjectConfigurationStateController_getConfigurationState","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Project configuration state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfigurationStateDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get current project configuration state","tags":["projects","versions"],"x-required-scopes":["api:read"]}},"/projects":{"get":{"description":"Returns a paginated, filterable list of all projects in the workspace.\n\n**What are Projects?**\nProjects are the central organizational unit in Leadtime. Every task, time booking, and activity is associated with a project. Projects can be either internal (company activities) or external (client work), and can be structured as single projects (one-off initiatives) or ongoing projects (continuous collaboration).\n\n**Project Types:**\n- **Single Projects**: Clear-cut initiatives with defined start and finish, usually planned and billed as quoted\n- **Ongoing Projects**: Continuous activities where tasks are handled and billed based on effort\n\n**Project Classification:**\n- **External Projects**: Billable customer projects that generate direct revenue\n- **Internal Projects**: Non-billable activities essential for running the company (e.g., administration, product development)\n\n**Value Groups:**\nProjects are classified by value creation:\n- **A - Direct value creation**: External customer projects\n- **B - Indirect value creation**: Internal projects that increase product/service value\n- **C - Not value creating**: Administrative tasks\n- **D - Waste**: Unproductive time (downtime, failed projects)\n\n**What is returned:**\nThe response includes project details such as name, short name (unique identifier), organization, category, status, phase, open tasks count, value group, type, tags, access permissions, and timestamps.\n\nRetrieves a paginated grid of projects with filtering and sorting capabilities. Quick search available on: name, shortName, orgName. Filterable fields: id, name, shortName, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt. Sortable fields: id, name, shortName, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt.","operationId":"ProjectsController_listProjects","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: name, shortName, orgName","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Project ID\n- **name** (string): Project name\n- **shortName** (string): Project short name (organization prefix + number)\n- **type** (set): Project type\n- **valueGroup** (set): Value group classification\n- **categoryId** (string): Project category ID\n- **statusId** (string): Project status ID\n- **phaseId** (string): Project phase ID\n- **organizationId** (string): Organization ID\n- **orgName** (string): Organization name\n- **guestAccess** (boolean): Whether guest access is enabled\n- **isFavorite** (boolean): Whether the project is marked as favorite by the current user\n- **isArchived** (boolean): Whether the project is archived\n- **openTasksCount** (number): Number of open tasks\n- **createdAt** (date): Creation timestamp\n- **editedAt** (date): Last update timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **name** (string): Project name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **shortName** (string): Project short name (organization prefix + number) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Project type (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **valueGroup** (set): Value group classification (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **categoryId** (string): Project category ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **statusId** (string): Project status ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **phaseId** (string): Project phase ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (string): Organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **orgName** (string): Organization name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **guestAccess** (boolean): Whether guest access is enabled (boolean filter). Available comparisons: equal, not_equal\n- **isFavorite** (boolean): Whether the project is marked as favorite by the current user (boolean filter). Available comparisons: equal, not_equal\n- **isArchived** (boolean): Whether the project is archived (boolean filter). Available comparisons: equal, not_equal\n- **openTasksCount** (number): Number of open tasks (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **editedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Project ID\n- **name**: Project name\n- **shortName**: Project short name (organization prefix + number)\n- **type**: Project type\n- **valueGroup**: Value group classification\n- **categoryId**: Project category ID\n- **statusId**: Project status ID\n- **phaseId**: Project phase ID\n- **organizationId**: Organization ID\n- **orgName**: Organization name\n- **guestAccess**: Whether guest access is enabled\n- **isFavorite**: Whether the project is marked as favorite by the current user\n- **isArchived**: Whether the project is archived\n- **openTasksCount**: Number of open tasks\n- **createdAt**: Creation timestamp\n- **editedAt**: Last update timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, name, shortName, icon, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, orgColor, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt","schema":{"example":"id,name","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of projects"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List projects","tags":["projects"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new project in the workspace.\n\n**Project Types:**\n- **Single Projects**: One-off initiatives with defined start and finish\n- **Ongoing Projects**: Continuous activities with recurring tasks\n\n**Internal vs External:**\n- **External Projects**: Set organizationId to link to a client organization. These are billable customer projects.\n- **Internal Projects**: Set organizationId to null. These are non-billable company activities.\n\n**Required Fields:**\n- name: Project name\n- type: Project type (Single or Ongoing)\n- valueGroup: Value classification (A-D)\n- categoryId: Project category UUID\n- statusId: Project status UUID\n- users: Array of user IDs (at least one)\n- taskTypes: Array of task type IDs (at least one)\n- activities: Array of activity IDs (at least one)\n\n**Optional Fields:**\n- phaseId: Required for external single projects, optional otherwise\n- organizationId: Required for external projects, must be null for internal projects\n- description: HTML or Markdown (will be converted to internal format)\n- icon: Icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:shopping_cart:`, `:mobile_phone:`). Use standard emoji short names or custom icon names.\n- deadline: ISO 8601 date string\n- defaultAccountableId: Default accountable user UUID\n- responsibleId: Responsible user UUID\n- teams: Array of team IDs\n- customFields: Key-value pairs for custom data\n- tags: Array of tag strings\n- guestAccess: Whether organization members can access (only for external projects)\n\n**Description Format:**\nThe description field accepts HTML or Markdown and will be automatically converted to the internal IDoc format. When retrieved later, it will be returned as HTML.","operationId":"ProjectsController_createProject","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"name":["Name is required"],"type":["Type is required"],"organizationId":["organizationId is required for client projects"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create project","tags":["projects"],"x-required-scopes":["api:write"]}},"/projects/categories":{"get":{"description":"Returns a list of all project categories configured in the workspace.\n\n**What are Project Categories?**\nCategories classify projects by functional area or project type (e.g., Onboarding, Support, Implementation, Website Development). They help organize and filter projects in the workspace. Categories can be configured in workspace settings and support multi-language translations.\n\n**What is returned:**\nEach category includes:\n- Unique identifier (ID)\n- Name and description\n- Icon identifier\n- Multi-language translations (if configured)\n\nThis is a read-only endpoint optimized for common list data retrieval.","operationId":"ProjectsController_listCategories","parameters":[],"responses":{"200":{"description":"Project categories retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectCategoryDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all project categories","tags":["projects","common-lists"],"x-required-scopes":["api:read"]}},"/projects/statuses":{"get":{"description":"Returns a list of all project statuses configured in the workspace.\n\n**What are Project Statuses?**\nStatuses represent the current progress stage of a project (e.g., Sales, Implementation, Billing, Done). They help track project lifecycle and workflow. Statuses can be configured in workspace settings and support multi-language translations.\n\n**Status Types:**\nEach status has a type that determines its behavior in the project workflow.\n\n**What is returned:**\nEach status includes:\n- Unique identifier (ID)\n- Name and description\n- Icon identifier\n- Status type\n- Multi-language translations (if configured)\n\nThis is a read-only endpoint optimized for common list data retrieval.","operationId":"ProjectsController_listStatuses","parameters":[],"responses":{"200":{"description":"Project statuses retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectStatusDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all project statuses","tags":["projects","common-lists"],"x-required-scopes":["api:read"]}},"/projects/phases":{"get":{"description":"Returns a list of all project phases configured in the workspace.\n\n**What are Project Phases?**\nPhases represent distinct stages or steps within a project lifecycle (e.g., Planning, Development, Testing, Deployment). They provide additional granularity beyond project statuses and are particularly useful for external single projects. Phases can be configured in workspace settings and support multi-language translations.\n\n**Phase Types:**\nEach phase has a type that determines its behavior in the project workflow.\n\n**What is returned:**\nEach phase includes:\n- Unique identifier (ID)\n- Name and description\n- Icon identifier\n- Phase type\n- Multi-language translations (if configured)\n\nThis is a read-only endpoint optimized for common list data retrieval.","operationId":"ProjectsController_listPhases","parameters":[],"responses":{"200":{"description":"Project phases retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectPhaseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all project phases","tags":["projects","common-lists"],"x-required-scopes":["api:read"]}},"/projects/{id}/component-overview":{"get":{"description":"Returns the hierarchical structure of project components, items, and associated tasks.\n\n**What are Components?**\nComponents are reusable project templates that standardize recurring project types. They serve as blueprints for planning, pricing, and executing similar projects consistently. When imported into a project, components create a structured tree of work items.\n\n**Component Structure:**\nComponents contain a hierarchical tree of items:\n- **Epics**: Groups related work packages around a common theme\n- **Work Packages**: Self-contained, clearly defined tasks that deliver tangible results\n- **Todo Lists**: Checklists for quality control and process steps\n- **Test Suites**: Acceptance tests for formal approval\n\n**What is returned:**\nThe overview shows:\n- Complete hierarchical structure of all components in the project\n- All component items (Epics, Work Packages, Todo Lists, Test Suites)\n- Tasks that have been connected to component items\n- Implementation progress and status information\n\nThis endpoint helps track how project components are being implemented and which tasks are associated with each component item.","operationId":"ProjectsController_getComponentOverview","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Component overview retrieved successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - missing required permission"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project component overview","tags":["projects"],"x-required-scopes":["api:read"]}},"/projects/{id}/objects":{"get":{"description":"Returns objects whose current projectId matches this project. Object visibility rules still apply.","operationId":"ProjectsController_listProjectObjects","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List objects assigned to a project","tags":["projects"],"x-required-scopes":["api:read"]}},"/projects/{id}":{"get":{"description":"Returns complete project details including all settings, relationships, and metadata.\n\n**What is returned:**\nThe response includes:\n- Basic information: name, short name, type, value group, description, icon\n- Classification: category, status, phase, organization\n- Access settings: guest access, assigned users and teams\n- Task configuration: enabled task types and activities\n- Custom data: custom fields, tags\n- Responsibilities: default accountable user, responsible user\n- Timestamps: creation date, last edit date, archive date\n- Project metadata: color, favorite status, express quotations setting\n\nThe description field is returned as HTML (converted from the internal IDoc format).","operationId":"ProjectsController_getProjectDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get project details","tags":["projects"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates only the fields provided in the request body. All fields are optional - only included fields will be updated.\n\n**How it works:**\n- Send only the fields you want to update\n- Fields not included in the request remain unchanged\n- Arrays (users, teams, taskTypes, activities, tags) replace the entire array\n- Set a field to null to clear it (where applicable)\n\n**Description Format:**\nIf you provide a description field, it accepts HTML or Markdown and will be converted to the internal IDoc format.\n\n**Important Notes:**\n- organizationId: Can be changed, but must be set for external projects and null for internal projects\n- phaseId: Can be updated, but is required for external single projects\n- enableExpressQuotations: Only applicable for external projects\n- guestAccess: Only applicable for external projects","operationId":"ProjectsController_patchProject","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchProjectDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update project","tags":["projects"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a project. The project will be marked as deleted (archived) but not permanently removed from the database.\n\n**What happens:**\n- The project is marked as archived\n- It will no longer appear in active project lists\n- Historical data (tasks, time bookings, etc.) is preserved\n- The project can be viewed in archived projects if needed\n\n**Note:** This is a soft delete operation. The project data remains in the database for historical reporting and audit purposes.","operationId":"ProjectsController_deleteProject","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete project","tags":["projects"],"x-required-scopes":["api:write"]}},"/projects/{id}/active-subscriptions":{"get":{"description":"Returns all active subscriptions (manual and product-based) for a project as of the current date.\n\n**What are Active Subscriptions?**\nActive subscriptions combine:\n- **Manual subscriptions**: Fixed price and variable price subscriptions configured directly for the project\n- **Product subscriptions**: Products with subscription pricing from the billing version/snapshot (for Single projects) or current products (for Support projects)\n\n**Project Type Behavior:**\n- **Single Projects**: Uses products from the billing version/snapshot (productsBillingProjectSnapshotId or billingProjectSnapshotId)\n- **Support Projects**: Uses current products (no snapshot)\n\n**What is returned:**\n- Only subscriptions that are currently active (activeFrom <= now <= activeTo)\n- Each subscription includes: name, activeFrom date, activeTo date, priceSubscription, pricePerUnit\n- Manual subscriptions: name comes from manualTitle, dates from fromDate/toDate\n- Product subscriptions: name comes from finalName, dates from activeFrom/activeTo\n\n**Note:** Requires project access permission.","operationId":"ProjectsController_getActiveSubscriptions","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Active subscriptions retrieved successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found or access denied"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get active subscriptions for a project","tags":["projects"],"x-required-scopes":["api:read"]}},"/projects/{id}/support-contingents":{"get":{"description":"Retrieves all support contingents (retainer plans) for a specific project with detailed information including available and consumed hours.\n\n**What are Support Contingents?**\nSupport contingents are retainer plans that define allocated hours and pricing for support periods. They help manage support contracts with predefined hours, rates, and transferability of unused hours.\n\n**What is returned:**\n- All support contingents for the project\n- Each contingent includes: title, date range, frequency, hours, transferability, active status\n- For active contingents: available hours and consumed hours for the current period\n- Available hours calculation considers transferable logic and consumed hours from invoices\n- Results are sorted by active status (active first) and then by fromDate\n\n**Note:** Requires project access permission.","operationId":"ProjectsController_getSupportContingentsWithDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Support contingents retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupportContingentWithDetailsResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List support contingents with details for a project","tags":["projects","projects","support-contingents"],"x-required-scopes":["api:read"]}},"/projects/{id}/support-contingents-details":{"get":{"description":"Retrieves a detailed period-by-period breakdown of all support contingents for a specific project.\n\n**What are Support Contingents?**\nSupport contingents are retainer plans that define allocated hours and pricing for support periods. They help manage support contracts with predefined hours, rates, and transferability of unused hours.\n\n**What is returned:**\n- All support contingents for the project\n- For each contingent: period-by-period breakdown from start date until present day\n- Each period includes: start/end dates, allocated hours, hours from previous period (if transferable), consumed hours, and list of tasks\n- Tasks include: title, short number, hours billed, invoice number (if billed), and unbilled flag (if in progress)\n- Current period includes unbilled tasks with their spent hours\n- Periods are sorted newest first, active contingents appear before inactive ones\n- Tasks within each period are sorted with unbilled tasks first, then by short number\n\n**Note:** Requires project access and `Projects.canSeeSupportContingentDetails` permission.","operationId":"ProjectsController_getSupportContingentsBreakdown","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Support contingents breakdown retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupportContingentWithBreakdownResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get detailed period-by-period breakdown of support contingents","tags":["projects","projects","support-contingents"],"x-required-scopes":["api:read"]}},"/object-types":{"get":{"operationId":"ObjectTypesController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ObjectTypeListItemDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List object types (admin)","tags":["object-types"],"x-required-scopes":["api:read"]},"post":{"operationId":"ObjectTypesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObjectTypeDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create object type (admin)","tags":["object-types"],"x-required-scopes":["api:write"]}},"/object-types/sort":{"post":{"operationId":"ObjectTypesController_saveObjectTypeSort","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveSortDTO"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder object types (admin)","tags":["object-types"],"x-required-scopes":["api:write"]}},"/object-types/{typeId}/statuses":{"get":{"operationId":"ObjectTypesController_listStatuses","parameters":[{"name":"typeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ObjectStatusDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List statuses for an object type (admin)","tags":["object-types"],"x-required-scopes":["api:read"]},"post":{"operationId":"ObjectTypesController_createStatus","parameters":[{"name":"typeId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObjectStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectStatusDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create object status (admin)","tags":["object-types"],"x-required-scopes":["api:write"]}},"/object-types/{typeId}/statuses/sort":{"post":{"operationId":"ObjectTypesController_saveStatusSort","parameters":[{"name":"typeId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveSortDTO"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder statuses for an object type (admin)","tags":["object-types"],"x-required-scopes":["api:write"]}},"/object-types/{typeId}/statuses/{statusId}":{"put":{"operationId":"ObjectTypesController_updateStatus","parameters":[{"name":"typeId","required":true,"in":"path","schema":{"type":"string"}},{"name":"statusId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectStatusDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectStatusDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update object status (admin)","tags":["object-types"],"x-required-scopes":["api:write"]},"delete":{"operationId":"ObjectTypesController_deleteStatus","parameters":[{"name":"typeId","required":true,"in":"path","schema":{"type":"string"}},{"name":"statusId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete object status (admin, soft delete)","tags":["object-types"],"x-required-scopes":["api:write"]}},"/object-types/{id}":{"get":{"operationId":"ObjectTypesController_getOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectTypeDetailResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get object type with statuses and custom fields (admin)","tags":["object-types"],"x-required-scopes":["api:read"]},"put":{"operationId":"ObjectTypesController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectTypeDto"}}}},"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update object type (admin)","tags":["object-types"],"x-required-scopes":["api:write"]},"delete":{"operationId":"ObjectTypesController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete object type (admin, soft delete). Allowed even when object instances exist; instances keep objectTypeId pointing at the soft-deleted type.","tags":["object-types"],"x-required-scopes":["api:write"]}},"/objects":{"get":{"operationId":"ObjectsController_list","parameters":[{"name":"objectTypeId","required":false,"in":"query","description":"Filter by object type UUID","schema":{"type":"string"}},{"name":"organizationId","required":false,"in":"query","description":"Filter by organization UUID","schema":{"type":"string"}},{"name":"projectId","required":false,"in":"query","description":"Filter by assigned project UUID","schema":{"type":"string"}},{"name":"statusId","required":false,"in":"query","description":"Filter by object status UUID","schema":{"type":"string"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match on name","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedObjectsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List objects (visibility rules apply)","tags":["objects"],"x-required-scopes":["api:read"]},"post":{"operationId":"ObjectsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObjectDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectInstanceResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create object","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/files":{"get":{"operationId":"ObjectsController_listFiles","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ObjectFileResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List files attached to an object","tags":["objects"],"x-required-scopes":["api:read"]},"post":{"description":"Upload via POST /workspace/upload first, then pass fileId here.","operationId":"ObjectsController_attachFile","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachObjectFileDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectFileResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Attach a file to an object","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/files/{objectFileId}":{"delete":{"description":"objectFileId is the ObjectFile join row id (not the raw File id).","operationId":"ObjectsController_deleteFile","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"objectFileId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Remove an object file attachment","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/files/{fileRowId}/download":{"get":{"description":"fileRowId is the ObjectFile join row id (same as in list files). Streams the file as an attachment.","operationId":"ObjectsController_downloadObjectFile","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"fileRowId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Download a file attached to an object","tags":["objects"],"x-required-scopes":["api:read"]}},"/objects/file-categories":{"get":{"operationId":"ObjectsController_listFileCategories","parameters":[],"responses":{"200":{"description":"Category id and name pairs","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List object file categories (workspace-wide)","tags":["objects"],"x-required-scopes":["api:read"]}},"/objects/file-categories/save":{"post":{"operationId":"ObjectsController_saveFileCategory","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Set to update"},"name":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create or update an object file category","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/file-categories/{categoryId}":{"delete":{"operationId":"ObjectsController_deleteFileCategory","parameters":[{"name":"categoryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Soft-delete an object file category","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/assignments/assign-to-organization":{"post":{"operationId":"ObjectsController_assignToOrganization","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignObjectsToOrganizationDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Assign objects to an organization","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/assignments/unassign-from-organization":{"post":{"operationId":"ObjectsController_unassignFromOrganization","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignObjectFromOrganizationDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Unassign an object from its organization","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/assignments/assign-to-project":{"post":{"operationId":"ObjectsController_assignToProject","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignObjectsToProjectDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Assign objects to a project","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/assignments/unassign-from-project":{"post":{"operationId":"ObjectsController_unassignFromProject","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignObjectFromProjectDto"}}}},"responses":{"201":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Unassign an object from its project","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/journal/{entryId}":{"get":{"operationId":"ObjectsController_getJournalEntry","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get one object journal entry","tags":["objects"],"x-required-scopes":["api:read"]},"put":{"description":"Requires canEditObject, or editing your own entry when you only have canViewObjects (same rules as app).","operationId":"ObjectsController_patchJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchObjectJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update object journal entry","tags":["objects"],"x-required-scopes":["api:write"]},"delete":{"operationId":"ObjectsController_deleteJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete object journal entry (soft delete)","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/journal":{"get":{"operationId":"ObjectsController_listJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List journal entries for an object (paginated grid)","tags":["objects"],"x-required-scopes":["api:read"]},"post":{"operationId":"ObjectsController_createJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObjectJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create object journal entry","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}/history":{"get":{"operationId":"ObjectsController_historyForObject","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedObjectHistoryResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Audit history for an object (paginated, newest first)","tags":["objects"],"x-required-scopes":["api:read"]}},"/objects/{id}/tasks":{"get":{"operationId":"ObjectsController_tasksForObject","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TasksByObjectResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List tasks linked to an object","tags":["objects"],"x-required-scopes":["api:read"]}},"/objects/tasks/link":{"post":{"operationId":"ObjectsController_linkObjectToTask","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkObjectToTaskPublicDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkObjectToTaskPublicResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Link an object to a task","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/tasks/link-batch":{"post":{"description":"Creates any missing links; already-linked pairs are skipped. Task-side and object-side audit entries match the internal batch semantics.","operationId":"ObjectsController_linkObjectsBatchToTask","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkObjectsBatchToTaskPublicDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkObjectsBatchPublicResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Link multiple objects to one task","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/tasks/unlink":{"post":{"operationId":"ObjectsController_unlinkObjectFromTask","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkObjectToTaskPublicDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Remove the link between an object and a task","tags":["objects"],"x-required-scopes":["api:write"]}},"/objects/{id}":{"get":{"operationId":"ObjectsController_getOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectInstanceResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get object by id","tags":["objects"],"x-required-scopes":["api:read"]},"put":{"operationId":"ObjectsController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectInstanceResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update object","tags":["objects"],"x-required-scopes":["api:write"]},"delete":{"operationId":"ObjectsController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Soft-delete object","tags":["objects"],"x-required-scopes":["api:write"]}},"/administration/document-settings":{"get":{"description":"Retrieves the current document settings for the workspace.\n\n**What are Document Settings?**\nDocument settings control the appearance and formatting of all documents automatically generated by Leadtime, including letters, invoices, quotes, specifications, and project documents. These settings apply workspace-wide and can be overridden at the organization or project level.\n\n**What is returned:**\n- **Document font**: The selected font family for all documents (e.g., Inter, Roboto, Arimo)\n- **Document logo URL**: Public URL to the workspace logo image (null if not set, defaults to Leadtime logo)\n- **Project document options**:\n - Title page toggle (automatically adds a title page)\n - Table of contents toggle (creates TOC at document start)\n - Heading style (controls how headings are numbered and formatted)\n- **Background image URLs**: Public URLs for background images used on cover pages:\n - Specification background (for specs documents)\n - Estimate background (for proposal/quote documents)\n - Custom editor background (for template-based documents)\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. All file URLs are public and can be accessed without authentication.","operationId":"DocumentSettingsController_getDocumentSettings","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetDocumentSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get document settings","tags":["administration","document-settings"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates document settings for the workspace. All fields are optional - only provided fields will be updated.\n\n**What are Document Settings?**\nDocument settings control the appearance and formatting of all documents automatically generated by Leadtime, including letters, invoices, quotes, specifications, and project documents.\n\n**How to update document settings:**\n1. **For file uploads** (logo, background images):\n - Upload image files using POST /api/public/workspace/upload\n - Get the file ID from the upload response\n - Use the file ID in the corresponding field (`documentLogoId`, `specificationBackgroundId`, etc.)\n - To remove a file, set the field to `null`\n2. **For font selection**: Choose from available fonts (Inter, Degular, Roboto, Arimo, Open Sans, PT Sans, Oswald, EB Garamond, Permanent Marker, IBM Plex Mono)\n3. **For project document options**: Set boolean flags and heading style enum values\n\n**Available heading styles:**\n- `Normal`: Headings without numbering\n- `Sequential`: Continuous numbering from level 1 (e.g., 1., 1.1., 1.1.1.)\n- `SequentialFromSecondLevel`: Top heading unnumbered, subchapters numbered (e.g., 1. Heading 2, 1.1. Heading 3)\n- `SequentialWithParagraphs`: Numbering with Β§ prefix from level 2 (e.g., Β§ 1., Β§ 1.1.) - ideal for contracts\n\n**Background image recommendations:**\n- Recommended size: 820 Γ 600 pixels\n- Formats: PNG, JPG, or SVG\n- Used on cover pages of generated documents\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Changes affect all documents generated after the update. Use GET endpoint to preview current settings.","operationId":"DocumentSettingsController_updateDocumentSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchDocumentSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update document settings","tags":["administration","document-settings"],"x-required-scopes":["api:write"]}},"/sales/estimates/grid":{"get":{"description":"**What are Sales Estimates?**\nSales Estimates provides a unified overview of all ongoing offers and sales opportunities in Leadtime. This endpoint combines two types of estimates into a single grid view:\n- **Project Documents**: Detailed estimates linked to larger projects, created through the project planning process with products, modules, and custom items\n- **Express Quotations**: Quick estimates created directly from tickets for smaller, ad-hoc customer requests\n\n**What data is returned:**\nThe response includes a paginated grid of estimate items with comprehensive pricing information:\n- Each item represents either a project document estimate or an express quotation\n- Only the latest estimate per project or task is returned (older versions are excluded)\n- Pricing breakdown includes fixed prices, subscription prices, and per-unit prices\n- Aggregated totals across all filtered results are provided at the response level\n\n**Pricing components:**\nEach estimate can have three types of pricing:\n- **Fixed Price**: One-time charges for services or products\n- **Subscriptions**: Recurring prices (monthly, quarterly, semi-annually, or annually)\n- **Per Unit**: Prices based on quantity (e.g., price per user or workspace)\n\nThe response includes both individual item pricing and aggregated totals (totalPriceFixed, totalPriceSubscriptions, totalPricePerUnit) across all filtered results.\n\n**Estimate types:**\n- **PROJECT_DOCUMENT**: Estimates created as part of project planning, typically more detailed and structured\n- **EXPRESS_QUOTATION**: Quick estimates created from tickets, ideal for small add-on tasks or support services\n\n**Estimate statuses:**\n- **Draft**: Estimate is being prepared and has not been sent\n- **WaitingForApproval**: Estimate is pending internal approval before sending\n- **Final**: Estimate has been finalized and approved\n- **Pending**: Express quotation has been sent to customer, awaiting response\n- **Accepted**: Customer has accepted the estimate\n- **Rejected**: Customer has rejected the estimate\n- **Parked**: Estimate has been set aside temporarily\n\n**Access restrictions:**\n- This endpoint is restricted to employees only. Organization members (external contacts) cannot access it\n- Results are automatically filtered by the user's project access permissions\n- Only estimates for projects the user has access to are returned\n\n**Supported operations:**\n- Filter by type, organization, project, task, status, pricing components, creator, and creation date\n- Sort by any field including title, organization, project, status, pricing, and dates\n- Quick search across estimate titles\n- Pagination with configurable page size\n- Field selection to return only specific fields in the response\n\n**Use cases:**\n- Generate sales pipeline reports showing all active estimates\n- Track revenue potential across different estimate types\n- Monitor estimate status distribution (draft, pending, accepted, etc.)\n- Analyze pricing breakdowns by organization or project\n- Export estimate data for external reporting tools\n\nRetrieves a paginated grid of estimates with filtering and sorting capabilities. Quick search available on: title, displayTitle. Filterable fields: id, type, title, displayTitle, organizationId, projectId, taskId, createdAt, status, priceFixed, priceSubscriptions, pricePerUnit, createdById, offerNumber. Sortable fields: id, type, title, displayTitle, organizationId, organizationName, projectId, projectName, taskId, taskShortNumber, createdAt, status, total, priceFixed, priceSubscriptions, pricePerUnit, createdById, createdByName, offerNumber.","operationId":"SalesEstimatesController_getEstimatesGrid","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: title, displayTitle","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Estimate ID\n- **type** (string): Estimate type (PROJECT_DOCUMENT or EXPRESS_QUOTATION)\n- **title** (string): Estimate title\n- **displayTitle** (string): Display title (combined title/offerNumber based on documentStyle)\n- **organizationId** (string): Organization ID\n- **projectId** (string): Project ID\n- **taskId** (string): Task ID (only for EXPRESS_QUOTATION)\n- **createdAt** (date): Creation timestamp\n- **status** (string): Estimate status (Draft, Final, WaitingForApproval, Pending, etc.)\n- **priceFixed** (number): Fixed price\n- **priceSubscriptions** (number): Subscription price\n- **pricePerUnit** (number): Per-unit price\n- **createdById** (string): Creator user ID\n- **offerNumber** (number): Offer number (for PROJECT_DOCUMENT type)\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Estimate ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (string): Estimate type (PROJECT_DOCUMENT or EXPRESS_QUOTATION) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **title** (string): Estimate title (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **displayTitle** (string): Display title (combined title/offerNumber based on documentStyle) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (string): Organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **taskId** (string): Task ID (only for EXPRESS_QUOTATION) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **status** (string): Estimate status (Draft, Final, WaitingForApproval, Pending, etc.) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **priceFixed** (number): Fixed price (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **priceSubscriptions** (number): Subscription price (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **pricePerUnit** (number): Per-unit price (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **createdById** (string): Creator user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **offerNumber** (number): Offer number (for PROJECT_DOCUMENT type) (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Estimate ID\n- **type**: Estimate type (PROJECT_DOCUMENT or EXPRESS_QUOTATION)\n- **title**: Estimate title\n- **displayTitle**: Display title (combined title/offerNumber based on documentStyle)\n- **organizationId**: Organization ID\n- **organizationName**: Organization name\n- **projectId**: Project ID\n- **projectName**: Project name\n- **taskId**: Task ID (only for EXPRESS_QUOTATION)\n- **taskShortNumber**: Task short number (only for EXPRESS_QUOTATION)\n- **createdAt**: Creation timestamp\n- **status**: Estimate status (Draft, Final, WaitingForApproval, Pending, etc.)\n- **total**: Total price (for express quotations)\n- **priceFixed**: Fixed price\n- **priceSubscriptions**: Subscription price\n- **pricePerUnit**: Per-unit price\n- **createdById**: Creator user ID\n- **createdByName**: Creator name\n- **offerNumber**: Offer number (for PROJECT_DOCUMENT type)\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, type, title, displayTitle, organizationId, organizationName, projectId, projectName, taskId, taskShortNumber, createdAt, status, total, priceFixed, priceSubscriptions, pricePerUnit, priceSubscriptionsDetail, pricePerUnitDetail, createdById, createdByName, offerNumber, formattedOfferNumber","schema":{"example":"id,type","type":"array","items":{}}}],"responses":{"200":{"description":"Estimates grid with pricing totals (totalPriceFixed, totalPriceSubscriptions, totalPricePerUnit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateGridResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get sales estimates grid","tags":["sales","estimates"],"x-required-scopes":["api:read"]}},"/sales/opportunities":{"get":{"description":"Retrieves a paginated grid of sales opportunities with filtering and sorting capabilities. Quick search available on: name, shortName, orgName. Filterable fields: id, name, shortName, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt. Sortable fields: id, name, shortName, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt.\n\n**What are Sales Opportunities?**\n\nSales opportunities represent potential projects in the customer lifecycle where a customer has not placed any order yet. They are used to organize leads, track sales stages, manage contacts, and systematically move potential deals forward. In Leadtime, sales opportunities work as projects that are assigned to an external organization (customer). The goal of every opportunity is to create an offer, and if successful, it can turn into an implementation project.\n\n**How Sales Opportunities Work:**\n\n- Sales opportunities are Single-type projects that have an organizationId (external projects)\n- They can be linked to one or more offers or estimates\n- They use project phases to track progress through the sales process (e.g., Uncontacted, Research, Contact made, Reminder, Implementation, Won, Finished)\n- They support custom fields for storing additional information like probability, source, region, or segment\n- They include a journal for documenting activities, feedback, and interactions with potential customers\n\n**Automatic Filtering:**\n\nThis endpoint automatically applies three filters to ensure only relevant sales opportunities are returned:\n1. **Project type**: Must be Single (only single projects can be sales opportunities)\n2. **Organization ID**: Must not be empty (only external projects linked to organizations)\n3. **Status exclusion**: Projects with Done status type are automatically excluded (only active opportunities are shown)\n\n**Data Returned:**\n\nThe response includes project grid items with fields such as:\n- Project identification: id, name, shortName, icon\n- Project classification: type, valueGroup, categoryId, statusId, phaseId\n- Organization information: organizationId, orgName, orgColor\n- Project metadata: createdAt, editedAt, isFavorite, isArchived, guestAccess\n- Task information: openTasksCount\n\n**Access Control:**\n\nUsers can only see opportunities for projects they have access to based on their project permissions. The endpoint requires the Opportunities.manageSalesOpportunities permission.","operationId":"SalesOpportunitiesController_listOpportunities","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: name, shortName, orgName","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Project ID\n- **name** (string): Project name\n- **shortName** (string): Project short name (organization prefix + number)\n- **type** (set): Project type\n- **valueGroup** (set): Value group classification\n- **categoryId** (string): Project category ID\n- **statusId** (string): Project status ID\n- **phaseId** (string): Project phase ID\n- **organizationId** (string): Organization ID\n- **orgName** (string): Organization name\n- **guestAccess** (boolean): Whether guest access is enabled\n- **isFavorite** (boolean): Whether the project is marked as favorite by the current user\n- **isArchived** (boolean): Whether the project is archived\n- **openTasksCount** (number): Number of open tasks\n- **createdAt** (date): Creation timestamp\n- **editedAt** (date): Last update timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **name** (string): Project name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **shortName** (string): Project short name (organization prefix + number) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Project type (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **valueGroup** (set): Value group classification (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **categoryId** (string): Project category ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **statusId** (string): Project status ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **phaseId** (string): Project phase ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (string): Organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **orgName** (string): Organization name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **guestAccess** (boolean): Whether guest access is enabled (boolean filter). Available comparisons: equal, not_equal\n- **isFavorite** (boolean): Whether the project is marked as favorite by the current user (boolean filter). Available comparisons: equal, not_equal\n- **isArchived** (boolean): Whether the project is archived (boolean filter). Available comparisons: equal, not_equal\n- **openTasksCount** (number): Number of open tasks (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **editedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Project ID\n- **name**: Project name\n- **shortName**: Project short name (organization prefix + number)\n- **type**: Project type\n- **valueGroup**: Value group classification\n- **categoryId**: Project category ID\n- **statusId**: Project status ID\n- **phaseId**: Project phase ID\n- **organizationId**: Organization ID\n- **orgName**: Organization name\n- **guestAccess**: Whether guest access is enabled\n- **isFavorite**: Whether the project is marked as favorite by the current user\n- **isArchived**: Whether the project is archived\n- **openTasksCount**: Number of open tasks\n- **createdAt**: Creation timestamp\n- **editedAt**: Last update timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, name, shortName, icon, type, valueGroup, categoryId, statusId, phaseId, organizationId, orgName, orgColor, guestAccess, isFavorite, isArchived, openTasksCount, createdAt, editedAt","schema":{"example":"id,name","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of sales opportunities"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List sales opportunities","tags":["sales"],"x-required-scopes":["api:read"]}},"/administration/subscription-status":{"get":{"description":"**What is Subscription Status?**\nSubscription Status provides comprehensive information about your workspace subscription, billing details, and payment information. This endpoint returns all data needed to display subscription management interfaces, including current plan details, upcoming invoices, payment history, and feature availability.\n\n**What data is returned:**\n\n**Core Subscription Information:**\n- **billingMode**: The workspace billing tier (free, regular, or enterprise)\n- **billingStatus**: Current subscription status (active, trialing, canceled, etc.)\n- **planCode**: The specific plan identifier\n- **billingInterval**: Billing frequency (monthly or yearly)\n- **features**: List of enabled workspace features\n- **featuresInfo**: Detailed feature information with pricing for each enabled feature\n\n**Stripe Integration:**\n- **stripeCustomerId**: Stripe customer identifier (null for free workspaces)\n- **stripeSubscriptionId**: Stripe subscription identifier (null for free workspaces)\n- **hasPaymentMethod**: Whether a payment method is on file\n\n**Trial Information:**\n- **trialEnd**: End date of trial period (null if not in trial)\n\n**Subscription Details** (Enterprise workspaces only):\n- **status**: Current subscription status from Stripe\n- **currentPeriodStart/End**: Current billing period dates\n- **items**: List of subscription items with product names, quantities, and pricing\n- **dashboardUrl**: Direct link to Stripe dashboard for this subscription\n\n**Invoice Information** (Paid workspaces only):\n- **nextInvoice**: Preview of upcoming invoice with:\n - Line items with descriptions and quantities\n - Subtotal, tax, and total amounts\n - Tax breakdown by rate\n - Due date\n- **latestInvoices**: Up to 5 most recent invoices with:\n - Invoice number and status\n - Amount and currency\n - Payment dates and due dates\n - Direct links to view invoices\n\n**Seat Management:**\n- **billableUsersCount**: Current number of billable users\n- **committedSeats**: Seats currently committed for billing\n- **pendingSeats**: Seats scheduled to be added in next period\n- **pendingEffectiveAt**: When pending seats become effective\n\n**Cancellation Information:**\n- **cancelAtPeriodEnd**: Whether subscription will cancel at period end\n- **cancellationEffectiveAt**: When cancellation becomes effective\n- **cancellationRequestedAt**: When cancellation was requested\n- **cancellationReason**: Reason provided for cancellation\n\n**Billing Interval Changes:**\n- **nextBillingInterval**: Scheduled billing interval change (if any)\n- **billingIntervalChangeScheduled**: When the change takes effect\n- **stillAvailableFeatures**: Features that remain available after interval change\n\n**Important Notes:**\n- This is a read-only endpoint - it does not modify subscription state\n- Free workspaces return basic information without Stripe details\n- Enterprise workspaces include detailed Stripe subscription information\n- Trial workspaces may have limited invoice history\n- All monetary amounts are in cents (divide by 100 for display)\n- Dates are returned in ISO 8601 format","operationId":"SubscriptionStatusController_getSubscriptionStatus","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionStatusResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get workspace subscription and billing status","tags":["administration","subscription-status"],"x-required-scopes":["api:read"]}},"/billing/invoices/new":{"get":{"description":"Returns a paginated, filterable, and sortable grid of invoices that are created but not yet sent, or sent but not yet overdue.\n\n**What are New Invoices?**\nThe \"New\" tab shows all invoices that have been created but not yet sent, or invoices that have been sent but are not yet overdue. These invoices are in status \"New\" or \"Sent\" and have either no due date or a due date in the future.\n\n**What is returned:**\n- Invoice identification (ID, number)\n- Project reference (projectId)\n- Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- Creation and sending dates (createdAt, sentAt)\n- Payment due date (dueDate)\n- Net amount before taxes and fees (netto)\n- Invoice status (New, Sent)\n\n**Filtering and search:**\n- Quick search across invoice number\n- Filter by project, type, status, dates, and amount\n- Sort by any field\n\nRetrieves a paginated grid of new invoices with filtering and sorting capabilities. Quick search available on: number. Filterable fields: id, number, projectId, type, createdAt, sentAt, dueDate, netto, status. Sortable fields: id, number, projectId, type, createdAt, sentAt, dueDate, netto, status.","operationId":"InvoicesController_getNewInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: number","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Invoice ID\n- **number** (string): Invoice number\n- **projectId** (string): Project ID\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt** (date): Invoice creation date\n- **sentAt** (date): Date when invoice was sent\n- **dueDate** (date): Payment due date\n- **netto** (number): Net amount (before taxes and fees)\n- **status** (set): Invoice status (New, Sent)\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Invoice ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **number** (string): Invoice number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Invoice creation date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **sentAt** (date): Date when invoice was sent (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **dueDate** (date): Payment due date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **netto** (number): Net amount (before taxes and fees) (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **status** (set): Invoice status (New, Sent) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Invoice ID\n- **number**: Invoice number\n- **projectId**: Project ID\n- **type**: Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt**: Invoice creation date\n- **sentAt**: Date when invoice was sent\n- **dueDate**: Payment due date\n- **netto**: Net amount (before taxes and fees)\n- **status**: Invoice status (New, Sent)\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, number, projectId, type, createdAt, sentAt, dueDate, netto, status","schema":{"example":"id,number","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved new invoices grid"},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get new invoices grid","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices/paid":{"get":{"description":"Returns a paginated, filterable, and sortable grid of invoices that have been marked as paid.\n\n**What are Paid Invoices?**\nThe \"Paid\" tab shows all invoices that have been fully settled. These invoices are in status \"Paid\" and represent completed transactions.\n\n**What is returned:**\n- Invoice identification (ID, number)\n- Project reference (projectId)\n- Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- Creation date (createdAt)\n- Net amount before taxes and fees (netto)\n- Invoice status (Paid)\n\n**Filtering and search:**\n- Quick search across invoice number\n- Filter by project, type, status, date, and amount\n- Sort by any field\n\nRetrieves a paginated grid of paid invoices with filtering and sorting capabilities. Quick search available on: number. Filterable fields: id, number, projectId, type, createdAt, netto, status. Sortable fields: id, number, projectId, type, createdAt, netto, status.","operationId":"InvoicesController_getPaidInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: number","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Invoice ID\n- **number** (string): Invoice number\n- **projectId** (string): Project ID\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt** (date): Invoice creation date\n- **netto** (number): Net amount (before taxes and fees)\n- **status** (set): Invoice status (Paid)\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Invoice ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **number** (string): Invoice number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Invoice creation date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **netto** (number): Net amount (before taxes and fees) (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **status** (set): Invoice status (Paid) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Invoice ID\n- **number**: Invoice number\n- **projectId**: Project ID\n- **type**: Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt**: Invoice creation date\n- **netto**: Net amount (before taxes and fees)\n- **status**: Invoice status (Paid)\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, number, projectId, type, createdAt, netto, status","schema":{"example":"id,number","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved paid invoices grid"},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get paid invoices grid","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices/canceled":{"get":{"description":"Returns a paginated, filterable, and sortable grid of invoices that have been cancelled.\n\n**What are Canceled Invoices?**\nThe \"Canceled\" tab shows all invoices that were officially cancelled after being sent out. Cancellation happens via credit note and balances out the original amount correctly from an accounting point of view.\n\n**What is returned:**\n- Invoice identification (ID, number)\n- Project reference (projectId)\n- Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- Creation date (createdAt)\n- Cancellation date (statusChangedAt)\n- Net amount before taxes and fees (netto)\n- Invoice status (Cancelled)\n\n**Filtering and search:**\n- Quick search across invoice number\n- Filter by project, type, status, dates, and amount\n- Sort by any field\n\nRetrieves a paginated grid of canceled invoices with filtering and sorting capabilities. Quick search available on: number. Filterable fields: id, number, projectId, type, createdAt, statusChangedAt, netto, status. Sortable fields: id, number, projectId, type, createdAt, statusChangedAt, netto, status.","operationId":"InvoicesController_getCanceledInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: number","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Invoice ID\n- **number** (string): Invoice number\n- **projectId** (string): Project ID\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt** (date): Invoice creation date\n- **statusChangedAt** (date): Date when invoice was cancelled\n- **netto** (number): Net amount (before taxes and fees)\n- **status** (set): Invoice status (Cancelled)\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Invoice ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **number** (string): Invoice number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Invoice creation date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **statusChangedAt** (date): Date when invoice was cancelled (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **netto** (number): Net amount (before taxes and fees) (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **status** (set): Invoice status (Cancelled) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Invoice ID\n- **number**: Invoice number\n- **projectId**: Project ID\n- **type**: Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt**: Invoice creation date\n- **statusChangedAt**: Date when invoice was cancelled\n- **netto**: Net amount (before taxes and fees)\n- **status**: Invoice status (Cancelled)\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** statusChangedAt (desc)","schema":{"example":"[{\"field\":\"statusChangedAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, number, projectId, type, createdAt, statusChangedAt, netto, status","schema":{"example":"id,number","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved canceled invoices grid"},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get canceled invoices grid","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices/overdue":{"get":{"description":"Returns a paginated, filterable, and sortable grid of invoices that are past their payment due date.\n\n**What are Overdue Invoices?**\nThe \"Overdue\" tab shows all invoices where the payment term has passed. These invoices are in status \"New\" or \"Sent\" and have a due date that is in the past. This view helps you monitor open receivables, send reminders, and manage payment deadlines.\n\n**What is returned:**\n- Invoice identification (ID, number)\n- Project reference (projectId)\n- Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- Creation and sending dates (createdAt, sentAt)\n- Payment due date (dueDate)\n- Reminder dates (firstReminderAt, secondReminderAt)\n- Number of days overdue (overdueDays)\n- Net amount before taxes and fees (netto)\n- Invoice status (New, Sent)\n\n**Filtering and search:**\n- Quick search across invoice number\n- Filter by project, type, status, dates, amount, and overdue days\n- Sort by any field (default: overdueDays descending)\n\nRetrieves a paginated grid of overdue invoices with filtering and sorting capabilities. Quick search available on: number. Filterable fields: id, number, projectId, type, createdAt, sentAt, dueDate, firstReminderAt, secondReminderAt, netto, status, overdueDays. Sortable fields: id, number, projectId, type, createdAt, sentAt, dueDate, firstReminderAt, secondReminderAt, netto, status, overdueDays.","operationId":"InvoicesController_getOverdueInvoices","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: number","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Invoice ID\n- **number** (string): Invoice number\n- **projectId** (string): Project ID\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt** (date): Invoice creation date\n- **sentAt** (date): Date when invoice was sent\n- **dueDate** (date): Payment due date\n- **firstReminderAt** (date): Date when first reminder was sent\n- **secondReminderAt** (date): Date when second reminder was sent\n- **netto** (number): Net amount (before taxes and fees)\n- **status** (set): Invoice status (New, Sent)\n- **overdueDays** (number): Number of days overdue\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Invoice ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **number** (string): Invoice number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (string): Project ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Invoice creation date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **sentAt** (date): Date when invoice was sent (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **dueDate** (date): Payment due date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **firstReminderAt** (date): Date when first reminder was sent (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **secondReminderAt** (date): Date when second reminder was sent (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **netto** (number): Net amount (before taxes and fees) (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **status** (set): Invoice status (New, Sent) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **overdueDays** (number): Number of days overdue (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Invoice ID\n- **number**: Invoice number\n- **projectId**: Project ID\n- **type**: Invoice type (Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment)\n- **createdAt**: Invoice creation date\n- **sentAt**: Date when invoice was sent\n- **dueDate**: Payment due date\n- **firstReminderAt**: Date when first reminder was sent\n- **secondReminderAt**: Date when second reminder was sent\n- **netto**: Net amount (before taxes and fees)\n- **status**: Invoice status (New, Sent)\n- **overdueDays**: Number of days overdue\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** overdueDays (desc)","schema":{"example":"[{\"field\":\"overdueDays\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, number, projectId, type, createdAt, sentAt, dueDate, firstReminderAt, secondReminderAt, netto, status, overdueDays","schema":{"example":"id,number","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved overdue invoices grid"},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get overdue invoices grid","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices":{"post":{"description":"Creates a new invoice from a potential invoice. A potential invoice represents billable items (tasks, products, subscriptions, express quotations) that are ready to be invoiced.\n\n**How invoice creation works:**\n1. First, retrieve available potential invoices using GET /billing/potential-invoices\n2. Review and customize the potential invoice details if needed (adjust billing periods, skip tasks, add manual positions)\n3. Create the invoice using this endpoint with the potential invoice ID\n4. The system automatically:\n - Generates a sequential invoice number in the format: `{ORG}{PRJ}-{YY}{MM}-{NNN}`\n - Calculates all amounts, taxes, and fees\n - Marks tasks, subscriptions, and express quotations as billed\n - Updates project billing status\n - Handles interim payments\n\n**What happens after creation:**\n- The invoice is created in status \"New\" (not yet sent)\n- All billable items included in the invoice are marked as billed\n- The invoice appears in the \"New\" invoices grid\n- You can then send the invoice using the invoice sending endpoints\n\n**Potential Invoice ID Format:**\nThe `potentialInvoiceId` follows the format: `{type}::{projectId}::{dateFrom}::{dateTo}`\n- Type: One of Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment\n- ProjectId: UUID of the project\n- DateFrom/DateTo: Dates in YYYY-MM-DD format\nExample: `SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31`\n\n**What is returned:**\n- Invoice ID (UUID) - Use this to reference the invoice in other endpoints\n- Invoice number - The official sequential invoice number for accounting","operationId":"InvoicesController_createInvoice","parameters":[],"requestBody":{"required":true,"description":"Potential invoice identifier to create invoice from","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceDto"}}}},"responses":{"200":{"description":"Invoice created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponseDto"}}}},"400":{"description":"Invalid potential invoice ID or validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/invoiceContacts/{projectId}":{"get":{"description":"Returns a list of organization members (contacts) from the project's customer organization who can be selected as invoice recipients. These contacts are the people who will receive invoices when they are sent via email.\n\n**What are Invoice Contacts?**\nInvoice contacts are organization members from the customer organization associated with the project. These are the people who can receive invoices via email. Each contact must have a valid email address to receive invoices.\n\n**What data is returned:**\n- List of organization members from the project's customer organization\n- Each contact includes ID (UUID), full name, avatar file ID (if available), and email address\n- Contacts are sorted alphabetically by first name, then last name\n- Only active (non-deleted) organization members are returned\n\n**How to use:**\n1. Get the list of available contacts for a project\n2. Select a contact ID from the list\n3. Use the POST /billing/setInvoiceContactId endpoint to set the contact for an invoice\n4. When the invoice is sent, it will be emailed to this contact\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project to view contacts.","operationId":"InvoicesController_getInvoiceContacts","parameters":[{"name":"projectId","required":true,"in":"path","description":"Project ID (UUID) to get contacts for","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Invoice contacts retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceContactResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Project not found or access denied"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get invoice contacts for a project","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices/{id}":{"get":{"description":"Returns complete details of an existing invoice, including all billable items, financial totals, and payment tracking information.\n\n**What is returned:**\n- Invoice identification (ID, number, type, status)\n- Project reference and billing period (billedFrom, billedTo)\n- All billable items:\n - Tasks with time tracking and hourly rates\n - Products with options, quantities, and pricing\n - Components with nested items and time estimates\n - Subscriptions (fixed, variable, one-time payments)\n - Express quotations with items and options\n - Support contingent charges (retainer plan charges for Support-type projects)\n - Support contingent usage (compensation/deductions from support contingents, negative amounts)\n - Manual positions (custom billing items)\n- Financial totals:\n - Net amount (before taxes and fees)\n - VAT amount and percentage\n - Leadtime fee (if applicable)\n - Gross amount (after taxes)\n - Full total (including all fees)\n- Payment tracking:\n - Due date and overdue status\n - Sent dates and recipients\n - Reminder dates (first and second)\n - Payment received date\n - Cancellation information\n- Overdue fees and interest calculations\n\n**Description fields:**\nAll description fields (products, components, manual positions, express quotations) are returned as HTML format for easy display in web applications.\n\n**Use cases:**\n- View complete invoice breakdown for accounting\n- Display invoice details in customer portals\n- Generate custom invoice documents\n- Track payment status and overdue amounts\n- Audit invoice contents and calculations","operationId":"InvoicesController_getInvoiceDetails","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved invoice details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetailsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get invoice details","tags":["billing","invoices"],"x-required-scopes":["api:read"]},"delete":{"description":"Deletes a new invoice that has not yet been sent. When an invoice is deleted, all included billable items are returned to potential invoices and can be billed again.\n\n**What happens when you delete an invoice:**\n1. The invoice is soft-deleted (marked with deletedAt timestamp)\n2. All included billable items are reverted to unbilled status:\n - Tasks: marked as unbilled (`billed=false`), invoice time cleared\n - Express quotations: marked as unbilled (`billed=false`)\n - Subscription billing rows: marked as unbilled (`billed=false`)\n - Projects: marked as unbilled (`billed=false`) for SingleProject invoices\n - Interim payments: marked as unbilled (`isBilled=false`)\n3. All items become available again in potential invoices (GET /billing/potential-invoices)\n\n**Important restrictions:**\n- Only invoices with status \"New\" can be deleted\n- Invoices that have been sent (status \"Sent\", \"Paid\", or \"Cancelled\") cannot be deleted\n- To cancel a sent invoice, use the cancel invoice endpoint instead\n\n**Use cases:**\n- Remove an invoice that was created by mistake\n- Return items to potential invoices for re-billing with different settings\n- Correct billing errors before sending the invoice\n\n**What is returned:**\n- Success response confirming the invoice was deleted\n- All billable items are automatically returned to potential invoices","operationId":"InvoicesController_deleteInvoice","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Invoice deleted successfully. All billable items have been returned to potential invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot be deleted (only invoices with status \"New\" can be deleted)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete an invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/mark-as-paid":{"post":{"description":"Marks an invoice as paid, indicating that payment has been received from the customer. This changes the invoice status from \"New\" or \"Sent\" to \"Paid\" and records the payment date and runtime.\n\n**What happens when you mark an invoice as paid:**\n1. Invoice status changes to \"Paid\"\n2. Payment date (`paidAt`) is recorded as the current date\n3. Payment runtime (`paidRuntime`) is calculated as the number of days between invoice creation and payment\n4. Status change timestamp and user are recorded\n5. The invoice moves from the \"New\" or \"Overdue\" tab to the \"Paid\" tab\n\n**Important restrictions:**\n- Only invoices with status \"New\" or \"Sent\" can be marked as paid\n- Invoices that are already \"Paid\" or \"Cancelled\" cannot be marked as paid\n- To revert a paid invoice, use the mark as unpaid endpoint\n\n**Use cases:**\n- Record payment received from customer\n- Update invoice status after manual payment confirmation\n- Track payment timing for financial reporting\n\n**What is returned:**\n- Success response confirming the invoice was marked as paid","operationId":"InvoicesController_markAsPaid","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Invoice marked as paid successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot be marked as paid (only invoices with status \"New\" or \"Sent\" can be marked as paid)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Mark invoice as paid","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/mark-as-unpaid":{"post":{"description":"Reverts a paid invoice back to unpaid status. This changes the invoice status from \"Paid\" back to \"New\" or \"Sent\" (depending on whether it was sent before), allowing you to correct payment records.\n\n**What happens when you mark an invoice as unpaid:**\n1. Invoice status changes from \"Paid\" back to \"New\" or \"Sent\"\n - If the invoice was sent before, it returns to \"Sent\" status\n - If the invoice was never sent, it returns to \"New\" status\n2. Payment date and runtime are cleared\n3. Status change timestamp and user are recorded\n4. The invoice moves from the \"Paid\" tab back to the appropriate tab\n\n**Important restrictions:**\n- Only invoices with status \"Paid\" can be marked as unpaid\n- Invoices that are \"Cancelled\" cannot be marked as unpaid\n- This operation is useful for correcting payment recording errors\n\n**Use cases:**\n- Correct payment recording errors\n- Revert accidental payment marking\n- Handle payment reversals or refunds\n\n**What is returned:**\n- Success response confirming the invoice was marked as unpaid","operationId":"InvoicesController_markAsUnpaid","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Invoice marked as unpaid successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot be marked as unpaid (only invoices with status \"Paid\" can be marked as unpaid)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Mark invoice as unpaid","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/mark-as-sent":{"post":{"description":"Marks an invoice as sent to the customer. This changes the invoice status from \"New\" to \"Sent\", records the sending date, and calculates the payment due date based on organization or workspace payment terms.\n\n**What happens when you mark an invoice as sent:**\n1. Invoice status changes from \"New\" to \"Sent\"\n2. Sending date (`sentAt`) is recorded as the current date\n3. Sending type is set to \"Manual\" (indicating manual marking, not email sending)\n4. Contact recipient is recorded (from invoice contactId)\n5. Payment due date (`dueDate`) is calculated based on:\n - Organization-specific payment terms (`invoiceDueDays`), or\n - Workspace default payment terms (`defaultInvoiceDueDays`)\n6. Status change timestamp and user are recorded\n7. The payment term starts running from this point\n\n**Important restrictions:**\n- Only invoices with status \"New\" or \"Sent\" can be marked as sent\n- Invoices that are \"Paid\" or \"Cancelled\" cannot be marked as sent\n- This endpoint marks the invoice as sent manually (use send invoice endpoint for email sending)\n\n**Use cases:**\n- Record that an invoice was sent manually (e.g., via postal mail or other channels)\n- Update invoice status after external sending\n- Start payment term tracking\n\n**What is returned:**\n- Success response confirming the invoice was marked as sent","operationId":"InvoicesController_markAsSent","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Invoice marked as sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot be marked as sent (only invoices with status \"New\" or \"Sent\" can be marked as sent)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Mark invoice as sent","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/mark-first-reminder-as-sent":{"post":{"description":"Marks the first reminder for an invoice as sent to the customer. This records the first reminder date and contact information.\n\n**What happens when you mark a first reminder as sent:**\n1. First reminder date (`firstReminderAt`) is recorded as the current date\n2. First reminder type is set to \"Manual\" (indicating manual marking, not email sending)\n3. Contact recipient is recorded (from invoice contactId)\n4. User who marked it as sent is recorded\n\n**Important restrictions:**\n- Only invoices with status \"New\" or \"Sent\" can have reminders marked as sent\n- The invoice must be overdue (past its due date) to send reminders\n- This endpoint marks the reminder as sent manually (use send reminder endpoint for email sending)\n\n**Use cases:**\n- Record that a first reminder was sent manually (e.g., via postal mail or other channels)\n- Update reminder status after external sending\n- Track reminder history\n\n**What is returned:**\n- Success response confirming the first reminder was marked as sent","operationId":"InvoicesController_markFirstReminderAsSent","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"First reminder marked as sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot have reminder marked as sent"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Mark first reminder as sent","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/mark-second-reminder-as-sent":{"post":{"description":"Marks the second reminder for an invoice as sent to the customer. This records the second reminder date and contact information.\n\n**What happens when you mark a second reminder as sent:**\n1. Second reminder date (`secondReminderAt`) is recorded as the current date\n2. Second reminder type is set to \"Manual\" (indicating manual marking, not email sending)\n3. Contact recipient is recorded (from invoice contactId)\n4. User who marked it as sent is recorded\n\n**Important restrictions:**\n- Only invoices with status \"New\" or \"Sent\" can have reminders marked as sent\n- The invoice must be overdue (past its due date) to send reminders\n- A first reminder should typically be sent before a second reminder\n- This endpoint marks the reminder as sent manually (use send reminder endpoint for email sending)\n\n**Use cases:**\n- Record that a second reminder was sent manually (e.g., via postal mail or other channels)\n- Update reminder status after external sending\n- Track reminder history\n\n**What is returned:**\n- Success response confirming the second reminder was marked as sent","operationId":"InvoicesController_markSecondReminderAsSent","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Second reminder marked as sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot have reminder marked as sent"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Mark second reminder as sent","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/setInvoiceContactId":{"post":{"description":"Updates the contact ID for an existing invoice. The contact must be a valid organization member from the invoice's project customer organization.\n\n**What happens when you set an invoice contact:**\n1. The invoice's contactId field is updated\n2. The contact must belong to the project's customer organization\n3. If contactId is set to null, the contact is cleared\n4. The contact will receive the invoice when it is sent via email\n\n**Important restrictions:**\n- The contact must be a valid organization member from the project's customer organization\n- Use GET /billing/invoiceContacts/{projectId} to get available contacts\n- The contact must have a valid email address to receive invoices\n\n**Use cases:**\n- Set or change the invoice recipient before sending\n- Clear the contact if needed\n- Update contact after invoice creation\n\n**What is returned:**\n- Success response confirming the contact was set","operationId":"InvoicesController_setInvoiceContactId","parameters":[],"requestBody":{"required":true,"description":"Invoice ID and contact ID to set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetInvoiceContactIdDto"}}}},"responses":{"200":{"description":"Invoice contact set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invalid invoice ID or contact ID"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found or contact not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Set invoice contact ID","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/sendInvoice":{"post":{"description":"Sends an invoice to the customer via email as a PDF attachment. The invoice must have a contact with a valid email address set.\n\n**What happens when you send an invoice:**\n1. Invoice PDF document is generated\n2. Invoice status changes from \"New\" to \"Sent\"\n3. Sending date (`sentAt`) is recorded as the current date\n4. Sending type is set to \"Email\" (indicating email sending)\n5. Contact recipient is recorded (from invoice contactId)\n6. Payment due date (`dueDate`) is calculated based on:\n - Organization-specific payment terms (`invoiceDueDays`), or\n - Workspace default payment terms (`defaultInvoiceDueDays`)\n7. Status change timestamp and user are recorded\n8. Email is sent to the contact's email address with PDF attachment\n9. The payment term starts running from this point\n\n**Important restrictions:**\n- Only invoices with status \"New\" or \"Sent\" can be sent\n- Invoices that are \"Paid\" or \"Cancelled\" cannot be sent\n- The invoice must have a contact with a valid email address\n- Use POST /billing/setInvoiceContactId to set the contact if needed\n\n**Use cases:**\n- Send invoice to customer via email\n- Automate invoice delivery\n- Track invoice sending and payment terms\n\n**What is returned:**\n- Success response confirming the invoice was sent","operationId":"InvoicesController_sendInvoice","parameters":[],"requestBody":{"required":true,"description":"Invoice ID to send","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvoiceDto"}}}},"responses":{"200":{"description":"Invoice sent successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Invoice cannot be sent (only invoices with status \"New\" or \"Sent\" can be sent, or contact email is missing)"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Send invoice via email","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/settings":{"get":{"description":"Returns invoice-specific settings including language, reminder fees, interest rates, and custom text templates. Invoice settings can override organization or workspace defaults.\n\n**What is returned:**\n- Invoice-specific settings (language, reminder fees, interest rates)\n- Parent settings (from organization or workspace) for reference\n- Custom text templates (returned as HTML) for:\n - Closing salutation (withBestRegards)\n - Invoice greeting\n - Invoice footer\n - Reminder fee warning\n - First and second reminder greetings and footers\n - Cancellation body\n\n**Settings hierarchy:**\nInvoice settings override organization settings, which override workspace defaults. If a setting is null at the invoice level, the parent setting is used.","operationId":"InvoicesController_getInvoiceSettings","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved invoice settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get invoice settings","tags":["billing","invoices"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates invoice-specific settings including language, reminder fees, interest rates, and custom text templates. Only provided fields are updated; omitted fields remain unchanged.\n\n**What can be updated:**\n- Invoice language\n- Reminder fee settings (enable/disable, amount)\n- Interest settings (enable/disable, base rate, rate)\n- Custom text templates (accepts HTML or Markdown)\n\n**Settings behavior:**\n- Setting a value to `null` will use the parent setting (organization or workspace default)\n- Custom texts can be provided as HTML or Markdown and will be converted to internal format\n- Empty custom texts are treated as null (uses defaults)\n\n**Custom text templates:**\nAll custom text fields support invoice variables (e.g., `#invoiceNumber`, `#projectName`, `#clientCompanyName`). See the invoice text variables documentation for a complete list of available variables.\n\n**What is returned:**\nUpdated invoice settings with custom texts returned as HTML.","operationId":"InvoicesController_updateInvoiceSettings","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"description":"Invoice settings to update (all fields optional)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchInvoiceSettingsDto"}}}},"responses":{"200":{"description":"Invoice settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceSettingsResponseDto"}}}},"400":{"description":"Invalid request data or validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update invoice settings","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/invoices/{id}/default-texts":{"get":{"description":"Returns default invoice text templates for a specific language. These are the default texts that will be used if no custom texts are set for the invoice.\n\n**How default texts are determined:**\n1. Workspace-level defaults for the specified language\n2. Organization-level defaults (if available)\n3. System defaults (translated to the specified language)\n\n**Language selection:**\nIf no language is provided, the system uses:\n1. Invoice language (if set)\n2. Organization invoice language (if set)\n3. Workspace invoice language (if set)\n4. Workspace default language\n\n**What is returned:**\nAll default text templates as HTML:\n- Closing salutation (withBestRegards)\n- Invoice greeting\n- Invoice footer\n- Reminder fee warning\n- First and second reminder greetings and footers\n- Cancellation body\n\n**Use cases:**\n- Preview default texts before customizing\n- Reset custom texts to defaults\n- Display default texts in UI for reference","operationId":"InvoicesController_getDefaultInvoiceTexts","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"format":"uuid","type":"string"}},{"name":"language","required":false,"in":"query","description":"Language code for default texts (e.g., \"en\", \"de\"). If not provided, uses invoice/organization/workspace language.","schema":{"example":"en","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved default invoice texts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultInvoiceTextsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get default invoice texts","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/invoices/{id}/file-url":{"get":{"description":"Returns a public URL to access the generated invoice file. The file is always regenerated to ensure it reflects the latest invoice settings and data. Files are stored with a hash-based key (invoice ID + file type + document type) to avoid creating duplicate files for the same invoice variant.\n\n**What is returned:**\n- Public URL that can be used to download or access the invoice file\n- Filename of the generated file\n\n**File types supported:**\n- `pdf`: PDF with embedded ZUGFeRD/XRechnung XML (hybrid PDF)\n- `pdf-without-invoice`: PDF without embedded XML\n- `xml-einvoice`: XML E-Invoice file (XRechnung format)\n\n**Document types supported:**\n- `invoice`: Standard invoice document\n- `cancel`: Cancellation/credit note document\n- `first-reminder`: First payment reminder\n- `second-reminder`: Second payment reminder\n\n**File storage behavior:**\nFiles are stored with a hash-based key (invoice ID + file type + document type) to ensure the same file URL is returned for the same invoice variant. However, files are always regenerated to ensure they reflect the latest invoice settings and data. This ensures accuracy while maintaining consistent URLs.\n\n**Use cases:**\n- Generate invoice PDFs for customer portals\n- Download invoices for accounting purposes\n- Access invoice files programmatically\n- Share invoice URLs with customers or partners","operationId":"InvoicesController_getInvoiceFileUrl","parameters":[{"name":"id","required":true,"in":"path","description":"Invoice ID (UUID)","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"fileType","required":true,"in":"query","description":"Type of file to generate","schema":{"example":"pdf","type":"string","enum":["pdf","pdf-without-invoice","xml-einvoice"]}},{"name":"documentType","required":true,"in":"query","description":"Type of document to generate","schema":{"example":"invoice","type":"string","enum":["invoice","cancel","first-reminder","second-reminder"]}}],"responses":{"200":{"description":"Invoice file URL retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceFileUrlResponseDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get invoice file URL","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/potential-invoices":{"get":{"description":"**What are Potential Invoices?**\nPotential invoices represent billable items that are ready to be invoiced but have not been converted to actual invoices yet. These are invoice drafts that appear in the invoice review section, waiting to be checked, adjusted, and finalized into official invoice documents.\n\n**What gets included:**\n- Subscription billing rows that have passed their billing date\n- Time-based work (tasks with logged time) that has not been billed yet\n- Express quotations that have been accepted by customers\n- Products and components that are ready for billing\n- Manual positions and interim payments\n\n**What data is returned:**\n- List of all potential invoices grouped by project, organization, and billing period\n- Each potential invoice includes the billing period (dateFrom, dateTo), total net amount, and invoice type\n- Results are automatically filtered based on project access permissions\n- Each entry shows which organization and project it belongs to\n\n**Invoice Types:**\n- **Mixed**: Combined invoice with multiple billing types (time, subscriptions, products, components)\n- **Subscription**: Recurring subscription billing only (monthly or periodic fees)\n- **TimeBased**: Time-based work (logged hours on tasks) only\n- **ExpressQuotation**: Accepted express quotations only (quick add-ons from tickets)\n- **SingleProject**: Single project invoice (project-based billing)\n- **InterimPayment**: Interim or advance payment invoice\n\n**How it works:**\nThe system automatically creates potential invoices when billable items become due. For example, completed tickets appear as time-based items, subscriptions generate entries on their billing dates, and accepted express quotations become billable immediately.\n\n**Permission requirements:**\nRequires Invoices.manage permission to view potential invoices. Results are scoped to projects you have access to.","operationId":"PotentialInvoicesController_getPotentialInvoices","parameters":[],"responses":{"200":{"description":"Potential invoices retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PotentialInvoiceResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get potential invoices","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/potential-invoices/{id}/contacts":{"get":{"description":"**What are Invoice Contacts?**\nReturns a list of organization members (contacts) from the customer organization who can be selected as invoice recipients. These contacts are the people who will receive the invoice when it is sent via email. You can set a contact for each potential invoice to specify who should receive the final invoice document.\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\nThe projectId is extracted from the invoice ID to determine which organization is the customer, and then returns contacts from that organization.\n\n**What data is returned:**\n- List of organization members from the project customer organization\n- Each contact includes ID (UUID), full name, avatar file ID (if available), and email address\n- Contacts are sorted alphabetically by first name, then last name\n- Only active (non-deleted) organization members are returned\n\n**How to use:**\n1. Get the list of available contacts for a potential invoice\n2. Select a contact ID from the list\n3. Use the PATCH endpoint to set the contactId for the potential invoice\n4. When the invoice is finalized and sent, it will be emailed to this contact\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project to view contacts.","operationId":"PotentialInvoicesController_getInvoiceContacts","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"responses":{"200":{"description":"Invoice contacts retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceContactResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get available contacts for potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:read"]}},"/billing/potential-invoices/{id}":{"get":{"description":"**What are Potential Invoice Details?**\nReturns the complete breakdown of a specific potential invoice, showing all billable items that make up the total amount. This is the detailed view you see when reviewing an invoice before finalizing it. You can see exactly what is being billed, adjust quantities or amounts, and configure additional settings.\n\n**What is included in the details:**\n- **Subscription billing rows**: Recurring fees with quantities, unit prices, and payment types (fixed, per-unit, one-time)\n- **Time-based tasks**: Completed tickets with logged hours, estimated time, billed time, and hourly rates\n- **Express quotations**: Accepted quick quotes from tickets with items, quantities, and unit prices\n- **Products**: Items from the product catalog with options, quantities, discounts, and pricing\n- **Components**: Project components with time estimates, hourly rates, and nested items\n- **Support contingent charges**: Retainer plan charges for Support-type projects, based on allocated hours and pricing for billing periods\n- **Manual positions**: Custom billing items (third-party costs, flat fees, interim payments)\n- **Leadtime fee settings**: Configuration for adding the Leadtime service fee to the invoice\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n- Type: One of Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment, SupportContingentCharge\n- ProjectId: UUID of the project\n- DateFrom/DateTo: Dates in YYYY-MM-DD format representing the billing period\n\n**What data is returned:**\n- Complete invoice structure with all billable items organized by type\n- Billing period (periodFrom, periodTo) and custom billed dates (billedFrom, billedTo)\n- Tax calculations (tax amount, reverse charge settings)\n- Contact information (contactId for invoice recipient)\n- Leadtime fee settings (percentage, method, task distribution, custom title)\n- Lists of skipped tasks and express quotations (items excluded from billing)\n- All items include detailed pricing, discounts, descriptions (as HTML), and metadata\n- Product and component descriptions are converted from ProseMirror IDoc format to HTML\n\n**How to use:**\n1. Get the list of potential invoices to find the invoice ID\n2. Use this endpoint to get full details of a specific invoice\n3. Review all billable items and their amounts\n4. Use the PATCH endpoint to adjust settings (billed dates, contact, etc.)\n5. Use other endpoints to skip items, add manual positions, or configure fees\n6. Once reviewed and adjusted, the invoice can be finalized into an actual invoice document\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project to view potential invoice details.","operationId":"PotentialInvoicesController_getPotentialInvoiceDetails","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"responses":{"200":{"description":"Potential invoice details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PotentialInvoiceDetailsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get potential invoice details","tags":["billing","invoices"],"x-required-scopes":["api:read"]},"patch":{"description":"**What can be updated:**\nThis endpoint allows partial updates to potential invoice settings. Only the fields you provide in the request body will be updated; all other fields remain unchanged. This means you can update just one field, multiple fields, or all fields in a single request.\n\n**Updatable fields:**\n- **billedFrom**: Billed from date (ISO 8601 date string). Sets the start date for the billing period that will appear on the final invoice document. This can differ from the actual service period (periodFrom) if you want to show a different date range on the invoice.\n- **billedTo**: Billed to date (ISO 8601 date string). Sets the end date for the billing period that will appear on the final invoice document. This can differ from the actual service period (periodTo) if you want to show a different date range on the invoice.\n- **contactId**: Contact ID (organization member UUID). Sets the invoice recipient who will receive the invoice when it is sent via email. Set to null to clear the contact and remove the recipient assignment.\n\n**How partial updates work:**\n- If you only provide billedFrom, only that field will be updated\n- If you only provide contactId, only that field will be updated\n- You can provide any combination of the three fields\n- Fields you omit will remain unchanged\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Date format:**\nDates can be provided in ISO 8601 format:\n- Date-only: \"2025-10-01\" (recommended)\n- ISO timestamp: \"2025-10-01T00:00:00.000Z\"\n\n**Contact validation:**\nWhen setting a contactId, the system validates that:\n- The contact exists and is active\n- The contact belongs to the project customer organization\n- If the contact is invalid, a NotFoundException is returned\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project to update potential invoice settings.","operationId":"PotentialInvoicesController_patchPotentialInvoice","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPotentialInvoiceDto"}}}},"responses":{"200":{"description":"Potential invoice updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update potential invoice settings","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/reset":{"post":{"description":"**What does reset do?**\nResets all customizations and metadata for a potential invoice, returning it to its default state. This clears all manual adjustments you have made, so the invoice will show the original billable items as they were automatically calculated by the system.\n\n**What gets cleared:**\n- Billed from and billed to dates (reverts to default billing period)\n- Contact ID (removes invoice recipient)\n- Subscription quantities and order (reverts to default quantities)\n- Custom manual positions (removes any manually added items)\n- Skipped tasks and express quotations (includes all items back in the invoice)\n- Leadtime fee settings (reverts to default configuration)\n\n**When to use:**\n- When you want to start fresh with default invoice settings\n- After making mistakes in invoice configuration and want to undo all changes\n- To clear all customizations before creating a new invoice from scratch\n- When you need to see the original calculated amounts without any adjustments\n\n**Important notes:**\n- This operation cannot be undone\n- The invoice will revert to showing all automatically calculated billable items\n- Any custom manual positions you added will be removed\n- The invoice will use default billing period dates\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project to reset potential invoice.","operationId":"PotentialInvoicesController_resetPotentialInvoice","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"responses":{"200":{"description":"Potential invoice reset successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reset potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/tasks/{taskId}/toggle-skipped":{"post":{"description":"**What does this do?**\nToggles whether a task is skipped (excluded) from the potential invoice. When a task is skipped, it is added to the skipped tasks list and will not appear on the final invoice. Toggling again removes it from the skipped list and includes it back in the invoice.\n\n**When to use:**\n- To exclude a task from billing without permanently marking it as \"do not bill\"\n- To temporarily remove a task from an invoice during review\n- To include a previously skipped task back in the invoice\n\n**How it works:**\n- First call: Adds task to skipped tasks list (excludes from invoice)\n- Second call: Removes task from skipped tasks list (includes in invoice)\n- The task itself is not modified, only the invoice metadata is updated\n\n**Task requirements:**\n- Task must belong to the potential invoice's project\n- Task must not be already billed (billed: false)\n- User must have access to the project\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_toggleSkippedTask","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"taskId","required":true,"in":"path","description":"Task ID (UUID) to toggle skipped status for","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"responses":{"200":{"description":"Task skipped status toggled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Toggle task skipped status","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/tasks/{taskId}/billed-time":{"post":{"description":"**What does this do?**\nSets the billed time (hours) for a task in a potential invoice. The billed time is the amount of time that will be charged to the customer, which may differ from the actual time spent on the task.\n\n**When to use:**\n- To adjust the billed hours up or down from the actual time spent\n- To bill the estimated time instead of actual time\n- To correct billing amounts before finalizing the invoice\n\n**How it works:**\n- Updates the task's billedTime field directly\n- The billed time is used to calculate the total charge (billedTime Γ hourly rate)\n- Can be set to any non-negative number\n- Setting a different value than spent time will show a difference in the invoice details\n\n**Task requirements:**\n- Task must belong to the potential invoice's project\n- Task must not be already billed (billed: false)\n- User must have access to the project\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_setTaskBilledTime","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"taskId","required":true,"in":"path","description":"Task ID (UUID) to set billed time for","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetTaskBilledTimeDto"}}}},"responses":{"200":{"description":"Task billed time set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Set task billed time","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/tasks/{taskId}/details":{"post":{"description":"**What does this do?**\nSets both the billed time and billed title for a task in a potential invoice. This allows you to customize how the task appears on the invoice, including adjusting the time charged and providing a more customer-friendly title.\n\n**When to use:**\n- To adjust both the billed hours and the task title in one operation\n- To customize how tasks appear on invoices for better customer clarity\n- To correct billing details before finalizing the invoice\n\n**How it works:**\n- Updates both task.billedTime and task.billedTitle fields\n- Both fields are optional - you can update just one or both\n- billedTime can be set to null to clear it (revert to using spent time)\n- billedTitle can be set to null to use the original task title\n- The billed time is used to calculate the total charge (billedTime Γ hourly rate)\n\n**Task requirements:**\n- Task must belong to the potential invoice's project\n- Task must not be already billed (billed: false)\n- User must have access to the project\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_setTaskDetails","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"taskId","required":true,"in":"path","description":"Task ID (UUID) to update details for","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetTaskDetailsDto"}}}},"responses":{"200":{"description":"Task details updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Set task billing details","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/tasks/{taskId}/skip-from-billing":{"post":{"description":"**What does this do?**\nSets the skipFromBilling flag on a task, which permanently marks the task as excluded from billing. Unlike toggling skipped status (which only affects the current invoice), this flag prevents the task from appearing in any future potential invoices.\n\n**When to use:**\n- To permanently exclude a task from billing (e.g., internal work, non-billable tasks)\n- To mark tasks that should never be invoiced\n- To undo a previous \"skip from billing\" decision (set to false)\n\n**How it works:**\n- Updates the task.skipFromBilling field directly on the task\n- When set to true, the task will not appear in any potential invoices\n- When set to false, the task can be included in invoices again\n- This is different from toggling skipped status, which only affects the current invoice metadata\n\n**Task requirements:**\n- Task must belong to the potential invoice's project\n- Task must not be already billed (billed: false)\n- User must have access to the project\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_skipFromBilling","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"taskId","required":true,"in":"path","description":"Task ID (UUID) to set skip from billing flag for","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkipFromBillingDto"}}}},"responses":{"200":{"description":"Task skip from billing flag set successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or task not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Set task skip from billing flag","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/manual-positions":{"post":{"description":"**What does this do?**\nAdds a custom manual position (line item) to a potential invoice. Manual positions allow you to bill for external costs, flat fees, or other items that aren't automatically created by tickets, products, or subscriptions.\n\n**When to use:**\n- To add external costs (e.g., translation services, license costs)\n- To add travel expenses or other one-time charges\n- To add flat rates with no ticket reference\n- To add items that were missing from the original offer\n\n**How it works:**\n- Creates a new manual position entry stored in the potential invoice metadata\n- The position appears immediately in the invoice preview\n- Manual positions are fully integrated into tax and total calculations\n- Only custom manual positions (type: manual) can be added, updated, or deleted\n- Project manual positions (from project snapshots) are read-only and cannot be modified\n\n**Position requirements:**\n- Must provide a unique UUID for the position ID\n- Title and price are required\n- Price must be a positive number (net amount before tax)\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_addManualPosition","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddManualPositionDto"}}}},"responses":{"200":{"description":"Manual position added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add manual position to potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/manual-positions/{positionId}":{"patch":{"description":"**What does this do?**\nUpdates an existing custom manual position in a potential invoice. You can modify the title and/or price of the position.\n\n**When to use:**\n- To correct the title or price of a manual position\n- To adjust pricing before finalizing the invoice\n- To update position details after initial creation\n\n**How it works:**\n- Updates the manual position stored in the potential invoice metadata\n- Only custom manual positions (type: manual) can be updated\n- Project manual positions (from project snapshots) are read-only and cannot be modified\n- Both title and price must be provided (even if only one is changing)\n\n**Position requirements:**\n- Position must exist in the potential invoice\n- Position must be a custom manual position (not a project position)\n- Title and price are required\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_updateManualPosition","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"positionId","required":true,"in":"path","description":"Manual position ID (UUID) to update","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateManualPositionDto"}}}},"responses":{"200":{"description":"Manual position updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or manual position not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update manual position in potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]},"delete":{"description":"**What does this do?**\nRemoves a custom manual position from a potential invoice. The position is permanently removed from the invoice and will no longer appear in the invoice preview or be included in calculations.\n\n**When to use:**\n- To remove a manual position that was added by mistake\n- To remove a position that is no longer needed\n- To clean up the invoice before finalizing\n\n**How it works:**\n- Removes the manual position from the potential invoice metadata\n- Only custom manual positions (type: manual) can be deleted\n- Project manual positions (from project snapshots) are read-only and cannot be deleted\n- The position is immediately removed from the invoice preview\n\n**Position requirements:**\n- Position must exist in the potential invoice\n- Position must be a custom manual position (not a project position)\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_deleteManualPosition","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"positionId","required":true,"in":"path","description":"Manual position ID (UUID) to delete","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"responses":{"200":{"description":"Manual position deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or manual position not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete manual position from potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/manual-positions/sort":{"post":{"description":"**What does this do?**\nReorders the manual positions in a potential invoice. The positions will appear in the order specified by the items array.\n\n**When to use:**\n- To change the display order of manual positions on the invoice\n- To group related positions together\n- To organize positions in a logical sequence\n\n**How it works:**\n- Updates the sort order of manual positions stored in the potential invoice metadata\n- Only custom manual positions (type: manual) can be reordered\n- Project manual positions (from project snapshots) maintain their original order\n- The items array should contain all position IDs in the desired order\n- Positions not included in the array will be placed at the end\n\n**Position requirements:**\n- All position IDs in the items array must exist in the potential invoice\n- Only custom manual positions can be reordered\n- The array can include a subset of positions (others will be placed at the end)\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_saveManualPositionsSort","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveManualPositionsSortDto"}}}},"responses":{"200":{"description":"Manual positions reordered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder manual positions in potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/subscriptions/sort":{"post":{"description":"**What does this do?**\nReorders the subscription billing rows in a potential invoice. The subscriptions will appear on the invoice in the order specified by the items array.\n\n**When to use:**\n- To change the display order of subscription billing rows on the invoice\n- To group related subscriptions together\n- To organize subscriptions in a logical sequence (e.g., by priority or billing type)\n\n**How it works:**\n- Updates the sort order of subscription billing rows stored in the potential invoice metadata\n- The items array should contain all subscription billing IDs (billingId) in the desired order\n- Subscriptions not included in the array will maintain their original order\n- The order affects how subscriptions appear on the final invoice document\n\n**Subscription requirements:**\n- All subscription billing IDs in the items array must exist in the potential invoice\n- Use the billingId field from subscription billing rows (not the id field)\n- The array can include a subset of subscriptions (others will maintain their order)\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_saveSubscriptionSort","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveSubscriptionSortDto"}}}},"responses":{"200":{"description":"Subscriptions reordered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder subscriptions in potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/billing/potential-invoices/{id}/subscriptions/{itemId}/quantity":{"post":{"description":"**What does this do?**\nSets a custom quantity for a subscription billing row in a potential invoice. For per-unit pricing subscriptions, this allows you to adjust how many units are billed, which may differ from the default quantity calculated by the system.\n\n**When to use:**\n- To adjust the quantity for per-unit pricing subscriptions before finalizing the invoice\n- To bill a different number of units than the default calculated amount\n- To correct billing quantities based on actual usage or customer agreements\n- To clear a custom quantity and revert to the default calculated quantity\n\n**How it works:**\n- Updates the subscription quantity stored in the potential invoice metadata\n- The quantity is used to calculate the total charge (quantity Γ unit price)\n- Setting value to null or omitting it clears the custom quantity and reverts to default\n- The quantity must be a non-negative integer\n- Only affects the current potential invoice; does not modify the subscription billing configuration\n\n**Subscription requirements:**\n- Subscription billing ID (itemId) must exist in the potential invoice\n- Use the billingId field from subscription billing rows\n- Only per-unit pricing subscriptions (payment type: perUnit) typically use quantities\n- Fixed monthly fees and one-time charges may not use quantities\n\n**Invoice ID Format:**\nThe invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}\n- Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31\n\n**Permission requirements:**\nRequires Invoices.manage permission and access to the project.","operationId":"PotentialInvoicesController_changeQuantity","parameters":[{"name":"id","required":true,"in":"path","description":"Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}","schema":{"example":"SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31","type":"string"}},{"name":"itemId","required":true,"in":"path","description":"Subscription billing ID (billingId UUID) to change quantity for","schema":{"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeQuantityDto"}}}},"responses":{"200":{"description":"Subscription quantity updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"User lacks Invoices.manage permission or project access"},"404":{"description":"Potential invoice or subscription billing not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Change subscription quantity in potential invoice","tags":["billing","invoices"],"x-required-scopes":["api:write"]}},"/helpdesk/settings":{"get":{"description":"Retrieves workspace-wide helpdesk settings including default configurations and email account settings.\n\n**What is Helpdesk?**\nHelpdesk is an automated email-to-task conversion system that transforms incoming emails into tasks. When enabled, the system automatically:\n- Pulls emails from configured email accounts (IMAP, Gmail, Microsoft Graph)\n- Converts emails into tasks with proper assignment, priority, and categorization\n- Sends automatic replies to new senders (if configured)\n- Links emails to tasks for full conversation history\n\n**What is returned:**\n- **Workspace settings**: Global helpdesk configuration including:\n - `isHelpdeskEnabled`: Whether helpdesk is enabled for the workspace\n - `defaultSettings`: Default task creation settings (project, type, status, priority, assignment)\n - `defaultReplyBody`: HTML template for automatic replies (supports variables like `taskNumber`)\n - `sendDefaultReply`: Whether to automatically send replies to new senders\n- **Email account settings**: List of all email accounts with their helpdesk status:\n - Each account shows if helpdesk is enabled\n - Account-specific overrides that override workspace defaults\n - Settings include task defaults, auto-reply configuration, and assignment rules\n\n**Settings inheritance:**\nEmail accounts can override workspace defaults. When an account has its own settings:\n- Non-null fields override workspace defaults\n- Null fields inherit from workspace defaults\n- `sendDefaultReply` supports 3-state inheritance: `null` (use default), `true` (enabled), `false` (disabled)\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission.","operationId":"HelpdeskController_getHelpdeskSettings","parameters":[],"responses":{"200":{"description":"Workspace helpdesk settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelpdeskSettingsApiResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get workspace helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:read"]},"put":{"description":"Updates workspace-wide default helpdesk settings. These settings apply to all email accounts unless overridden at the account level.\n\n**What can be configured:**\n- **Default task priority**: Priority level for all helpdesk tasks (Urgent, High, Normal, Low)\n- **Default task type**: Task type ID that will be assigned to helpdesk tasks\n- **Default task status**: Task status ID for newly created helpdesk tasks\n- **Auto-assign user**: Optional user ID to automatically assign tasks to\n- **Default reply body**: HTML template for automatic replies (supports variables like `taskNumber`)\n- **Send default reply**: Whether to automatically send replies to new email senders\n\n**How it works:**\n- These settings become the base configuration for all helpdesk operations\n- Individual email accounts can override any of these defaults\n- When an email account has no specific settings, it uses these workspace defaults\n- The `isHelpdeskEnabled` flag is preserved from current settings (not updated via this endpoint)\n\n**Auto-reply system:**\nWhen `sendDefaultReply` is enabled, the system automatically sends replies to initial emails from new senders:\n- Only triggers for first-time senders (not replies to existing conversations)\n- Uses the `defaultReplyBody` template with variable substitution\n- Variables like `taskNumber` are replaced with actual values\n- Replies are sent from the same email account that received the original email\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Changes affect all email accounts that don't have account-specific overrides.","operationId":"HelpdeskController_updateHelpdeskSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHelpdeskSettingsDto"}}}},"responses":{"200":{"description":"Workspace helpdesk settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelpdeskSettingsApiResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update workspace helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:write"]}},"/helpdesk/email-accounts":{"get":{"description":"Retrieves all email accounts in the workspace with their helpdesk enabled status and settings.\n\n**What is returned:**\nA list of all email accounts configured in the workspace, each containing:\n- **Account identification**: ID, email address, and display name\n- **Helpdesk status**: Whether helpdesk is enabled for this account\n- **Account settings**: If enabled, includes all account-specific helpdesk settings:\n - Task defaults (project, type, status, priority, assignment)\n - Auto-reply configuration\n - Any overrides that differ from workspace defaults\n\n**Use cases:**\n- View which email accounts have helpdesk enabled\n- Check account-specific settings and overrides\n- Identify accounts that are using workspace defaults vs. custom settings\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission.","operationId":"HelpdeskController_getEmailAccounts","parameters":[],"responses":{"200":{"description":"Email accounts retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmailAccountHelpdeskStatusResponse"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get email accounts with helpdesk status","tags":["helpdesk"],"x-required-scopes":["api:read"]}},"/helpdesk/email-accounts/{accountId}/settings":{"get":{"description":"Retrieves helpdesk settings for a specific email account, including any account-level overrides.\n\n**What is returned:**\n- **Account information**: ID, email address, display name\n- **Helpdesk status**: Whether helpdesk is enabled for this account\n- **Account settings**: If enabled, returns all account-specific settings:\n - Task defaults that override workspace defaults\n - Auto-reply configuration (with 3-state inheritance support)\n - Assignment rules\n - Any other account-level overrides\n\n**Settings inheritance:**\nIf the account has custom settings:\n- Non-null fields override workspace defaults\n- Null fields inherit from workspace defaults\n- The response shows the effective settings (merged defaults + overrides)\n\n**Error handling:**\nReturns 404 if the email account is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission.","operationId":"HelpdeskController_getEmailAccountSettings","parameters":[{"name":"accountId","required":true,"in":"path","description":"Email account ID","schema":{"example":"account-uuid-123","type":"string"}}],"responses":{"200":{"description":"Email account settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccountHelpdeskStatusResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Email account not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get specific email account helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:read"]},"put":{"description":"Updates helpdesk settings for a specific email account. These settings override workspace defaults. Omitted fields inherit from workspace defaults.\n\n**What can be configured:**\nAll fields are optional - only provided fields will override workspace defaults:\n- **Task priority**: Override default priority for this account\n- **Task type**: Override default task type ID\n- **Task status**: Override default task status ID\n- **Auto-assign user**: Override default assignment (set to `null` to remove override)\n- **Default reply body**: Override auto-reply template (supports variables like `taskNumber`)\n- **Send default reply**: 3-state control - `null` (inherit), `true` (enabled), `false` (disabled)\n\n**How inheritance works:**\n- Providing a value overrides the workspace default\n- Omitting a field (or setting to `null` for some fields) inherits from workspace defaults\n- `sendDefaultReply` has special 3-state behavior: `null` = use workspace default, `true`/`false` = override\n- Updating settings automatically enables helpdesk for the account (`isEnabled: true`)\n\n**Example scenarios:**\n- Set only `defaultTaskPriority: High` β Account uses High priority, all other settings from workspace\n- Set `sendDefaultReply: false` β Disables auto-reply for this account only\n- Set `sendDefaultReply: null` β Account inherits workspace auto-reply setting\n\n**Error handling:**\nReturns 404 if the email account is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission.","operationId":"HelpdeskController_updateEmailAccountSettings","parameters":[{"name":"accountId","required":true,"in":"path","description":"Email account ID","schema":{"example":"account-uuid-123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailAccountHelpdeskSettingsDto"}}}},"responses":{"200":{"description":"Email account settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccountHelpdeskStatusResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Email account not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update email account helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:write"]}},"/helpdesk/email-accounts/{accountId}/enable":{"post":{"description":"Enables helpdesk functionality for a specific email account. The account will use workspace default settings unless account-level overrides are configured.\n\n**What this does:**\n- Enables helpdesk processing for the specified email account\n- The account will start receiving and processing emails automatically\n- Uses workspace default settings if no account-specific overrides exist\n- Preserves any existing account-level settings if they were previously configured\n\n**How it works:**\n1. The system verifies the email account exists and belongs to the workspace\n2. Sets `isEnabled: true` for the account's helpdesk settings\n3. If no account settings exist, they are created with workspace defaults\n4. If account settings exist, only the `isEnabled` flag is updated\n5. The account becomes eligible for automated email pulling via cron jobs\n\n**After enabling:**\n- Emails sent to this account will be automatically pulled (every minute via cron)\n- Incoming emails will be converted to tasks using workspace defaults (or account overrides)\n- Auto-replies will be sent if configured in workspace or account settings\n- Tasks will be created with proper assignment, priority, and categorization\n\n**Error handling:**\nReturns 404 if the email account is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Workspace helpdesk must be enabled (`isHelpdeskEnabled: true`) for this to work.","operationId":"HelpdeskController_enableHelpdeskForAccount","parameters":[{"name":"accountId","required":true,"in":"path","description":"Email account ID","schema":{"example":"account-uuid-123","type":"string"}}],"responses":{"200":{"description":"Helpdesk enabled for email account successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccountHelpdeskStatusResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Email account not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Enable helpdesk for email account","tags":["helpdesk"],"x-required-scopes":["api:write"]}},"/helpdesk/email-accounts/{accountId}/disable":{"delete":{"description":"Disables helpdesk functionality for a specific email account. Any account-level override settings are preserved but not applied until re-enabled.\n\n**What this does:**\n- Disables helpdesk processing for the specified email account\n- Stops automatic email pulling and task creation for this account\n- Preserves all account-specific settings for future re-enabling\n- The account settings remain in the database but are not used\n\n**How it works:**\n1. The system verifies the email account exists and belongs to the workspace\n2. Sets `isEnabled: false` for the account's helpdesk settings\n3. All account-level overrides are preserved (task defaults, auto-reply, etc.)\n4. The account is removed from automated email pulling cron jobs\n\n**After disabling:**\n- No new emails will be pulled from this account\n- No tasks will be created from emails sent to this account\n- Existing tasks and email history remain unchanged\n- Settings can be restored by re-enabling the account\n\n**Use cases:**\n- Temporarily disable helpdesk for an account (e.g., during maintenance)\n- Stop processing emails for a specific account without losing configuration\n- Test different configurations by disabling/enabling accounts\n\n**Error handling:**\nReturns 404 if the email account is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission.","operationId":"HelpdeskController_disableHelpdeskForAccount","parameters":[{"name":"accountId","required":true,"in":"path","description":"Email account ID","schema":{"example":"account-uuid-123","type":"string"}}],"responses":{"200":{"description":"Helpdesk disabled for email account successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccountHelpdeskStatusResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Email account not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Disable helpdesk for email account","tags":["helpdesk"],"x-required-scopes":["api:write"]}},"/helpdesk/organization-settings":{"get":{"description":"**This endpoint is deprecated.** Use `GET /helpdesk/organizations/:organizationId/settings` instead.\n\nThis endpoint was designed to retrieve organization-specific helpdesk settings, but requires an organization ID to function properly. Please use the endpoint with the organization ID in the path parameter.","operationId":"HelpdeskController_getOrganizationHelpdeskSettings","parameters":[],"responses":{"200":{"description":"Organization helpdesk settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationHelpdeskSettingsApiResponse"}}}},"400":{"description":"Organization ID is required"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization helpdesk settings (deprecated)","tags":["helpdesk"],"x-required-scopes":["api:read"]}},"/helpdesk/organizations/{organizationId}/settings":{"get":{"description":"Retrieves organization-specific helpdesk settings for a given organization.\n\n**What is Organization Helpdesk?**\nOrganizations can have their own helpdesk settings that override workspace defaults. This allows different organizations to have different task routing, priorities, and auto-reply configurations when emails are sent to the same helpdesk email account.\n\n**Settings priority (highest to lowest):**\n1. **Organization settings with mode='all'**: Override everything for all senders\n2. **Organization settings for member**: Apply when sender is an organization member (mode='onlyMembers')\n3. **Workspace email account settings**: Account-specific overrides at workspace level\n4. **Workspace defaults**: Base configuration for all helpdesk operations\n\n**What is returned:**\n- **Organization settings**: Organization-level configuration including:\n - Organization ID and name\n - Email account settings with organization-specific overrides\n - Organization mode (`onlyMembers` or `all`)\n - Task defaults, auto-reply configuration, and assignment rules\n- **Email account settings**: List of email accounts with organization-level settings:\n - Each account shows organization-specific overrides\n - Includes effective defaults (merged from workspace + organization settings)\n - Shows which settings override workspace defaults\n\n**Organization modes:**\n- **`onlyMembers`**: Settings apply only when the email sender is a member of this organization\n- **`all`**: Settings apply to ALL emails sent to the account, regardless of sender\n\n**Error handling:**\nReturns 404 if the organization is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `Organizations.edit` permission.","operationId":"HelpdeskController_getOrganizationHelpdeskSettingsById","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization ID","schema":{"example":"org-uuid-123","type":"string"}}],"responses":{"200":{"description":"Organization helpdesk settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationHelpdeskSettingsApiResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Organization not found"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:read"]},"put":{"description":"Updates organization-specific helpdesk settings. These settings override workspace defaults for the specified organization.\n\n**What can be configured:**\n- **Organization mode**: How settings apply (`onlyMembers` or `all`)\n - `onlyMembers`: Settings apply only when sender is a member of this organization\n - `all`: Settings apply to ALL emails sent to the account, regardless of sender\n- **Default task priority**: Priority level for organization helpdesk tasks\n- **Default task type**: Task type ID for organization helpdesk tasks\n- **Default task status**: Task status ID for organization helpdesk tasks\n- **Auto-assign user**: Optional user ID to automatically assign tasks to\n- **Default reply body**: HTML template for automatic replies (supports variables like `taskNumber`)\n- **Send default reply**: Whether to automatically send replies to new email senders\n\n**How it works:**\n1. Organization settings override workspace defaults when emails are processed\n2. Settings apply based on the organization mode:\n - `onlyMembers`: Only when sender is an organization member\n - `all`: For all emails to the account (highest priority)\n3. Null fields inherit from workspace email account settings or workspace defaults\n4. Multiple organizations can have settings for the same email account\n\n**Settings resolution example:**\nIf an email is sent to `support@company.com`:\n- First check: Any org with mode='all'? β Use that org's settings\n- Second check: Is sender a member? β Use their org's settings (if mode='onlyMembers')\n- Third check: Workspace email account settings\n- Final fallback: Workspace defaults\n\n**Error handling:**\nReturns 404 if the organization is not found or doesn't belong to the workspace.\n\n**Note:** This endpoint requires the `Organizations.edit` permission. Organization settings provide fine-grained control over helpdesk behavior per organization.","operationId":"HelpdeskController_updateOrganizationHelpdeskSettings","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization ID","schema":{"example":"org-uuid-123","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationHelpdeskSettingsDto"}}}},"responses":{"200":{"description":"Organization helpdesk settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationHelpdeskSettingsApiResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Organization not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization helpdesk settings","tags":["helpdesk"],"x-required-scopes":["api:write"]}},"/administration/appearance-settings":{"get":{"description":"Retrieves the current workspace appearance settings.\n\n**What is returned:**\n- **Main workspace color**: The primary color theme used throughout the workspace\n- **Logo URL**: Public URL for the workspace logo (shown in light theme)\n- **Logo dark theme URL**: Public URL for the workspace logo used in dark theme\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Appearance settings affect how the workspace looks to all users in the workspace.","operationId":"AppearanceSettingsController_getAppearanceSettings","parameters":[],"responses":{"200":{"description":"Appearance settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppearanceSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get workspace appearance settings","tags":["administration","appearance-settings"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates workspace appearance settings. All fields are optional - only provided fields will be updated.\n\n**What can be updated:**\n- **Main workspace color**: Changes the primary color theme used throughout the workspace\n- **Logo**: Upload a logo file for light theme display\n- **Logo dark theme**: Upload a separate logo file optimized for dark theme display\n\n**To upload logo files:**\n1. Call POST /api/public/workspace/upload to upload each logo file\n2. Get the file ID from the response\n3. Use that file ID in the `logoId` or `logoDarkThemeId` field\n4. Set to `null` to remove an existing logo\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Changes affect how the workspace appears to all users. The system validates that provided file IDs exist and belong to the workspace.","operationId":"AppearanceSettingsController_updateAppearanceSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchAppearanceSettingsDto"}}}},"responses":{"200":{"description":"Appearance settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"File not found - Invalid logoId or logoDarkThemeId provided"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update workspace appearance settings","tags":["administration","appearance-settings"],"x-required-scopes":["api:write"]}},"/administration/basic-settings":{"get":{"description":"Retrieves the current basic workspace settings.\n\n**What is returned:**\n- **Workspace identification**: ID and brand color\n- **Localization**: Default language, country of operation, timezone\n- **Attendance tracking**: Whether attendance is enabled, color thresholds for time tracking quality\n- **Default working hours**: Default start and end times for the workspace\n- **Time tracker**: Reminder interval settings\n- **Sprint configuration**: Sprint duration, start day, and end day\n- **Journal notifications**: User IDs who receive notifications for journal entries\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. These settings affect how the entire workspace operates and are used as defaults throughout the system.","operationId":"BasicSettingsController_getBasicSettings","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetBasicSettingsDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get workspace basic settings","tags":["administration","basic-settings"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates workspace basic settings. All fields are optional - only provided fields will be updated.\n\n**What can be updated:**\n- **Brand color**: Hex color code for workspace branding\n- **Default language**: Default language for the workspace (e.g., \"en\", \"de\")\n- **Country of operation**: ISO country code (e.g., \"US\", \"DE\")\n- **Timezone**: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/Berlin\")\n- **Attendance tracking**: Enable or disable attendance tracking for employees\n- **Time tracking thresholds**: Percentage thresholds for marking time tracking as \"good\" or \"bad\"\n- **Default working hours**: Default start and end times for employees\n- **Time tracker reminders**: Interval in minutes for reminding users to track time (5-120 minutes)\n- **Sprint configuration**: Sprint duration in days, start day (1=Monday), and end day\n- **Journal notifications**: List of user IDs who should receive notifications for journal entries\n\n**Validation rules:**\n- `timeColorBadPercent` must be less than `timeColorGoodPercent`\n- `defaultTimeTo` must be after `defaultTimeFrom`\n- `timeTrackerAnnoyanceInMin` must be between 5 and 120\n- `sprintStartDay` and `sprintEndDay` must be between 1 (Monday) and 7 (Sunday)\n\n**Note:** This endpoint requires the `WsSettings.manageSettings` permission. Changes affect the entire workspace and all users.","operationId":"BasicSettingsController_patchBasicSettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchBasicSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update workspace basic settings","tags":["administration","basic-settings"],"x-required-scopes":["api:write"]}},"/holidays/settings":{"get":{"description":"Retrieves the workspace holiday configuration, including the default holiday country/region and all available holiday sources.\n\n**What are Holiday Settings?**\nHoliday settings determine which regional holiday rules the system uses for capacity planning. Leadtime needs to know when employees are not available due to regional holidays, which is essential for accurate capacity management.\n\n**What is returned:**\n- `defaultHolidayCode`: The default holiday country/region code for the workspace (e.g., \"US\", \"DE\", \"US-CA\")\n- `availableCountries`: List of all available holiday countries and states with their codes and localized names\n\n**How it works:**\n- The default holiday code is automatically applied to all new employees\n- Individual employees can have different holiday rules set in their profile\n- Holidays are displayed in the team calendar and used for capacity calculations\n- Use the `language` query parameter to get country names in a specific language (default: \"en\")\n\n**Note:** This endpoint requires the `manageSettings` permission.","operationId":"HolidaysController_getHolidaySettings","parameters":[{"name":"language","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Holiday settings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidaySettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get holiday settings","tags":["holidays","time-management"],"x-required-scopes":["api:read"]},"put":{"description":"Updates the default holiday country/region code for the workspace.\n\n**What this does:**\nSets the default holiday source that will be automatically applied to all new employees. This ensures consistent holiday rules across your workspace while still allowing individual customization.\n\n**Important:**\n- This only affects new employees - existing employees keep their current holiday settings\n- The country code must be one of the available codes from `GET /holidays/countries`\n- Examples: \"US\" (United States), \"DE\" (Germany), \"US-CA\" (California), \"AT\" (Austria)\n\n**Use cases:**\n- Setting up a new workspace with a primary location\n- Changing the default for a workspace that has moved or expanded to a new region\n- Standardizing holiday rules across the organization","operationId":"HolidaysController_updateHolidaySettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHolidaySettingsDto"}}}},"responses":{"200":{"description":"Holiday settings updated successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update holiday settings","tags":["holidays","time-management"],"x-required-scopes":["api:write"]}},"/holidays/countries":{"get":{"description":"Retrieves the complete list of available holiday countries and states that can be used for holiday configurations.\n\n**What is returned:**\n- List of all supported holiday regions with:\n - `code`: Country/region code (e.g., \"US\", \"DE\", \"US-CA\", \"AT\")\n - `name`: Localized country/region name (e.g., \"United States\", \"Germany\", \"California\", \"Austria\")\n\n**How to use:**\n- Use these codes when setting default holiday settings or individual employee holiday rules\n- Country codes follow ISO 3166-1 alpha-2 format (e.g., \"US\", \"DE\")\n- State codes use format \"COUNTRY-STATE\" (e.g., \"US-CA\" for California, \"US-NY\" for New York)\n- Use the `language` query parameter to get country names in a specific language (default: \"en\")\n\n**Note:** This list includes all regions for which Leadtime has official holiday data. Holidays are automatically loaded from official sources for these regions.","operationId":"HolidaysController_getHolidayCountries","parameters":[{"name":"language","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Holiday countries retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HolidayCountryDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get available holiday countries","tags":["holidays","time-management"],"x-required-scopes":["api:read"]}},"/holidays/years":{"get":{"description":"Retrieves the complete holiday configuration for a specific year and country/region.\n\n**What is returned:**\nThe endpoint returns one of three types of holiday configurations:\n\n1. **Default** (`type: \"default\"`): Official holidays from the holiday data source\n - No `id` field (not a custom year)\n - Cannot be modified directly\n - Used when no custom configuration exists\n\n2. **Custom** (`type: \"custom\"`): Workspace-specific holiday configuration\n - Has an `id` field (UUID)\n - Can be modified (add, edit, delete holidays)\n - Created when you customize holidays for a year\n - May have a `validTill` year that controls propagation to future years\n\n3. **Derived** (`type: \"derived\"`): Configuration inherited from a previous custom year\n - Has an `id` field (UUID)\n - Shows `derivedFrom` year that it was copied from\n - Created automatically when a custom year's `validTill` extends to future years\n - Can be modified like custom years\n\n**Holiday types:**\nEach holiday in the list can be:\n- **Fixed**: A specific date (e.g., \"2024-12-25\" for Christmas)\n- **Rule**: A computed date based on a rule (e.g., \"25 december\" or \"easter monday\")\n\n**Response fields:**\n- `id`: Holiday year ID (only for custom/derived types)\n- `year`: The year this configuration applies to\n- `country`: Country/region code\n- `type`: Configuration type (\"default\", \"custom\", or \"derived\")\n- `derivedFrom`: Source year for derived configurations\n- `validTill`: Last year this configuration applies to (null = indefinite)\n- `holidays`: Array of all holidays with name, date, type, rule, and substitute flag\n\n**Use cases:**\n- Displaying holidays in a calendar view\n- Checking if a year has been customized\n- Getting the complete holiday list for capacity planning\n- Understanding the relationship between years (derived configurations)","operationId":"HolidaysController_getHolidayYear","parameters":[{"name":"year","required":true,"in":"query","description":"The year to retrieve holidays for. Must be 1900 or later. The endpoint will return the appropriate configuration type (default, custom, or derived) for this year.","schema":{"example":2024,"type":"number"}},{"name":"country","required":true,"in":"query","description":"Country or region code (e.g., \"US\", \"DE\", \"US-CA\"). Must be one of the available codes from `GET /holidays/countries`.","schema":{"example":"US","type":"string"}}],"responses":{"200":{"description":"Holiday year retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidayYearResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get holiday year","tags":["holidays","time-management"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a custom holiday year configuration for the workspace, allowing you to customize holidays for a specific year and country/region.\n\n**What this does:**\nCreates a workspace-specific holiday configuration by copying the default holidays for the specified year and country. Once created, you can add, modify, or delete holidays using the holiday days endpoints.\n\n**Important behavior:**\n- If a custom year already exists for the specified year/country, it will be **deleted and recreated**\n- This effectively resets the year to default holidays\n- All existing custom holidays for that year will be lost\n- Use this endpoint to start customizing a year or to reset it back to defaults\n\n**Validity period (`validTill`):**\nThe `validTill` field controls how the custom configuration propagates to future years:\n- If `validTill` is set (e.g., 2026), the configuration applies to all years from the specified year through `validTill`\n- If `validTill` is `null`, the configuration applies indefinitely to future years\n- Future years will automatically be created as \"derived\" configurations\n- You can update `validTill` later using `PUT /holidays/years/:yearId`\n\n**Use cases:**\n- Adding company-specific holidays (e.g., \"Company Outing\", \"Festivus\")\n- Removing holidays that don't apply to your organization\n- Modifying holiday dates for your specific needs\n- Resetting a customized year back to defaults\n\n**Next steps:**\nAfter creating a custom year, use:\n- `POST /holidays/days` to add new holidays\n- `PUT /holidays/days/:dayId` to modify existing holidays\n- `DELETE /holidays/days/:dayId` to remove holidays","operationId":"HolidaysController_createHolidayYear","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHolidayYearDto"}}}},"responses":{"201":{"description":"Custom holiday year created successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create custom holiday year","tags":["holidays","time-management"],"x-required-scopes":["api:write"]}},"/holidays/years/{yearId}":{"put":{"description":"Updates the validity period (`validTill`) of a custom holiday year configuration.\n\n**What this does:**\nChanges how long a custom holiday configuration applies to future years. This is useful when you want to extend or limit the scope of your customizations.\n\n**How `validTill` works:**\n- **Set to a specific year** (e.g., `2026`): The configuration applies from the year's start year through 2026\n - Future years within this range will be automatically created as \"derived\" configurations\n - Years beyond `validTill` will use default holidays\n\n- **Set to `null`**: The configuration applies indefinitely to all future years\n - All future years will automatically inherit this configuration as \"derived\" years\n - Useful for permanent company holidays that should always apply\n\n**Example scenarios:**\n1. **Temporary change**: You add a special holiday for 2024-2025 only\n - Create year 2024 with `validTill: 2025`\n - Both 2024 and 2025 will use the custom configuration\n - 2026 and beyond will use defaults\n\n2. **Permanent company holiday**: You add \"Company Foundation Day\" that should always be a holiday\n - Create year 2024 with `validTill: null`\n - All future years will automatically include this holiday\n\n3. **Extending validity**: You previously set `validTill: 2025` but want to extend to 2027\n - Update the year with `validTill: 2027`\n - Years 2026 and 2027 will now also use the custom configuration\n\n**Note:** This endpoint only works on custom holiday years (those with an `id`). Default years cannot be updated - you must create a custom year first using `POST /holidays/years`.","operationId":"HolidaysController_updateHolidayYear","parameters":[{"name":"yearId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHolidayYearDto"}}}},"responses":{"200":{"description":"Holiday year updated successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update holiday year","tags":["holidays","time-management"],"x-required-scopes":["api:write"]},"delete":{"description":"**Note:** This endpoint is not implemented. To reset a custom holiday year back to defaults, use `POST /holidays/years` instead.\n\n**How to reset a year:**\nTo delete a custom holiday year and return to default holidays:\n1. Call `POST /holidays/years` with the same `year` and `country` values\n2. This will delete the existing custom year and recreate it with default holidays\n3. All custom holidays for that year will be removed\n\n**Why this approach?**\nThe holiday service uses a \"recreate\" pattern where creating a custom year automatically deletes any existing custom year for the same year/country combination. This ensures a clean reset to defaults while maintaining data consistency.","operationId":"HolidaysController_deleteHolidayYear","parameters":[{"name":"yearId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Holiday year deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete custom holiday year","tags":["holidays","time-management"],"x-required-scopes":["api:write"]}},"/holidays/days":{"post":{"description":"Adds a new holiday day to a custom holiday year configuration.\n\n**What this does:**\nCreates a new holiday in a custom holiday year. This allows you to add company-specific holidays that don't exist in the default holiday data (e.g., \"Company Outing\", \"Festivus\", \"Team Building Day\").\n\n**Holiday types:**\nOnly **Fixed** holidays can be created via this endpoint:\n- **Fixed**: A specific date that doesn't change (e.g., \"2024-12-25\" for Christmas)\n- **Rule-based**: Holidays computed from rules (e.g., \"25 december\", \"easter monday\") come from default definitions\n - Rule-based holidays can only be edited, not created\n - They exist in default holiday configurations and can be modified in custom years\n\n**Requirements:**\n- The `yearId` must belong to a custom holiday year (created via `POST /holidays/years`)\n- You cannot add holidays to default years - create a custom year first\n- The `date` must be in ISO 8601 format (e.g., \"2024-12-25\")\n- The `name` should be descriptive (e.g., \"Company Foundation Day\")\n\n**Use cases:**\n- Adding company-specific holidays\n- Adding regional holidays not in the default data\n- Creating special event days that should be treated as holidays\n\n**Example:**\nTo add \"Company Outing\" on June 15, 2024:\n```json\n{\n \"yearId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"name\": \"Company Outing\",\n \"type\": \"Fixed\",\n \"date\": \"2024-06-15\"\n}\n```","operationId":"HolidaysController_createHolidayDay","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHolidayDayDto"}}}},"responses":{"201":{"description":"Holiday day created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidayDayResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add holiday day","tags":["holidays","time-management"],"x-required-scopes":["api:write"]}},"/holidays/days/{dayId}":{"put":{"description":"Updates an existing holiday day in a custom holiday year configuration.\n\n**What this does:**\nModifies a holiday's name, type, date, or rule. This allows you to customize holidays from the default set or modify holidays you've previously added.\n\n**Holiday types:**\nYou can update holidays to be either type:\n\n1. **Fixed** (`type: \"Fixed\"`):\n - A specific date that doesn't change\n - Requires a `date` field in ISO 8601 format (e.g., \"2024-12-25\")\n - Example: \"Christmas Day\" on December 25\n\n2. **Rule** (`type: \"Rule\"`):\n - A computed date based on a rule string\n - Requires a `rule` field (e.g., \"25 december\", \"easter monday\", \"first monday in september\")\n - The date is automatically computed from the rule for each year\n - If converting from Fixed to Rule, you must provide a `rule` (or it will use the existing rule if available)\n\n**Important constraints:**\n- You cannot convert a Fixed holiday to Rule without providing a `rule`\n- If the holiday already has a rule and you're converting to Rule type, the existing rule will be preserved if you don't provide one\n- The holiday must belong to a custom year (not a default year)\n- The `yearId` is automatically determined from the existing holiday\n\n**Use cases:**\n- Renaming a holiday (e.g., \"Christmas\" β \"Holiday Break\")\n- Changing a holiday date\n- Converting a fixed holiday to a rule-based one (e.g., \"First Monday in September\" for Labor Day)\n- Modifying rule-based holidays from the default set\n\n**Example - Converting Fixed to Rule:**\n```json\n{\n \"name\": \"Labor Day\",\n \"type\": \"Rule\",\n \"rule\": \"first monday in september\"\n}\n```","operationId":"HolidaysController_updateHolidayDay","parameters":[{"name":"dayId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHolidayDayDto"}}}},"responses":{"200":{"description":"Holiday day updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidayDayResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update holiday day","tags":["holidays","time-management"],"x-required-scopes":["api:write"]},"delete":{"description":"Deletes a holiday day from a custom holiday year configuration.\n\n**What this does:**\nRemoves a holiday from the custom year configuration. The holiday is soft-deleted, meaning it's marked as deleted but not permanently removed from the database.\n\n**Important:**\n- Only holidays in custom years can be deleted\n- You cannot delete holidays from default years - create a custom year first\n- This is useful for removing holidays that don't apply to your organization\n- The holiday will no longer appear in holiday lists or affect capacity calculations\n\n**Use cases:**\n- Removing regional holidays that don't apply to your organization\n- Removing religious holidays that aren't observed by your company\n- Cleaning up holidays you previously added but no longer need\n\n**Note:** If you want to restore a deleted holiday, you can either:\n- Recreate the custom year using `POST /holidays/years` (resets to defaults)\n- Add the holiday back using `POST /holidays/days`","operationId":"HolidaysController_deleteHolidayDay","parameters":[{"name":"dayId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Holiday day deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete holiday day","tags":["holidays","time-management"],"x-required-scopes":["api:write"]}},"/contacts/grid":{"get":{"description":"Returns a paginated, filterable, and sortable grid of all contacts in the workspace.\n\n**What are Contacts?**\nThe contacts grid provides a unified view of all people in your workspace:\n- **Employees**: Internal team members from your own company\n- **Organization Members**: External contacts from partner or customer organizations\n\nThis unified view allows you to search, filter, and manage all contacts in one place, regardless of whether they are internal employees or external contacts.\n\n**What is returned:**\n- Contact identification (ID, name, type)\n- Contact information (email, phone, position, title, degree)\n- Organization information (for organization members)\n- Complete address details\n- Employee-specific fields (employment mode, entry/exit dates, tax class)\n- Organization member-specific fields (influence level, attitude, personality type)\n- Status information (active, can login)\n- Personal details (birth date, gender, avatar)\n\n**Filtering and search:**\n- Quick search across name, email, phone, position, organization, and address fields\n- Advanced filtering by contact type, status, organization, and many other fields\n- Sorting by any sortable field\n- Server-side pagination for large contact lists\n\n**Note:** This endpoint requires the `Contacts.canSeeContacts` permission. The contacts grid is the foundation for the Address Book feature, which can be synced via CardDAV or exported as vCard.","operationId":"ContactsController_getContactsGrid","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: firstName, lastName, email, phone, position, organizationName, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Contact ID\n- **type** (set): Contact type (EMPLOYEE, ORGANIZATION_MEMBER)\n- **firstName** (string): First name\n- **lastName** (string): Last name\n- **email** (string): Email address\n- **phone** (string): Phone number\n- **position** (string): Job position\n- **title** (string): Title (e.g., Dr., Prof.)\n- **degree** (string): Academic degree\n- **organizationId** (string): Organization ID (for organization members)\n- **organizationName** (string): Organization name (for organization members)\n- **addressStreet** (string): Street address\n- **addressZip** (string): ZIP/Postal code\n- **addressCity** (string): City\n- **addressCountry** (string): Country\n- **addressHouseNumber** (string): House number\n- **avatarId** (string): Avatar file ID\n- **isActive** (boolean): Whether contact is active\n- **canLogin** (boolean): Whether contact can login to the system\n- **employmentMode** (string): Employment mode (for employees)\n- **entryDate** (date): Entry date (for employees)\n- **exitDate** (date): Exit date (for employees)\n- **incomeTaxClass** (string): Income tax class (for employees)\n- **influenceLevel** (string): Influence level (for organization members)\n- **attitudeLevel** (string): Attitude level (for organization members)\n- **personalityType** (string): Personality type (for organization members)\n- **socialNetworkLink** (string): Social network profile link (for organization members)\n- **birthDate** (date): Birth date\n- **gender** (string): Gender\n- **createdAt** (date): Creation timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Contact ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Contact type (EMPLOYEE, ORGANIZATION_MEMBER) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **firstName** (string): First name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **lastName** (string): Last name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **email** (string): Email address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **phone** (string): Phone number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **position** (string): Job position (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **title** (string): Title (e.g., Dr., Prof.) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **degree** (string): Academic degree (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (string): Organization ID (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationName** (string): Organization name (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressStreet** (string): Street address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressZip** (string): ZIP/Postal code (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCity** (string): City (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCountry** (string): Country (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressHouseNumber** (string): House number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **avatarId** (string): Avatar file ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **isActive** (boolean): Whether contact is active (boolean filter). Available comparisons: equal, not_equal\n- **canLogin** (boolean): Whether contact can login to the system (boolean filter). Available comparisons: equal, not_equal\n- **employmentMode** (string): Employment mode (for employees) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **entryDate** (date): Entry date (for employees) (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **exitDate** (date): Exit date (for employees) (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **incomeTaxClass** (string): Income tax class (for employees) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **influenceLevel** (string): Influence level (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **attitudeLevel** (string): Attitude level (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **personalityType** (string): Personality type (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **socialNetworkLink** (string): Social network profile link (for organization members) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **birthDate** (date): Birth date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **gender** (string): Gender (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Contact ID\n- **type**: Contact type (EMPLOYEE, ORGANIZATION_MEMBER)\n- **firstName**: First name\n- **lastName**: Last name\n- **name**: Full name (firstName + lastName, virtual field)\n- **position**: Job position\n- **organizationId**: Organization ID (for organization members)\n- **organizationName**: Organization name (for organization members)\n- **addressCity**: City\n- **addressCountry**: Country\n- **isActive**: Whether contact is active\n- **canLogin**: Whether contact can login to the system\n- **employmentMode**: Employment mode (for employees)\n- **entryDate**: Entry date (for employees)\n- **exitDate**: Exit date (for employees)\n- **influenceLevel**: Influence level (for organization members)\n- **attitudeLevel**: Attitude level (for organization members)\n- **personalityType**: Personality type (for organization members)\n- **birthDate**: Birth date\n- **createdAt**: Creation timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** name (asc)","schema":{"example":"[{\"field\":\"name\",\"direction\":\"asc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, type, firstName, lastName, name, email, phone, position, title, degree, organizationId, organizationName, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber, avatarId, isActive, canLogin, employmentMode, entryDate, exitDate, incomeTaxClass, influenceLevel, attitudeLevel, personalityType, socialNetworkLink, birthDate, gender, createdAt","schema":{"example":"id,type","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved contacts grid"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get contacts grid","tags":["contacts"],"x-required-scopes":["api:read"]}},"/administration/custom-icons":{"get":{"description":"Retrieves all custom icons configured for the workspace.\n\n**What are Custom Icons?**\nCustom icons are user-uploaded symbols (images) that can be used throughout the workspace to visually organize and tag content. They help make information easier to grasp quickly.\n\n**Where can custom icons be used:**\n- Projects\n- Tickets/Tasks\n- Documents\n- Organization profiles\n- Employee profiles\n\n**What is returned:**\n- Icon ID and name (e.g., `:company_logo:` or `:team_sales:`)\n- Image file ID and public URL\n- Author information (who created the icon)\n- Creation and last update timestamps\n\n**Note:** This endpoint requires the `CustomIcons.create` permission. All custom icons are available to all users in the workspace.","operationId":"CustomIconsController_getCustomIcons","parameters":[],"responses":{"200":{"description":"Custom icons retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CustomIconResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List custom icons","tags":["administration","custom-icons"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new custom icon for the workspace.\n\n**What are Custom Icons?**\nCustom icons are user-uploaded symbols (images) that can be used throughout the workspace to visually organize and tag content. They help make information easier to grasp quickly.\n\n**How to create a custom icon:**\n1. Upload an image file (PNG or SVG format) using POST /api/public/workspace/upload\n2. Get the file ID from the upload response\n3. Provide a unique icon name (e.g., `:company_logo:`, `:team_sales:`, `:lt_editor:`)\n4. Use the file ID in the `imageId` field\n\n**Icon name requirements:**\n- Must be alphanumeric characters and underscores only\n- Cannot conflict with default emoji names\n- Format: typically wrapped in colons (e.g., `:icon_name:`)\n\n**Note:** This endpoint requires the `CustomIcons.create` permission. Once created, the icon is available to all users in the workspace and can be used in projects, tickets, documents, and profiles.","operationId":"CustomIconsController_createCustomIcon","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomIconDto"}}}},"responses":{"201":{"description":"Custom icon created successfully","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create custom icon","tags":["administration","custom-icons"],"x-required-scopes":["api:write"]}},"/administration/custom-icons/{id}":{"put":{"description":"Updates an existing custom icon by replacing its image.\n\n**What can be updated:**\n- **Image only**: The icon image can be replaced with a new one\n- **Name is readonly**: The icon name cannot be changed after creation\n\n**How to update a custom icon:**\n1. Upload a new image file (PNG or SVG format) using POST /api/public/workspace/upload\n2. Get the file ID from the upload response\n3. Use the file ID in the `imageId` field\n\n**Note:** This endpoint requires the `CustomIcons.create` permission. The icon name remains unchanged - only the image is updated. The updated icon will be reflected throughout the workspace wherever it's used.","operationId":"CustomIconsController_updateCustomIcon","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomIconDto"}}}},"responses":{"200":{"description":"Custom icon updated successfully","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update custom icon","tags":["administration","custom-icons"],"x-required-scopes":["api:write"]},"delete":{"description":"Permanently deletes a custom icon from the workspace.\n\n**What happens:**\n- The custom icon is permanently removed from the workspace\n- The icon will no longer be available for use in projects, tickets, documents, or profiles\n- Any existing uses of the icon may display as missing/broken\n- This action cannot be undone\n\n**Note:** This endpoint requires the `CustomIcons.create` permission. Use with caution as deleting an icon may affect content that references it.","operationId":"CustomIconsController_deleteCustomIcon","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Custom icon deleted successfully","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete custom icon","tags":["administration","custom-icons"],"x-required-scopes":["api:write"]}},"/timebookings/timeGrid":{"get":{"description":"Retrieves a paginated, filterable grid of all time booking entries in the workspace.\n\n**What are Time Bookings?**\nTime bookings (also called time logs or time entries) are records of working hours that employees have logged to specific tasks or projects. They document how much time was spent on different activities, which is essential for:\n- Project planning and resource allocation\n- Billing customers accurately\n- Analyzing productivity and team workload\n- Understanding where time is being spent in the organization\n\n**What data is returned:**\nThe grid returns time booking entries with the following information:\n- **Date**: When the time was logged\n- **Hours**: Amount of time logged (decimal format, e.g., 8.5 for 8 hours 30 minutes)\n- **Comment**: Optional notes about the work performed\n- **Project ID**: The project the time was logged to\n- **Task ID**: The specific task (if time was logged to a task rather than just a project)\n- **User ID**: Which employee logged the time\n- **Activity ID**: The type of work performed (e.g., development, research, management)\n- **Value Group**: The project value group for categorization\n\n**Response includes:**\n- Paginated list of time booking items\n- Total count of matching entries\n- **totalHours**: Sum of all hours across filtered entries (useful for reporting)\n- Current page and page size\n\n**Filtering and sorting:**\nYou can filter by date range, project, task, user, activity, or value group. Quick search is available on comments. Results are sorted by date (newest first) by default.\n\n**Permissions:**\nRequires either \"seeLoggedTimeDetails\" (to see your own time) or \"seeCompanyLoggedTime\" (to see all company time).","operationId":"TimebookingsController_getTimeGrid","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: comment","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **date** (date): Date of the time log entry\n- **hours** (number): Hours logged\n- **comment** (string): Comment for the time log entry\n- **projectId** (set): Project ID\n- **taskId** (set): Task ID\n- **userId** (set): User ID who logged the time\n- **activityId** (set): Activity ID\n- **valueGroup** (set): Project value group\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **date** (date): Date of the time log entry (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **hours** (number): Hours logged (number filter). Available comparisons: equal, not_equal, >, <, >=, <=, is_empty, is_not_empty\n- **comment** (string): Comment for the time log entry (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **projectId** (set): Project ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **taskId** (set): Task ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **userId** (set): User ID who logged the time (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **activityId** (set): Activity ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **valueGroup** (set): Project value group (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **date**: Date of the time log entry\n- **hours**: Hours logged\n- **projectId**: Project ID\n- **taskId**: Task ID\n- **userId**: User ID who logged the time\n- **activityId**: Activity ID\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** date (desc)","schema":{"example":"[{\"field\":\"date\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** date, hours, comment, projectId, taskId, userId, activityId, valueGroup","schema":{"example":"date,hours","type":"array","items":{}}},{"name":"group","required":false,"in":"query","description":"Group time bookings by date. When set, response includes groupMeta with fragment/full totals per group. Use \"none\" for ungrouped list. Default: none.","schema":{"enum":["day","week","month","none"],"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved time bookings grid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimebookingsGridResponseDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get time bookings grid","tags":["timebookings","time-tracking"],"x-required-scopes":["api:read"]}},"/timebookings":{"post":{"description":"Creates a new time booking entry to record working hours spent on a task or project.\n\n**What is a Time Booking?**\nA time booking is a record of working hours that you have spent on a specific task or project. Time bookings are used for retroactive time tracking - documenting work that has already been completed.\n\n**Two types of time bookings:**\n1. **Task-based**: Time logged to a specific task within a project. Use this when you want to track time for a particular work item (e.g., \"Fix bug in login form\"). The time automatically counts toward the parent project.\n2. **Project-based**: Time logged directly to a project without a specific task. Use this for general project activities that are not tied to a particular task (e.g., \"Marketing research for Q1 campaign\").\n\n**Required information:**\n- **Type**: Either \"task\" or \"project\"\n- **Task ID** (if type is \"task\"): The UUID of the task you worked on\n- **Project ID** (if type is \"project\"): The UUID of the project\n- **Activity ID**: The type of work performed (e.g., development, design, management). Activities are defined in your workspace settings.\n- **Hours**: The amount of time spent (decimal format, e.g., 2.5 for 2 hours 30 minutes)\n- **Date**: The date when the work was performed (ISO date format: YYYY-MM-DD)\n\n**Optional information:**\n- **Minutes**: Additional minutes (0-59) to add to the hours. If you provide both hours and minutes, they are combined (e.g., hours: 2, minutes: 30 = 2.5 hours total).\n- **Comment**: Notes about what was accomplished during this time\n\n**How it works:**\n- Time bookings are always created for the authenticated user (you cannot log time for other users)\n- When logging time to a task, the system automatically links it to the task's parent project\n- The time entry is immediately available in time tracking reports and project analytics\n- Hours and minutes are combined: if you provide hours: 2 and minutes: 30, the total is 2.5 hours\n\n**Example use cases:**\n- Documenting time spent on a completed feature\n- Recording billable hours for client projects\n- Tracking time for internal projects and activities\n- Completing time logs at the end of the day or week\n\n**Note:** For real-time time tracking while working, use the Time Tracker feature instead of manual time bookings.","operationId":"TimebookingsController_createTimeBooking","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTimeBookingDto"}}}},"responses":{"201":{"description":"Time booking created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Missing permission to log time"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new time booking","tags":["timebookings","time-tracking"],"x-required-scopes":["api:write"]}},"/timebookings/{id}":{"patch":{"description":"Updates an existing time booking entry. You can modify any field of the time booking.\n\n**Who can update time bookings:**\n- You can always update your own time bookings\n- If you have the \"editAnyTimeLog\" permission, you can update any time booking in the workspace\n- Otherwise, you cannot update time bookings created by other users\n\n**What can be updated:**\nAll fields are optional in the update request. Only provide the fields you want to change:\n- **Type**: Change between task-based and project-based booking\n- **Task ID**: Switch to a different task (if type is \"task\")\n- **Project ID**: Switch to a different project (if type is \"project\")\n- **Activity ID**: Change the activity type\n- **Hours**: Adjust the logged hours\n- **Minutes**: Adjust additional minutes (0-59)\n- **Comment**: Update the comment text\n- **Date**: Change the date when the work was performed\n\n**How it works:**\n- Fields not provided in the update request will keep their existing values\n- If you change the type from \"task\" to \"project\" (or vice versa), make sure to provide the appropriate ID field\n- Hours and minutes are combined: if you provide both, they are added together\n- The system validates that the time booking exists and belongs to your workspace\n\n**Common use cases:**\n- Correcting a typo in hours or comment\n- Moving time from one task to another\n- Changing the activity type for better categorization\n- Updating the date if it was logged incorrectly","operationId":"TimebookingsController_updateTimeBooking","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchTimeBookingDto"}}}},"responses":{"200":{"description":"Time booking updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Missing permission to edit this time booking"},"404":{"description":"Time booking not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update an existing time booking","tags":["timebookings","time-tracking"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a time booking entry. The entry is marked as deleted but not permanently removed from the database.\n\n**Who can delete time bookings:**\n- You can always delete your own time bookings\n- If you have the \"deleteAnyTimeLog\" permission, you can delete any time booking in the workspace\n- Otherwise, you cannot delete time bookings created by other users\n\n**How it works:**\n- The time booking is soft deleted (marked as deleted, not permanently removed)\n- Deleted entries are no longer visible in time tracking grids and reports\n- The system validates that the time booking exists and belongs to your workspace\n- If the time booking was linked to a task, the task's total time will be recalculated\n\n**Use cases:**\n- Removing accidentally created duplicate entries\n- Deleting time logged to the wrong task or project\n- Cleaning up test or incorrect time entries","operationId":"TimebookingsController_deleteTimeBooking","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Time booking deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Missing permission to delete this time booking"},"404":{"description":"Time booking not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete a time booking","tags":["timebookings","time-tracking"],"x-required-scopes":["api:write"]}},"/time/timetable":{"get":{"description":"Retrieves comprehensive time table data for employees over a specified date range. The time table provides a calendar view showing attendance, time bookings, vacations, sickness, holidays, and work hours for team members.\n\n**What is the Time Table?**\nThe time table is a unified calendar view that combines multiple time-related data sources:\n- Attendance tracking (clock in/out times, total hours, mood)\n- Time bookings (hours logged on projects and tasks)\n- Vacation requests (pending and approved)\n- Sickness records\n- Public holidays (based on employee holiday codes)\n- Work day configuration (working days, work day length)\n- Chargeable time goals and actuals\n\n**Required Permission:**\nUser must be an Employee type. Additionally, one of the following time table viewing permissions is required:\n- TimeTablePermissions.viewAll: View all employees\n- TimeTablePermissions.viewOwn: View own data only\n- TimeTablePermissions.viewTeams: View own team members\n\n**User Filtering Options:**\nThe usersFilter parameter controls which employees are included in the response:\n- \"all\": Returns all employees in the workspace. Requires TimeTablePermissions.viewAll permission.\n- \"me\": Returns only the authenticated user. Requires TimeTablePermissions.viewOwn or TimeTablePermissions.viewTeams permission.\n- \"team:{teamId}\": Returns all members of the specified team. Requires TimeTablePermissions.viewTeams permission, and the user must be a member of that team.\n\n**Data Visibility Rules:**\nThe response includes different data fields based on permissions and workspace settings:\n- spentHours and chargeableTime: Only included if user has Tasks.seeLoggedTime permission\n- Attendance data (timeFrom, timeTo, totalHours, mood): Only included if workspace has attendanceEnabled flag set\n- If attendance is disabled, totalHours shows time booking data instead\n- Returns empty object {} if user has no time table viewing permissions\n\n**Date Handling:**\n- Dates must be in ISO 8601 format (YYYY-MM-DD)\n- Dates are normalized to UTC at midnight\n- If dateStart > dateEnd, they are automatically swapped\n- Response includes all days in the range, including weekends\n\n**Response Structure:**\nReturns an object keyed by userId. Each key contains:\n- employeeId: Employee UUID\n- userId: User UUID\n- name: Employee full name\n- days: Array of day objects, one for each date in the range\n\n**Day Object Fields:**\nEach day object contains:\n- type: 0 for Attendance mode, 1 for TimeBooking mode\n- date: ISO date string\n- isWeekend: Whether the day is a weekend based on employee work schedule\n- workDayLength: Expected work hours for the day\n- mood: Attendance mood (if attendance enabled)\n- timeFrom/timeTo: Clock in/out times (if attendance enabled)\n- totalHours: Total hours worked (attendance) or logged (time booking)\n- spentHours: Hours logged on tasks (requires Tasks.seeLoggedTime permission)\n- chargeableTime: Hours logged on billable projects (requires Tasks.seeLoggedTime permission)\n- chargeableGoal: Daily chargeable hours goal for the employee\n- holiday: Name of public holiday if applicable\n- vacation: Vacation request data if day falls within a vacation period\n- sickness: Sickness record data if day falls within a sickness period\n- contractStarted: Whether employee contract has started by this date\n- comment: Optional comment for the day\n- highlight: Whether the day should be highlighted in UI","operationId":"TimetableController_getTimeTable","parameters":[{"name":"dateStart","required":true,"in":"query","description":"Start date of the time table range in ISO 8601 format (YYYY-MM-DD). The date is normalized to UTC at midnight. If dateStart is greater than dateEnd, they will be automatically swapped.","schema":{"example":"2025-10-06","type":"string"}},{"name":"dateEnd","required":true,"in":"query","description":"End date of the time table range in ISO 8601 format (YYYY-MM-DD). The date is normalized to UTC at midnight. All days from dateStart to dateEnd (inclusive) are included in the response.","schema":{"example":"2025-10-26","type":"string"}},{"name":"usersFilter","required":true,"in":"query","description":"Filter to control which employees are included in the response. Options: \"all\" (requires TimeTablePermissions.viewAll), \"me\" (requires TimeTablePermissions.viewOwn or viewTeams), or \"team:{teamId}\" (requires TimeTablePermissions.viewTeams and user must be in the team). The team ID format must be exactly \"team:\" followed by the team UUID with no spaces.","schema":{"example":"me","type":"string"}}],"responses":{"200":{"description":"Time table data successfully retrieved. Returns an object keyed by userId.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TimeTableUserRowDto"}}}}},"400":{"description":"Invalid date format or filter value"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get time table data for date range","tags":["time","timetable"],"x-required-scopes":["api:read"]}},"/account/time-tracker":{"get":{"description":"Returns all time trackers for the current user. The Time Tracker is a real-time time tracking feature that allows users to measure work time while actively working on tasks or projects.\n\nEach tracker can be associated with a specific task or project, includes activity categorization, optional comments, and tracks time through intervals (start/end periods).\n\nResponse includes calculated fields:\n- isRunning: Whether the tracker currently has an active interval\n- hours: Total tracked time in hours (sum of all intervals plus correction)\n- autoEnded: Whether any interval was automatically ended at end of day\n- isOld: Whether the tracker contains intervals from previous days\n- hoursPadded/minutesPadded: Formatted time strings for display\n\nAlso returns lastInteraction timestamp indicating when the user last interacted with any tracker.","operationId":"TimeTrackerController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackerListResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all time trackers","tags":["account","time-tracker"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new time tracker and starts real-time tracking. When a new tracker is created, it automatically stops all other running trackers for the user (only one tracker can run at a time).\n\nThe tracker immediately starts with an active interval beginning at the current time. You can specify:\n- timeTrackingType: Whether to track on Task or Project level\n- projectId: Optional project to associate with\n- taskId: Optional task to associate with (requires timeTrackingType: Task)\n- activityId: Optional activity category\n- comment: Optional description of the work\n- correction: Optional time adjustment in minutes (can be positive or negative)\n\nReturns the created tracker with calculated fields including isRunning: true.","operationId":"TimeTrackerController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerCreateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerResponseDto"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create new time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:write"]}},"/account/time-tracker/{id}":{"get":{"description":"Returns a specific time tracker by ID with all calculated fields. The tracker must belong to the authenticated user.\n\nCalculated fields include running status, total hours (from intervals and correction), formatted time strings, and flags for auto-ended intervals or old trackers.","operationId":"TimeTrackerController_getOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Tracker not found or does not belong to user"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get single time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates metadata of an existing time tracker. You can modify any of the following fields:\n- timeTrackingType: Change between Task and Project tracking\n- projectId: Change or remove project association\n- taskId: Change or remove task association\n- activityId: Change or remove activity category\n- comment: Update or remove the comment\n- correction: Adjust tracked time in minutes (positive to add time, negative to subtract)\n\nAll fields are optional - only provided fields will be updated. The tracker must belong to the authenticated user.\n\nNote: This does not affect the tracker intervals or running status. Use pause/resume endpoints to control time tracking.","operationId":"TimeTrackerController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerUpdateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerResponseDto"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Tracker not found or does not belong to user"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update existing time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:write"]},"delete":{"description":"Permanently deletes a time tracker and all its associated intervals. This action cannot be undone.\n\nOnly the tracker owner can delete their own trackers. If the tracker is currently running, it will be stopped before deletion.","operationId":"TimeTrackerController__delete","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Tracker not found or does not belong to user"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:write"]}},"/account/time-tracker/{id}/pause":{"post":{"description":"Pauses a running time tracker by ending its current active interval. The interval end time is set to the current time.\n\nAfter pausing, the tracker stops accumulating time but can be resumed later using the resume endpoint. This is useful for breaks or when switching to other work.\n\nIf the tracker is not currently running, this endpoint has no effect.","operationId":"TimeTrackerController_pause","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Tracker not found or does not belong to user"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Pause running time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:write"]}},"/account/time-tracker/{id}/resume":{"post":{"description":"Resumes a paused time tracker by creating a new active interval starting at the current time.\n\nWhen resuming a tracker, all other running trackers for the user are automatically paused (only one tracker can run at a time). This ensures accurate time tracking without overlaps.\n\nThe tracker will continue accumulating time until paused or stopped again.","operationId":"TimeTrackerController_resume","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTrackerResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Tracker not found or does not belong to user"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Resume paused time tracker","tags":["account","time-tracker"],"x-required-scopes":["api:write"]}},"/administration/company-settings":{"get":{"description":"Retrieves the company master data including legal entity information, contact details, and address.\n\n**What is Company Data?**\nCompany data contains all the legal, administrative, and contact details of your company. This information is used automatically throughout the system in invoices, contracts, projects, and other documents.\n\n**What is returned:**\n- **Company identification**: Official company name and legal form (e.g., GmbH, AG, LLC)\n- **Complete address**: Country, postal code, city, street, house number\n- **Contact information**: Phone number, email address, website URL, fax number\n- **Tax and registry details**: Tax identification number, business registration number, registration court\n- **Company description**: Short description of what the company does\n- **Financial information**: Bank account number (IBAN) used for invoices\n\n**Note:** This endpoint requires the `Company.view` permission. Company data serves as the foundation for correct legal information, consistent communication, and automated document generation throughout Leadtime.","operationId":"CompanySettingsController_getCompanySettings","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCompanySettingsDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get company settings","tags":["administration","company-settings"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates company master data. All fields are optional - only provided fields will be updated.\n\n**What is Company Data?**\nCompany data contains all the legal, administrative, and contact details of your company. This information is used automatically throughout the system in invoices, contracts, projects, and other documents.\n\n**What can be updated:**\n- **Company identification**: Official company name and legal form (e.g., GmbH, AG, LLC, sole proprietorship)\n- **Complete address**: Country, postal code, city, street, house number\n- **Contact information**: Phone number, email address, website URL, fax number\n- **Tax and registry details**: Tax identification number (needed for invoices), business registration number, registration court\n- **Company description**: Short description of what the company does (e.g., \"Manufacturer of Leadtime β an ERP system for software providers\")\n- **Financial information**: Bank account number (IBAN format) used for invoices\n\n**Validation rules:**\n- Email addresses must be valid email format\n- Website URLs must be valid URL format\n- All string fields can be empty strings to clear values\n\n**Note:** This endpoint requires the `Company.manage` permission. Changes take effect immediately and are used throughout the system for document generation and communication.","operationId":"CompanySettingsController_patchCompanySettings","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCompanySettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update company settings","tags":["administration","company-settings"],"x-required-scopes":["api:write"]}},"/organizations/members/journal":{"get":{"description":"Retrieves a paginated grid of organization member journal entries with filtering and sorting capabilities. Filterable fields: id, memberId, createdAt, createdBy, mood, reminder. Sortable fields: id, memberId, createdAt, createdBy, mood, reminder.\n\n**What are Organization Member Journals?**\nOrganization member journals are used to document notes, observations, conversations, and feedback about external organization members (contacts). They help track interactions, agreements, and important information about business partners, customers, suppliers, or other external contacts.\n\n**What is returned:**\n- Journal entry ID and associated member ID\n- Rich text content (body) converted to HTML format\n- Mood indicator (Happy, Neutral, or Sad)\n- Optional reminder date for follow-ups\n- Creation and update timestamps\n- Creator user ID\n\n**Permission-based filtering:**\n- Users with `Organizations.seeJournal` permission: See all journal entries for all members\n- Users without `Organizations.seeJournal` permission: Only see entries for their own member record where `visibleToSubject = true`\n- Organization members can create their own entries, which are automatically marked as visible to themselves\n\n**Filtering options:**\n- Filter by `memberId` to view entries for a specific organization member\n- Filter by `mood` to find entries with specific emotional indicators\n- Filter by `createdAt` or `lastUpdated` to find entries within date ranges\n- Filter by `reminder` to find entries with upcoming or past reminders\n\n**Use cases:**\n- Track conversations and agreements with external contacts\n- Document feedback and observations about business partners\n- Set reminders for follow-up actions\n- Maintain a chronological record of interactions with organization members","operationId":"OrganizationMembersJournalController_listMemberJournals","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Journal entry ID\n- **memberId** (string): Organization member ID\n- **createdAt** (date): Journal entry creation timestamp\n- **createdBy** (string): Creator user ID\n- **mood** (set): Journal entry mood\n- **reminder** (date): Reminder date\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Journal entry ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **memberId** (string): Organization member ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Journal entry creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **createdBy** (string): Creator user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **mood** (set): Journal entry mood (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **reminder** (date): Reminder date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Journal entry ID\n- **memberId**: Organization member ID\n- **createdAt**: Journal entry creation timestamp\n- **createdBy**: Creator user ID\n- **mood**: Journal entry mood\n- **reminder**: Reminder date\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, memberId, createdAt, createdBy, mood, reminder, body","schema":{"example":"id,memberId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of organization member journal entries"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List organization member journal entries","tags":["organizations","organization-members","journal","organizations","organization-members"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new journal entry for an organization member (external contact).\n\n**What you need to provide:**\n- `memberId` (required): UUID of the organization member this entry is about\n- `body` (required): Rich text content in HTML or Markdown format. Supports:\n - Headings, paragraphs, lists, and formatting\n - Links and embedded content\n - The content is automatically converted to the internal document format\n- `mood` (optional): Emotional indicator - Happy, Neutral, or Sad (defaults to Neutral)\n- `reminder` (optional): ISO 8601 date string for follow-up reminders (e.g., \"2024-12-31\")\n\n**Access control:**\n- Users with `Organizations.writeJournal` permission can create entries for any member\n- Organization members can create entries for their own member record\n- The `memberId` must exist and be accessible to the current user\n- Returns 400 if the member does not exist or is not accessible\n\n**Visibility behavior:**\n- If the user is creating an entry for their own member record, `visibleToSubject` is automatically set to `true`\n- If the user has `Organizations.writeJournal` permission and creates an entry for another member, `visibleToSubject` is set to `false` (internal only)\n\n**What is returned:**\nThe complete journal entry with all fields, including the body converted to HTML format and timestamps.","operationId":"OrganizationMembersJournalController_createMemberJournal","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationMemberJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberJournalResponseDto"}}}},"400":{"description":"Validation errors or member not accessible","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"memberId":["Member ID is required","Invalid memberId or member not accessible"],"body":["Body content is required"],"mood":["Mood must be one of: Happy, Neutral, Sad"],"reminder":["Reminder must be a valid ISO 8601 date string"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create organization member journal entry","tags":["organizations","organization-members","journal","organizations","organization-members"],"x-required-scopes":["api:write"]}},"/organizations/members/journal/{id}":{"get":{"description":"Returns complete details for a specific organization member journal entry.\n\n**What is returned:**\n- Journal entry ID and associated member ID\n- Rich text content (body) converted to HTML format from the internal document format\n- Mood indicator (Happy, Neutral, or Sad)\n- Optional reminder date in ISO 8601 format (null if not set)\n- Creation timestamp (when the entry was created)\n- Last update timestamp (when the entry was last modified)\n- Creator user ID (who created the entry)\n\n**Access control:**\n- Creator of the entry can access\n- Users with `Organizations.writeJournal` permission can access any journal entry\n- Returns 404 if the entry does not exist, has been deleted, or the user does not have access\n\n**Note:** The body content is automatically converted from the internal document format (IDoc) to HTML for easy display in web applications.","operationId":"OrganizationMembersJournalController_getMemberJournalDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization member journal entry details","tags":["organizations","organization-members","journal","organizations","organization-members"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates specific fields of an existing organization member journal entry. Only provided fields are updated; all fields are optional.\n\n**What you can update:**\n- `memberId` (optional): Change which member this entry is associated with\n- `body` (optional): Update the rich text content (HTML or Markdown format)\n- `mood` (optional): Change the emotional indicator (Happy, Neutral, or Sad)\n- `reminder` (optional): Update or clear the reminder date\n - Provide an ISO 8601 date string (e.g., \"2024-12-31\") to set/update\n - Provide `null` to clear an existing reminder\n - Omit the field to keep the existing reminder unchanged\n\n**Access control:**\n- Users with `Organizations.writeJournal` permission can update any journal entry\n- Organization members can update their own entries where `visibleToSubject = true`\n- If updating `memberId`, the new member must exist and be accessible\n- Returns 404 if the entry does not exist, has been deleted, or the user does not have access\n- Returns 400 if the new `memberId` is invalid or not accessible\n\n**Visibility behavior:**\n- If changing `memberId` to the user's own member record, `visibleToSubject` is automatically set to `true`\n- Otherwise, the existing `visibleToSubject` value is preserved\n\n**What is returned:**\nThe complete updated journal entry with all fields, including the body converted to HTML format and updated timestamps.","operationId":"OrganizationMembersJournalController_patchMemberJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchOrganizationMemberJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberJournalResponseDto"}}}},"400":{"description":"Validation errors or member not accessible"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update organization member journal entry","tags":["organizations","organization-members","journal","organizations","organization-members"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes an organization member journal entry. The entry is marked as deleted but not permanently removed from the database.\n\n**What happens:**\n- The journal entry is marked with a `deletedAt` timestamp\n- The entry will no longer appear in list queries or be accessible via the API\n- The data is preserved in the database for audit purposes\n- The entry cannot be restored through the API (restoration would require database access)\n\n**Access control:**\n- Users with `Organizations.writeJournal` permission can delete any journal entry\n- Organization members can delete their own entries where `visibleToSubject = true`\n- Returns 404 if the entry does not exist, has already been deleted, or the user does not have access\n\n**Note:** This is a soft delete operation. The entry is not permanently removed and can potentially be recovered by database administrators if needed.","operationId":"OrganizationMembersJournalController_deleteMemberJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete organization member journal entry","tags":["organizations","organization-members","journal","organizations","organization-members"],"x-required-scopes":["api:write"]}},"/organizations/members":{"get":{"description":"**Organization Members** are external contacts associated with organizations (customers, partners, suppliers, etc.). They represent people you work with outside your company.\n\nThis endpoint returns a paginated, filterable, and sortable list of all organization members in your workspace.\n\n**What you can do:**\n- Filter members by organization, status, position, or role\n- Search by name or email\n- Sort by any column\n- Select specific fields to return\n\n**Returns:** A grid response with organization member data including name, position, email, active status, login capability, and avatar information.\n\nRetrieves a paginated grid of organization members with filtering and sorting capabilities. Quick search available on: firstName, lastName, email. Filterable fields: id, organizationId, firstName, lastName, email, position, isActive, canLogin, gender, phone, addressCity, addressCountry, roleId, userId, avatarId, createdAt, editedAt. Sortable fields: id, organizationId, firstName, lastName, email, position, isActive, canLogin, gender, addressCity, addressCountry, roleId, userId, createdAt, editedAt.","operationId":"OrganizationMembersController_listOrganizationMembers","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: firstName, lastName, email","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Organization member ID\n- **organizationId** (string): Organization ID\n- **firstName** (string): First name\n- **lastName** (string): Last name\n- **email** (string): Email address\n- **position** (string): Position/title in organization\n- **isActive** (boolean): Whether member is active\n- **canLogin** (boolean): Whether member can login (derived from user status)\n- **gender** (set): Gender\n- **phone** (string): Phone number\n- **addressCity** (string): City\n- **addressCountry** (string): Country\n- **roleId** (string): User role ID\n- **userId** (string): Associated user ID\n- **avatarId** (string): Avatar file ID\n- **createdAt** (date): Creation timestamp\n- **editedAt** (date): Last update timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Organization member ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (string): Organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **firstName** (string): First name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **lastName** (string): Last name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **email** (string): Email address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **position** (string): Position/title in organization (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **isActive** (boolean): Whether member is active (boolean filter). Available comparisons: equal, not_equal\n- **canLogin** (boolean): Whether member can login (derived from user status) (boolean filter). Available comparisons: equal, not_equal\n- **gender** (set): Gender (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **phone** (string): Phone number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCity** (string): City (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCountry** (string): Country (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **roleId** (string): User role ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **userId** (string): Associated user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **avatarId** (string): Avatar file ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **editedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Organization member ID\n- **organizationId**: Organization ID\n- **firstName**: First name\n- **lastName**: Last name\n- **email**: Email address\n- **position**: Position/title in organization\n- **isActive**: Whether member is active\n- **canLogin**: Whether member can login (derived from user status)\n- **gender**: Gender\n- **addressCity**: City\n- **addressCountry**: Country\n- **roleId**: User role ID\n- **userId**: Associated user ID\n- **createdAt**: Creation timestamp\n- **editedAt**: Last update timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** lastName (asc)","schema":{"example":"[{\"field\":\"lastName\",\"direction\":\"asc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, organizationId, firstName, lastName, email, position, isActive, canLogin, gender, phone, addressCity, addressCountry, roleId, userId, avatarId, createdAt, editedAt","schema":{"example":"id,organizationId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of organization members"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List organization members","tags":["organizations","organization-members"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new organization member (external contact) for an organization. This automatically creates a user account that can be used for guest access to Leadtime.\n\n**What happens:**\n1. A new organization member record is created\n2. A user account is automatically created and linked to the member\n3. If `canLogin` is `true`:\n - User status is set to Active\n - An invitation email is sent with a magic link\n - The user can log in as a guest user\n4. If `canLogin` is `false` or omitted:\n - User status is set to Inactive\n - No invitation is sent\n - The member exists as a contact only\n\n**Required fields:**\n- `organizationId` - The organization this member belongs to\n- `firstName` - Member's first name\n- `lastName` - Member's last name\n- `email` - Email address (used for user account)\n- `roleId` - User role ID (e.g., `workspace-id_guest_` for guest access)\n\n**Avatar upload process:**\n1. First, call `POST /workspace/upload` to upload the image file\n2. Receive a file ID in the response\n3. Use that file ID in the `avatarId` field when creating the member\n\n**Personality classifications:**\n- **Influence level:** Low, Medium, High, Dominant\n- **Attitude level:** Enthusiastic, WellMeaning, Neutral, Opposing\n- **Personality type:** Dominant, Conscientious, Steady, Initiative\n\n**Returns:** The created organization member with all details including the generated user ID.","operationId":"OrganizationMembersController_createOrganizationMember","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationMemberDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"firstName":["First name is required"],"lastName":["Last name is required"],"email":["Email is required","Email must be valid"],"roleId":["Role ID is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create organization member","tags":["organizations","organization-members"],"x-required-scopes":["api:write"]}},"/organizations/members/{id}":{"get":{"description":"Returns complete details for a specific organization member.\n\n**What's included:**\n- **Basic information:** Name, position, academic degree, date of birth, gender, active status\n- **Access to Leadtime:** Whether the member can log in, their role ID, and associated user ID\n- **Contact details:** Full address (street, city, ZIP, country, house number), phone, email, social network links\n- **Personality traits:** Influence level, attitude level, and personality type classifications\n- **Avatar:** Profile picture URL if available\n- **Timestamps:** Creation and last update dates\n\n**Use cases:**\n- View complete member profile\n- Check access permissions and login status\n- Retrieve contact information for communication\n- Review personality classifications for relationship management","operationId":"OrganizationMembersController_getOrganizationMemberDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization member details","tags":["organizations","organization-members"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates an existing organization member. Only the fields you provide will be updated; all other fields remain unchanged.\n\n**Automatic user synchronization:**\nChanges to certain fields automatically sync to the associated user account:\n- `firstName` β Updates user's first name\n- `lastName` β Updates user's last name\n- `email` β Updates user's email address\n- `roleId` β Updates user's role\n- `canLogin` β Controls user access and status\n\n**Login access changes:**\n- **Enabling login** (`canLogin: false β true`):\n - User status changes to Active\n - An invitation email is sent with a magic link\n - User can now log in as a guest user\n- **Disabling login** (`canLogin: true β false`):\n - User status changes to Inactive\n - Invite token is cleared\n - User can no longer log in\n\n**Avatar management:**\n- To update avatar: Upload via `POST /workspace/upload` first, then provide the file ID\n- To remove avatar: Set `avatarId` to `null` or an empty string\n\n**All other fields** (address, phone, personality traits, etc.) can be updated independently without affecting the user account.","operationId":"OrganizationMembersController_updateOrganizationMember","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchOrganizationMemberDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMemberResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization member","tags":["organizations","organization-members"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes an organization member and the associated user account.\n\n**What happens:**\n- The organization member is marked as deleted (soft delete)\n- The associated user account is also marked as deleted\n- The avatar file is permanently deleted from storage\n- Records remain in the database but are hidden from normal queries\n\n**Note:** This is a soft delete operation. The data is not permanently removed and could potentially be restored through database operations if needed.","operationId":"OrganizationMembersController_deleteOrganizationMember","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete organization member","tags":["organizations","organization-members"],"x-required-scopes":["api:write"]}},"/organizations/letters":{"get":{"description":"**What are Organization Letters?**\nOrganization letters are formal business correspondence documents that can be created, managed, and stored directly in Leadtime. They provide centralized, traceable communication linked to each organization, reducing media discontinuity and making it easier to document business correspondence.\n\n**What this endpoint does:**\nReturns a paginated, sortable, and filterable list of all organization letters in the workspace. You can view letters for a specific organization or all letters across the workspace.\n\n**What data is returned:**\n- Letter metadata: ID, subject, date, organization, member (if applicable)\n- Timestamps: creation date, last update date\n- Creator information: who created the letter\n- Address type: whether the letter is addressed to the organization or a specific member\n\n**Supported operations:**\nRetrieves a paginated grid of organization letters with filtering and sorting capabilities. Quick search available on: subject. Filterable fields: id, organizationId, organizationName, memberId, subject, dateOfLetter, addressType, createdAt, lastUpdated, createdBy. Sortable fields: id, organizationId, organizationName, memberId, subject, dateOfLetter, addressType, createdAt, lastUpdated, createdBy.\n\n**Use cases:**\n- View all letters for a specific organization\n- Search and filter letters by subject, date, or member\n- Track letter creation and modification history\n- Export letter lists for reporting\n\n**Note:** Requires `seeLetters` permission on the Organizations resource.","operationId":"OrganizationLettersController_listOrganizationLetters","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: subject","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Letter ID\n- **organizationId** (set): Organization ID\n- **organizationName** (string): Organization name\n- **memberId** (set): Organization member ID (null if not member-specific)\n- **subject** (string): Letter subject\n- **dateOfLetter** (date): Date of the letter\n- **addressType** (set): Address type (Organization or Member)\n- **createdAt** (date): Creation timestamp\n- **lastUpdated** (date): Last update timestamp\n- **createdBy** (set): ID of user who created the letter\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Letter ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **organizationId** (set): Organization ID (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **organizationName** (string): Organization name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **memberId** (set): Organization member ID (null if not member-specific) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **subject** (string): Letter subject (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **dateOfLetter** (date): Date of the letter (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **addressType** (set): Address type (Organization or Member) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **lastUpdated** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **createdBy** (set): ID of user who created the letter (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Letter ID\n- **organizationId**: Organization ID\n- **organizationName**: Organization name\n- **memberId**: Organization member ID (null if not member-specific)\n- **subject**: Letter subject\n- **dateOfLetter**: Date of the letter\n- **addressType**: Address type (Organization or Member)\n- **createdAt**: Creation timestamp\n- **lastUpdated**: Last update timestamp\n- **createdBy**: ID of user who created the letter\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** lastUpdated (desc)","schema":{"example":"[{\"field\":\"lastUpdated\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, organizationId, organizationName, memberId, subject, dateOfLetter, addressType, createdAt, lastUpdated, createdBy","schema":{"example":"id,organizationId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of organization letters"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List organization letters","tags":["organizations","organization-letters","organizations"],"x-required-scopes":["api:read"]},"post":{"description":"**What this endpoint does:**\nCreates a new formal business letter linked to an organization. Letters can be addressed to the organization itself or to a specific organization member (contact person).\n\n**Required information:**\n- **Organization ID**: The organization this letter belongs to (must exist in workspace)\n- **Subject**: Title or topic of the letter\n- **Date of letter**: The date shown on the letter (can be backdated if needed)\n- **Address type**: Choose between organization address or member's private address\n- **Body content**: The letter text in HTML or Markdown format\n\n**Optional information:**\n- **Member ID**: If provided, links the letter to a specific organization member/contact person. The member must belong to the specified organization.\n\n**Content formatting:**\nAccepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n\n\n## Available Template Variables\n\nYou can use the following variables in your organization letter body. Variables are represented as HTML spans:\n\n`clientCompanyName`, `contactPerson`, `senderNameAndPosition`, `senderName`, `senderPosition`, `todayDate`, `dearCustomer`, `signature`\n\n**Example HTML**: `ACME Corp`, `John Doe`\n\n**Validation rules:**\n- Organization ID must exist and be accessible in your workspace\n- If member ID is provided, it must belong to the specified organization\n- Subject cannot be empty\n- Body content cannot be empty\n- Date must be a valid date\n\n**What happens after creation:**\n- Letter is saved and linked to the organization\n- Letter appears in the organization's letters list\n- Letter can be viewed, edited, or downloaded as PDF\n- Letter body is automatically converted from HTML/Markdown to internal format (IDoc)\n\n**Use cases:**\n- Create formal correspondence with customers or partners\n- Generate personalized letters using template variables\n- Document business communication in a centralized location\n- Track all letters sent to specific organizations or members\n\n**Note:** Requires `writeLetters` permission on the Organizations resource.","operationId":"OrganizationLettersController_createOrganizationLetter","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLetterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"organizationId":["Organization ID is required"],"subject":["Subject is required"],"dateOfLetter":["Date is required"],"addressType":["Address type is required"],"body":["Body content is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create organization letter","tags":["organizations","organization-letters","organizations"],"x-required-scopes":["api:write"]}},"/organizations/letters/{id}":{"get":{"description":"**What this endpoint does:**\nRetrieves complete details of a specific organization letter, including the full letter body content converted to HTML format.\n\n**What is returned:**\n- Letter metadata: ID, subject, date, organization ID, member ID (if applicable)\n- Address type: Organization or Member\n- Body content: Full letter text in HTML format (converted from internal IDoc format)\n- Timestamps: Creation date and last update date\n- Creator: User ID of who created the letter\n\n**Use cases:**\n- Display letter content in a viewer or editor\n- Generate PDF exports of letters\n- Retrieve letter details for editing\n- Audit letter history and metadata\n\n**Note:** Requires `seeLetters` permission on the Organizations resource.","operationId":"OrganizationLettersController_getOrganizationLetterDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization letter details","tags":["organizations","organization-letters","organizations"],"x-required-scopes":["api:read"]},"patch":{"description":"**What this endpoint does:**\nUpdates specific fields of an existing organization letter. Only the fields you provide will be updated; all other fields remain unchanged. This allows you to make targeted changes without resubmitting the entire letter.\n\n**What can be updated:**\n- **Organization ID**: Change which organization the letter belongs to\n- **Member ID**: Link/unlink the letter to a specific member (use `null` to clear the member association)\n- **Subject**: Update the letter title\n- **Date of letter**: Change the date shown on the letter\n- **Address type**: Switch between organization address and member address\n- **Body content**: Update the letter text\n\n**Content formatting:**\nAccepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n\n\n## Available Template Variables\n\nYou can use the following variables in your organization letter body. Variables are represented as HTML spans:\n\n`clientCompanyName`, `contactPerson`, `senderNameAndPosition`, `senderName`, `senderPosition`, `todayDate`, `dearCustomer`, `signature`\n\n**Example HTML**: `ACME Corp`, `John Doe`\n\n**Validation rules:**\n- Letter must exist and be accessible in your workspace\n- If organization ID is provided, it must exist and be accessible\n- If member ID is provided (or set to `null`), the member must belong to the specified organization (or the letter's current organization if organization ID is not being updated)\n- All field validations from the create endpoint apply to updated fields\n\n**How partial updates work:**\n- Fields not provided in the request remain unchanged\n- If you provide `memberId: null`, it clears the member association\n- Body content is automatically converted from HTML/Markdown to internal format (IDoc) if provided\n- The `lastUpdated` timestamp is automatically updated\n\n**Use cases:**\n- Correct typos or update letter content\n- Change the recipient (member) of an existing letter\n- Update letter date if backdating is needed\n- Modify letter subject or address type\n\n**Note:** Requires `writeLetters` permission on the Organizations resource.","operationId":"OrganizationLettersController_patchOrganizationLetter","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchLetterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update organization letter","tags":["organizations","organization-letters","organizations"],"x-required-scopes":["api:write"]},"delete":{"description":"**What this endpoint does:**\nSoft deletes an organization letter, marking it as deleted without permanently removing it from the database. The letter will no longer appear in normal listings but can be recovered if needed.\n\n**What happens:**\n- Letter is marked as deleted (soft delete)\n- Letter disappears from organization letters list\n- Letter data is preserved in the database\n- Letter can potentially be restored through database operations\n\n**Use cases:**\n- Remove letters that are no longer needed\n- Clean up test or draft letters\n- Maintain data integrity while allowing cleanup\n\n**Note:** Requires `writeLetters` permission on the Organizations resource.","operationId":"OrganizationLettersController_deleteOrganizationLetter","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete organization letter","tags":["organizations","organization-letters","organizations"],"x-required-scopes":["api:write"]}},"/administration/organization-settings/custom-fields":{"get":{"description":"Retrieves all custom fields configured for organizations in the workspace.\n\n**What are Custom Fields?**\nCustom fields allow you to capture additional information about organizations that matters to your company. These fields are flexible and can hold different types of data.\n\n**Supported field types:**\n- Text: Single-line text input\n- Textarea: Multi-line text input\n- Number: Numeric values\n- Date: Date selection\n- Checkbox: Boolean true/false\n- Select: Single selection from predefined options\n- MultiSelect: Multiple selections from predefined options\n\n**Common use cases:**\n- Industry classification (e.g., Technology, Healthcare, Finance)\n- Business relationship data (e.g., Contract type, Payment terms)\n- CRM-relevant information (e.g., Lead source, Account tier)\n- Individual extra info for special organization types\n\n**What is returned:**\n- Field ID, name, description, type, and entity (always \"Organization\")\n- Sort order (for display ordering)\n- Multilingual translations\n- Select options (for Select and MultiSelect types)\n\n**Note:** Custom fields are especially useful in CRM and add organization management features with specific data points tailored to your business needs.","operationId":"OrganizationSettingsController_getOrganizationCustomFields","parameters":[],"responses":{"200":{"description":"Organization custom fields retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationCustomFieldResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List organization custom fields","tags":["administration","organization-settings","organization-custom-fields"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new custom field for capturing additional organization information.\n\n**Required fields:**\n- `name`: Display name for the field (e.g., \"Priority Level\", \"Region\")\n- `type`: Field type enum value (Text, Textarea, Number, Date, Checkbox, Select, MultiSelect)\n- `translations`: Array of translations for multilingual support\n\n**Optional fields:**\n- `id`: Optional ID for the field (for updating existing fields)\n- `description`: Additional context about the field\n- `selectOptions`: Required for Select and MultiSelect types - array of option objects with:\n - `id`: Optional identifier (use value if not provided)\n - `value`: Display value for the option\n - `translations`: Array of translations for the option name\n- `translationsDescriptions`: Translations for the field description\n\n**Field type requirements:**\n- Select and MultiSelect types MUST include selectOptions array\n- Other types do not use selectOptions\n\n**Note:** Once created, the custom field will appear when creating or editing organizations. The field can be reordered using the sort endpoint.","operationId":"OrganizationSettingsController_createOrganizationCustomField","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationCustomFieldDto"}}}},"responses":{"201":{"description":"Organization custom field created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCustomFieldResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create organization custom field","tags":["administration","organization-settings","organization-custom-fields"],"x-required-scopes":["api:write"]}},"/administration/organization-settings/custom-fields/{id}":{"put":{"description":"Updates an existing organization custom field. All fields must be provided (full replacement).\n\n**Required fields:**\n- `name`: Updated display name\n- `type`: Field type enum value\n- `translations`: Complete translations array (all languages)\n\n**Optional fields:**\n- `description`: Updated description\n- `selectOptions`: Updated options array (required for Select and MultiSelect types)\n- `translationsDescriptions`: Updated description translations\n\n**Important:**\n- Changing field type may cause data loss if existing values are incompatible\n- For Select/MultiSelect types, all options must be included in the request\n- Removing options that are in use may cause validation errors\n\n**Note:** This is a full update operation. Use PATCH endpoint if you only want to update specific fields.","operationId":"OrganizationSettingsController_updateOrganizationCustomField","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationCustomFieldDto"}}}},"responses":{"200":{"description":"Organization custom field updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCustomFieldResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization custom field","tags":["administration","organization-settings","organization-custom-fields"],"x-required-scopes":["api:write"]},"delete":{"description":"Deletes an organization custom field using soft delete (marked as deleted but not permanently removed).\n\n**Important considerations:**\n- The field will no longer appear in organization forms\n- Existing organization data stored in this field will be retained but not displayed\n- Deleted fields can be restored using the restore defaults endpoint\n\n**Note:** This operation requires workspace settings management permission. Consider exporting data before deleting fields if you need to preserve historical information.","operationId":"OrganizationSettingsController_deleteOrganizationCustomField","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Organization custom field deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete organization custom field","tags":["administration","organization-settings","organization-custom-fields"],"x-required-scopes":["api:write"]}},"/administration/organization-settings/custom-fields/sort":{"post":{"description":"Updates the display order of organization custom fields by providing an ordered array of field IDs.\n\n**How it works:**\n1. Provide an array of custom field IDs in the desired display order\n2. The first ID in the array will have sort order 0, second will have 1, etc.\n3. Fields not included in the array will maintain their current sort order\n\n**Example:**\nIf you provide [\"field-3\", \"field-1\", \"field-2\"], then:\n- field-3 will appear first in organization forms\n- field-1 will appear second\n- field-2 will appear third\n\n**Note:** This affects the order in which custom fields appear in organization creation and editing forms.","operationId":"OrganizationSettingsController_sortOrganizationCustomFields","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortOrganizationCustomFieldsDto"}}}},"responses":{"200":{"description":"Organization custom fields reordered successfully"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Reorder organization custom fields","tags":["administration","organization-settings","organization-custom-fields"],"x-required-scopes":["api:write"]}},"/organizations":{"get":{"description":"Returns a paginated, filterable, and sortable grid of all organizations in the workspace.\n\n**What are Organizations?**\nOrganizations represent external business partners that your company has contact with:\n- **Customers**: Existing business partners with ongoing projects\n- **Prospects**: Potential customers with first contact or active offers\n- **Suppliers**: External providers of goods or services\n- **Partners**: Strategic partners or resellers\n- **Competitors**: Competitors in the same industry\n- **Service Providers**: Supporting external providers (e.g., for support)\n- **Investors**: Financial or institutional investors\n- **Authorities**: Public institutions or government agencies\n- **Educational Institutions**: Universities, schools, or research institutes\n- **Target Groups**: Companies that belong to your target customer group\n\nOrganizations are the foundation for managing external projects, contacts (organization members), invoices, and business relationships. They allow you to structure and analyze all external partnerships in one place.\n\n**What is returned:**\n- Organization identification (ID, name, short name, type, color, icon)\n- Status information (active/inactive)\n- Relationship data (number of linked projects, number of members/contacts)\n- Creation and update timestamps\n- Logo information\n\n**Filtering and search:**\n- Quick search across organization name, short name, and other fields\n- Advanced filtering by type, status, and other attributes\n- Sorting by any sortable field\n- Server-side pagination for large organization lists\n\n**Note:** This endpoint requires the Organizations.view permission. Retrieves a paginated grid of organizations with filtering and sorting capabilities. Quick search available on: name, shortName. Filterable fields: id, name, shortName, type, isActive, email, phoneNumber, website, addressCity, addressCountry, addressStreet, addressZip, startOfCollaboration, createdAt, editedAt, isFavorite, parentOrganizationId, parentOrganizationName. Sortable fields: id, name, shortName, type, isActive, addressCity, addressCountry, startOfCollaboration, createdAt, editedAt, isFavorite, parentOrganizationId.","operationId":"OrganizationsController_listOrganizations","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: name, shortName","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Organization ID\n- **name** (string): Organization name\n- **shortName** (string): Short identifier\n- **type** (set): Organization type (Customer, Vendor, Partner, etc.)\n- **isActive** (boolean): Whether organization is active\n- **email** (string): Email address\n- **phoneNumber** (string): Phone number\n- **website** (string): Website URL\n- **addressCity** (string): City\n- **addressCountry** (string): Country\n- **addressStreet** (string): Street address\n- **addressZip** (string): ZIP/Postal code\n- **startOfCollaboration** (date): Start of collaboration date\n- **createdAt** (date): Creation timestamp\n- **editedAt** (date): Last update timestamp\n- **isFavorite** (boolean): Whether the organization is marked as favorite by the current user\n- **parentOrganizationId** (string): Parent organization ID\n- **parentOrganizationName** (string): Parent organization name\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **name** (string): Organization name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **shortName** (string): Short identifier (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **type** (set): Organization type (Customer, Vendor, Partner, etc.) (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **isActive** (boolean): Whether organization is active (boolean filter). Available comparisons: equal, not_equal\n- **email** (string): Email address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **phoneNumber** (string): Phone number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **website** (string): Website URL (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCity** (string): City (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCountry** (string): Country (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressStreet** (string): Street address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressZip** (string): ZIP/Postal code (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **startOfCollaboration** (date): Start of collaboration date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **editedAt** (date): Last update timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **isFavorite** (boolean): Whether the organization is marked as favorite by the current user (boolean filter). Available comparisons: equal, not_equal\n- **parentOrganizationId** (string): Parent organization ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **parentOrganizationName** (string): Parent organization name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Organization ID\n- **name**: Organization name\n- **shortName**: Short identifier\n- **type**: Organization type (Customer, Vendor, Partner, etc.)\n- **isActive**: Whether organization is active\n- **addressCity**: City\n- **addressCountry**: Country\n- **startOfCollaboration**: Start of collaboration date\n- **createdAt**: Creation timestamp\n- **editedAt**: Last update timestamp\n- **isFavorite**: Whether the organization is marked as favorite by the current user\n- **parentOrganizationId**: Parent organization ID\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** name (asc)","schema":{"example":"[{\"field\":\"name\",\"direction\":\"asc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, name, shortName, type, color, isActive, email, phoneNumber, website, addressCity, addressCountry, addressStreet, addressZip, startOfCollaboration, createdAt, editedAt, isFavorite, parentOrganizationId, parentOrganizationName","schema":{"example":"id,name","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of organizations"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List organizations","tags":["organizations"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new organization (external business partner) in your workspace.\n\n**What are Organizations?**\nOrganizations represent external business partners like customers, suppliers, partners, or competitors. They serve as the foundation for managing external projects, contacts, invoices, and business relationships.\n\n**Required fields:**\n- name: Full company name (e.g., \"Acme Corporation\")\n- type: Organization type (Customer, Prospect, Supplier, Partner, etc.)\n- color: Hex color code for visual identification (e.g., \"#FF5733\")\n\n**Optional fields:**\n- shortName: 3-5 character abbreviation (auto-generated if not provided)\n- icon: Icon identifier for visual representation\n- legalForm: Legal company form (e.g., \"GmbH\", \"AG\", \"LLC\")\n- startOfCollaboration: Date when business relationship started (ISO date format: YYYY-MM-DD)\n- Contact information: Address fields, phone, fax, email, website\n- Legal information: Tax number, registration number, registration court\n- Invoice settings: Hourly rate, payment terms, reminder fees, interest rates\n- Document settings: Table of contents, title page, heading style\n\n**Uploading a logo:**\n1. First, call POST /api/public/workspace/upload to upload the logo file\n2. The upload endpoint returns a file ID (UUID)\n3. Use that file ID in the logoId field when creating the organization\n\n**Auto-generated fields:**\n- If shortName is not provided, it will be automatically generated from the organization name\n- The organization will be created with isActive: true by default\n\n**What is returned:**\nThe complete organization object with all fields, including computed values like logoUrl and timestamps.\n\n**Note:** This endpoint requires the Organizations.create permission. All validation errors will be returned with detailed field-level messages.","operationId":"OrganizationsController_createOrganization","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"name":["Name is required"],"type":["Type is required"],"color":["Color must be a valid hex code"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create organization","tags":["organizations"],"x-required-scopes":["api:write"]}},"/organizations/{id}/objects":{"get":{"description":"Returns objects whose organization matches this organization. Visibility rules for objects still apply.","operationId":"OrganizationsController_listOrganizationObjects","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"minimum":1,"maximum":200,"default":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedObjectsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List objects for an organization","tags":["organizations"],"x-required-scopes":["api:read"]}},"/organizations/{id}":{"get":{"description":"Retrieves complete details of a specific organization, including all master data, contact information, legal details, and settings.\n\n**What is returned:**\n- **Basic information**: Name, short name, icon, type, color, legal form, description\n- **Contact details**: Full address (street, city, ZIP, country, house number), phone, fax, email, website\n- **Legal information**: Tax number, registration number, registration court\n- **Business relationship**: Start of collaboration date, active status\n- **Invoice settings**: Hourly rate, payment terms, reminder fees, interest rates, invoice language\n- **Document settings**: Table of contents, title page, heading style, default contact\n- **Logo**: Public URL to the organization logo (if uploaded)\n- **Timestamps**: Creation and last update dates\n\n**Note:** This endpoint requires the Organizations.view permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_getOrganizationDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization details","tags":["organizations"],"x-required-scopes":["api:read"]},"put":{"description":"Updates an existing organization by replacing all fields. This is a full update operation - all fields must be provided, even if you only want to change a few values.\n\n**When to use:**\nUse this endpoint when you want to update multiple fields or replace the entire organization data. For partial updates (changing only specific fields), use PATCH /organizations/:id instead.\n\n**Required fields:**\nAll fields that are required for creation must be provided:\n- name: Full company name\n- type: Organization type\n- color: Hex color code\n\n**Optional fields:**\nAll other fields can be provided or omitted (will be set to null/undefined if omitted).\n\n**Updating the logo:**\n1. Call POST /api/public/workspace/upload to upload the new logo file\n2. Use the returned file ID in the logoId field\n3. To remove the logo, set logoId to null\n\n**What is returned:**\nThe complete updated organization object with all fields and computed values.\n\n**Note:** This endpoint requires the Organizations.edit permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_updateOrganization","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization","tags":["organizations"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes an organization and all associated projects. The organization and its projects will be marked as deleted but not permanently removed from the database.\n\n**What happens:**\n- The organization is marked as deleted (soft delete)\n- All associated projects are also soft deleted\n- Organization members (contacts) are not deleted\n- Historical data (invoices, journal entries, etc.) remains intact\n- The organization will no longer appear in normal listings\n\n**Recovery:**\nSoft-deleted organizations can potentially be recovered through database operations, but this is not exposed via the API.\n\n**Note:** This endpoint requires the Organizations.delete permission. The organization must exist in your workspace. This operation cannot be undone via the API.","operationId":"OrganizationsController_deleteOrganization","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete organization","tags":["organizations"],"x-required-scopes":["api:write"]},"patch":{"description":"Partially updates an organization. Only the fields you provide will be updated; all other fields remain unchanged. This is the recommended way to update organizations when you only need to change specific fields.\n\n**When to use:**\nUse this endpoint for partial updates (changing only specific fields). For full updates (replacing all fields), use PUT /organizations/:id instead.\n\n**Available fields:**\nAll organization fields can be updated, including:\n- Basic info: name, shortName, icon, type, color, legalForm, description\n- Contact details: address fields, phone, fax, email, website\n- Legal info: taxNumber, registrationNumber, registrationCourt\n- Business: startOfCollaboration, isActive (via full update)\n- Invoice settings: hourRate, invoiceDueDays, reminder fees, interest rates, invoiceLanguage\n- Document settings: table of contents, title page, heading style, default contact\n\n**Updating the logo:**\n1. Call POST /api/public/workspace/upload to upload the new logo file\n2. Use the returned file ID in the logoId field\n3. To remove the logo, set logoId to null\n\n**Behavior:**\n- Omitted fields remain unchanged\n- Provided fields replace existing values\n- Set fields to null to clear them (where allowed)\n- Date fields should be provided in ISO format (YYYY-MM-DD)\n\n**What is returned:**\nThe complete updated organization object with all fields and computed values.\n\n**Note:** This endpoint requires the Organizations.edit permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_patchOrganization","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchOrganizationDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update organization","tags":["organizations"],"x-required-scopes":["api:write"]}},"/organizations/{id}/document-settings":{"get":{"description":"Retrieves document formatting settings for a specific organization. These settings control how project documents (quotes, requirement documents, contracts) are formatted for this organization.\n\n**What are Document Settings?**\nDocument settings allow you to customize the appearance and structure of automatically generated project documents on a per-organization basis. These settings override the workspace defaults, enabling customer-specific document layouts and formatting.\n\n**What is returned:**\n- **Organization-specific settings**: Values set for this organization (can be null to inherit from workspace)\n - projectDocumentEnableToc: Whether to include a table of contents\n - projectDocumentTitlePage: Whether to show a title/cover page\n - projectDocumentHeadingStyle: Formatting style for headings (e.g., Sequential, Normal)\n - projectDocumentDefaultContactUserId: Default contact person for documents\n- **Workspace defaults**: The default values that apply when organization settings are null\n - projectDocumentEnableTocDefault: Workspace default for table of contents\n - projectDocumentTitlePageDefault: Workspace default for title page\n - projectDocumentHeadingStyleDefault: Workspace default heading style\n\n**Inheritance behavior:**\n- If an organization setting is null, the workspace default is used\n- If an organization setting has a value, it overrides the workspace default\n- This allows you to customize documents per customer while maintaining workspace-wide defaults\n\n**Use cases:**\n- Different document layouts for specific customers\n- Custom corporate design requirements\n- Creating documents for external partners without internal formatting\n\n**Note:** This endpoint requires the Organizations.view permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_getOrganizationDocumentSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetOrganizationDocumentSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization document settings","tags":["organizations"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates document formatting settings for an organization. Only the fields you provide will be updated; all other fields remain unchanged.\n\n**What are Document Settings?**\nDocument settings control how project documents (quotes, requirement documents, contracts) are formatted for this organization. These settings can override workspace defaults to enable customer-specific layouts.\n\n**Available settings:**\n- projectDocumentEnableToc: Include table of contents (boolean or null to inherit)\n- projectDocumentTitlePage: Show title/cover page (boolean or null to inherit)\n- projectDocumentHeadingStyle: Heading formatting style (enum value or null to inherit)\n- projectDocumentDefaultContactUserId: Default contact person UUID (or null to clear)\n\n**Inheritance:**\n- Set any field to null to inherit the workspace default for that setting\n- Provide a value to override the workspace default for this organization\n- Omit fields you do not want to change (they remain unchanged)\n\n**Example use cases:**\n- Enable table of contents for a specific customer: { \"projectDocumentEnableToc\": true }\n- Reset to workspace default: { \"projectDocumentEnableToc\": null }\n- Set multiple settings at once: { \"projectDocumentEnableToc\": true, \"projectDocumentTitlePage\": false }\n\n**Note:** This endpoint requires the Organizations.edit permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_updateOrganizationDocumentSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchOrganizationDocumentSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization document settings","tags":["organizations"],"x-required-scopes":["api:write"]}},"/organizations/{id}/custom-fields":{"patch":{"description":"Updates only the custom field values for an organization. This endpoint is optimized for updating custom fields without affecting other organization data.\n\n**Request body:**\n- `customFields`: Object with custom field IDs as keys and their values\n - Keys should match custom field IDs configured in workspace settings\n - Values must match the field type (string, number, boolean, date, etc.)\n - Use the GET /administration/organization-settings/custom-fields endpoint to retrieve available custom fields\n\n**Example:**\n```json\n{\n \"customFields\": {\n \"field-id-1\": \"Text value\",\n \"field-id-2\": 123,\n \"field-id-3\": true,\n \"field-id-4\": \"2024-01-01\"\n }\n}\n```\n\n**Note:** This endpoint requires the Organizations.edit permission. The organization must exist in your workspace and not be deleted.","operationId":"OrganizationsController_updateOrganizationCustomFields","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customFields":{"type":"object","additionalProperties":true,"description":"Custom field values as key-value pairs"}},"required":["customFields"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization custom fields","tags":["organizations"],"x-required-scopes":["api:write"]}},"/organizations/{id}/invoice-settings":{"get":{"description":"Retrieves invoice and billing settings for a specific organization. These settings control payment terms, reminder rules, and custom text templates for invoices and reminders.\n\n**What are Invoice Settings?**\nInvoice settings allow you to define organization-specific billing parameters that override workspace defaults. This enables customer-specific payment terms, reminder rules, and invoice texts.\n\n**What is returned:**\n- **Payment terms**:\n - hourRate: Customer-specific hourly rate (used for all billable times)\n - invoiceDueDays: Number of days until payment is due (1-120)\n - invoiceLanguage: Language code for invoice generation (e.g., \"en\", \"de\")\n- **Reminder fees**:\n - enableInvoiceReminderFee: Whether reminder fees are charged\n - invoiceReminderFee: Amount charged for overdue invoices (0-1000)\n- **Interest on arrears**:\n - enableInvoiceInterest: Whether interest is charged on overdue invoices\n - baseInvoiceInterest: Base interest rate percentage (0-1000)\n - invoiceInterest: Interest rate percentage added to base rate (0-1000)\n- **Custom text templates**: All custom invoice and reminder texts, returned as HTML:\n - withBestRegards: Closing text for invoices\n - invoiceGreeting: Greeting text on invoices\n - invoiceFooter: Footer text on invoices\n - invoiceReminderFeeWarning: Warning about reminder fees\n - firstReminderGreeting: Greeting for first reminder\n - firstReminderFooter: Footer for first reminder\n - secondReminderGreeting: Greeting for second reminder\n - secondReminderFooter: Footer for second reminder\n - cancelationBody: Text for invoice cancellations\n\n**Use cases:**\n- Individual agreements with key clients (longer payment terms, no reminder fees)\n- Customer-specific hourly rates (different rates per customer type)\n- Goodwill rules for important customers (gentler reminders)\n- Stricter rules for risky customers (shorter terms, higher fees)\n- International customers (different interest rates, languages, legal requirements)\n\n**Note:** This endpoint requires the Organizations.view permission. The organization must exist in your workspace and not be deleted. Custom texts are stored internally in IDoc format but returned as HTML for easier consumption.","operationId":"OrganizationsController_getOrganizationInvoiceSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvoiceSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get organization invoice settings","tags":["organizations"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates invoice and billing settings for an organization. Only the fields you provide will be updated; all other fields remain unchanged.\n\n**What are Invoice Settings?**\nInvoice settings define organization-specific billing parameters that override workspace defaults, enabling customer-specific payment terms, reminder rules, and invoice texts.\n\n**Available settings:**\n- **Payment terms**:\n - hourRate: Customer-specific hourly rate (number or null)\n - invoiceDueDays: Days until payment is due, 1-120 (number or null)\n - invoiceLanguage: Language code for invoices (string or null)\n- **Reminder fees**:\n - enableInvoiceReminderFee: Enable reminder fees (boolean or null)\n - invoiceReminderFee: Reminder fee amount, 0-1000 (number or null)\n- **Interest on arrears**:\n - enableInvoiceInterest: Enable interest on overdue invoices (boolean or null)\n - baseInvoiceInterest: Base interest rate percentage, 0-1000 (number or null)\n - invoiceInterest: Interest rate percentage, 0-1000 (number or null)\n- **Custom text templates**: Object with HTML or Markdown content (converted to IDoc internally):\n - withBestRegards, invoiceGreeting, invoiceFooter\n - invoiceReminderFeeWarning\n - firstReminderGreeting, firstReminderFooter\n - secondReminderGreeting, secondReminderFooter\n - cancelationBody\n\n**Custom text templates:**\n- Can be provided as HTML or Markdown\n- Will be automatically converted to internal IDoc format\n- Support macros/variables (e.g., #dear, #clientCompanyName, #invoiceNumber)\n- Set to null or empty string to clear a template\n- Omit fields you do not want to change\n\n**Behavior:**\n- Omitted fields remain unchanged\n- Provided fields replace existing values\n- Set fields to null to reset to workspace defaults (where applicable)\n- Custom texts are converted from HTML/Markdown to IDoc format for storage\n\n**What is returned:**\nThe complete updated invoice settings object, with custom texts returned as HTML.\n\n**Note:** This endpoint requires the Organizations.edit permission. The organization must exist in your workspace and not be deleted. Custom texts are stored internally in IDoc format but can be provided as HTML or Markdown.","operationId":"OrganizationsController_patchOrganizationInvoiceSettings","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchOrganizationInvoiceSettingsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvoiceSettingsResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update organization invoice settings","tags":["organizations"],"x-required-scopes":["api:write"]}},"/teams":{"get":{"description":"Returns a list of all teams in the workspace with their members.\n\n**What are Teams?**\nTeams group employees together to simplify project access management and form the basis for structured evaluations. Instead of assigning permissions to each employee individually, you can grant entire teams access to specific projects or areas. This makes it easier to manage rights, responsibilities, and resources in one place.\n\nTeams are also used for:\n- Filtering charts and dashboards by team\n- Organizing employees into logical groups\n- Project access management\n- Team-based reporting and insights\n\n**What is returned:**\n- Team identification (ID, name, icon)\n- Number of users in the team\n- Complete list of team members with their details (ID, name, avatar)\n\n**Note:** This endpoint requires the Teams.manage permission.","operationId":"TeamsController_listTeams","parameters":[],"responses":{"200":{"description":"List of teams","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List all teams","tags":["teams"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new team with the specified name, icon, and members.\n\n**How to create a team:**\n1. Provide a team name (required) - choose any descriptive name\n2. Select an icon emoji (required) - used for visual identification\n3. Assign at least one user to the team (required) - provide an array of user IDs\n\n**Validation rules:**\n- Team name must be a non-empty string\n- Icon must be a non-empty string (typically an emoji)\n- Users array must contain at least one user ID\n- All user IDs must be valid UUIDs of existing employees in the workspace\n\n**What happens after creation:**\n- The team is immediately available for project assignments\n- Team members can be granted access to projects as a group\n- The team appears in team lists and can be used for filtering\n- The team can be edited or deleted later\n\n**What is returned:**\n- Complete team details including the generated team ID\n- All assigned members with their information\n- Team metadata (name, icon, user count)\n\n**Note:** This endpoint requires the Teams.create permission.","operationId":"TeamsController_createTeam","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTeamDto"}}}},"responses":{"200":{"description":"Created team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"name":["Name is required"],"icon":["Icon is required"],"users":["At least one user is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create a new team","tags":["teams"],"x-required-scopes":["api:write"]}},"/teams/{id}":{"get":{"description":"Returns full details of a specific team including all members.\n\n**What is returned:**\n- Team identification (ID, name, icon emoji)\n- Number of users in the team\n- Complete list of all team members with:\n - User ID\n - First and last name\n - Avatar file ID (if available)\n\n**Use cases:**\n- Displaying team information in a detail view\n- Verifying team membership before making changes\n- Getting complete team data for editing\n\n**Note:** Returns 404 if the team does not exist or has been deleted. This endpoint requires the Teams.manage permission.","operationId":"TeamsController_getTeamDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Team details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get team details","tags":["teams"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates only the provided fields of a team. All fields are optional.\n\n**How partial updates work:**\n- Only include the fields you want to change\n- Omitted fields remain unchanged\n- You can update the name, icon, members, or any combination\n\n**Update scenarios:**\n- Change team name: Provide only the \"name\" field\n- Change icon: Provide only the \"icon\" field\n- Update members: Provide only the \"users\" array with new user IDs\n- Update multiple fields: Provide any combination of fields\n\n**Important notes:**\n- When updating members, provide the complete list of user IDs you want in the team\n- The users array replaces the entire team membership (not merged)\n- At least one user must remain in the team after update\n- All user IDs must be valid UUIDs of existing employees\n\n**What is returned:**\n- Complete updated team details\n- All current team members\n- Updated metadata (name, icon, user count)\n\n**Note:** Returns 404 if the team does not exist or has been deleted. This endpoint requires the Teams.edit permission.","operationId":"TeamsController_patchTeam","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchTeamDto"}}}},"responses":{"200":{"description":"Updated team","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update a team","tags":["teams"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes a team. The team will be marked as deleted but not permanently removed from the database.\n\n**What happens when a team is deleted:**\n- The team is marked as deleted (soft delete)\n- The team no longer appears in team lists\n- Project assignments to this team are removed\n- Historical data and associations are preserved\n- The team cannot be restored through the API\n\n**Important considerations:**\n- Verify the team exists before deletion (endpoint returns 404 if not found)\n- Consider removing team members or project assignments first if needed\n- Deleted teams do not appear in GET requests\n- This operation cannot be undone through the API\n\n**What is returned:**\n- Success confirmation\n\n**Note:** Returns 404 if the team does not exist or has already been deleted. This endpoint requires the Teams.delete permission.","operationId":"TeamsController_deleteTeam","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Team successfully deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete a team","tags":["teams"],"x-required-scopes":["api:write"]}},"/vacations/pending":{"get":{"description":"Retrieves all pending vacation requests that are awaiting manager approval.\n\n**What is Vacation Management?**\nVacation management digitizes the entire vacation process and ensures transparent, traceable, and efficient vacation planning. Employees can submit vacation requests, and managers can review and approve them while considering business workload and capacity.\n\n**What is returned:**\nEach vacation request includes:\n- `id`: Unique vacation request identifier\n- `dateFrom`: Start date of the vacation period (ISO 8601 date string)\n- `dateTo`: End date of the vacation period (ISO 8601 date string)\n- `status`: Current status of the request (always \"Pending\" for this endpoint)\n- `userId`: ID of the employee who requested the vacation\n- `capacity`: Optional capacity utilization percentage for the vacation period\n\n**How it works:**\n- Only vacation requests with status \"Pending\" are returned\n- Managers with \"manageAll\" permission see all pending requests across the workspace\n- Managers with \"manageTeams\" permission only see requests from employees in their teams\n- Use the optional `teamId` query parameter to filter requests for a specific team\n- Results are sorted by start date (earliest first)\n\n**Use cases:**\n- Displaying a list of vacation requests that need approval\n- Building a vacation approval dashboard\n- Filtering requests by team for team-specific managers","operationId":"VacationsController_getPendingVacations","parameters":[{"name":"teamId","required":false,"in":"query","description":"Optional team ID (UUID) to filter vacation requests for a specific team. If not provided, returns requests based on the manager permissions (all teams for manageAll, or manager teams for manageTeams). This parameter is useful for team-specific managers who want to focus on a particular team.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved pending vacations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get pending vacation requests","tags":["vacations","time-management"],"x-required-scopes":["api:read"]}},"/vacations/upcoming":{"get":{"description":"Retrieves all approved vacations that have not yet ended (end date is today or in the future).\n\n**What is returned:**\nEach vacation includes:\n- `id`: Unique vacation identifier\n- `dateFrom`: Start date of the vacation period (ISO 8601 date string)\n- `dateTo`: End date of the vacation period (ISO 8601 date string)\n- `status`: Current status (always \"Approved\" for this endpoint)\n- `userId`: ID of the employee taking the vacation\n- `capacity`: Optional capacity utilization percentage for the vacation period\n\n**How it works:**\n- Only vacations with status \"Approved\" and end date >= today are returned\n- This includes both current vacations (in progress) and future approved vacations\n- Managers with \"manageAll\" permission see all upcoming vacations across the workspace\n- Managers with \"manageTeams\" permission only see vacations from employees in their teams\n- Use the optional `teamId` query parameter to filter vacations for a specific team\n- Results are sorted by start date (earliest first)\n\n**Use cases:**\n- Displaying an overview of upcoming time off for capacity planning\n- Building a team calendar showing approved absences\n- Identifying potential scheduling conflicts\n- Showing managers which employees will be absent in the near future","operationId":"VacationsController_getUpcomingVacations","parameters":[{"name":"teamId","required":false,"in":"query","description":"Optional team ID (UUID) to filter upcoming vacations for a specific team. If not provided, returns vacations based on the manager permissions (all teams for manageAll, or manager teams for manageTeams). This parameter is useful for team-specific managers who want to focus on a particular team.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved upcoming approved vacations","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get upcoming approved vacations","tags":["vacations","time-management"],"x-required-scopes":["api:read"]}},"/vacations/{id}/approve":{"post":{"description":"Approves a pending vacation request, changing its status from \"Pending\" to \"Approved\".\n\n**What this does:**\n- Updates the vacation request status to \"Approved\"\n- Records who approved the request and when (statusChangedBy, statusChangedAt)\n- Sends a notification to the employee who requested the vacation\n- The approved vacation will now appear in upcoming vacations and team calendars\n\n**How it works:**\n- The vacation must be in \"Pending\" status to be approved\n- Only managers with \"manageAll\" or \"manageTeams\" permission can approve requests\n- Managers with \"manageTeams\" can only approve requests from employees in their teams\n- The vacation ID is provided as a URL parameter\n- Returns 404 if the vacation request is not found\n\n**Use cases:**\n- Approving vacation requests from a management dashboard\n- Bulk approval workflows\n- Automated approval based on business rules\n\n**Note:** After approval, the vacation will be visible in the upcoming vacations endpoint and will affect capacity calculations.","operationId":"VacationsController_approveVacation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Vacation request approved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Vacation request not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Approve a vacation request","tags":["vacations","time-management"],"x-required-scopes":["api:write"]}},"/vacations/{id}/decline":{"post":{"description":"Declines a pending vacation request or cancels an approved vacation.\n\n**What this does:**\n- For pending requests: Changes status from \"Pending\" to \"Rejected\"\n- For approved vacations: Changes status from \"Approved\" to \"Cancelled\"\n- Records who declined/cancelled the request and when (statusChangedBy, statusChangedAt)\n- Optionally records a reason for the decline/cancellation\n- Sends a notification to the employee who requested the vacation\n\n**How it works:**\n- The vacation ID is provided as a URL parameter\n- The optional reason can be provided in the request body\n- Only managers with \"manageAll\" or \"manageTeams\" permission can decline/cancel requests\n- Managers with \"manageTeams\" can only decline/cancel requests from employees in their teams\n- Returns 404 if the vacation request is not found\n- After decline/cancellation, the vacation will appear in the vacation history\n\n**Request body:**\n- `reason` (optional): Text explanation for why the vacation was declined or cancelled\n - Example: \"Insufficient coverage during this period\"\n - This reason will be visible in the vacation history\n\n**Use cases:**\n- Rejecting vacation requests that conflict with business needs\n- Cancelling previously approved vacations due to changed circumstances\n- Providing feedback to employees about why their request was not approved","operationId":"VacationsController_declineVacation","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclineVacationDto"}}}},"responses":{"200":{"description":"Vacation request declined successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"},"404":{"description":"Vacation request not found"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Decline or cancel a vacation request","tags":["vacations","time-management"],"x-required-scopes":["api:write"]}},"/vacations/history":{"get":{"description":"Retrieves vacation history with support for filtering, sorting, and pagination.\n\n**What is returned:**\nA paginated grid response containing vacation history items. Each item includes:\n- `id`: Unique vacation identifier\n- `dateFrom`: Start date of the vacation period\n- `dateTo`: End date of the vacation period\n- `status`: Vacation status (\"Rejected\", \"Cancelled\", or past \"Approved\" vacations)\n- `employeeId`: ID of the employee who requested the vacation\n- `statusChangedAt`: Timestamp when the status was last changed\n- `statusChangedBy`: ID of the user who changed the status (null if not changed by a user)\n- `reason`: Optional reason provided when the vacation was declined or cancelled\n\n**What is included in history:**\n- All rejected vacation requests\n- All cancelled vacations (previously approved but then cancelled)\n- All approved vacations that have ended (dateTo < today)\n- Does not include pending or upcoming approved vacations (use the pending/upcoming endpoints for those)\n\n**Grid features:**\n- **Filtering**: Filter by date range, employee, status, or any other field\n- **Sorting**: Sort by any column (default sorting can be specified)\n- **Pagination**: Standard grid pagination with page size control\n- Grid parameters are automatically parsed from query string using standard grid format\n\n**How it works:**\n- Managers with \"manageAll\" permission see all vacation history across the workspace\n- Managers with \"manageTeams\" permission only see history from employees in their teams\n- Use the optional `teamId` query parameter to filter history for a specific team\n- Supports standard grid server-side parameters (filters, sort, pagination)\n\n**Use cases:**\n- Building a vacation history table with search and filter capabilities\n- Analyzing vacation patterns and trends\n- Reviewing past vacation decisions and reasons\n- Generating reports on vacation usage","operationId":"VacationsController_getVacationHistory","parameters":[{"name":"teamId","required":false,"in":"query","description":"Optional team ID (UUID) to filter vacation history for a specific team. If not provided, returns history based on the manager permissions (all teams for manageAll, or manager teams for manageTeams). This parameter is useful for team-specific managers who want to focus on a particular team.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved vacation history grid","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get vacation history grid","tags":["vacations","time-management"],"x-required-scopes":["api:read"]}},"/employees/journal":{"get":{"description":"Retrieves a paginated grid of employee journal entries with filtering and sorting capabilities. Filterable fields: id, employeeId, createdAt, createdBy, mood, reminder. Sortable fields: id, employeeId, createdAt, createdBy, mood, reminder.\n\n**What are Employee Journals?**\nEmployee journals are used to document notes, observations, conversations, and feedback about employees. They help track interactions, performance notes, and important information about team members.\n\n**What is returned:**\n- Journal entry ID and associated employee ID\n- Rich text content (body) converted to HTML format\n- Mood indicator (Happy, Neutral, or Sad)\n- Optional reminder date for follow-ups\n- Creation and update timestamps\n- Creator user ID\n\n**Permission-based filtering:**\n- Users with `Employees.manage` permission: See all journal entries for all employees\n- Users without `Employees.manage` permission: Only see entries for their own employee record where `visibleToSubject = true`\n- Employees can create their own entries, which are automatically marked as visible to themselves\n\n**Filtering options:**\n- Filter by `employeeId` to view entries for a specific employee\n- Filter by `mood` to find entries with specific emotional indicators\n- Filter by `createdAt` or `lastUpdated` to find entries within date ranges\n- Filter by `reminder` to find entries with upcoming or past reminders\n\n**Use cases:**\n- Track conversations and agreements with employees\n- Document feedback and observations about team members\n- Set reminders for follow-up actions\n- Maintain a chronological record of interactions with employees","operationId":"EmployeesJournalController_listEmployeeJournals","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Journal entry ID\n- **employeeId** (string): Employee ID\n- **createdAt** (date): Journal entry creation timestamp\n- **createdBy** (string): Creator user ID\n- **mood** (set): Journal entry mood\n- **reminder** (date): Reminder date\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Journal entry ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **employeeId** (string): Employee ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **createdAt** (date): Journal entry creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **createdBy** (string): Creator user ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **mood** (set): Journal entry mood (set filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **reminder** (date): Reminder date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Journal entry ID\n- **employeeId**: Employee ID\n- **createdAt**: Journal entry creation timestamp\n- **createdBy**: Creator user ID\n- **mood**: Journal entry mood\n- **reminder**: Reminder date\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** createdAt (desc)","schema":{"example":"[{\"field\":\"createdAt\",\"direction\":\"desc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, employeeId, createdAt, createdBy, mood, reminder, body","schema":{"example":"id,employeeId","type":"array","items":{}}}],"responses":{"200":{"description":"Paginated list of employee journal entries"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List employee journal entries","tags":["employees","journal","employees"],"x-required-scopes":["api:read"]},"post":{"description":"Creates a new journal entry for an employee.\n\n**What you need to provide:**\n- `employeeId` (required): UUID of the employee this entry is about\n- `body` (required): Rich text content in HTML or Markdown format. Supports:\n - Headings, paragraphs, lists, and formatting\n - Links and embedded content\n - The content is automatically converted to the internal document format\n- `mood` (optional): Emotional indicator - Happy, Neutral, or Sad (defaults to Neutral)\n- `reminder` (optional): ISO 8601 date string for follow-up reminders (e.g., \"2024-12-31\")\n\n**Access control:**\n- Users with `Employees.edit` permission can create entries for any employee\n- Employees can create entries for their own employee record\n- The `employeeId` must exist and be accessible to the current user\n- Returns 400 if the employee does not exist or is not accessible\n\n**Visibility behavior:**\n- If the user is creating an entry for their own employee record, `visibleToSubject` is automatically set to `true`\n- If the user has `Employees.edit` permission and creates an entry for another employee, `visibleToSubject` is set to `false` (internal only)\n\n**What is returned:**\nThe complete journal entry with all fields, including the body converted to HTML format and timestamps.","operationId":"EmployeesJournalController_createEmployeeJournal","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeJournalResponseDto"}}}},"400":{"description":"Validation errors or employee not accessible","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"employeeId":["Employee ID is required","Invalid employeeId or employee not accessible"],"body":["Body content is required"],"mood":["Mood must be one of: Happy, Neutral, Sad"],"reminder":["Reminder must be a valid ISO 8601 date string"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create employee journal entry","tags":["employees","journal","employees"],"x-required-scopes":["api:write"]}},"/employees/journal/{id}":{"get":{"description":"Returns complete details for a specific employee journal entry.\n\n**What is returned:**\n- Journal entry ID and associated employee ID\n- Rich text content (body) converted to HTML format from the internal document format\n- Mood indicator (Happy, Neutral, or Sad)\n- Optional reminder date in ISO 8601 format (null if not set)\n- Creation timestamp (when the entry was created)\n- Last update timestamp (when the entry was last modified)\n- Creator user ID (who created the entry)\n\n**Access control:**\n- Creator of the entry can access\n- Users with `Employees.edit` permission can access any journal entry\n- Returns 404 if the entry does not exist, has been deleted, or the user does not have access\n\n**Note:** The body content is automatically converted from the internal document format (IDoc) to HTML for easy display in web applications.","operationId":"EmployeesJournalController_getEmployeeJournalDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeJournalResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get employee journal entry details","tags":["employees","journal","employees"],"x-required-scopes":["api:read"]},"patch":{"description":"Updates specific fields of an existing employee journal entry. Only provided fields are updated; all fields are optional.\n\n**What you can update:**\n- `employeeId` (optional): Change which employee this entry is associated with\n- `body` (optional): Update the rich text content (HTML or Markdown format)\n- `mood` (optional): Change the emotional indicator (Happy, Neutral, or Sad)\n- `reminder` (optional): Update or clear the reminder date\n - Provide an ISO 8601 date string (e.g., \"2024-12-31\") to set/update\n - Provide `null` to clear an existing reminder\n - Omit the field to keep the existing reminder unchanged\n\n**Access control:**\n- Users with `Employees.edit` permission can update any journal entry\n- Employees can update their own entries (creator or subject)\n- If updating `employeeId`, the new employee must exist and be accessible\n- Returns 404 if the entry does not exist, has been deleted, or the user does not have access\n- Returns 400 if the new `employeeId` is invalid or not accessible\n\n**Visibility behavior:**\n- If changing `employeeId` to the user's own employee record, `visibleToSubject` is automatically set to `true`\n- Otherwise, the existing `visibleToSubject` value is preserved\n\n**What is returned:**\nThe complete updated journal entry with all fields, including the body converted to HTML format and updated timestamps.","operationId":"EmployeesJournalController_patchEmployeeJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchEmployeeJournalDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeJournalResponseDto"}}}},"400":{"description":"Validation errors or employee not accessible"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Partially update employee journal entry","tags":["employees","journal","employees"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes an employee journal entry. The entry is marked as deleted but not permanently removed from the database.\n\n**What happens:**\n- The journal entry is marked with a `deletedAt` timestamp\n- The entry will no longer appear in list queries or be accessible via the API\n- The data is preserved in the database for audit purposes\n- The entry cannot be restored through the API (restoration would require database access)\n\n**Access control:**\n- Users with `Employees.edit` permission can delete any journal entry\n- Employees can delete their own entries (creator or subject)\n- Returns 404 if the entry does not exist, has already been deleted, or the user does not have access\n\n**Note:** This is a soft delete operation. The entry is not permanently removed and can potentially be recovered by database administrators if needed.","operationId":"EmployeesJournalController_deleteEmployeeJournal","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete employee journal entry","tags":["employees","journal","employees"],"x-required-scopes":["api:write"]}},"/employees/grid":{"get":{"description":"Returns a paginated, filterable, and sortable grid of all employees in the workspace.\n\n**What are Employees?**\nEmployees are internal team members from your own company. Each employee can have:\n- A user account with login access (if `canLogin` is true)\n- Team assignments for organizational structure\n- Employment details (entry/exit dates, employment mode, tax class)\n- Personal information (name, email, phone, address, birth date)\n- Professional details (position, title, degree)\n\n**What is returned:**\n- Employee identification (ID, name)\n- Contact information (email, phone, position, title, degree)\n- Complete address details (street, city, ZIP, country, house number)\n- Employment information (employment mode, entry date, exit date, income tax class)\n- Status information (isActive, canLogin, roleId)\n- Team assignments (teamIds array)\n- Personal details (birth date, avatar)\n- Timestamps (createdAt)\n\n**Filtering and search:**\n- Quick search across name, email, phone, position, and address fields\n- Advanced filtering by active status, employment mode, position, role, teams, and many other fields\n- Sorting by any sortable field (default: firstName ascending)\n- Server-side pagination for large employee lists\n\n**Note:** This endpoint requires the `Employees.manage` permission. The employees grid is separate from the contacts grid, which combines employees and organization members.","operationId":"EmployeesController_getEmployeesGrid","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page","schema":{"example":100,"type":"number"}},{"name":"viewId","required":false,"in":"query","description":"View identifier for saved grid configurations","schema":{"example":"all","type":"string"}},{"name":"quickSearch","required":false,"in":"query","description":"Quick search text. Searches across: firstName, lastName, email, phone, position, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber","schema":{"example":"contacts","type":"string"}},{"name":"filters","required":false,"in":"query","description":"JSON string containing filter configuration.\n\n**Available Fields:**\n- **id** (string): Employee ID\n- **firstName** (string): First name\n- **lastName** (string): Last name\n- **email** (string): Email address\n- **phone** (string): Phone number\n- **position** (string): Job position\n- **title** (string): Title (e.g., Dr., Prof.)\n- **degree** (string): Academic degree\n- **addressStreet** (string): Street address\n- **addressZip** (string): ZIP/Postal code\n- **addressCity** (string): City\n- **addressCountry** (string): Country\n- **addressHouseNumber** (string): House number\n- **employmentMode** (string): Employment mode (FullTime, Contract, Temporary, Freelance)\n- **entryDate** (date): Entry date\n- **exitDate** (date): Exit date\n- **incomeTaxClass** (string): Income tax class\n- **birthDate** (date): Birth date\n- **avatarId** (string): Avatar file ID\n- **isActive** (boolean): Whether employee is active (no exitDate or exitDate > today)\n- **canLogin** (boolean): Whether employee can login to the system\n- **roleId** (string): User role ID\n- **teamIds** (array): Team IDs (array)\n- **createdAt** (date): Creation timestamp\n\n**Filter Structure:**\n```json\n[\n {\n \"type\": \"string|number|date|set|boolean|array|task_status|task_type\",\n \"fieldName\": \"field_name\",\n \"value\": {\n \"comparison\": \"comparison_type\",\n \"value\": \"filter_value\"\n }\n }\n]\n```\n\n**Group Filters (AND/OR Combinations):**\n```json\n[\n {\n \"type\": \"group\",\n \"fieldName\": \"group0.18807479823070028\",\n \"value\": {\n \"type\": \"or\",\n \"filters\": [\n {\n \"type\": \"string\",\n \"fieldName\": \"fileName\",\n \"value\": {\n \"comparison\": \"contain\",\n \"value\": \"aa\"\n }\n },\n {\n \"type\": \"number\",\n \"fieldName\": \"rowCount\",\n \"value\": {\n \"comparison\": \">=\",\n \"value\": 33\n }\n }\n ]\n }\n }\n]\n```\n\n**Available Comparison Operators:**\n- **id** (string): Employee ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **firstName** (string): First name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **lastName** (string): Last name (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **email** (string): Email address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **phone** (string): Phone number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **position** (string): Job position (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **title** (string): Title (e.g., Dr., Prof.) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **degree** (string): Academic degree (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressStreet** (string): Street address (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressZip** (string): ZIP/Postal code (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCity** (string): City (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressCountry** (string): Country (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **addressHouseNumber** (string): House number (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **employmentMode** (string): Employment mode (FullTime, Contract, Temporary, Freelance) (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **entryDate** (date): Entry date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **exitDate** (date): Exit date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **incomeTaxClass** (string): Income tax class (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **birthDate** (date): Birth date (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n- **avatarId** (string): Avatar file ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **isActive** (boolean): Whether employee is active (no exitDate or exitDate > today) (boolean filter). Available comparisons: equal, not_equal\n- **canLogin** (boolean): Whether employee can login to the system (boolean filter). Available comparisons: equal, not_equal\n- **roleId** (string): User role ID (string filter). Available comparisons: contain, not_contain, equal, starts_with, ends_with, is_empty, is_not_empty\n- **teamIds** (array): Team IDs (array) (array filter). Available comparisons: in, not_in, is_empty, is_not_empty\n- **createdAt** (date): Creation timestamp (date filter). Available comparisons: equal, not_equal, >, <, >=, <=, between, lastMonth, thisMonth, is_empty, is_not_empty\n\n**Note:** Use `quickSearch` parameter for simple text search instead of adding it to filters.","schema":{"example":"[]","type":"string"}},{"name":"sort","required":false,"in":"query","description":"JSON array of sort objects.\n\n**Sortable Fields:**\n- **id**: Employee ID\n- **firstName**: First name\n- **lastName**: Last name\n- **name**: Full name (firstName + lastName, virtual field)\n- **position**: Job position\n- **addressCity**: City\n- **addressCountry**: Country\n- **employmentMode**: Employment mode (FullTime, Contract, Temporary, Freelance)\n- **entryDate**: Entry date\n- **exitDate**: Exit date\n- **birthDate**: Birth date\n- **isActive**: Whether employee is active (no exitDate or exitDate > today)\n- **canLogin**: Whether employee can login to the system\n- **createdAt**: Creation timestamp\n\n**Sort Structure:**\n```json\n[\n {\n \"field\": \"field_name\",\n \"direction\": \"asc|desc\"\n }\n]\n```\n\n**Default Sort:** firstName (asc)","schema":{"example":"[{\"field\":\"firstName\",\"direction\":\"asc\"}]","type":"string"}},{"name":"fieldsToReturn","required":false,"in":"query","description":"Comma-separated list of field names to include in response items. If not provided, all fields are returned.\n\n**Available Fields:** id, firstName, lastName, name, email, phone, position, title, degree, addressStreet, addressZip, addressCity, addressCountry, addressHouseNumber, employmentMode, entryDate, exitDate, incomeTaxClass, birthDate, avatarId, isActive, canLogin, roleId, teamIds, createdAt","schema":{"example":"id,firstName","type":"array","items":{}}}],"responses":{"200":{"description":"Successfully retrieved employees grid"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get employees grid","tags":["employees"],"x-required-scopes":["api:read"]}},"/employees/{id}/calendar-feed":{"get":{"description":"Returns the HTTPS URL for the employeeβs Leadtime calendar feed (.ics). Requires a linked user account on the employee.","operationId":"EmployeesController_getEmployeeCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarFeedConfigResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get employee calendar export (ICS subscription URL)","tags":["employees"],"x-required-scopes":["api:read"]}},"/employees/{id}/calendar-feed/regenerate":{"post":{"description":"Issues a new ICS subscription token; previous URLs stop working.","operationId":"EmployeesController_regenerateEmployeeCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarFeedConfigResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Regenerate employee calendar export URL","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/external-calendar-feeds":{"get":{"description":"Returns configured HTTPS ICS feeds that sync busy blocks into Leadtime for this employee.","operationId":"EmployeesController_listEmployeeExternalCalendarFeeds","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalCalendarFeedResponseDto"}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"List employee external calendar imports","tags":["employees"],"x-required-scopes":["api:read"]},"post":{"operationId":"EmployeesController_createEmployeeExternalCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeExternalCalendarFeedDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCalendarFeedResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Add external calendar feed for employee","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/external-calendar-feeds/{feedId}":{"patch":{"operationId":"EmployeesController_patchEmployeeExternalCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"feedId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchEmployeeExternalCalendarFeedDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCalendarFeedResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update employee external calendar feed","tags":["employees"],"x-required-scopes":["api:write"]},"delete":{"operationId":"EmployeesController_deleteEmployeeExternalCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"feedId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Remove employee external calendar feed","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/external-calendar-feeds/{feedId}/sync":{"post":{"operationId":"EmployeesController_syncEmployeeExternalCalendarFeed","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"feedId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCalendarFeedResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Sync employee external calendar feed now","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}":{"get":{"description":"Returns complete details for a specific employee, including all personal information, employment data, user account details, team assignments, and working conditions.\n\n**What is returned:**\n- All employee personal information (name, email, phone, address, birth date)\n- Professional details (position, title, degree)\n- Employment information (employment mode, entry date, exit date, income tax class)\n- User account details (userId, roleId, canLogin status)\n- Team assignments (array of team IDs)\n- Avatar URL (if avatar is set)\n- Status flags (isActive calculated from exitDate)\n- Working conditions (chargeableHoursDayGoal)\n- Weekly working time entries (array with dateFrom, workingDays, weeklyWorkingHours)\n- Salary entries (array with dateFrom, salary)\n- Vacation days entries (array with dateFrom, days)\n- Timestamps (createdAt, updatedAt)\n\n**Note:** Returns 404 if the employee does not exist or has been deleted.","operationId":"EmployeesController_getEmployeeDetails","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:read"]},{"bearer":[]}],"summary":"Get employee details","tags":["employees"],"x-required-scopes":["api:read"]},"patch":{"description":"Partially updates an existing employee. Only the fields you provide will be updated; all other fields remain unchanged.\n\n**How updates work:**\n- **Personal information** (firstName, lastName, email, phone, address, birth date, title, degree, position):\n - Updates the employee record\n - If email, firstName, or lastName changes, the associated user account is automatically synced\n- **Access settings** (canLogin, roleId):\n - Updates the user account permissions\n - If `canLogin` changes from `false` to `true`:\n - User account is created if it doesn't exist\n - User status becomes Active\n - An invitation email is sent automatically\n - If email is changed and a HelpdeskUser with that email exists, it will be upgraded to Employee type\n- **Team assignments** (teams):\n - Replaces the entire team assignment list\n - Provide an empty array to remove all team assignments\n- **Avatar** (avatarId):\n - Set to a file ID from POST /workspace/upload to update the avatar\n - Set to `null` to remove the avatar\n- **Working conditions** (chargeableHoursDayGoal):\n - Updates the chargeable (billable) hours per day goal\n - Used for time tracking targets and notifications\n - Set to `null` to remove the goal\n\n**Update process:**\n1. Verify the employee exists (returns 404 if not found)\n2. Update personal information if provided\n3. Update access settings if provided\n4. Update team assignments if provided\n5. Update working conditions if provided\n6. Return the updated employee with all current data\n\n**Note:** All updates are validated and will fail if validation rules are violated (e.g., email must be unique). The response includes the complete updated employee record.","operationId":"EmployeesController_updateEmployee","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchEmployeeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Update employee","tags":["employees"],"x-required-scopes":["api:write"]},"delete":{"description":"Soft deletes an employee and the associated user account. The employee is not permanently removed from the database, but marked as deleted with anonymized data.\n\n**What happens when deleting an employee:**\n1. Employee record is marked as deleted\n2. Associated user account is also marked as deleted\n3. Personal data is anonymized for privacy:\n - firstName and lastName are set to \"Deleted User\"\n - Email is anonymized\n - Other personal information is cleared\n4. Billing is automatically recalculated to reflect the removal\n5. The employee will no longer appear in employee lists or grids\n\n**Note:** This is a soft delete operation. The employee data remains in the database but is anonymized and hidden. This operation cannot be undone. Returns 404 if the employee does not exist.","operationId":"EmployeesController_deleteEmployee","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete employee","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees":{"post":{"description":"Creates a new employee in the workspace with automatic user account creation and team assignments.\n\n**How employee creation works:**\n1. A new employee record is created with the provided information\n2. If `canLogin` is `true`, a user account is automatically created:\n - User status is set to Active\n - An invitation email is sent to the employee\n - The user is assigned the specified role\n3. If an existing HelpdeskUser with the same email exists, it will be upgraded to Employee type\n4. Teams are assigned if provided in the `teams` array\n5. Employee data is automatically synced with the user account\n\n**Required fields:**\n- `firstName`: Employee first name\n- `lastName`: Employee last name\n- `email`: Unique email address (must not exist in the workspace)\n- `roleId`: Role ID to assign to the user account\n\n**Optional fields:**\n- `position`: Job title/position\n- `canLogin`: Whether employee can login (default: false)\n- `teams`: Array of team IDs to assign the employee to\n- `avatarId`: File ID from POST /workspace/upload endpoint\n\n**Avatar upload process:**\n1. First, upload the avatar file using POST /workspace/upload\n2. Get the file ID from the upload response\n3. Use that file ID in the `avatarId` field when creating the employee\n\n**Note:** The email address must be unique within the workspace. If `canLogin` is false, no user account is created initially, but one can be created later by updating the employee.","operationId":"EmployeesController_createEmployee","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"400":{"description":"Validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Bad Request"},"errors":{"type":"object","example":{"firstName":["First name is required"],"lastName":["Last name is required"],"email":["Email is required","Email must be valid"],"roleId":["Role ID is required"]}}}}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create employee","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/weekly-working-time":{"post":{"description":"Creates a new weekly working time entry or updates an existing one for an employee.\n\n**How it works:**\n- If `id` is provided in the request body, updates the existing entry with that ID\n- If `id` is omitted, creates a new entry\n\n**What is weekly working time?**\nWeekly working time defines the employee's work schedule:\n- `workingDays`: Array of 7 numbers (Monday=0, Sunday=6), where 1 means the employee works that day, 0 means they don't\n- `weeklyWorkingHours`: Total hours per week (maximum 168)\n- `dateFrom`: Date when this configuration starts applying\n\n**Active entry selection:**\n- The active entry for a given date is the one with the most recent `dateFrom` that is still on or before that date\n- If no entry exists for a date, no entry is considered active\n\n**Returns:** The updated employee object with all weekly working time entries.","operationId":"EmployeesController_createOrUpdateWeeklyWorkingTime","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrUpdateWeeklyWorkingTimeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create or update weekly working time entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/weekly-working-time/{entryId}":{"delete":{"description":"Deletes a weekly working time entry for an employee.\n\n**Returns:** The updated employee object with remaining weekly working time entries.","operationId":"EmployeesController_deleteWeeklyWorkingTime","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete weekly working time entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/salaries":{"post":{"description":"Creates a new salary entry or updates an existing one for an employee.\n\n**How it works:**\n- If `id` is provided in the request body, updates the existing entry with that ID\n- If `id` is omitted, creates a new entry\n- Each entry defines a monthly salary amount that applies from a specific date\n\n**Returns:** The updated employee object with all salary entries.","operationId":"EmployeesController_createOrUpdateSalary","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrUpdateSalaryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create or update salary entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/salaries/{entryId}":{"delete":{"description":"Deletes a salary entry for an employee.\n\n**Returns:** The updated employee object with remaining salary entries.","operationId":"EmployeesController_deleteSalary","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete salary entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/vacation-days":{"post":{"description":"Creates a new vacation days entry or updates an existing one for an employee.\n\n**How it works:**\n- If `id` is provided in the request body, updates the existing entry with that ID\n- If `id` is omitted, creates a new entry\n- Each entry defines vacation days per year that apply from a specific date\n\n**Returns:** The updated employee object with all vacation days entries.","operationId":"EmployeesController_createOrUpdateVacationDays","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrUpdateVacationDaysDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"400":{"description":"Validation errors"},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Create or update vacation days entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/employees/{id}/vacation-days/{entryId}":{"delete":{"description":"Deletes a vacation days entry for an employee.\n\n**Returns:** The updated employee object with remaining vacation days entries.","operationId":"EmployeesController_deleteVacationDays","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"entryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponseDto"}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token"},"403":{"description":"Forbidden - Insufficient API scopes or permissions"}},"security":[{"OAuth2":["api:write"]},{"bearer":[]}],"summary":"Delete vacation days entry","tags":["employees"],"x-required-scopes":["api:write"]}},"/automations/webhooks/{secret}":{"post":{"summary":"Trigger automation via webhook","description":"Unauthenticated inbound webhook for automation triggers. No Bearer token required. The secret is webhookSecret from a webhook trigger (returned in automation triggers after create/update). POST with Content-Type: application/json; request body is passed to the agent as context. Returns 202 with { \"accepted\": true } when the secret matches an enabled webhook trigger and the automation executor is eligible. Returns 202 with { \"accepted\": false } when the secret is valid but the executor is inactive or no longer in the workspace (no run is enqueued).","operationId":"AutomationWebhooks_handleWebhook","tags":["automations"],"parameters":[{"name":"secret","in":"path","required":true,"schema":{"type":"string"},"description":"webhookSecret from the automation trigger"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Arbitrary JSON; passed to the agent as webhook payload"}}}},"responses":{"202":{"description":"Request processed: accepted true if a run was enqueued; accepted false if the executor cannot run automations","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean","description":"True when the automation run was queued; false when the executor is ineligible"}}}}}},"404":{"description":"Webhook not found (invalid or disabled secret)"}},"servers":[{"url":"https://leadtime.app/api","description":"API base for webhook endpoints"}],"security":[]}}},"info":{"title":"Leadtime Public API","description":"Versioned public API.\n\nAuthentication:\n- Personal Access Tokens (PAT): Create/manage in your Profile β API Tokens. Use the raw token once returned to you as Bearer: `Authorization: Bearer `.\n- OAuth 2.0 (Authorization Code + PKCE): Workspace admin creates an OAuth client in Workspace Settings β API & Integrations, then obtain tokens via the standard OAuth flow. Use the access token as Bearer. Refresh tokens are supported at `/api/oauth/token`.\n\nDynamic Client Registration (RFC 7591):\nThe API supports RFC 7591 compliant dynamic client registration, allowing applications to register OAuth clients programmatically without requiring workspace admin setup.\n\n**Registration Endpoint**: `POST /api/oauth/register`\n\n**Features**:\n- Automatically creates OAuth clients with generated `client_id` and optional `client_secret`\n- Clients are auto-installed in workspaces when the API feature is enabled\n- Supports multiple authentication methods: `none` (public clients), `client_secret_post`, `client_secret_basic`\n- Idempotent registration: If a client with the same name and redirect URIs already exists, the existing client is updated instead of creating a duplicate\n- Returns RFC 7591 compliant registration response with client credentials and metadata\n\n**Request Body**:\n- `redirect_uris` (required): Array of redirect URIs for the client\n- `client_name` (optional): Display name for the client (defaults to \"Dynamically Registered Client\")\n- `client_uri` (optional): Homepage URL of the client application\n- `logo_uri` (optional): Logo URL for the client\n- `token_endpoint_auth_method` (optional): Authentication method (`none`, `client_secret_post`, or `client_secret_basic`, defaults to `none`)\n\n**Response**:\n- `client_id`: Unique client identifier (format: `dcr_`)\n- `client_secret`: Client secret (only returned for confidential clients, not for `none` auth method)\n- `client_name`: Client display name\n- `redirect_uris`: Array of allowed redirect URIs\n- `token_endpoint_auth_method`: Authentication method used\n- `grant_types`: Supported grant types (`authorization_code`, `refresh_token`)\n- `response_types`: Supported response types (`code`)\n- `client_id_issued_at`: Unix timestamp when client was created\n- `client_secret_expires_at`: Expiration timestamp (0 means no expiration)\n- `registration_client_uri`: URI for client registration management\n\n**Discovery**:\nThe registration endpoint URL is available via OAuth 2.0 Authorization Server Metadata at `/api/.well-known/oauth-authorization-server` (see `registration_endpoint` field).\n\nImposter Mode (Testing/Debugging):\nβ οΈ **Permission Required**: `PublicApi.allowImposterMode`\n\nOptional headers for testing and debugging (case-insensitive):\n- `LT_IMPOSTER_USER_ID` / `lt_imposter_user_id`: Override authenticated user with specified user ID. User must exist and belong to the same workspace. Original token permissions are preserved.\n- `LT_CUSTOM_NOW` / `lt_custom_now`: Override current time with custom date (ISO 8601 format). Useful for testing time-sensitive operations.\n\nExample:\n```\ncurl -X GET \"https://api.example.com/api/public/account/info\" \\\n -H \"Authorization: Bearer \" \\\n -H \"LT_IMPOSTER_USER_ID: user-123\" \\\n -H \"LT_CUSTOM_NOW: 2024-01-15T10:00:00Z\"\n```\n\nBase URL: https://leadtime.app/api/public","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"https://leadtime.app/api/public","description":"Leadtime Public API Server"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://leadtime.app/api/oauth/authorize","tokenUrl":"https://leadtime.app/api/oauth/token","refreshUrl":"https://leadtime.app/api/oauth/token","scopes":{"api:read":"api:read","api:write":"api:write"}}}}},"schemas":{"AccountInfoResponse":{"type":"object","properties":{"ok":{"type":"boolean","example":true,"description":"Operation success flag"},"userId":{"type":"string","example":"user_123","description":"Current user ID"},"workspaceId":{"type":"string","example":"workspace_456","description":"Current workspace ID"},"email":{"type":"string","example":"jane.doe@example.com"},"firstName":{"type":"object","example":"Jane","nullable":true},"lastName":{"type":"object","example":"Doe","nullable":true},"name":{"type":"string","example":"Jane Doe","description":"Convenience full name"},"type":{"type":"string","enum":["Employee","OrganizationMember","Bot","LeadtimeSupport","HelpdeskUser"],"description":"User type"},"roleId":{"type":"string","example":"role_abc"},"roleName":{"type":"string","example":"Admin"},"permissions":{"description":"Granted permission keys","type":"array","items":{"type":"string"}},"avatarUrl":{"type":"object","example":"https://app.example.com/api/files/public/avatar_123","nullable":true,"description":"Public URL for user avatar image"},"employeeId":{"type":"object","example":"emp_789","nullable":true,"description":"Employee ID if user is Employee"},"memberId":{"type":"object","example":null,"nullable":true,"description":"Organization member ID if user is OrganizationMember"},"source":{"type":"string","enum":["webapp","api_pat","api_oauth","mcp","agent"],"description":"Authentication source"},"language":{"type":"string","example":"en","description":"User preferred language"},"emailNotifications":{"type":"boolean","example":true,"description":"Email notifications enabled"},"userWorkspaceColor":{"type":"string","enum":["INHERIT","DEFAULT","BLACK","RED","ROSE","MAGENTA","GREEN","BLUE","YELLOW","VIOLET"],"description":"User workspace color preference"}},"required":["ok","userId","workspaceId","email","firstName","lastName","name","type","roleId","roleName","permissions","avatarUrl","employeeId","memberId","source","language","emailNotifications","userWorkspaceColor"]},"EmployeeDataResponse":{"type":"object","properties":{"id":{"type":"string","example":"emp_123","description":"Employee ID"},"firstName":{"type":"object","example":"John","nullable":true,"description":"First name"},"lastName":{"type":"object","example":"Doe","nullable":true,"description":"Last name"},"email":{"type":"object","example":"john.doe@example.com","nullable":true,"description":"Email address"},"title":{"type":"object","example":"Software Engineer","nullable":true,"description":"Job title"},"degree":{"type":"object","example":"Bachelor","nullable":true,"description":"Degree"},"addressStreet":{"type":"object","example":"Main Street","nullable":true,"description":"Street address"},"addressZip":{"type":"object","example":"12345","nullable":true,"description":"ZIP code"},"addressCity":{"type":"object","example":"Berlin","nullable":true,"description":"City"},"addressCountry":{"type":"object","example":"Germany","nullable":true,"description":"Country"},"addressHouseNumber":{"type":"object","example":"12","nullable":true,"description":"House number"},"phone":{"type":"object","example":"+49 123 456789","nullable":true,"description":"Phone number"},"birthDate":{"type":"object","example":"1990-01-01T00:00:00.000Z","nullable":true,"description":"Birth date"},"signatureUrl":{"type":"object","example":"https://app.example.com/api/files/public/signature_123","nullable":true,"description":"Signature file URL"}},"required":["id","firstName","lastName","email","title","degree","addressStreet","addressZip","addressCity","addressCountry","addressHouseNumber","phone","birthDate","signatureUrl"]},"UpdateWorkspaceColorRequest":{"type":"object","properties":{"color":{"type":"string","enum":["INHERIT","DEFAULT","BLACK","RED","ROSE","MAGENTA","GREEN","BLUE","YELLOW","VIOLET"],"description":"New workspace color"}},"required":["color"]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Operation success flag"}},"required":["success"]},"UpdateLanguageRequest":{"type":"object","properties":{"language":{"type":"string","example":"en","description":"Preferred language code","enum":["en","de"]}},"required":["language"]},"UpdateEmailNotificationsRequest":{"type":"object","properties":{"enabled":{"type":"boolean","example":true,"description":"Enable email notifications"}},"required":["enabled"]},"UpdateEmployeeDataRequest":{"type":"object","properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"title":{"type":"string"},"degree":{"type":"string"},"addressStreet":{"type":"string"},"addressZip":{"type":"string"},"addressCity":{"type":"string"},"addressCountry":{"type":"string","example":"US","description":"ISO 3166-1 alpha-2 country code (2 uppercase letters)"},"addressHouseNumber":{"type":"string"},"phone":{"type":"string"},"birthDate":{"type":"string","description":"ISO8601 date string"},"signatureFileId":{"type":"string","description":"File ID for signature (upload via POST /api/public/workspace/upload first)"},"avatarId":{"type":"object","description":"File ID for avatar (upload via POST /api/public/workspace/upload first). Set to null to remove avatar.","nullable":true}}},"BankDataResponse":{"type":"object","properties":{"id":{"type":"string","example":"emp_123","description":"Employee ID"},"bankAccountBIC":{"type":"object","example":"DEUTDEFF","nullable":true,"description":"Bank BIC code"},"bankAccountIBAN":{"type":"object","example":"DE89370400440532013000","nullable":true,"description":"Bank IBAN"},"bankAccountName":{"type":"object","example":"Deutsche Bank","nullable":true,"description":"Bank account name"},"bankAccountOwner":{"type":"object","example":"John Doe","nullable":true,"description":"Account owner name"}},"required":["id","bankAccountBIC","bankAccountIBAN","bankAccountName","bankAccountOwner"]},"UpdateBankDataRequest":{"type":"object","properties":{"bankAccountBIC":{"type":"object","example":"DEUTDEFF","description":"Bank BIC code"},"bankAccountIBAN":{"type":"object","example":"DE89370400440532013000","description":"Bank IBAN"},"bankAccountOwner":{"type":"object","example":"John Doe","description":"Account owner name"},"bankAccountName":{"type":"object","example":"Deutsche Bank","description":"Bank name"}}},"OrgMemberDataResponse":{"type":"object","properties":{"id":{"type":"string","example":"member_123","description":"Organization member ID"},"firstName":{"type":"object","example":"John","nullable":true,"description":"First name"},"lastName":{"type":"object","example":"Doe","nullable":true,"description":"Last name"},"email":{"type":"object","example":"john.doe@example.com","nullable":true,"description":"Email address"},"title":{"type":"object","example":"Software Engineer","nullable":true,"description":"Job title"},"degree":{"type":"object","example":"Bachelor","nullable":true,"description":"Degree"},"position":{"type":"object","example":"Senior Developer","nullable":true,"description":"Position"},"addressStreet":{"type":"object","example":"Main Street","nullable":true,"description":"Street address"},"addressZip":{"type":"object","example":"12345","nullable":true,"description":"ZIP code"},"addressCity":{"type":"object","example":"Berlin","nullable":true,"description":"City"},"addressCountry":{"type":"object","example":"Germany","nullable":true,"description":"Country"},"addressHouseNumber":{"type":"object","example":"12","nullable":true,"description":"House number"},"phone":{"type":"object","example":"+49 123 456789","nullable":true,"description":"Phone number"},"birthDate":{"type":"object","example":"1990-01-01T00:00:00.000Z","nullable":true,"description":"Birth date"}},"required":["id","firstName","lastName","email","title","degree","position","addressStreet","addressZip","addressCity","addressCountry","addressHouseNumber","phone","birthDate"]},"UpdateOrgMemberDataRequest":{"type":"object","properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"title":{"type":"string"},"degree":{"type":"string"},"position":{"type":"string"},"addressStreet":{"type":"string"},"addressZip":{"type":"string"},"addressCity":{"type":"string"},"addressCountry":{"type":"string","example":"DE","description":"ISO 3166-1 alpha-2 country code (2 uppercase letters)"},"addressHouseNumber":{"type":"string"},"phone":{"type":"string"},"birthDate":{"type":"string","description":"ISO8601 date string"},"avatarId":{"type":"object","description":"File ID for avatar (upload via POST /api/public/workspace/upload first). Set to null to remove avatar.","nullable":true}}},"FutureVacationResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"dateFrom":{"type":"string","example":"2024-06-01"},"dateTo":{"type":"string","example":"2024-06-05"},"status":{"type":"string","example":"Approved","enum":["Pending","Approved","Rejected"]}},"required":["id","dateFrom","dateTo","status"]},"VacationStatsResponse":{"type":"object","properties":{"year":{"type":"number","example":2024},"byContract":{"type":"number","example":25},"daysPeriods":{"example":[{"from":"2024-01-01T00:00:00.000Z","to":"2024-12-31T23:59:59.999Z","days":25}],"type":"array","items":{"type":"string"}},"pendingVacationDays":{"type":"number","example":5},"approvedFutureVacationDays":{"type":"number","example":10},"approvedPastVacationDays":{"type":"number","example":8},"fromOvertime":{"type":"number","example":2},"added":{"type":"number","example":0},"deducted":{"type":"number","example":0},"totalVacationDays":{"type":"number","example":27},"totalUsedVacationDays":{"type":"number","example":8},"totalRemainingVacationDays":{"type":"number","example":19},"potentialVacationDays":{"type":"number","example":3}},"required":["year","byContract","daysPeriods","pendingVacationDays","approvedFutureVacationDays","approvedPastVacationDays","fromOvertime","added","deducted","totalVacationDays","totalUsedVacationDays","totalRemainingVacationDays"]},"VacationHistoryResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"dateFrom":{"type":"string","example":"2024-06-01T00:00:00.000Z"},"dateTo":{"type":"string","example":"2024-06-05T00:00:00.000Z"},"status":{"type":"string","example":"Approved","enum":["Pending","Approved","Rejected"]},"employeeId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174001"},"statusChangedAt":{"type":"string","example":"2024-06-02T10:30:00.000Z","nullable":true},"statusChangedBy":{"type":"object","example":"John Doe","nullable":true},"reason":{"type":"object","example":"Family vacation","nullable":true}},"required":["id","dateFrom","dateTo","status","employeeId","statusChangedAt","statusChangedBy","reason"]},"VacationHistoryGridResponse":{"type":"object","properties":{"total":{"type":"number","example":50},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":10},"items":{"type":"array","items":{"$ref":"#/components/schemas/VacationHistoryResponse"}}},"required":["total","page","pageSize","items"]},"VacationCompensationResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"employeeId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174001"},"type":{"type":"string","example":"Overtime","enum":["Overtime","Unused","Bonus"]},"year":{"type":"number","example":2024},"toYear":{"type":"number","example":2025},"days":{"type":"number","example":5},"createdAt":{"type":"string","example":"2024-06-01T10:30:00.000Z"}},"required":["id","employeeId","type","year","toYear","days","createdAt"]},"VacationCompensationGridResponse":{"type":"object","properties":{"total":{"type":"number","example":25},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":10},"items":{"type":"array","items":{"$ref":"#/components/schemas/VacationCompensationResponse"}}},"required":["total","page","pageSize","items"]},"RequestVacationDto":{"type":"object","properties":{"dateFrom":{"format":"date-time","type":"string","example":"2024-06-01T00:00:00.000Z","description":"Start date of vacation"},"dateTo":{"format":"date-time","type":"string","example":"2024-06-05T00:00:00.000Z","description":"End date of vacation"}},"required":["dateFrom","dateTo"]},"SicknessRowResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"dateFrom":{"type":"string","example":"2024-06-01T00:00:00.000Z"},"dateTo":{"type":"string","example":"2024-06-03T00:00:00.000Z"},"employeeId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174001"},"comment":{"type":"object","example":"Flu symptoms","nullable":true},"attachedFilesIds":{"example":["file1.pdf","file2.jpg"],"type":"array","items":{"type":"string"}}},"required":["id","dateFrom","dateTo","employeeId","comment","attachedFilesIds"]},"SicknessGridResponse":{"type":"object","properties":{"total":{"type":"number","example":15},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":10},"items":{"type":"array","items":{"$ref":"#/components/schemas/SicknessRowResponse"}}},"required":["total","page","pageSize","items"]},"RequestSicknessDto":{"type":"object","properties":{"dateFrom":{"type":"string","example":"2024-06-01T00:00:00.000Z","description":"Start date of sickness"},"dateTo":{"type":"string","example":"2024-06-03T00:00:00.000Z","description":"End date of sickness"},"comment":{"type":"string","example":"Flu symptoms","description":"Optional comment about the sickness"},"attachedFilesIds":{"description":"Array of file IDs for medical certificates (upload via POST /api/public/workspace/upload first)","type":"array","items":{"type":"string"}}},"required":["dateFrom","dateTo"]},"JournalEntryResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"type":"string","example":"2024-06-01T10:30:00.000Z"},"createdBy":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174001","description":"ID of the user who created the journal entry"},"mood":{"type":"object","example":"Happy","description":"Mood of the journal entry"},"reminder":{"type":"object","example":"2024-06-15T09:00:00.000Z","description":"Reminder date"},"body":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n
\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under
. Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n"}},"required":["id","createdAt","createdBy","body"]},"JournalGridResponse":{"type":"object","properties":{"items":{"description":"Array of journal entries","type":"array","items":{"$ref":"#/components/schemas/JournalEntryResponse"}},"total":{"type":"number","example":150,"description":"Total number of journal entries"},"page":{"type":"number","example":1,"description":"Current page number"},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"viewId":{"type":"string","example":"default","description":"View ID for the grid"}},"required":["items","total","page","pageSize"]},"CreateJournalDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000","description":"Journal entry ID for updates"},"mood":{"type":"string","example":"Happy","enum":["Sad","Neutral","Happy"],"description":"Mood of the journal entry"},"reminder":{"type":"string","example":"2024-06-15T09:00:00.000Z","description":"Reminder date"},"body":{"type":"string","example":"Today was a great day!
","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n
\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under
. Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n"}},"required":["body"]},"PatchJournalDto":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000","description":"Journal entry ID for updates"},"mood":{"type":"string","example":"Happy","enum":["Sad","Neutral","Happy"],"description":"Mood of the journal entry"},"reminder":{"type":"string","example":"2024-06-15T09:00:00.000Z","description":"Reminder date"},"body":{"type":"string","example":"Today was a great day!
","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n
\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under
. Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n"}}},"UpdateVacationRequest":{"type":"object","properties":{"dateFrom":{"type":"string","example":"2024-06-01T00:00:00.000Z","description":"Vacation start date"},"dateTo":{"type":"string","example":"2024-06-05T00:00:00.000Z","description":"Vacation end date"}},"required":["dateFrom","dateTo"]},"UpdateSicknessRequest":{"type":"object","properties":{"dateFrom":{"type":"string","example":"2024-06-01T00:00:00.000Z","description":"Sickness start date"},"dateTo":{"type":"string","example":"2024-06-05T00:00:00.000Z","description":"Sickness end date"},"comment":{"type":"string","example":"Flu symptoms","description":"Comment about the sickness"},"attachedFilesIds":{"example":["file-id-1","file-id-2"],"description":"Array of attached file IDs","type":"array","items":{"type":"string"}}},"required":["dateFrom","dateTo","attachedFilesIds"]},"OvertimeStatsResponse":{"type":"object","properties":{"startDate":{"format":"date-time","type":"string","example":"2023-01-01T00:00:00.000Z","description":"Start date of employment"},"workingSince":{"format":"date-time","type":"string","example":"2023-01-15T00:00:00.000Z","description":"Date when employee started working"},"totalHoursLogged":{"type":"number","example":1750.5,"description":"Total hours logged"},"totalCompensatedHours":{"type":"number","example":50,"description":"Total compensated hours"},"workingHours":{"type":"number","example":1600,"description":"Expected working hours"},"workingDays":{"type":"number","example":200,"description":"Total working days"},"vacationThisYearHours":{"type":"number","example":80,"description":"Vacation hours taken this year"},"paidThisYearHours":{"type":"number","example":40,"description":"Paid vacation hours this year"},"unpaidThisYearHours":{"type":"number","example":40,"description":"Unpaid vacation hours this year"},"vacationDaysThisYear":{"type":"number","example":10,"description":"Vacation days taken this year"},"balance":{"type":"number","example":100.5,"description":"Current overtime balance in hours"}},"required":["startDate","workingSince","totalHoursLogged","totalCompensatedHours","workingHours","workingDays","vacationThisYearHours","paidThisYearHours","unpaidThisYearHours","vacationDaysThisYear","balance"]},"OvertimeCompensationResponse":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000","description":"Compensation record ID"},"employeeId":{"type":"string","example":"emp_789","description":"Employee ID"},"type":{"type":"string","example":"PAID","description":"Compensation type"},"hours":{"type":"number","example":8,"description":"Number of hours compensated"},"vacationYear":{"type":"object","example":2024,"nullable":true,"description":"Vacation year if applicable"},"vacationDays":{"type":"object","example":1,"nullable":true,"description":"Number of vacation days if applicable"},"createdAt":{"format":"date-time","type":"string","example":"2024-03-15T10:30:00.000Z","description":"Compensation creation date"}},"required":["id","employeeId","type","hours","vacationYear","vacationDays","createdAt"]},"OvertimeCompensationGridResponse":{"type":"object","properties":{"total":{"type":"number","example":25},"page":{"type":"number","example":1},"pageSize":{"type":"number","example":10},"items":{"type":"array","items":{"$ref":"#/components/schemas/OvertimeCompensationResponse"}}},"required":["total","page","pageSize","items"]},"ClaimAgentConnectorSetupDto":{"type":"object","properties":{"setupToken":{"type":"string","description":"One-time setup token generated from the bot settings page.","example":"lt_conn_abc123"},"gatewayPublicUrl":{"type":"string","description":"Public OpenClaw/Hermes gateway URL reachable by Leadtime for webhook delivery.","example":"https://agent.example.com"},"agentId":{"type":"string","description":"Runtime-specific agent id to attach this Leadtime bot to.","example":"main"},"runtimeVersion":{"type":"string","description":"Connector/runtime version reported by the installer.","example":"openclaw-leadtime-plugin@0.1.0"}},"required":["setupToken","gatewayPublicUrl"]},"AppendAgentSessionActivityDto":{"type":"object","properties":{"activityType":{"type":"string","enum":["thought","action","elicitation","response","error","prompt","log","modelRequest","modelResponse","toolCall","toolResult"]},"body":{"type":"string"},"action":{"type":"string"},"parameter":{"type":"string"},"result":{"type":"string"},"providerEventId":{"type":"string"},"providerEventType":{"type":"string"},"raw":{"type":"object"},"idempotencyKey":{"type":"string"}},"required":["activityType","body"]},"UpdateAgentSessionStatusDto":{"type":"object","properties":{"status":{"type":"string","enum":["queued","running","waitingInput","waitingApproval","done","failed","canceled"]},"message":{"type":"string"},"idempotencyKey":{"type":"string"}},"required":["status"]},"ToggleFavoriteRequestDto":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier (UUID) of the entity to favorite or unfavorite. This is the ID of the task, project, organization, or command you want to toggle.","example":"550e8400-e29b-41d4-a716-446655440000"},"entityType":{"type":"string","description":"The type of entity being favorited. Determines which entity table to check and what metadata to return. Valid values: Project, Task, Organization, Command.","enum":["Project","Task","Organization","Command"],"example":"Task"}},"required":["entityId","entityType"]},"ToggleFavoriteResponseDto":{"type":"object","properties":{"isFavorite":{"type":"boolean","description":"Whether the entity is now favorited after the toggle operation. True means the entity was added to favorites, false means it was removed.","example":true}},"required":["isFavorite"]},"FavoritesListResponseDto":{"type":"object","properties":{"favorites":{"description":"Array of all favorites for the authenticated user, sorted by custom sort order (if set) or creation date. Each favorite includes entity-specific metadata. Deleted entities are automatically excluded from the results.","items":{"type":"array"},"type":"array"}},"required":["favorites"]},"FormCategoryTranslationResponseDto":{"type":"object","properties":{"language":{"type":"string"},"name":{"type":"object","nullable":true},"description":{"type":"object","nullable":true}},"required":["language"]},"FormCategoryResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"object","nullable":true},"sort":{"type":"number"},"defaultKey":{"type":"object","nullable":true},"translations":{"type":"array","items":{"$ref":"#/components/schemas/FormCategoryTranslationResponseDto"}}},"required":["id","name","icon","sort","translations"]},"FormCategoryTranslationRequestDto":{"type":"object","properties":{"language":{"type":"string","example":"en"},"name":{"type":"object","nullable":true},"description":{"type":"object","nullable":true}},"required":["language"]},"CreateFormCategoryDto":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string","example":":clipboard:"},"description":{"type":"object","nullable":true},"translations":{"type":"array","items":{"$ref":"#/components/schemas/FormCategoryTranslationRequestDto"}}},"required":["name","icon","translations"]},"UpdateFormCategoryDto":{"type":"object","properties":{"name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"object","nullable":true},"translations":{"type":"array","items":{"$ref":"#/components/schemas/FormCategoryTranslationRequestDto"}}}},"SortFormCategoriesDto":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]},"SortFormTemplatesDto":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]},"FormTemplateFieldResponseDto":{"type":"object","properties":{"id":{"type":"string"},"templateId":{"type":"string"},"sort":{"type":"number"},"key":{"type":"object","nullable":true,"description":"When set, this string is the `valueKey` for PATCH `/tasks/{identifier}/form-instances/{formInstanceId}` payloads; when null, use the field `id` instead."},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url","SectionHeading","FileUpload","Signature","Radio"]},"placeholder":{"type":"object","nullable":true},"helpText":{"type":"object","nullable":true},"required":{"type":"boolean"},"settings":{"type":"object","description":"Type-specific settings JSON"},"selectOptions":{"type":"array","items":{"type":"object"},"description":"Options for Select, MultiSelect, Radio"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","templateId","sort","label","description","type","required","settings","selectOptions","createdAt","updatedAt"]},"SortFormTemplateFieldsDto":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]},"CreateFormTemplateFieldDto":{"type":"object","properties":{"sort":{"type":"number"},"key":{"type":"object","nullable":true},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url","SectionHeading","FileUpload","Signature","Radio"]},"placeholder":{"type":"object","nullable":true},"helpText":{"type":"object","nullable":true},"required":{"type":"boolean"},"settings":{"type":"object"},"selectOptions":{"type":"array","items":{"type":"object"}}},"required":["label","type"]},"UpdateFormTemplateFieldDto":{"type":"object","properties":{"sort":{"type":"number"},"key":{"type":"object","nullable":true},"label":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url","SectionHeading","FileUpload","Signature","Radio"]},"placeholder":{"type":"object","nullable":true},"helpText":{"type":"object","nullable":true},"required":{"type":"boolean"},"settings":{"type":"object"},"selectOptions":{"type":"array","items":{"type":"object"}}}},"FormTemplateListItemResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"categoryId":{"type":"string"},"tags":{"description":"Assigned form-template tag IDs (UUIDs).","type":"array","items":{"type":"string"}},"icon":{"type":"object","nullable":true},"sort":{"type":"number"},"fieldsCount":{"type":"number","description":"Number of non-deleted fields on this template."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"createdBy":{"type":"string"},"updatedBy":{"type":"object","nullable":true},"category":{"type":"object"}},"required":["id","name","description","categoryId","tags","sort","fieldsCount","createdAt","updatedAt","createdBy","category"]},"FormTemplateDetailResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"categoryId":{"type":"string"},"tags":{"description":"Assigned form-template tag IDs (UUIDs).","type":"array","items":{"type":"string"}},"icon":{"type":"object","nullable":true},"sort":{"type":"number"},"fieldsCount":{"type":"number","description":"Number of non-deleted fields on this template."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"createdBy":{"type":"string"},"updatedBy":{"type":"object","nullable":true},"category":{"type":"object"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormTemplateFieldResponseDto"}}},"required":["id","name","description","categoryId","tags","sort","fieldsCount","createdAt","updatedAt","createdBy","category","fields"]},"CreateFormTemplateDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"categoryId":{"type":"string"},"tags":{"description":"Tag IDs (UUIDs) of type form-template. List or create tags via GET/POST `tags/form-template/list` and `tags/form-template/create`.","type":"array","items":{"type":"string"}},"icon":{"type":"object","nullable":true}},"required":["name","categoryId"]},"UpdateFormTemplateDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"categoryId":{"type":"string"},"tags":{"description":"Tag IDs (UUIDs) of type form-template. List tags via GET `tags/form-template/list`.","type":"array","items":{"type":"string"}},"icon":{"type":"object","nullable":true}}},"AttendanceRequestDto":{"type":"object","properties":{"date":{"type":"string","description":"Date of the workday in ISO 8601 format (YYYY-MM-DD). This is the date for which attendance is being recorded.","example":"2025-01-15"},"timeFrom":{"type":"string","description":"Clock-in time (start of work) in HH:mm format (24-hour format). This is when the employee started working. Example: \"09:00\" for 9 AM, \"13:30\" for 1:30 PM.","example":"09:00","pattern":"^([0-1][0-9]|2[0-3]):[0-5][0-9]$"},"timeTo":{"type":"string","description":"Clock-out time (end of work) in HH:mm format (24-hour format). Optional - if not provided, you can clock out later. Must be after timeFrom if provided. Example: \"17:30\" for 5:30 PM.","example":"17:30","pattern":"^([0-1][0-9]|2[0-3]):[0-5][0-9]$"},"mood":{"type":"string","description":"Employee mood for the workday. Indicates how the employee felt during the day: Good (positive), Neutral (normal), or Bad (challenging).","enum":["Good","Neutral","Bad"],"example":"Good"},"comment":{"type":"string","description":"Optional notes or comments about the workday. Can include information about the work performed, special circumstances, or any relevant details.","example":"Regular workday"}},"required":["date","timeFrom","mood"]},"AttendanceResponseDto":{"type":"object","properties":{"date":{"type":"string","description":"Date of the attendance record","example":"2025-01-15T00:00:00.000Z"},"timeFrom":{"type":"string","description":"Clock-in time (when work started). ISO 8601 datetime format. Null if not yet clocked in.","example":"1970-01-01T09:00:00.000Z","nullable":true},"timeTo":{"type":"string","description":"Clock-out time (when work ended). ISO 8601 datetime format. Null if not yet clocked out.","example":"1970-01-01T17:30:00.000Z","nullable":true},"totalHours":{"type":"number","description":"Total hours worked, automatically calculated from clock-in and clock-out times. Null if end time is not yet recorded.","example":8.5,"nullable":true},"mood":{"type":"string","description":"Employee mood for the workday (Good, Neutral, or Bad). Indicates how the employee felt during the day.","enum":["Good","Neutral","Bad"],"example":"Good","nullable":true},"comment":{"type":"string","description":"Optional notes or comments about the workday. Can include information about work performed or special circumstances.","example":"Regular workday","nullable":true},"type":{"type":"string","description":"Type of attendance record. Indicates the nature of the workday (e.g., Workday, Holiday, etc.).","enum":["Workday","Vacation","VacationPending","Sick","Away"],"example":"Workday"},"deletedAt":{"type":"string","description":"Deletion timestamp (null if not deleted)","example":null,"nullable":true}},"required":["date","timeFrom","timeTo","totalHours","mood","comment","type","deletedAt"]},"DeleteAttendanceRequestDto":{"type":"object","properties":{"date":{"type":"string","description":"Date of the attendance record to delete in ISO 8601 format (YYYY-MM-DD). The attendance record for this date will be permanently deleted.","example":"2025-01-15"}},"required":["date"]},"CreateWorkspaceProviderApiKeyDto":{"type":"object","properties":{"provider":{"type":"string","enum":["cursorCloud","claudeManaged"]},"apiKey":{"type":"string","description":"Raw provider API key to save securely."},"label":{"type":"string","nullable":true}},"required":["provider","apiKey"]},"CreateWorkspaceAgentSkillDto":{"type":"object","properties":{"name":{"type":"string","description":"Skill slug used in SKILL.md frontmatter. Lowercase letters, numbers, and hyphens only.","example":"invoice-analysis"},"displayTitle":{"type":"string","description":"Human-readable skill title shown in Leadtime."},"description":{"type":"string","description":"Short description used for skill discovery. Maximum 1024 characters."},"body":{"type":"string","description":"Markdown instructions loaded when the skill is activated."}},"required":["name","displayTitle","description","body"]},"CreateBotDto":{"type":"object","properties":{"name":{"type":"string","description":"Bot display name.","example":"Company Manager"},"roleId":{"type":"string","description":"Role id to assign. Defaults to the workspace Bot role."},"connectionProvider":{"type":"string","enum":["selfHosted","claudeManaged","cursorCloud","geminiManaged","geminiAgentRuntime","native"],"description":"Optional hosted-agent connection provider to initialize: selfHosted, cursorCloud, or claudeManaged."}},"required":["name"]},"SetPublicBotStatusDto":{"type":"object","properties":{}},"SetPublicBotConnectionProviderDto":{"type":"object","properties":{}},"UpdatePublicBotAgentSettingsDto":{"type":"object","properties":{}},"SetPublicBotConnectionEnabledDto":{"type":"object","properties":{}},"SavePublicCursorCloudBotSettingsDto":{"type":"object","properties":{}},"ValidatePublicCursorCloudConnectionDto":{"type":"object","properties":{}},"ClaudeManagedMcpOAuthCredentialDto":{"type":"object","properties":{"accessToken":{"type":"string","nullable":true},"refreshToken":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true},"tokenEndpoint":{"type":"string","nullable":true},"tokenEndpointAuthType":{"type":"string","enum":["none","client_secret_basic","client_secret_post"],"nullable":true},"scope":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"clientSecret":{"type":"string","nullable":true}}},"ClaudeManagedMcpServerDto":{"type":"object","properties":{"id":{"type":"string","description":"Stable local id for an existing MCP row."},"name":{"type":"string","description":"Display name for the MCP server. If omitted, Leadtime derives one from the URL."},"url":{"type":"string","description":"Hosted MCP server URL."},"authMode":{"type":"string","enum":["none","bearer","oauth"],"description":"Authentication mode for this MCP server."},"bearerToken":{"type":"string","nullable":true,"description":"Bearer token to store for bearer-token MCP servers."},"credentialConfigured":{"type":"boolean","description":"Whether Leadtime already has a stored credential for this MCP server."},"oauthCredential":{"nullable":true,"description":"OAuth credential details for an OAuth MCP server.","allOf":[{"$ref":"#/components/schemas/ClaudeManagedMcpOAuthCredentialDto"}]}},"required":["url"]},"ClaudeManagedSkillRefDto":{"type":"object","properties":{"type":{"type":"string","enum":["anthropic","custom"]},"skillId":{"type":"string","description":"Anthropic built-in skill id (for example xlsx) or Leadtime workspace skill id for custom skills."},"version":{"type":"string","nullable":true,"description":"Optional Anthropic skill version. Defaults to latest when omitted."}},"required":["type","skillId"]},"ClaudeManagedLeadtimeManagedAgentDto":{"type":"object","properties":{"instructions":{"oneOf":[{"type":"string"},{"type":"object"}],"description":"Standard Leadtime editor field for managed Claude agent instructions. Accepts Markdown, HTML, or ProseMirror IDoc JSON (object or JSON string); Leadtime converts it to internal IDoc before storing and syncing the rendered HTML to Claude.\n\nUse only the nodes and marks documented below for this field.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n"},"modelId":{"type":"string","example":"claude-sonnet-4-6","description":"Claude model id from the bot settings model cache/resources refresh, for example claude-sonnet-4-6 or claude-opus-4-8."},"mcpServers":{"description":"Custom hosted MCP servers to attach to this Claude agent.","type":"array","items":{"$ref":"#/components/schemas/ClaudeManagedMcpServerDto"}},"skills":{"description":"Skills attached to this Leadtime-managed Claude agent. Maximum 20. Only supported when agentSource is leadtimeManaged.","type":"array","items":{"$ref":"#/components/schemas/ClaudeManagedSkillRefDto"}}}},"ClaudeManagedGithubRepositoryDto":{"type":"object","properties":{"id":{"type":"number","description":"GitHub repository id."},"name":{"type":"string","description":"Repository short name."},"fullName":{"type":"string","description":"Repository full name, for example owner/repo."},"url":{"type":"string","description":"GitHub web URL."},"cloneUrl":{"type":"string","nullable":true,"description":"Repository clone URL."},"private":{"type":"boolean","description":"Whether the GitHub repository is private."}},"required":["id","name","fullName","url","cloneUrl","private"]},"ClaudeManagedBotConfigDto":{"type":"object","properties":{"agentSource":{"type":"string","enum":["leadtimeManaged","existing"],"description":"Use leadtimeManaged when Leadtime should create and repair the Claude agent, environment, and vault."},"agentId":{"type":"string","nullable":true,"description":"Existing Anthropic agent id when agentSource is existing."},"environmentId":{"type":"string","nullable":true,"description":"Existing Anthropic environment id when agentSource is existing."},"userVaultIds":{"description":"Additional user-managed Claude vault ids to attach to sessions.","type":"array","items":{"type":"string"}},"toolMode":{"type":"string","enum":["basic","full"],"description":"Leadtime MCP tool set exposed to Claude task sessions."},"exposeRawApiCredentialToAgent":{"type":"boolean","description":"Expose a raw Leadtime API credential to the agent for trusted automation."},"customGuidance":{"type":"string","nullable":true,"description":"Extra guidance appended to Leadtime task-session instructions."},"managedAgent":{"description":"Leadtime-managed Claude agent configuration. Put modelId, instructions, and mcpServers here.","allOf":[{"$ref":"#/components/schemas/ClaudeManagedLeadtimeManagedAgentDto"}]},"githubRepositoryDefaults":{"description":"Default GitHub repositories mounted into Claude coding sessions for this bot.","type":"array","items":{"$ref":"#/components/schemas/ClaudeManagedGithubRepositoryDto"}}}},"SavePublicClaudeManagedBotSettingsDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable or disable this bot connection."},"providerApiKeyId":{"type":"string","nullable":true,"description":"Saved Anthropic provider API key id to use for this bot."},"anthropicApiKey":{"type":"string","nullable":true,"description":"Raw Anthropic API key. Prefer providerApiKeyId when a saved key exists."},"config":{"description":"Claude Managed configuration. Put model changes under config.managedAgent.modelId and GitHub defaults under config.githubRepositoryDefaults.","allOf":[{"$ref":"#/components/schemas/ClaudeManagedBotConfigDto"}]}}},"ValidatePublicClaudeManagedConnectionDto":{"type":"object","properties":{"providerApiKeyId":{"type":"string","nullable":true,"description":"Saved Anthropic provider API key id to validate."},"anthropicApiKey":{"type":"string","nullable":true,"description":"Raw Anthropic API key to validate."}}},"PublicClaudeManagedMcpOAuthConnectUrlDto":{"type":"object","properties":{"server":{"$ref":"#/components/schemas/ClaudeManagedMcpServerDto"}},"required":["server"]},"SaveProjectAgentProviderSettingsDto":{"type":"object","properties":{}},"ValidateProjectAgentProviderSettingsDto":{"type":"object","properties":{}},"ManualPositionCategoryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique category identifier. A UUID that uniquely identifies this category within the workspace. Use this ID when assigning the category to manual positions or when updating/deleting the category.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Category name. The display name of the category as it appears in the application. This is the name that will be shown when the category is assigned to manual positions in offers and invoices.","example":"Development"}},"required":["id","name"]},"CreateOrUpdateManualPositionCategoryDto":{"type":"object","properties":{"id":{"type":"string","description":"Category identifier (UUID). When provided, updates the existing category with this ID. When omitted or set to `null`, creates a new category. Must be a valid UUID format if provided.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Category name. A descriptive label for organizing manual positions. Examples: \"Development\", \"Consulting\", \"Travel Expenses\", \"External Services\", \"Licenses\". Must be a non-empty string. Category names are case-sensitive and can be used across all projects in the workspace.","example":"Development"}},"required":["name"]},"WorkspaceDetailsResponse":{"type":"object","properties":{"id":{"type":"string","example":"workspace_456","description":"Unique identifier for the workspace. Used to reference the workspace in other API endpoints."},"domain":{"type":"string","example":"company-domain","description":"Workspace domain/subdomain identifier. Used in workspace URLs and API routing."},"companyName":{"type":"string","example":"Acme Corp","description":"Company or organization name associated with the workspace. This is the display name shown throughout the application."},"isBillingLocked":{"type":"boolean","example":false,"description":"Indicates whether the workspace is locked due to past due billing status. When true, certain workspace operations may be restricted until billing issues are resolved."},"attendanceEnabled":{"type":"boolean","example":false,"description":"Indicates whether attendance tracking (clock in/out) is enabled for the workspace AND the current user is an Employee type. This field is false if attendance is disabled or if the current user is not an Employee."},"isHelpdeskEnabled":{"type":"boolean","example":true,"description":"Indicates whether the helpdesk feature is enabled for the workspace. When enabled, the workspace can use ticket-based support workflows."},"features":{"type":"array","description":"Array of all enabled workspace features. Includes both currently active features and features that are still available but not yet activated. Features define what functionality is available in the workspace.","items":{"type":"string","enum":["HELPDESK","API","AGENT"]}},"workspaceLanguage":{"type":"string","example":"en","description":"Default language code for the workspace (e.g., \"en\" for English, \"de\" for German). This setting applies to new users; individual users can override this in their profile settings."},"sprintStartDay":{"type":"number","example":1,"description":"Day of the week when sprints/pipeline periods start. 1 = Monday, 2 = Tuesday, ..., 7 = Sunday. Used for capacity planning and pipeline views."},"sprintPeriodDays":{"type":"number","example":14,"description":"Duration of sprint/pipeline periods in days. Typically 7 (one week) or 14 (two weeks). Defines the time span for capacity planning in the pipeline view."},"mainWorkspaceColor":{"type":"string","enum":["DEFAULT","BLACK","RED","ROSE","MAGENTA","GREEN","BLUE","YELLOW","VIOLET"],"description":"Main accent color theme for the workspace interface. Options include Default, Black, Red, Pink, Magenta, Green, Blue, Yellow, Purple. This color affects navigation elements, buttons, and active states throughout the application."},"logoUrl":{"type":"object","example":"https://app.example.com/api/files/public/logo_123","nullable":true,"description":"Public URL for the workspace logo image used in light mode. This logo appears in the top left corner of the workspace above the navigation. Null if no logo has been uploaded. Recommended format: PNG with transparent background, ideal size 1000x260 pixels."},"logoDarkThemeUrl":{"type":"object","example":"https://app.example.com/api/files/public/logo_dark_456","nullable":true,"description":"Public URL for the workspace logo image used in dark mode. This logo appears when users have dark theme enabled. Null if no dark theme logo has been uploaded. Recommended format: PNG with transparent background, ideal size 1000x260 pixels."},"branding":{"type":"object","description":"Workspace branding settings including custom brand color. The brandColor field (if set) is a HEX color code that matches the company brand and is used for internal projects in various views of the application."},"customIcons":{"description":"Array of custom icons available in the workspace. Custom icons are user-uploaded images (PNG or SVG) that can be used to visually tag tickets, projects, documents, or other entities. Each icon has a unique name (e.g., \":team_sales:\") and an associated image file ID.","type":"array","items":{"type":"string"}}},"required":["id","domain","companyName","isBillingLocked","attendanceEnabled","isHelpdeskEnabled","features","workspaceLanguage","sprintStartDay","sprintPeriodDays","mainWorkspaceColor","logoUrl","logoDarkThemeUrl","branding","customIcons"]},"ObjectStatusDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"sort":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","color","sort","createdAt"]},"ObjectCustomFieldInTypeDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"sort":{"type":"number"},"objectTypeId":{"type":"string"},"showInList":{"type":"boolean"},"showInHeader":{"type":"boolean"},"selectOptions":{"type":"array"},"translations":{"type":"array"}},"required":["id","name","description","type","sort","objectTypeId","showInList","showInHeader","selectOptions","translations"]},"ObjectTypeDetailResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"object","nullable":true},"sort":{"type":"number"},"createdAt":{"type":"string"},"statuses":{"type":"array","items":{"$ref":"#/components/schemas/ObjectStatusDto"}},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/ObjectCustomFieldInTypeDto"}}},"required":["id","name","slug","icon","sort","createdAt","statuses","customFields"]},"WorkspaceObjectSettingsResponseDto":{"type":"object","properties":{"objectTypes":{"description":"All non-deleted object types with nested statuses and per-type custom field definitions (read-only bundle for forms and integrations).","type":"array","items":{"$ref":"#/components/schemas/ObjectTypeDetailResponseDto"}}},"required":["objectTypes"]},"FileUploadResponse":{"type":"object","properties":{"id":{"type":"string","example":"file_123","description":"Unique file identifier. Use this ID to reference the file in other API endpoints that accept file references (e.g., when setting workspace logos, user avatars, or custom icons)."},"filename":{"type":"string","example":"logo.png","description":"Original filename of the uploaded file as provided by the client. This is preserved for reference but may differ from the stored filename."},"mimetype":{"type":"string","example":"image/png","description":"MIME type of the uploaded file (e.g., \"image/png\", \"image/jpeg\", \"image/svg+xml\"). Indicates the file format and how it should be processed or displayed."},"size":{"type":"number","example":1024,"description":"File size in bytes. Use this to validate file size limits or display file size information to users."},"url":{"type":"string","example":"https://app.example.com/api/files/public/file_123","description":"Public URL that can be used to access the file directly. This URL can be embedded in HTML, shared, or used in API responses. The file is accessible without authentication through this URL."}},"required":["id","filename","mimetype","size","url"]},"WorkspaceUserDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the user. Use this ID to reference the user in other API endpoints or when assigning tasks, projects, or other entities to users."},"name":{"type":"string","description":"Full display name of the user, constructed from firstName and lastName. This is the name shown in user lists, dropdowns, and throughout the application interface."},"avatarId":{"type":"object","description":"File ID of the user avatar image. Use this ID with the file API to retrieve the avatar image URL. Null if no avatar has been uploaded for this user."},"position":{"type":"string","description":"Job title or position of the user within the workspace or organization. This field may be empty for users who do not have a position set."},"employeeId":{"type":"object","description":"Employee ID associated with this user, if the user is an Employee type. This links the user to their employee record which contains additional employee-specific information. Null if the user is not an Employee or does not have an associated employee record."},"userType":{"type":"string","enum":["Employee","OrganizationMember","Bot","LeadtimeSupport","HelpdeskUser"],"description":"Type of user account. Options: Employee (internal workspace employee), OrganizationMember (external organization member), LeadtimeSupport (Leadtime support staff). The user type determines what features and data the user can access."},"canLogin":{"type":"boolean","description":"Indicates whether the user account is active and can log in to the workspace. False if the user account is inactive, suspended, or otherwise unable to authenticate."},"isDeleted":{"type":"boolean","description":"Indicates whether the user account has been soft-deleted. Deleted users are typically hidden from active user lists but may still be included in responses depending on the includeDeleted query parameter."},"botSystemKey":{"type":"object","description":"System bot provider key for bot users, such as cursorCloud or claudeManaged. Null for human users and generic self-hosted bots.","nullable":true}},"required":["id","name","position","userType","canLogin","isDeleted"]},"QuickSearchResultDto":{"type":"object","properties":{"title":{"type":"string","description":"Display title or name of the entity. This is the primary text shown in search results and is what the search term matched against.","example":"Project Alpha"},"type":{"type":"string","description":"Type of entity that was found. Indicates which kind of workspace resource this result represents. Use this to determine how to handle or display the result in your application.","enum":["employee","organization","organizationMember","workspace","project","task","team","contact"],"example":"project"},"meta":{"type":"object","description":"Entity metadata object containing the entity ID and additional type-specific fields. The id field is always present and can be used to fetch full entity details. Other fields vary by entity type (e.g., projectId for tasks, organizationId for projects).","example":{"id":"uuid","projectId":"uuid","organizationId":"uuid"}},"color":{"type":"string","description":"Color associated with the entity, typically in HEX format (e.g., \"#ff0000\"). Used for visual identification in lists, kanban boards, and other UI components. May be null if the entity type does not support colors.","example":"#ff0000"},"icon":{"type":"object","description":"Icon identifier for the entity, typically a FontAwesome icon class name (e.g., \"faSquare\", \"faUser\"). Used for visual representation in UI components. May be null if no icon is set for the entity.","example":"faSquare","nullable":true},"shortName":{"type":"object","description":"Short name or code for the entity, often used for quick identification (e.g., \"ORG-001\", \"PRJ-123\"). This is a human-readable identifier that may be displayed alongside the title. May be null if the entity type does not use short names.","example":"ORG-001","nullable":true}},"required":["title","type","meta"]},"ProductListItemDto":{"type":"object","properties":{"id":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000","description":"Unique identifier for the product. Use this ID to reference the product in other API endpoints or when adding the product to projects or tasks."},"name":{"type":"string","example":"Premium Software License","description":"Display name of the product. This is the name shown in product lists, dropdowns, and when the product is added to projects or tasks."},"categoryId":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440001","description":"Identifier of the product category this product belongs to. Categories help organize products in the catalog and can be used for filtering or grouping."},"logoId":{"type":"object","example":"550e8400-e29b-41d4-a716-446655440002","nullable":true,"description":"File ID of the product logo image. Use this ID with the file API to retrieve the logo image URL. Null if no logo has been uploaded for this product."},"priceFixed":{"type":"object","example":5000,"nullable":true,"description":"Fixed one-time price for the product, typically in the smallest currency unit (e.g., cents for USD). Null if this product does not have a fixed price. Products can have multiple pricing types (fixed, subscription, per-unit) or just one."},"priceSubscription":{"type":"object","example":25,"nullable":true,"description":"Recurring subscription price for the product, typically in the smallest currency unit per billing period (e.g., cents for USD). Null if this product does not have subscription pricing. Used for products that are billed on a recurring basis."},"pricePerUnit":{"type":"object","example":150,"nullable":true,"description":"Per-unit price for the product, typically in the smallest currency unit (e.g., cents for USD). Null if this product does not have per-unit pricing. Used when the product price depends on quantity."}},"required":["id","name","categoryId","logoId","priceFixed","priceSubscription","pricePerUnit"]},"WorkspaceFormTemplatesResponseDto":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/FormCategoryResponseDto"}},"templates":{"type":"array","items":{"$ref":"#/components/schemas/FormTemplateListItemResponseDto"}}},"required":["categories","templates"]},"DocumentTemplateApiResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the document template (UUID)","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"The name/title of the document template","example":"Project Contract Template"},"description":{"type":"string","description":"A brief description explaining the purpose or use case of this template","example":"Standard contract template for project agreements"},"language":{"type":"string","description":"ISO 639-1 language code for the template (e.g., \"en\", \"de\")","example":"en"},"type":{"type":"string","description":"The type of document this template generates","enum":["ProjectDocument"],"example":"ProjectDocument"},"content":{"type":"string","description":"Template content as HTML. The content includes static text, formatting, and variable placeholders. Variables are represented as HTML spans: `...`. The content may also include conditional sections and page breaks.","example":"Project Contract
Project: Website Redesign
"},"workspaceId":{"type":"string","description":"The workspace ID this template belongs to","example":"123e4567-e89b-12d3-a456-426614174000"},"createdAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp when the template was created","example":"2024-01-15T10:30:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp when the template was last updated","example":"2024-01-20T14:45:00Z"},"createdBy":{"type":"string","description":"User ID of the user who created this template","example":"123e4567-e89b-12d3-a456-426614174000"},"updatedBy":{"type":"object","description":"User ID of the user who last updated this template (null if never updated)","example":"123e4567-e89b-12d3-a456-426614174000","nullable":true},"documentCustomVariables":{"description":"Array of custom variables defined for this template. Custom variables extend beyond standard system variables and allow template-specific placeholders. Each variable includes its type, default value (if any), options (for Select/MultiSelect), and whether it is required when generating documents from this template.","example":[{"id":"var-123","name":"client_name","description":"Client company name","type":"Text","value":"Acme Corp","options":[],"required":true}],"type":"array","items":{"type":"object"}}},"required":["id","name","description","language","type","content","workspaceId","createdAt","updatedAt","createdBy","updatedBy","documentCustomVariables"]},"DocumentCustomVariableDto":{"type":"object","properties":{"id":{"type":"string","description":"Variable ID (UUID). Only required when updating an existing variable. Omit when creating a new variable.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Variable name/key used to reference this variable in the template content. Use lowercase with underscores (e.g., \"client_name\", \"project_budget\"). This name is used in the variable reference: custom.variable_name.","example":"client_name"},"description":{"type":"string","description":"Human-readable label/description for this variable. This is displayed to users when they are prompted to fill in the variable value when generating a document.","example":"Client Company Name"},"type":{"type":"string","description":"The data type of this variable. Determines what kind of input is expected and how the value is validated. Available types: Text (short text), LongText (multi-line text), Number (numeric value), Date (date/time), Boolean (true/false), Select (single choice from options), MultiSelect (multiple choices from options).","enum":["Text","LongText","Number","Date","Boolean","Select","MultiSelect"],"example":"Text"},"value":{"description":"Default value for this variable. The type of value depends on the variable type: - Text/LongText/Select: string\n- Number: number\n- Boolean: boolean\n- Date: ISO 8601 date string (e.g., \"2024-01-15\")\n- MultiSelect: array of strings\n\nThis value is pre-filled when generating a document, but users can override it.","example":"Acme Corp","oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}]},"options":{"description":"Available options for Select or MultiSelect variable types. For Select, users choose one option. For MultiSelect, users can choose multiple options. This field is ignored for other variable types.","example":["Option 1","Option 2","Option 3"],"type":"array","items":{"type":"string"}},"required":{"type":"boolean","description":"Whether this variable must be filled in when generating a document from the template. If true, users cannot proceed without providing a value. If false, the variable is optional.","example":false,"default":false}},"required":["name","type"]},"CreateDocumentTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name/title of the document template. This is displayed in the templates list and when selecting a template.","example":"Project Contract Template"},"description":{"type":"string","description":"A brief description explaining the purpose or use case of this template. Helps users understand when to use this template.","example":"Standard contract template for project agreements with custom payment terms"},"language":{"type":"string","description":"ISO 639-1 language code for the template (e.g., \"en\" for English, \"de\" for German). Determines which language version of the template is used.","example":"en"},"type":{"type":"string","description":"The type of document this template generates. Currently only \"ProjectDocument\" is available, which is used for generating project-related documents.","enum":["ProjectDocument"],"example":"ProjectDocument"},"content":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array }.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n\n\n## Available Template Variables\n\nYou can use the following variables in your document templates. Variables are represented as HTML spans:\n\n**workspace**: `workspace.vat`, `workspace.hourRate`, `workspace.invoiceDaysTillOverdue`, `workspace.standardReminderFee`, `workspace.baseInterestRate`, `workspace.interestRate`\n**company**: `company.companyName`, `company.legalForm`, `company.country`, `company.zip`, `company.city`, `company.street`, `company.houseNumber`, `company.phone`, `company.email`, `company.website`, `company.fax`, `company.taxNumber`, `company.registrationNumber`, `company.registrationCourt`\n**organization**: `organization.companyName`, `organization.shortName`, `organization.legalForm`, `organization.description`, `organization.country`, `organization.zip`, `organization.city`, `organization.street`, `organization.houseNumber`, `organization.phone`, `organization.email`, `organization.website`, `organization.fax`, `organization.taxNumber`, `organization.registrationNumber`, `organization.registrationCourt`, `organization.hourRate`, `organization.invoiceDaysTillOverdue`, `organization.standardReminderFee`, `organization.baseInterestRate`, `organization.interestRate`\n**project**: `project.name`, `project.category`, `project.status`, `project.defaultAccountable`, `project.country`, `project.projectId`, `project.activeVersionId`, `project.activeVersionName`\n**currentUser**: `currentUser.title`, `currentUser.degree`, `currentUser.email`, `currentUser.firstName`, `currentUser.lastName`, `currentUser.country`, `currentUser.zip`, `currentUser.city`, `currentUser.street`, `currentUser.houseNr`, `currentUser.birthday`, `currentUser.phone`, `currentUser.signature`\n**recipient**: `recipient.firstName`, `recipient.lastName`, `recipient.position`, `recipient.gender`, `recipient.title`, `recipient.degree`, `recipient.birthdate`, `recipient.activeVersionName`, `recipient.country`, `recipient.zip`, `recipient.city`, `recipient.street`, `recipient.houseNumber`, `recipient.phone`, `recipient.email`, `recipient.socialNetwork`\n**macros**: `macros.todaysDate`, `macros.dearCustomer`\n\n**Example HTML**: `John`, `Website Redesign`","example":"Project Overview
Created by John for Website Redesign.
"},"customVariables":{"description":"Custom variables define template-specific placeholders that extend beyond standard system variables. Each variable can be referenced in the template content using `...` syntax. When generating a document from this template, users will be prompted to fill in these values. Variables support different types (Text, Number, Date, Boolean, Select, MultiSelect) and can be marked as required.","example":[{"name":"client_name","description":"Client company name","type":"Text","value":"Acme Corporation","required":true},{"name":"project_budget","description":"Project budget in USD","type":"Number","value":50000,"required":false}],"type":"array","items":{"$ref":"#/components/schemas/DocumentCustomVariableDto"}}},"required":["name","description","language","type","content"]},"UpdateDocumentTemplateDto":{"type":"object","properties":{"name":{"type":"string","description":"The name/title of the document template. This is displayed in the templates list and when selecting a template.","example":"Project Contract Template"},"description":{"type":"string","description":"A brief description explaining the purpose or use case of this template. Helps users understand when to use this template.","example":"Standard contract template for project agreements with custom payment terms"},"language":{"type":"string","description":"ISO 639-1 language code for the template (e.g., \"en\" for English, \"de\" for German). Determines which language version of the template is used.","example":"en"},"type":{"type":"string","description":"The type of document this template generates. Currently only \"ProjectDocument\" is available, which is used for generating project-related documents.","enum":["ProjectDocument"],"example":"ProjectDocument"},"content":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array }.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n\n\n## Available Template Variables\n\nYou can use the following variables in your document templates. Variables are represented as HTML spans:\n\n**workspace**: `workspace.vat`, `workspace.hourRate`, `workspace.invoiceDaysTillOverdue`, `workspace.standardReminderFee`, `workspace.baseInterestRate`, `workspace.interestRate`\n**company**: `company.companyName`, `company.legalForm`, `company.country`, `company.zip`, `company.city`, `company.street`, `company.houseNumber`, `company.phone`, `company.email`, `company.website`, `company.fax`, `company.taxNumber`, `company.registrationNumber`, `company.registrationCourt`\n**organization**: `organization.companyName`, `organization.shortName`, `organization.legalForm`, `organization.description`, `organization.country`, `organization.zip`, `organization.city`, `organization.street`, `organization.houseNumber`, `organization.phone`, `organization.email`, `organization.website`, `organization.fax`, `organization.taxNumber`, `organization.registrationNumber`, `organization.registrationCourt`, `organization.hourRate`, `organization.invoiceDaysTillOverdue`, `organization.standardReminderFee`, `organization.baseInterestRate`, `organization.interestRate`\n**project**: `project.name`, `project.category`, `project.status`, `project.defaultAccountable`, `project.country`, `project.projectId`, `project.activeVersionId`, `project.activeVersionName`\n**currentUser**: `currentUser.title`, `currentUser.degree`, `currentUser.email`, `currentUser.firstName`, `currentUser.lastName`, `currentUser.country`, `currentUser.zip`, `currentUser.city`, `currentUser.street`, `currentUser.houseNr`, `currentUser.birthday`, `currentUser.phone`, `currentUser.signature`\n**recipient**: `recipient.firstName`, `recipient.lastName`, `recipient.position`, `recipient.gender`, `recipient.title`, `recipient.degree`, `recipient.birthdate`, `recipient.activeVersionName`, `recipient.country`, `recipient.zip`, `recipient.city`, `recipient.street`, `recipient.houseNumber`, `recipient.phone`, `recipient.email`, `recipient.socialNetwork`\n**macros**: `macros.todaysDate`, `macros.dearCustomer`\n\n**Example HTML**: `John`, `Website Redesign`","example":"Project Overview
Created by John for Website Redesign.
"},"customVariables":{"description":"Custom variables define template-specific placeholders that extend beyond standard system variables. Each variable can be referenced in the template content using `...` syntax. When generating a document from this template, users will be prompted to fill in these values. Variables support different types (Text, Number, Date, Boolean, Select, MultiSelect) and can be marked as required.","example":[{"name":"client_name","description":"Client company name","type":"Text","value":"Acme Corporation","required":true},{"name":"project_budget","description":"Project budget in USD","type":"Number","value":50000,"required":false}],"type":"array","items":{"$ref":"#/components/schemas/DocumentCustomVariableDto"}}},"required":["name","description","language","type","content"]},"PatchDocumentTemplateDto":{"type":"object","properties":{"content":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array }.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n\n\n## Available Template Variables\n\nYou can use the following variables in your document templates. Variables are represented as HTML spans:\n\n**workspace**: `workspace.vat`, `workspace.hourRate`, `workspace.invoiceDaysTillOverdue`, `workspace.standardReminderFee`, `workspace.baseInterestRate`, `workspace.interestRate`\n**company**: `company.companyName`, `company.legalForm`, `company.country`, `company.zip`, `company.city`, `company.street`, `company.houseNumber`, `company.phone`, `company.email`, `company.website`, `company.fax`, `company.taxNumber`, `company.registrationNumber`, `company.registrationCourt`\n**organization**: `organization.companyName`, `organization.shortName`, `organization.legalForm`, `organization.description`, `organization.country`, `organization.zip`, `organization.city`, `organization.street`, `organization.houseNumber`, `organization.phone`, `organization.email`, `organization.website`, `organization.fax`, `organization.taxNumber`, `organization.registrationNumber`, `organization.registrationCourt`, `organization.hourRate`, `organization.invoiceDaysTillOverdue`, `organization.standardReminderFee`, `organization.baseInterestRate`, `organization.interestRate`\n**project**: `project.name`, `project.category`, `project.status`, `project.defaultAccountable`, `project.country`, `project.projectId`, `project.activeVersionId`, `project.activeVersionName`\n**currentUser**: `currentUser.title`, `currentUser.degree`, `currentUser.email`, `currentUser.firstName`, `currentUser.lastName`, `currentUser.country`, `currentUser.zip`, `currentUser.city`, `currentUser.street`, `currentUser.houseNr`, `currentUser.birthday`, `currentUser.phone`, `currentUser.signature`\n**recipient**: `recipient.firstName`, `recipient.lastName`, `recipient.position`, `recipient.gender`, `recipient.title`, `recipient.degree`, `recipient.birthdate`, `recipient.activeVersionName`, `recipient.country`, `recipient.zip`, `recipient.city`, `recipient.street`, `recipient.houseNumber`, `recipient.phone`, `recipient.email`, `recipient.socialNetwork`\n**macros**: `macros.todaysDate`, `macros.dearCustomer`\n\n**Example HTML**: `John`, `Website Redesign`","example":"Project Overview
Created by John for Website Redesign.
"},"customVariables":{"description":"Custom variables define template-specific placeholders that extend beyond standard system variables. Each variable can be referenced in the template content using `...` syntax. When generating a document from this template, users will be prompted to fill in these values. Variables support different types (Text, Number, Date, Boolean, Select, MultiSelect) and can be marked as required. If provided, the entire custom variables array replaces the existing one.","example":[{"name":"client_name","description":"Client company name","type":"Text","value":"Acme Corporation","required":true},{"name":"project_budget","description":"Project budget in USD","type":"Number","value":50000,"required":false}],"type":"array","items":{"$ref":"#/components/schemas/DocumentCustomVariableDto"}}},"required":["content"]},"AutomationApiResponse":{"type":"object","properties":{"id":{"type":"string","description":"Automation ID"},"workspaceId":{"type":"string","description":"Workspace ID"},"title":{"type":"string","description":"Automation title"},"executionType":{"type":"string","description":"Execution type","enum":["agent","workflow"]},"userPrompt":{"type":"object","description":"User prompt for agent (HTML, automation prompt format: basic nodes, mentions, images; no files or videos)","nullable":true},"executionConfig":{"type":"object","description":"Execution config"},"scope":{"type":"string","description":"Scope","enum":["personal","workspace"]},"ownerUserId":{"type":"object","description":"Owner user ID (for personal scope)","nullable":true},"executorUserId":{"type":"string","description":"Executor user ID"},"isEnabled":{"type":"boolean","description":"Whether automation is enabled"},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Creator user ID"},"updatedBy":{"type":"object","description":"Last updater user ID","nullable":true},"triggers":{"type":"array","description":"Triggers. For type webhook, webhookSecret is present after save; use POST {base}/api/automations/webhooks/{webhookSecret} to run. For type slackMessageInPublicChannel, definition contains channelId (Slack Cβ¦) and optional textPattern/useRegex.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["daily","weekly","monthly","customCron","webhook","organizationCreated","projectCreated","taskCreated","objectCreated","slackMessageInPublicChannel"]},"isEnabled":{"type":"boolean"},"sortOrder":{"type":"number"},"definition":{"type":"object"},"webhookSecret":{"type":"string","nullable":true,"description":"Only for webhook triggers. Present after save. Inbound webhook: POST {base}/api/automations/webhooks/{webhookSecret} with Content-Type: application/json. No auth; secret authenticates. Request body is passed to the agent as context."}}}}},"required":["id","workspaceId","title","executionType","userPrompt","executionConfig","scope","ownerUserId","executorUserId","isEnabled","createdAt","updatedAt","createdBy","updatedBy","triggers"]},"AutomationTriggerDto":{"type":"object","properties":{"type":{"type":"string","description":"Trigger variant: daily, weekly, monthly, customCron, webhook, organizationCreated, projectCreated, taskCreated, objectCreated, or slackMessageInPublicChannel. slackMessageInPublicChannel fires on new messages in a monitored **public** Slack channel; the workspace must have Slack connected and the bot must be in that channel.","enum":["daily","weekly","monthly","customCron","webhook","organizationCreated","projectCreated","taskCreated","objectCreated","slackMessageInPublicChannel"],"example":"daily"},"isEnabled":{"type":"boolean","description":"Whether the trigger is enabled","example":true},"sortOrder":{"type":"number","description":"Sort order for multiple triggers","example":0},"definition":{"type":"object","description":"Per-trigger settings. **slackMessageInPublicChannel** β required `channelId`: Slack **public channel ID** (`Cβ¦`), not the human-readable name. Optional `textPattern` (message must contain this substring, case-insensitive) and `useRegex` (if true, `textPattern` is a JavaScript regex). Example: `{\"channelId\":\"C012ABCDE\",\"textPattern\":\"bug\",\"useRegex\":false}`. On run, the agent receives `triggerEventPayload.slack`: `channelId`, `channelType`, `userId`, `text`, `ts`, `threadTs` β use with Slack integration tools to reply in-thread (`threadTs ?? ts`) and add/remove reactions on `ts`. **organizationCreated / projectCreated / taskCreated / objectCreated** β optional `filters` (FilterStripModel). Field names and `value` shapes must match the **list grid** for that entity: use `action-details` on **`GET /tasks/grid`** for `taskCreated`, **`GET /projects`** for `projectCreated`, **`GET /organizations`** for `organizationCreated`, internal **`GET β¦/objects/grid`** for `objectCreated` (not interchangeable). For event triggers, `definition.filters` must be a full FilterStripModel object such as `{\"quickSearch\":\"\",\"filters\":[...]}`. **Schedules** β timeOfDay (HH:mm), weekday (0-6), dayOfMonth (1-31), cronExpression (customCron). **webhook** β no required fields.","example":{"channelId":"C012ABCDE","textPattern":"bug","useRegex":false}}},"required":["type"]},"CreateAutomationDto":{"type":"object","properties":{"title":{"type":"string","description":"Automation title","example":"Daily standup reminder"},"executionType":{"type":"string","description":"Execution type (agent or workflow). Currently only agent is supported.","enum":["agent","workflow"],"example":"agent"},"userPrompt":{"type":"object","description":"User prompt for agent (HTML or Markdown). Automation prompt format: basic nodes, mentions, images; no files or videos.","example":"Summarize yesterday progress
","nullable":true},"executionConfig":{"type":"object","description":"Execution config (agent-specific or workflow metadata). Not used for trigger matching filters; event trigger filters belong in `triggers[].definition.filters`.","example":{}},"scope":{"type":"string","description":"Scope (personal or workspace). Personal requires managePersonalAutomations; workspace requires manageWorkspaceAutomations.","enum":["personal","workspace"],"example":"personal"},"executorUserId":{"type":"string","description":"User ID of the executor (current user or a bot)","example":"123e4567-e89b-12d3-a456-426614174000"},"isEnabled":{"type":"boolean","description":"Whether the automation is enabled","example":true},"triggers":{"description":"Triggers (daily, weekly, monthly, customCron, webhook, organizationCreated, projectCreated, taskCreated, objectCreated, slackMessageInPublicChannel). At least one required. For webhook, POST JSON to {WORKC_URL}/api/automations/webhooks/{webhookSecret} (no auth). For slackMessageInPublicChannel, see definition.channelId (Slack public channel ID) and optional text filters in AutomationTriggerDto. For event triggers, filters belong inside `triggers[].definition.filters`, not `executionConfig`.","type":"array","items":{"$ref":"#/components/schemas/AutomationTriggerDto"}}},"required":["title","executionType","userPrompt","executionConfig","scope","executorUserId","triggers"]},"UpdateAutomationDto":{"type":"object","properties":{"title":{"type":"string","description":"Automation title","example":"Daily standup reminder"},"executionType":{"type":"string","description":"Execution type (agent or workflow). Currently only agent is supported.","enum":["agent","workflow"],"example":"agent"},"userPrompt":{"type":"object","description":"User prompt for agent (HTML or Markdown). Automation prompt format: basic nodes, mentions, images; no files or videos.","example":"Summarize yesterday progress
","nullable":true},"executionConfig":{"type":"object","description":"Execution config (agent-specific or workflow metadata). Not used for trigger matching filters; event trigger filters belong in `triggers[].definition.filters`.","example":{}},"scope":{"type":"string","description":"Scope (personal or workspace). Personal requires managePersonalAutomations; workspace requires manageWorkspaceAutomations.","enum":["personal","workspace"],"example":"personal"},"executorUserId":{"type":"string","description":"User ID of the executor (current user or a bot)","example":"123e4567-e89b-12d3-a456-426614174000"},"isEnabled":{"type":"boolean","description":"Whether the automation is enabled","example":true},"triggers":{"description":"Triggers (daily, weekly, monthly, customCron, webhook, organizationCreated, projectCreated, taskCreated, objectCreated, slackMessageInPublicChannel). At least one required. For webhook, POST JSON to {WORKC_URL}/api/automations/webhooks/{webhookSecret} (no auth). For slackMessageInPublicChannel, see definition.channelId (Slack public channel ID) and optional text filters in AutomationTriggerDto. For event triggers, filters belong inside `triggers[].definition.filters`, not `executionConfig`.","type":"array","items":{"$ref":"#/components/schemas/AutomationTriggerDto"}}},"required":["title","executionType","userPrompt","executionConfig","scope","executorUserId","triggers"]},"TestRunAutomationDto":{"type":"object","properties":{}},"AutomationRunCreatedResponse":{"type":"object","properties":{"id":{"type":"string","description":"Created run ID"},"automationId":{"type":"string","description":"Automation ID"},"status":{"type":"string","description":"Run status (queued)"}},"required":["id","automationId","status"]},"AutomationRunApiResponse":{"type":"object","properties":{"id":{"type":"string","description":"Run ID"},"automationId":{"type":"string","description":"Automation ID"},"cause":{"type":"string","description":"Run cause (triggerFired, testRun)"},"status":{"type":"string","description":"Run status (queued, running, done, failed, canceled)"},"executionType":{"type":"string","description":"Execution type"},"executorUserId":{"type":"string","description":"Executor user ID"},"requestedByUserId":{"type":"object","description":"Requested by user ID","nullable":true},"agentRunId":{"type":"object","description":"Agent run ID when linked","nullable":true},"failureKind":{"type":"object","description":"Failure classification (technical or agentReported) when status is failed","nullable":true},"resultSummary":{"type":"object","description":"Outcome summary reported by the agent","nullable":true},"resultPayload":{"type":"object","description":"Structured result payload from the agent","nullable":true},"testContextDoc":{"type":"object","description":"Optional test context snapshot used for this run","nullable":true},"firedAt":{"format":"date-time","type":"string","description":"When the run was fired"},"startedAt":{"type":"object","description":"When execution started","nullable":true},"finishedAt":{"type":"object","description":"When execution finished","nullable":true},"metadata":{"type":"object","description":"Run metadata"},"messages":{"type":"array","description":"Agent transcript messages when agentRunId is linked (id, role, parts)","items":{"type":"object"}}},"required":["id","automationId","cause","status","executionType","executorUserId","requestedByUserId","agentRunId","failureKind","resultSummary","resultPayload","testContextDoc","firedAt","startedAt","finishedAt","metadata"]},"IProductVariantApiResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the variant"},"name":{"type":"string","description":"Name of the variant (e.g., \"Standard\", \"Pro\", \"Enterprise\")"},"descriptionHtml":{"type":"object","description":"Variant description converted to HTML format. Null if no description is set.","nullable":true},"priceSubscription":{"type":"number","description":"Recurring subscription price for this variant"},"priceFixed":{"type":"number","description":"One-time fixed price for this variant"},"pricePerUnit":{"type":"number","description":"Price per unit for this variant"},"isActivated":{"type":"boolean","description":"Whether this variant is currently activated and available for selection"}},"required":["id","name","descriptionHtml","priceSubscription","priceFixed","pricePerUnit","isActivated"]},"IProductApiResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the product"},"name":{"type":"string","description":"Name of the product or service"},"descriptionHtml":{"type":"string","description":"Product description converted to HTML format for easy display"},"categoryId":{"type":"string","description":"UUID of the product category this product belongs to"},"logoId":{"type":"object","description":"File ID of the product logo. Null if no logo is set.","nullable":true},"logoUrl":{"type":"object","description":"Public URL to access the product logo image. Constructed from logoId if a logo is set. Null if no logo is available.","nullable":true},"priceFixed":{"type":"number","description":"One-time fixed price for the product"},"priceSubscription":{"type":"number","description":"Recurring subscription price for the product"},"pricePerUnit":{"type":"number","description":"Price per unit for quantity-based billing"},"priceUnitName":{"type":"object","description":"Name of the unit for per-unit pricing (e.g., \"user\", \"hour\"). Null if per-unit pricing is not used.","nullable":true},"priceFrequency":{"type":"object","description":"Billing frequency in months (1, 3, 6, or 12). Null if subscription or per-unit pricing is not used.","nullable":true},"variants":{"description":"List of all product variants with their pricing and descriptions","type":"array","items":{"$ref":"#/components/schemas/IProductVariantApiResponse"}},"options":{"description":"List of all product options with their values and configurations. Structure matches ProductOptionApiDto but with additional internal fields.","type":"array","items":{"type":"string"}}},"required":["id","name","descriptionHtml","categoryId","logoId","logoUrl","priceFixed","priceSubscription","pricePerUnit","priceUnitName","priceFrequency","variants","options"]},"ProductVariantApiDto":{"type":"object","properties":{"id":{"type":"string","description":"Variant ID. Include this when updating an existing variant. Omit when creating a new variant."},"name":{"type":"string","description":"Name of the variant (e.g., \"Standard\", \"Pro\", \"Enterprise\"). Used to distinguish different performance levels or configurations of the same product."},"description":{"type":"object","description":"Variant description explaining what this variant includes or offers. Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n
\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\n
link text example\n```\n\n**bold**\nAtts: none\n```html\n
bold text example\n```\n\n**code**\nAtts: none\n```html\n
code text example\n```\n\n**italic**\nAtts: none\n```html\n
italic text example\n```\n\n**strike**\nAtts: none\n```html\n
strike text example\n```\n\n**underline**\nAtts: none\n```html\n
underline text example\n```\n","nullable":true},"priceFixed":{"type":"object","description":"One-time fixed price for this variant. Use this for one-time purchases (e.g., hardware, installation). Can be combined with subscription or per-unit pricing.","nullable":true,"example":999.99},"priceSubscription":{"type":"object","description":"Recurring subscription price for this variant. Use this for recurring revenue models (e.g., monthly SaaS subscription). The billing frequency is set at the product level via priceFrequency.","nullable":true,"example":29.99},"pricePerUnit":{"type":"object","description":"Price per unit for this variant. Use this for flexible billing by quantity (e.g., per user, per hour, per license). Requires priceUnitName to be set at the product level.","nullable":true,"example":5}},"required":["name","description"]},"ProductOptionValueApiDto":{"type":"object","properties":{"id":{"type":"string","description":"Option value ID. Include this when updating an existing option value. Omit when creating a new option value."},"name":{"type":"string","description":"Name of the option value (e.g., \"Add workshop\", \"Enable premium support\", \"Extra 10GB storage\"). This is what customers see when selecting options."},"extraPriceFixed":{"type":"object","description":"Additional one-time fixed price added when this option value is selected. Use this for one-time add-ons or upgrades.","nullable":true,"example":50},"extraPriceSubscription":{"type":"object","description":"Additional recurring subscription price added when this option value is selected. Use this for recurring add-ons (e.g., monthly premium support).","nullable":true,"example":10},"extraPricePerUnit":{"type":"object","description":"Additional per-unit price added when this option value is selected. Use this for quantity-based add-ons.","nullable":true,"example":2.5}},"required":["name"]},"ProductOptionApiDto":{"type":"object","properties":{"id":{"type":"string","description":"Option ID. Include this when updating an existing option. Omit when creating a new option."},"name":{"type":"string","description":"Name of the option group (e.g., \"Additional Services\", \"Storage Options\", \"Support Level\"). This groups related option values together."},"values":{"description":"List of available values for this option. Each value can have its own pricing. At least one value must be provided.","type":"array","items":{"$ref":"#/components/schemas/ProductOptionValueApiDto"}},"isRequired":{"type":"boolean","description":"Whether this option must be selected. If true, customers must choose at least one value from this option before proceeding.","example":false},"isMultiple":{"type":"boolean","description":"Whether customers can select multiple values from this option. If true, customers can select multiple values (e.g., \"Add workshop\" AND \"Enable premium support\"). If false, only one value can be selected.","example":false}},"required":["name","values","isRequired","isMultiple"]},"CreateProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the product or service. This is the primary identifier shown in the catalog, quotes, and invoices.","example":"Website Hosting Package"},"description":{"type":"string","description":"Product description explaining what the product includes, its benefits, and key features. Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n
\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\n
link text example\n```\n\n**bold**\nAtts: none\n```html\n
bold text example\n```\n\n**code**\nAtts: none\n```html\n
code text example\n```\n\n**italic**\nAtts: none\n```html\n
italic text example\n```\n\n**strike**\nAtts: none\n```html\n
strike text example\n```\n\n**underline**\nAtts: none\n```html\n
underline text example\n```\n"},"categoryId":{"type":"string","description":"UUID of the product category this product belongs to. Categories help organize products into groups (e.g., \"Hardware\", \"Software\", \"Services\").","example":"123e4567-e89b-12d3-a456-426614174000"},"logoId":{"type":"object","description":"File ID of the product logo image. To upload a logo, first call POST /api/public/workspace/upload to upload the image file, then use the returned file ID here. Set to null if no logo is needed.","nullable":true,"example":"123e4567-e89b-12d3-a456-426614174000"},"priceFixed":{"type":"object","description":"One-time fixed price for the product. Use this for one-time purchases (e.g., hardware, installation fees, one-time services). Can be combined with subscription or per-unit pricing.","nullable":true,"example":999.99},"priceSubscription":{"type":"object","description":"Recurring subscription price for the product. Use this for recurring revenue models (e.g., monthly SaaS subscription, annual maintenance). The billing frequency is controlled by priceFrequency.","nullable":true,"example":29.99},"pricePerUnit":{"type":"object","description":"Price per unit for flexible quantity-based billing. Use this when pricing depends on quantity (e.g., per user, per hour, per license, per GB). Requires priceUnitName to be set.","nullable":true,"example":5},"priceUnitName":{"type":"string","description":"Name of the unit for per-unit pricing (e.g., \"user\", \"hour\", \"license\", \"GB\"). Required when pricePerUnit is greater than 0. This is displayed in quotes and invoices.","example":"user"},"priceFrequency":{"type":"number","description":"Billing frequency in months for subscription or per-unit pricing. Required when pricePerUnit or priceSubscription is greater than 0. Valid values: 1 (monthly), 3 (quarterly), 6 (semi-annually), 12 (annually).","example":1,"enum":[1,3,6,12]},"contractPeriodMonths":{"type":"number","description":"Contract period in months. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to 12 months if not specified.","example":12},"renewalMode":{"type":"string","description":"Renewal mode for the product subscription. Automatic means the subscription will automatically renew, Stops means it will stop at the end of the contract period. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to Automatic.","enum":["Automatic","Stops"],"example":"Automatic"},"variants":{"description":"List of product variants. Variants represent different configurations or performance levels of the same product (e.g., Standard, Pro, Enterprise). Each variant can have its own pricing and description. At least one variant must be provided.","type":"array","items":{"$ref":"#/components/schemas/ProductVariantApiDto"}},"options":{"description":"List of product options. Options are extra services or add-ons that customers can optionally select (e.g., \"Add workshop\", \"Enable premium support\"). Options are organized into groups with multiple selectable values. Can be an empty array if no options are needed.","type":"array","items":{"$ref":"#/components/schemas/ProductOptionApiDto"}}},"required":["name","description","categoryId","variants","options"]},"UpdateProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the product or service. This is the primary identifier shown in the catalog, quotes, and invoices.","example":"Website Hosting Package"},"description":{"type":"string","description":"Product description explaining what the product includes, its benefits, and key features. Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n
\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\n
link text example\n```\n\n**bold**\nAtts: none\n```html\n
bold text example\n```\n\n**code**\nAtts: none\n```html\n
code text example\n```\n\n**italic**\nAtts: none\n```html\n
italic text example\n```\n\n**strike**\nAtts: none\n```html\n
strike text example\n```\n\n**underline**\nAtts: none\n```html\n
underline text example\n```\n"},"categoryId":{"type":"string","description":"UUID of the product category this product belongs to. Categories help organize products into groups (e.g., \"Hardware\", \"Software\", \"Services\").","example":"123e4567-e89b-12d3-a456-426614174000"},"logoId":{"type":"object","description":"File ID of the product logo image. To upload a logo, first call POST /api/public/workspace/upload to upload the image file, then use the returned file ID here. Set to null if no logo is needed.","nullable":true,"example":"123e4567-e89b-12d3-a456-426614174000"},"priceFixed":{"type":"object","description":"One-time fixed price for the product. Use this for one-time purchases (e.g., hardware, installation fees, one-time services). Can be combined with subscription or per-unit pricing.","nullable":true,"example":999.99},"priceSubscription":{"type":"object","description":"Recurring subscription price for the product. Use this for recurring revenue models (e.g., monthly SaaS subscription, annual maintenance). The billing frequency is controlled by priceFrequency.","nullable":true,"example":29.99},"pricePerUnit":{"type":"object","description":"Price per unit for flexible quantity-based billing. Use this when pricing depends on quantity (e.g., per user, per hour, per license, per GB). Requires priceUnitName to be set.","nullable":true,"example":5},"priceUnitName":{"type":"string","description":"Name of the unit for per-unit pricing (e.g., \"user\", \"hour\", \"license\", \"GB\"). Required when pricePerUnit is greater than 0. This is displayed in quotes and invoices.","example":"user"},"priceFrequency":{"type":"number","description":"Billing frequency in months for subscription or per-unit pricing. Required when pricePerUnit or priceSubscription is greater than 0. Valid values: 1 (monthly), 3 (quarterly), 6 (semi-annually), 12 (annually).","example":1,"enum":[1,3,6,12]},"contractPeriodMonths":{"type":"number","description":"Contract period in months. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to 12 months if not specified.","example":12},"renewalMode":{"type":"string","description":"Renewal mode for the product subscription. Automatic means the subscription will automatically renew, Stops means it will stop at the end of the contract period. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to Automatic.","enum":["Automatic","Stops"],"example":"Automatic"},"variants":{"description":"List of product variants. Variants represent different configurations or performance levels of the same product (e.g., Standard, Pro, Enterprise). Each variant can have its own pricing and description. At least one variant must be provided.","type":"array","items":{"$ref":"#/components/schemas/ProductVariantApiDto"}},"options":{"description":"List of product options. Options are extra services or add-ons that customers can optionally select (e.g., \"Add workshop\", \"Enable premium support\"). Options are organized into groups with multiple selectable values. Can be an empty array if no options are needed.","type":"array","items":{"$ref":"#/components/schemas/ProductOptionApiDto"}}},"required":["name","description","categoryId","variants","options"]},"PatchProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the product or service. This is the primary identifier shown in the catalog, quotes, and invoices.","example":"Website Hosting Package"},"description":{"type":"string","description":"Product description explaining what the product includes, its benefits, and key features. Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n
\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\n
link text example\n```\n\n**bold**\nAtts: none\n```html\n
bold text example\n```\n\n**code**\nAtts: none\n```html\n
code text example\n```\n\n**italic**\nAtts: none\n```html\n
italic text example\n```\n\n**strike**\nAtts: none\n```html\n
strike text example\n```\n\n**underline**\nAtts: none\n```html\n
underline text example\n```\n"},"categoryId":{"type":"string","description":"UUID of the product category this product belongs to. Categories help organize products into groups (e.g., \"Hardware\", \"Software\", \"Services\").","example":"123e4567-e89b-12d3-a456-426614174000"},"logoId":{"type":"object","description":"File ID of the product logo image. To upload a logo, first call POST /api/public/workspace/upload to upload the image file, then use the returned file ID here. Set to null if no logo is needed.","nullable":true,"example":"123e4567-e89b-12d3-a456-426614174000"},"priceFixed":{"type":"object","description":"One-time fixed price for the product. Use this for one-time purchases (e.g., hardware, installation fees, one-time services). Can be combined with subscription or per-unit pricing.","nullable":true,"example":999.99},"priceSubscription":{"type":"object","description":"Recurring subscription price for the product. Use this for recurring revenue models (e.g., monthly SaaS subscription, annual maintenance). The billing frequency is controlled by priceFrequency.","nullable":true,"example":29.99},"pricePerUnit":{"type":"object","description":"Price per unit for flexible quantity-based billing. Use this when pricing depends on quantity (e.g., per user, per hour, per license, per GB). Requires priceUnitName to be set.","nullable":true,"example":5},"priceUnitName":{"type":"string","description":"Name of the unit for per-unit pricing (e.g., \"user\", \"hour\", \"license\", \"GB\"). Required when pricePerUnit is greater than 0. This is displayed in quotes and invoices.","example":"user"},"priceFrequency":{"type":"number","description":"Billing frequency in months for subscription or per-unit pricing. Required when pricePerUnit or priceSubscription is greater than 0. Valid values: 1 (monthly), 3 (quarterly), 6 (semi-annually), 12 (annually).","example":1,"enum":[1,3,6,12]},"contractPeriodMonths":{"type":"number","description":"Contract period in months. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to 12 months if not specified.","example":12},"renewalMode":{"type":"string","description":"Renewal mode for the product subscription. Automatic means the subscription will automatically renew, Stops means it will stop at the end of the contract period. Required when pricePerUnit or priceSubscription is greater than 0. Defaults to Automatic.","enum":["Automatic","Stops"],"example":"Automatic"},"variants":{"description":"List of product variants. Variants represent different configurations or performance levels of the same product (e.g., Standard, Pro, Enterprise). Each variant can have its own pricing and description. At least one variant must be provided.","type":"array","items":{"$ref":"#/components/schemas/ProductVariantApiDto"}},"options":{"description":"List of product options. Options are extra services or add-ons that customers can optionally select (e.g., \"Add workshop\", \"Enable premium support\"). Options are organized into groups with multiple selectable values. Can be an empty array if no options are needed.","type":"array","items":{"$ref":"#/components/schemas/ProductOptionApiDto"}}}},"ProductCategoryTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German). This determines which language interface will display this translation.","example":"en"},"name":{"type":"object","description":"Translated name of the product category in the specified language. This name appears in multilingual user interfaces and documents when the user language matches.","example":"Software"},"description":{"type":"object","description":"Translated description of the product category in the specified language. This description appears in multilingual user interfaces and documents when the user language matches.","example":"Software products and licenses"}},"required":["language"]},"ProductCategoryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the product category. Use this ID to reference the category in other API calls.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the product category. This is the primary name used to identify and organize products.","example":"Software"},"icon":{"type":"string","description":"Icon identifier for the product category in emoji-style format :icon_name:. Icons help visually distinguish categories in lists and dropdowns.","example":":package:"},"description":{"type":"object","description":"Optional description explaining what products or services belong to this category. Helps users understand the category purpose when creating or assigning products.","example":"Software products and licenses"},"sort":{"type":"number","description":"Numeric sort order for displaying categories. Lower numbers appear first. Used to control the order in which categories appear in dropdowns and lists.","example":1},"defaultKey":{"type":"object","description":"Default key identifier for system-defined categories (e.g., \"software\", \"hardware\", \"consulting\", \"external_costs\"). Only present for categories that were created from system defaults. Custom categories created by users do not have a defaultKey. This key is used when restoring default categories.","example":"software"},"translations":{"description":"Array of translations for multilingual support. Each translation provides the category name and description in a specific language. Translations are automatically used in multilingual user interfaces and documents based on the user language preference.","example":[{"language":"en","name":"Software","description":"Software products and licenses"},{"language":"de","name":"Software","description":"Softwareprodukte und Lizenzen"}],"type":"array","items":{"$ref":"#/components/schemas/ProductCategoryTranslationDto"}},"createdAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp indicating when the product category was created. Format: YYYY-MM-DDTHH:mm:ss.sssZ","example":"2024-01-01T00:00:00.000Z"},"deletedAt":{"type":"object","description":"ISO 8601 timestamp indicating when the product category was soft-deleted, or null if not deleted. Format: YYYY-MM-DDTHH:mm:ss.sssZ. Soft-deleted categories are marked as deleted but not permanently removed.","example":null}},"required":["id","name","icon","translations","createdAt"]},"CreateProductCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the product category. This is the primary name used to identify and organize products. Examples: \"Hardware\", \"Software\", \"Consulting\", \"Subscriptions\".","example":"Software"},"icon":{"type":"string","description":"Icon identifier for the product category in emoji-style format :icon_name:. Icons help visually distinguish categories in lists and dropdowns. Examples: :computer:, :desktop_computer:, :money_with_wings:, :office_worker:, :package:. Default is :rocket: if not specified.","example":":package:"},"description":{"type":"object","description":"Optional description explaining what products or services belong to this category. Helps users understand the category purpose when creating or assigning products.","example":"Software products and licenses"},"translations":{"description":"Array of translations for multilingual support. Each translation provides the category name and description in a specific language. Translations are automatically used in multilingual user interfaces and documents based on the user language preference. Common languages: \"en\" (English), \"de\" (German).","example":[{"language":"en","name":"Software","description":"Software products and licenses"},{"language":"de","name":"Software","description":"Softwareprodukte und Lizenzen"}],"type":"array","items":{"$ref":"#/components/schemas/ProductCategoryTranslationDto"}}},"required":["name","icon","translations"]},"UpdateProductCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the product category. This is the primary name used to identify and organize products. Examples: \"Hardware\", \"Software\", \"Consulting\", \"Subscriptions\". All fields are required in PUT requests.","example":"Software"},"icon":{"type":"string","description":"Icon identifier for the product category in emoji-style format :icon_name:. Icons help visually distinguish categories in lists and dropdowns. Examples: :computer:, :desktop_computer:, :money_with_wings:, :office_worker:, :package:. All fields are required in PUT requests.","example":":package:"},"description":{"type":"object","description":"Optional description explaining what products or services belong to this category. Helps users understand the category purpose when creating or assigning products. All fields are required in PUT requests.","example":"Software products and licenses"},"translations":{"description":"Array of translations for multilingual support. Each translation provides the category name and description in a specific language. Translations are automatically used in multilingual user interfaces and documents based on the user language preference. Common languages: \"en\" (English), \"de\" (German). All fields are required in PUT requests.","type":"array","items":{"$ref":"#/components/schemas/ProductCategoryTranslationDto"}}}},"PatchProductCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the product category. This is the primary name used to identify and organize products. Examples: \"Hardware\", \"Software\", \"Consulting\", \"Subscriptions\". Only include this field if you want to update the name. If not provided, the existing name remains unchanged.","example":"Software"},"icon":{"type":"string","description":"Icon identifier for the product category in emoji-style format :icon_name:. Icons help visually distinguish categories in lists and dropdowns. Examples: :computer:, :desktop_computer:, :money_with_wings:, :office_worker:, :package:. Only include this field if you want to update the icon. If not provided, the existing icon remains unchanged.","example":":package:"},"description":{"type":"object","description":"Optional description explaining what products or services belong to this category. Helps users understand the category purpose when creating or assigning products. Only include this field if you want to update the description. If not provided, the existing description remains unchanged. Set to null to clear the description.","example":"Software products and licenses"},"translations":{"description":"Array of translations for multilingual support. Each translation provides the category name and description in a specific language. Translations are automatically used in multilingual user interfaces and documents based on the user language preference. Common languages: \"en\" (English), \"de\" (German). Only include this field if you want to update translations. If provided, it replaces all existing translations. If not provided, existing translations remain unchanged.","type":"array","items":{"$ref":"#/components/schemas/ProductCategoryTranslationDto"}}}},"SortProductCategoriesDto":{"type":"object","properties":{"ids":{"description":"Array of product category IDs in the desired display order. The first ID in the array will be displayed first, the second ID will be displayed second, and so on. All category IDs must be valid UUIDs that exist in the workspace. The sort order is updated for all categories based on their position in this array.","example":["123e4567-e89b-12d3-a456-426614174000","223e4567-e89b-12d3-a456-426614174001","323e4567-e89b-12d3-a456-426614174002"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"RestoreProductCategoriesDto":{"type":"object","properties":{"keepCustom":{"type":"boolean","description":"Whether to preserve custom (user-created) product categories when restoring default categories. If true, system default categories are restored while keeping any custom categories you created. If false (default), all custom categories are removed and only system defaults are restored. System default categories include: External Costs, Software, Hardware, and Consulting with multilingual translations.","example":false,"default":false}}},"RoleListItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the role. Base roles have IDs containing underscore-prefixed identifiers (e.g., \"_root_\", \"_ceo_\", \"_staff_\"). Custom roles have workspace-prefixed IDs.","example":"workspace-id_employee"},"name":{"type":"string","description":"Display name of the role, localized based on user language preference.","example":"Employee"},"description":{"type":"string","description":"Human-readable description of the role purpose and responsibilities, localized based on user language preference.","example":"Standard employee role"},"icon":{"type":"string","description":"Icon identifier for the role. Can be a RemixIcon class name (e.g., \"ri-user-line\") or an emoji code (e.g., \":person_in_tuxedo:\"). Used for visual identification in role lists.","example":"ri-user-line"},"parentId":{"type":"string","description":"ID of the parent role if this role inherits permissions from another role. Undefined if the role has no parent (e.g., base roles or top-level custom roles).","example":"workspace-id_admin"},"type":{"type":"string","description":"Role type indicating the intended use case. \"normal\" for internal team members, \"guest\" for external users. Determines permission restrictions.","example":"normal"},"readOnly":{"type":"boolean","description":"Boolean flag indicating if this is a base role (system-defined) that cannot be modified or deleted. Base roles include Root, CEO, Team Leader, Staff, and Guest.","example":false}},"required":["id","name","description","icon","type","readOnly"]},"PermissionItem":{"type":"object","properties":{"key":{"type":"string","description":"Unique permission identifier using dot notation format \"category.action\" (e.g., \"projects.create\", \"tasks.delete\"). This key is used when assigning permissions to roles.","example":"projects.create"},"group":{"type":"string","description":"Functional group that this permission belongs to. Permissions are organized into groups like \"projects\", \"tasks\", \"employees\", \"roles\", etc. for easier management and UI display.","example":"projects"}},"required":["key","group"]},"RoleDetailsResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the role. Base roles have IDs containing underscore-prefixed identifiers (e.g., \"_root_\", \"_ceo_\", \"_staff_\"). Custom roles have workspace-prefixed IDs.","example":"workspace-id_employee"},"name":{"type":"string","description":"Display name of the role, localized based on user language preference.","example":"Employee"},"description":{"type":"string","description":"Human-readable description of the role purpose and responsibilities, localized based on user language preference.","example":"Standard employee role"},"icon":{"type":"string","description":"Icon identifier for the role. Can be a RemixIcon class name (e.g., \"ri-user-line\") or an emoji code (e.g., \":person_in_tuxedo:\"). Used for visual identification in role lists.","example":"ri-user-line"},"parentId":{"type":"string","description":"ID of the parent role if this role inherits permissions from another role. Undefined if the role has no parent (e.g., base roles or top-level custom roles).","example":"workspace-id_admin"},"type":{"type":"string","description":"Role type indicating the intended use case. \"normal\" for internal team members, \"guest\" for external users. Determines permission restrictions.","example":"normal"},"permissions":{"type":"object","description":"Complete map of all permissions for this role. Keys are permission identifiers (e.g., \"projects.create\", \"tasks.delete\"). Values are true if the permission is explicitly allowed, false if explicitly disallowed, or missing if inherited from parent role. This map includes both explicitly set permissions and inherited permissions.","example":{"projects.create":true,"projects.delete":false}},"readOnly":{"type":"boolean","description":"Boolean flag indicating if this is a base role (system-defined) that cannot be modified or deleted. Base roles include Root, CEO, Team Leader, Staff, and Guest.","example":false},"createdBy":{"type":"string","description":"User ID of the person who created this custom role. Only present for custom roles, not base roles."},"createdAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp indicating when this custom role was created. Only present for custom roles, not base roles."},"editedAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp indicating when this custom role was last modified. Only present for custom roles, not base roles."}},"required":["id","name","description","icon","type","permissions","readOnly"]},"CreateRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the role. This is shown in user interfaces when selecting or displaying roles.","example":"Team Lead"},"description":{"type":"string","description":"Human-readable description explaining the role purpose and responsibilities. Maximum 400 characters.","example":"Leads a delivery team"},"icon":{"type":"string","description":"Icon identifier for the role. Can be a RemixIcon class name (e.g., \"ri-user-star-line\") or an emoji code (e.g., \":person_in_tuxedo:\"). Used for visual identification in role lists and user interfaces.","example":"ri-user-star-line"},"parentId":{"type":"string","description":"ID of the parent role for permission inheritance. If provided, this role will inherit all permissions from the parent role. Inherited permissions can be overridden by explicitly setting them in the permissions map. Must not create circular dependencies (cannot set a child role as parent).","example":"workspace-id_employee"},"type":{"type":"string","description":"Role type determines the intended use case and permission restrictions. \"normal\" roles are for internal team members (employees, managers). \"guest\" roles are for external users like clients or partners and have additional permission restrictions.","example":"normal","enum":["normal","guest"]},"permissions":{"type":"object","description":"Map of permission keys to boolean values. Keys are permission identifiers (e.g., \"projects.create\", \"tasks.delete\"). Values are true to allow the permission or false to disallow it. If not provided and a parent role is set, permissions are inherited from the parent. Guest roles cannot have certain permissions (e.g., workspace administration).","example":{"projects.create":true,"projects.delete":false}}},"required":["name","icon","type"]},"UpdateRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the role. This is shown in user interfaces when selecting or displaying roles.","example":"Team Lead"},"description":{"type":"string","description":"Human-readable description explaining the role purpose and responsibilities. Maximum 400 characters.","example":"Leads a delivery team"},"icon":{"type":"string","description":"Icon identifier for the role. Can be a RemixIcon class name (e.g., \"ri-user-star-line\") or an emoji code (e.g., \":person_in_tuxedo:\"). Used for visual identification in role lists and user interfaces.","example":"ri-user-star-line"},"parentId":{"type":"string","description":"ID of the parent role for permission inheritance. If provided, this role will inherit all permissions from the parent role. Inherited permissions can be overridden by explicitly setting them in the permissions map. Must not create circular dependencies (cannot set a child role as parent).","example":"workspace-id_employee"},"type":{"type":"string","description":"Role type determines the intended use case and permission restrictions. \"normal\" roles are for internal team members (employees, managers). \"guest\" roles are for external users like clients or partners and have additional permission restrictions.","example":"normal","enum":["normal","guest"]},"permissions":{"type":"object","description":"Complete map of permission keys to boolean values. Keys are permission identifiers (e.g., \"projects.create\", \"tasks.delete\"). Values are true to allow the permission or false to disallow it. This replaces the entire permission map - all permissions must be specified. Guest roles cannot have certain permissions (e.g., workspace administration).","example":{"projects.create":true,"projects.delete":false}}},"required":["name","icon","type"]},"PatchRoleDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the role. If provided, updates the role name. If not provided, the existing name is kept.","example":"Team Lead"},"description":{"type":"string","description":"Human-readable description explaining the role purpose and responsibilities. Maximum 400 characters. If provided, updates the description. If not provided, the existing description is kept.","example":"Leads a delivery team"},"icon":{"type":"string","description":"Icon identifier for the role. Can be a RemixIcon class name (e.g., \"ri-user-star-line\") or an emoji code (e.g., \":person_in_tuxedo:\"). If provided, updates the icon. If not provided, the existing icon is kept.","example":":person_in_tuxedo:"},"parentId":{"type":"string","description":"ID of the parent role for permission inheritance. If provided, changes the parent role and permissions are recalculated based on the new parent. If not provided, the existing parent is kept. Must not create circular dependencies (cannot set a child role as parent).","example":"workspace-id_employee"},"type":{"type":"string","description":"Role type determines the intended use case and permission restrictions. \"normal\" roles are for internal team members. \"guest\" roles are for external users and have additional permission restrictions. If provided, changes the role type. If not provided, the existing type is kept.","example":"normal","enum":["normal","guest"]}}},"ReplacePermissionsDto":{"type":"object","properties":{"permissions":{"type":"object","description":"Complete map of permission keys to boolean values that replaces the entire permission set for the role. Keys are permission identifiers using dot notation (e.g., \"projects.create\", \"tasks.delete\"). Values are true to allow the permission or false to disallow it. This is a complete replacement - all permissions must be specified. Permissions set to false are removed from the role. Permissions are validated against disallowed permissions for the role type.","example":{"projects.create":true,"projects.delete":false,"projects.edit":true}}},"required":["permissions"]},"TogglePermissionDto":{"type":"object","properties":{"allow":{"type":"boolean","description":"Boolean value indicating whether to grant (true) or revoke (false) the permission specified in the URL path. Setting to true explicitly allows the permission, even if it was inherited from a parent role. Setting to false explicitly disallows the permission, overriding any inheritance.","example":true}},"required":["allow"]},"TaskAutoGenerationSettingsDto":{"type":"object","properties":{"tasksAutoGenerateTitle":{"type":"boolean","description":"Whether to automatically generate task titles","example":true},"tasksAutoGenerateSummary":{"type":"boolean","description":"Whether to automatically generate task summaries","example":true},"tasksAutoGenerateIcon":{"type":"boolean","description":"Whether to automatically generate task icons","example":true}},"required":["tasksAutoGenerateTitle","tasksAutoGenerateSummary","tasksAutoGenerateIcon"]},"CustomFieldTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"Language code following ISO 639-1 format (e.g., \"en\", \"de\", \"fr\")","example":"en"},"name":{"type":"string","description":"Translated name for this language. Overrides the default name when user's language matches.","example":"Priority"}},"required":["language","name"]},"FieldOptionDto":{"type":"object","properties":{"id":{"type":"object","description":"Option ID","example":"1"},"value":{"type":"string","description":"Default option value (used as fallback when no translation exists for user's language)","example":"High"},"translations":{"description":"Language-specific translations for this option. Overrides the default value when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}}},"required":["value","translations"]},"TaskCustomFieldResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Custom field ID","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Default custom field name (used as fallback when no translation exists for user's language)","example":"Priority"},"description":{"type":"object","description":"Default custom field description (used as fallback when no translation exists for user's language)","example":"Task priority level","nullable":true},"sort":{"type":"number","description":"Sort order","example":1},"type":{"type":"string","description":"Custom field type","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"entity":{"type":"string","description":"Entity type (always Task for task custom fields)","enum":["Task","Project","Organization","Object"],"example":"Task"},"translations":{"description":"Language-specific translations for field name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}},"selectOptions":{"description":"Select options with their translations. Each option has a default value and language-specific overrides.","type":"array","items":{"$ref":"#/components/schemas/FieldOptionDto"}}},"required":["id","name","description","sort","type","entity","translations","selectOptions"]},"CreateTaskCustomFieldDto":{"type":"object","properties":{"id":{"type":"string","description":"Custom field ID (optional for create)","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Default custom field name (used as fallback when no translation exists for user's language)","example":"Priority"},"description":{"type":"string","description":"Default custom field description (used as fallback when no translation exists for user's language)","example":"Task priority level"},"type":{"type":"string","description":"Custom field type","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"selectOptions":{"description":"Select options (required for Select and MultiSelect types)","type":"array","items":{"$ref":"#/components/schemas/FieldOptionDto"}},"translations":{"description":"Language-specific translations for field name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}},"translationsDescriptions":{"description":"Language-specific translations for field description. Overrides the default description when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}}},"required":["name","description","type","selectOptions","translations","translationsDescriptions"]},"UpdateTaskCustomFieldDto":{"type":"object","properties":{"id":{"type":"string","description":"Custom field ID (optional, taken from URL)","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Default custom field name (used as fallback when no translation exists for user's language)","example":"Priority"},"description":{"type":"string","description":"Default custom field description (used as fallback when no translation exists for user's language)","example":"Task priority level"},"type":{"type":"string","description":"Custom field type","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"selectOptions":{"description":"Select options (required for Select and MultiSelect types)","type":"array","items":{"$ref":"#/components/schemas/FieldOptionDto"}},"translations":{"description":"Language-specific translations for field name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}},"translationsDescriptions":{"description":"Language-specific translations for field description. Overrides the default description when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationDto"}}},"required":["name","description","type","selectOptions","translations","translationsDescriptions"]},"SortTaskCustomFieldsDto":{"type":"object","properties":{"ids":{"description":"Array of custom field IDs in the desired order","example":["123e4567-e89b-12d3-a456-426614174000","987fcdeb-51a2-43d7-b456-426614174000"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"RestoreDefaultsDto":{"type":"object","properties":{"keepCustom":{"type":"boolean","description":"Whether to keep custom task types, statuses, and work activities","example":false}},"required":["keepCustom"]},"WorkActivityTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"Language code following ISO 639-1 format (e.g., \"en\", \"de\", \"fr\")","example":"en"},"name":{"type":"string","description":"Translated name for this language. Overrides the default name when user's language matches.","example":"Development"}},"required":["language","name"]},"WorkActivityResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Work activity ID","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Default work activity name (used as fallback when no translation exists for user's language)","example":"Development"},"sort":{"type":"number","description":"Sort order","example":1},"translations":{"description":"Language-specific translations for activity name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/WorkActivityTranslationDto"}}},"required":["id","name","sort","translations"]},"CreateWorkActivityDto":{"type":"object","properties":{"id":{"type":"string","description":"Work activity ID (optional for create)","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Default work activity name (used as fallback when no translation exists for user's language)","example":"Development"},"translations":{"description":"Language-specific translations for activity name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/WorkActivityTranslationDto"}}},"required":["name","translations"]},"UpdateWorkActivityDto":{"type":"object","properties":{"name":{"type":"string","description":"Default work activity name (used as fallback when no translation exists for user's language)","example":"Development"},"translations":{"description":"Language-specific translations for activity name. Overrides the default name when user's language matches.","type":"array","items":{"$ref":"#/components/schemas/WorkActivityTranslationDto"}}},"required":["name","translations"]},"SortWorkActivitiesDto":{"type":"object","properties":{"ids":{"description":"Array of work activity IDs in the desired order","example":["123e4567-e89b-12d3-a456-426614174000","987fcdeb-51a2-43d7-b456-426614174000"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"TaskStatusTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"Language code (e.g., \"en\", \"de\")","example":"en"},"name":{"type":"string","description":"Translated name of the task status","example":"In Progress"}},"required":["language","name"]},"TaskStatusResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the task status","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the task status","example":"In Progress"},"icon":{"type":"string","description":"Icon for the task status in format :icon_name: (e.g., :hourglass_flowing_sand:, :check_mark:, :x:)","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Type of the task status","enum":["New","InProgress","Feedback","Backlog","Resolved","Closed"],"example":"InProgress"},"sort":{"type":"number","description":"Sort order of the task status","example":1},"translations":{"description":"Translations for the task status","example":[{"language":"en","name":"In Progress"},{"language":"de","name":"In Bearbeitung"}],"type":"array","items":{"$ref":"#/components/schemas/TaskStatusTranslationDto"}}},"required":["id","name","icon","type","sort","translations"]},"CreateTaskStatusDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the task status","example":"In Progress"},"icon":{"type":"string","description":"Icon for the task status in format :icon_name: (e.g., :hourglass_flowing_sand:, :check_mark:, :x:)","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Type of the task status","enum":["New","InProgress","Feedback","Backlog","Resolved","Closed"],"example":"InProgress"},"translations":{"description":"Translations for the task status","example":[{"language":"en","name":"In Progress"},{"language":"de","name":"In Bearbeitung"}],"type":"array","items":{"$ref":"#/components/schemas/TaskStatusTranslationDto"}}},"required":["name","icon","type","translations"]},"UpdateTaskStatusDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the task status","example":"In Progress"},"icon":{"type":"string","description":"Icon for the task status in format :icon_name: (e.g., :hourglass_flowing_sand:, :check_mark:, :x:)","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Type of the task status","enum":["New","InProgress","Feedback","Backlog","Resolved","Closed"],"example":"InProgress"},"translations":{"description":"Translations for the task status","example":[{"language":"en","name":"In Progress"},{"language":"de","name":"In Bearbeitung"}],"type":"array","items":{"$ref":"#/components/schemas/TaskStatusTranslationDto"}}}},"SortTaskStatusesDto":{"type":"object","properties":{"ids":{"description":"Array of task status IDs in the desired order","example":["status-1","status-2","status-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"TaskTypeTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"Language code for the translation","example":"en"},"name":{"type":"string","description":"Translated name of the task type","example":"Feature"}},"required":["language","name"]},"TaskTypeResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the task type","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the task type","example":"Feature"},"icon":{"type":"string","description":"Icon for the task type in format :icon_name: (e.g., :rocket:, :bug:, :star:)","example":":rocket:"},"type":{"type":"string","description":"Type of the task type","enum":["Feature","Bug"],"example":"Feature"},"sort":{"type":"number","description":"Sort order of the task type","example":1},"translations":{"description":"Translations for the task type","example":[{"language":"en","name":"Feature"},{"language":"de","name":"Funktion"}],"type":"array","items":{"$ref":"#/components/schemas/TaskTypeTranslationDto"}},"statuses":{"description":"Array of task status IDs that can be used with this task type","example":["status-1","status-2"],"type":"array","items":{"type":"string"}},"customFields":{"description":"Array of custom field IDs that are available for this task type","example":["field-1","field-2"],"type":"array","items":{"type":"string"}},"templateDoc":{"type":"string","description":"Template document content as HTML","example":"
Task Template
This is a template for new tasks of this type.
"},"requiredFields":{"description":"Array of required field names for this task type","example":["title","description"],"type":"array","items":{"type":"string"}}},"required":["id","name","icon","type","sort","translations","statuses","customFields","templateDoc","requiredFields"]},"CreateTaskTypeDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the task type","example":"Feature"},"icon":{"type":"string","description":"Icon for the task type in format :icon_name: (e.g., :rocket:, :bug:, :star:)","example":":rocket:"},"type":{"type":"string","description":"Type of the task type","enum":["Feature","Bug"],"example":"Feature"},"translations":{"description":"Translations for the task type","example":[{"language":"en","name":"Feature"},{"language":"de","name":"Funktion"}],"type":"array","items":{"$ref":"#/components/schemas/TaskTypeTranslationDto"}},"statuses":{"description":"Array of task status IDs that can be used with this task type","example":["status-1","status-2"],"type":"array","items":{"type":"string"}},"customFields":{"description":"Array of custom field IDs that are available for this task type","example":["field-1","field-2"],"type":"array","items":{"type":"string"}},"templateDoc":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**embedVideo**\nType: block\nEmbeds a third-party video in an iframe. The div carries data-video-embed with data-embed-url (iframe src) and data-original-url (canonical page URL).\n- embedUrl: Must be a real embed/iframe URL (e.g. YouTube embed) that matches originalUrl.\n- originalUrl: Human-facing link to the video page; keep it in sync with embedUrl. Do not leave placeholder URLs in final HTML if you claim a real video.\nAtts:\n- originalUrl: \n- embedUrl: \n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n","example":"Task Template
This is a template for new tasks of this type.
"},"requiredFields":{"description":"Array of required field names for this task type","example":["title","description"],"type":"array","items":{"type":"string"}}},"required":["name","icon","type","translations","statuses","customFields","templateDoc","requiredFields"]},"UpdateTaskTypeDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the task type","example":"Feature"},"icon":{"type":"string","description":"Icon for the task type in format :icon_name: (e.g., :rocket:, :bug:, :star:)","example":":rocket:"},"type":{"type":"string","description":"Type of the task type","enum":["Feature","Bug"],"example":"Feature"},"translations":{"description":"Translations for the task type","example":[{"language":"en","name":"Feature"},{"language":"de","name":"Funktion"}],"type":"array","items":{"$ref":"#/components/schemas/TaskTypeTranslationDto"}},"statuses":{"description":"Array of task status IDs that can be used with this task type","example":["status-1","status-2"],"type":"array","items":{"type":"string"}},"customFields":{"description":"Array of custom field IDs that are available for this task type","example":["field-1","field-2"],"type":"array","items":{"type":"string"}},"templateDoc":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**embedVideo**\nType: block\nEmbeds a third-party video in an iframe. The div carries data-video-embed with data-embed-url (iframe src) and data-original-url (canonical page URL).\n- embedUrl: Must be a real embed/iframe URL (e.g. YouTube embed) that matches originalUrl.\n- originalUrl: Human-facing link to the video page; keep it in sync with embedUrl. Do not leave placeholder URLs in final HTML if you claim a real video.\nAtts:\n- originalUrl: \n- embedUrl: \n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n","example":"Task Template
This is a template for new tasks of this type.
"},"requiredFields":{"description":"Array of required field names for this task type","example":["title","description"],"type":"array","items":{"type":"string"}}}},"PatchTaskTypeDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the task type","example":"Feature"},"icon":{"type":"string","description":"Icon for the task type in format :icon_name: (e.g., :rocket:, :bug:, :star:)","example":":rocket:"},"type":{"type":"string","description":"Type of the task type","enum":["Feature","Bug"],"example":"Feature"},"translations":{"description":"Translations for the task type","example":[{"language":"en","name":"Feature"},{"language":"de","name":"Funktion"}],"type":"array","items":{"$ref":"#/components/schemas/TaskTypeTranslationDto"}},"statuses":{"description":"Array of task status IDs that can be used with this task type","example":["status-1","status-2"],"type":"array","items":{"type":"string"}},"customFields":{"description":"Array of custom field IDs that are available for this task type","example":["field-1","field-2"],"type":"array","items":{"type":"string"}},"templateDoc":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**embedVideo**\nType: block\nEmbeds a third-party video in an iframe. The div carries data-video-embed with data-embed-url (iframe src) and data-original-url (canonical page URL).\n- embedUrl: Must be a real embed/iframe URL (e.g. YouTube embed) that matches originalUrl.\n- originalUrl: Human-facing link to the video page; keep it in sync with embedUrl. Do not leave placeholder URLs in final HTML if you claim a real video.\nAtts:\n- originalUrl: \n- embedUrl: \n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n","example":"Task Template
This is a template for new tasks of this type.
"},"requiredFields":{"description":"Array of required field names for this task type","example":["title","description"],"type":"array","items":{"type":"string"}}}},"SortTaskTypesDto":{"type":"object","properties":{"ids":{"description":"Array of task type IDs in the desired sort order","example":["type-1","type-2","type-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"ObjectCustomFieldResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"sort":{"type":"number"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"]},"entity":{"type":"string","enum":["Task","Project","Organization","Object"]},"objectTypeId":{"type":"string"},"showInList":{"type":"boolean"},"showInHeader":{"type":"boolean"},"translations":{"type":"array"},"selectOptions":{"type":"array"}},"required":["id","name","description","sort","type","entity","objectTypeId","showInList","showInHeader","translations","selectOptions"]},"SaveSortDTO":{"type":"object","properties":{}},"CustomFieldTranslationPublicDto":{"type":"object","properties":{"language":{"type":"string"},"name":{"type":"string"}},"required":["language","name"]},"FieldOptionPublicDto":{"type":"object","properties":{"id":{"type":"object"},"value":{"type":"string"},"translations":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationPublicDto"}}},"required":["id","value","translations"]},"CreateObjectCustomFieldDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"]},"objectTypeId":{"type":"string","description":"Must be the object type this field belongs to"},"showInList":{"type":"boolean"},"showInHeader":{"type":"boolean"},"selectOptions":{"type":"array","items":{"$ref":"#/components/schemas/FieldOptionPublicDto"}},"translations":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationPublicDto"}},"translationsDescriptions":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationPublicDto"}}},"required":["name","type","objectTypeId","translations","translationsDescriptions"]},"UpdateObjectCustomFieldDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"]},"objectTypeId":{"type":"string"},"showInList":{"type":"boolean"},"showInHeader":{"type":"boolean"},"selectOptions":{"type":"array","items":{"$ref":"#/components/schemas/FieldOptionPublicDto"}},"translations":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationPublicDto"}},"translationsDescriptions":{"type":"array","items":{"$ref":"#/components/schemas/CustomFieldTranslationPublicDto"}}},"required":["name","type","objectTypeId","translations","translationsDescriptions"]},"ProjectCategoryTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German)","example":"en"},"name":{"type":"object","description":"Translated name of the project category in this language. Used for multilingual display in the user interface.","example":"Development"},"description":{"type":"object","description":"Translated description of the project category in this language. Provides context about when to use this category.","example":"Software development projects"}},"required":["language"]},"ProjectCategoryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the project category. Used to reference this category when creating or updating projects.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the project category. Shown in dropdowns and project lists.","example":"Development"},"icon":{"type":"string","description":"Icon identifier in emoji format (e.g., \":rocket:\"). Displayed next to the category name throughout the application.","example":":rocket:"},"description":{"type":"object","description":"Optional description providing context about when to use this category.","example":"Projects related to software development"},"sort":{"type":"number","description":"Numeric sort order for display purposes. Lower numbers appear first in lists and dropdowns. May be undefined if not explicitly set.","example":1},"translations":{"description":"Complete array of translations for all supported languages. Each translation contains the language code and localized name/description.","example":[{"language":"en","name":"Development","description":"Software development projects"},{"language":"de","name":"Entwicklung","description":"Softwareentwicklungsprojekte"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCategoryTranslationDto"}}},"required":["id","name","icon","translations"]},"CreateProjectCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the project category. Used to organize projects by type or purpose (e.g., \"Development\", \"Support\", \"New Client Project\").","example":"Development"},"icon":{"type":"string","description":"Icon identifier in emoji format. Must be wrapped in colons (e.g., \":rocket:\", \":wrench:\", \":briefcase:\"). The icon appears next to the category name throughout the application.","example":":rocket:"},"description":{"type":"object","description":"Optional description providing context about when to use this category. Helps users understand the purpose of the category.","example":"Projects related to software development"},"translations":{"description":"Array of translations for multilingual support. Each translation object contains a language code and translated name/description. The system automatically displays the correct language based on user preferences.","example":[{"language":"en","name":"Development","description":"Software development projects"},{"language":"de","name":"Entwicklung","description":"Softwareentwicklungsprojekte"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCategoryTranslationDto"}}},"required":["name","icon","translations"]},"UpdateProjectCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project category","example":"Development"},"icon":{"type":"string","description":"Icon for the project category in format :icon_name:","example":":rocket:"},"description":{"type":"object","description":"Description of the project category","example":"Projects related to software development"},"translations":{"description":"Translations for the project category","type":"array","items":{"$ref":"#/components/schemas/ProjectCategoryTranslationDto"}}}},"PatchProjectCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project category","example":"Development"},"icon":{"type":"string","description":"Icon for the project category in format :icon_name:","example":":rocket:"},"description":{"type":"object","description":"Description of the project category","example":"Projects related to software development"},"translations":{"description":"Translations for the project category","type":"array","items":{"$ref":"#/components/schemas/ProjectCategoryTranslationDto"}}}},"SortProjectCategoriesDto":{"type":"object","properties":{"ids":{"description":"Array of project category IDs in the desired order","example":["category-1","category-2","category-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"ProjectStatusTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German)","example":"en"},"name":{"type":"object","description":"Translated name of the project status in this language. Used for multilingual display in the user interface.","example":"In Progress"},"description":{"type":"object","description":"Translated description of the project status in this language. Provides context about when to use this status.","example":"Project is currently in progress"}},"required":["language"]},"ProjectStatusResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the project status. Used to reference this status when creating or updating projects.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the project status. Shown in dropdowns and project lists.","example":"In Progress"},"icon":{"type":"string","description":"Icon identifier in emoji format (e.g., \":hourglass_flowing_sand:\"). Displayed next to the status name throughout the application.","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Status type enum value that categorizes the status. Determines billing eligibility and workflow behavior. Valid values: Sales, Requirements, Implementation, QualityManagement, Billing, Done.","enum":["Sales","Requirements","Implementation","QualityManagement","Billing","Done"],"example":"Implementation"},"description":{"type":"object","description":"Optional description providing context about when to use this status.","example":"Project is currently in development phase"},"sort":{"type":"number","description":"Numeric sort order for display purposes. Lower numbers appear first in lists and dropdowns. May be undefined if not explicitly set.","example":1},"translations":{"description":"Complete array of translations for all supported languages. Each translation contains the language code and localized name/description.","example":[{"language":"en","name":"In Progress","description":"Project is currently in progress"},{"language":"de","name":"In Bearbeitung","description":"Projekt ist derzeit in Bearbeitung"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectStatusTranslationDto"}}},"required":["id","name","icon","type","translations"]},"CreateProjectStatusDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the project status. Represents a phase in the project workflow (e.g., \"In Progress\", \"On Hold\", \"Quality Review\").","example":"In Progress"},"icon":{"type":"string","description":"Icon identifier in emoji format. Must be wrapped in colons (e.g., \":hourglass_flowing_sand:\", \":check_mark:\", \":moneybag:\"). The icon appears next to the status name throughout the application.","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Status type enum value that categorizes the status. Determines billing eligibility and workflow behavior. Valid values: Sales, Requirements, Implementation, QualityManagement, Billing, Done.","enum":["Sales","Requirements","Implementation","QualityManagement","Billing","Done"],"example":"Implementation"},"description":{"type":"object","description":"Optional description providing context about when to use this status. Helps users understand the purpose of the status.","example":"Project is currently in development phase"},"translations":{"description":"Array of translations for multilingual support. Each translation object contains a language code and translated name/description. The system automatically displays the correct language based on user preferences.","example":[{"language":"en","name":"In Progress","description":"Project is currently in progress"},{"language":"de","name":"In Bearbeitung","description":"Projekt ist derzeit in Bearbeitung"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectStatusTranslationDto"}}},"required":["name","icon","type","translations"]},"UpdateProjectStatusDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project status","example":"In Progress"},"icon":{"type":"string","description":"Icon for the project status in format :icon_name:","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Type of the project status","enum":["Sales","Requirements","Implementation","QualityManagement","Billing","Done"],"example":"Implementation"},"description":{"type":"object","description":"Description of the project status","example":"Project is currently in development phase"},"translations":{"description":"Translations for the project status","type":"array","items":{"$ref":"#/components/schemas/ProjectStatusTranslationDto"}}}},"PatchProjectStatusDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project status","example":"In Progress"},"icon":{"type":"string","description":"Icon for the project status in format :icon_name:","example":":hourglass_flowing_sand:"},"type":{"type":"string","description":"Type of the project status","enum":["Sales","Requirements","Implementation","QualityManagement","Billing","Done"],"example":"Implementation"},"description":{"type":"object","description":"Description of the project status","example":"Project is currently in development phase"},"translations":{"description":"Translations for the project status","type":"array","items":{"$ref":"#/components/schemas/ProjectStatusTranslationDto"}}}},"SortProjectStatusesDto":{"type":"object","properties":{"ids":{"description":"Array of project status IDs in the desired order","example":["status-1","status-2","status-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"ProjectPhaseTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German)","example":"en"},"name":{"type":"object","description":"Translated name of the project phase in this language. Used for multilingual display in the user interface.","example":"Planning"},"description":{"type":"object","description":"Translated description of the project phase in this language. Provides context about when to use this phase.","example":"Project planning and preparation phase"}},"required":["language"]},"ProjectPhaseResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the project phase. Used to reference this phase when creating or updating opportunities.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the project phase. Shown in dropdowns and the Sales Kanban board.","example":"Planning"},"icon":{"type":"string","description":"Icon identifier in emoji format (e.g., \":calendar:\"). Displayed next to the phase name throughout the application.","example":":calendar:"},"type":{"type":"string","description":"Phase type enum value that determines which Kanban column the opportunity appears in. Valid values: new, inProgress, done.","enum":["new","inProgress","done"],"example":"new"},"description":{"type":"object","description":"Optional description providing context about when to use this phase.","example":"Initial planning and requirement gathering phase"},"sort":{"type":"number","description":"Numeric sort order for display purposes. Lower numbers appear first in lists and dropdowns. May be undefined if not explicitly set.","example":1},"translations":{"description":"Complete array of translations for all supported languages. Each translation contains the language code and localized name/description.","example":[{"language":"en","name":"Planning","description":"Project planning phase"},{"language":"de","name":"Planung","description":"Projektplanungsphase"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectPhaseTranslationDto"}}},"required":["id","name","icon","type","translations"]},"CreateProjectPhaseDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the project phase. Represents a stage in the sales pipeline (e.g., \"Qualification\", \"Proposal Sent\", \"Negotiation\").","example":"Planning"},"icon":{"type":"string","description":"Icon identifier in emoji format. Must be wrapped in colons (e.g., \":calendar:\", \":phone:\", \":trophy:\"). The icon appears next to the phase name throughout the application.","example":":calendar:"},"type":{"type":"string","description":"Phase type enum value that determines which Kanban column the opportunity appears in. Valid values: new (appears in \"New\" column), inProgress (appears in \"In Progress\" column), done (appears in \"Done\" column).","enum":["new","inProgress","done"],"example":"new"},"description":{"type":"object","description":"Optional description providing context about when to use this phase. Helps users understand the purpose of the phase.","example":"Initial planning and requirement gathering phase"},"translations":{"description":"Array of translations for multilingual support. Each translation object contains a language code and translated name/description. The system automatically displays the correct language based on user preferences.","example":[{"language":"en","name":"Planning","description":"Project planning phase"},{"language":"de","name":"Planung","description":"Projektplanungsphase"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectPhaseTranslationDto"}}},"required":["name","icon","type","translations"]},"UpdateProjectPhaseDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project phase","example":"Planning"},"icon":{"type":"string","description":"Icon for the project phase in format :icon_name:","example":":calendar:"},"type":{"type":"string","description":"Type of the project phase","enum":["new","inProgress","done"],"example":"new"},"description":{"type":"object","description":"Description of the project phase","example":"Initial planning and requirement gathering phase"},"translations":{"description":"Translations for the project phase","type":"array","items":{"$ref":"#/components/schemas/ProjectPhaseTranslationDto"}}}},"PatchProjectPhaseDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the project phase","example":"Planning"},"icon":{"type":"string","description":"Icon for the project phase in format :icon_name:","example":":calendar:"},"type":{"type":"string","description":"Type of the project phase","enum":["new","inProgress","done"],"example":"new"},"description":{"type":"object","description":"Description of the project phase","example":"Initial planning and requirement gathering phase"},"translations":{"description":"Translations for the project phase","type":"array","items":{"$ref":"#/components/schemas/ProjectPhaseTranslationDto"}}}},"SortProjectPhasesDto":{"type":"object","properties":{"ids":{"description":"Array of project phase IDs in the desired order","example":["phase-1","phase-2","phase-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"ProjectCustomFieldTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German)","example":"en"},"name":{"type":"string","description":"Translated name of the custom field in this language. Used for multilingual display in project forms.","example":"Priority Level"},"description":{"type":"string","description":"Translated description of the custom field in this language. Provides context about what information should be entered.","example":"Priority level for the project"}},"required":["language"]},"ProjectCustomFieldSelectOptionTranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"ISO 639-1 language code for the translation (e.g., \"en\" for English, \"de\" for German)","example":"en"},"name":{"type":"string","description":"Translated display name for the select option in this language. Shown to users when selecting from dropdown options.","example":"High Priority"}},"required":["language","name"]},"ProjectCustomFieldSelectOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Optional unique identifier for the select option. If not provided, the value will be used as the identifier. Required when updating existing options.","example":"option-1"},"value":{"type":"string","description":"Display value for the select option. This is the value stored when the option is selected. Must be unique within the field.","example":"High Priority"},"translations":{"description":"Array of translations for multilingual support. Each translation contains a language code and translated display name. The system automatically shows the correct language based on user preferences.","example":[{"language":"en","name":"High Priority"},{"language":"de","name":"Hohe PrioritΓ€t"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldSelectOptionTranslationDto"}}},"required":["value","translations"]},"ProjectCustomFieldResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the custom field. Used to reference this field when setting values on projects.","example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the custom field. Shown as the field label in project forms.","example":"Priority Level"},"description":{"type":"string","description":"Description providing context about what information should be entered in this field.","example":"Priority level for the project"},"sort":{"type":"number","description":"Numeric sort order for display purposes. Lower numbers appear first in project forms. Determines the order in which fields are displayed.","example":1},"type":{"type":"string","description":"Field type enum value indicating the input type. Valid values: Text, Textarea, Number, Date, Checkbox, Select, MultiSelect.","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"entity":{"type":"string","description":"Entity type identifier. Always \"Project\" for project custom fields. Used internally to scope fields to specific entity types.","example":"Project"},"translations":{"description":"Complete array of translations for the field name. Each translation contains the language code and localized name.","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldTranslationDto"}},"selectOptions":{"description":"Array of select options for Select and MultiSelect field types. Each option contains an ID, value, and translations. Empty array for other field types.","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldSelectOptionDto"}}},"required":["id","name","description","sort","type","entity","translations","selectOptions"]},"CreateProjectCustomFieldDto":{"type":"object","properties":{"id":{"type":"string","description":"Optional unique identifier for the custom field. Only needed when updating an existing field. If omitted, a new field will be created."},"name":{"type":"string","description":"Display name for the custom field. Shown as the field label in project forms (e.g., \"Priority Level\", \"Region\", \"Server Name\").","example":"Priority Level"},"description":{"type":"string","description":"Optional description providing context about what information should be entered in this field. Helps users understand the purpose of the field.","example":"Priority level for the project"},"type":{"type":"string","description":"Field type enum value that determines what kind of input is used. Valid values: Text (single-line), Textarea (multi-line), Number, Date, Checkbox, Select (single choice), MultiSelect (multiple choices).","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"selectOptions":{"description":"Array of select options. REQUIRED for Select and MultiSelect field types. Each option contains a value and translations. Not used for other field types.","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldSelectOptionDto"}},"translations":{"description":"Array of translations for the field name. Each translation contains a language code and translated name. The system automatically displays the correct language based on user preferences.","example":[{"language":"en","name":"Priority Level"},{"language":"de","name":"PrioritΓ€tsstufe"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldTranslationDto"}},"translationsDescriptions":{"description":"Optional array of translations for the field description. Each translation contains a language code and translated description. Used for multilingual help text.","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldTranslationDto"}}},"required":["name","type","translations"]},"UpdateProjectCustomFieldDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the custom field","example":"Priority Level"},"description":{"type":"string","description":"Description of the custom field","example":"Priority level for the project"},"type":{"type":"string","description":"Type of the custom field","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"example":"Select"},"selectOptions":{"description":"Select options (required for Select type fields)","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldSelectOptionDto"}},"translations":{"description":"Translations for the custom field name","example":[{"language":"en","name":"Priority Level"},{"language":"de","name":"PrioritΓ€tsstufe"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldTranslationDto"}},"translationsDescriptions":{"description":"Translations for the custom field description","type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFieldTranslationDto"}}},"required":["name","type","translations"]},"SortProjectCustomFieldsDto":{"type":"object","properties":{"ids":{"description":"Array of custom field IDs in the desired order","example":["field-1","field-2","field-3"],"type":"array","items":{"type":"string"}}},"required":["ids"]},"RestoreProjectSettingsDto":{"type":"object","properties":{"keepCustom":{"type":"boolean","description":"Boolean flag controlling whether custom entries are preserved when restoring defaults. If false (default), all custom categories, statuses, and phases are deleted and only defaults are restored. If true, custom entries are kept and defaults are added alongside them.","example":false,"default":false}},"required":["keepCustom"]},"SupportContingentResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the support contingent (UUID)","example":"550e8400-e29b-41d4-a716-446655440000"},"projectId":{"type":"string","description":"ID of the project this contingent belongs to (UUID)","example":"550e8400-e29b-41d4-a716-446655440001"},"title":{"type":"string","description":"Title or name of the support contingent plan","example":"Maintenance flatrate"},"fromDate":{"type":"string","description":"Start date of the contingent period (ISO 8601 date format)","example":"2025-01-01"},"toDate":{"type":"string","description":"End date of the contingent period (ISO 8601 date format). If not set, the contingent is active forever.","example":"2025-12-31"},"frequency":{"type":"number","description":"Frequency in months for the contingent period","example":12},"price":{"type":"number","description":"Total price for the contingent period","example":10000},"hours":{"type":"number","description":"Total hours allocated for the contingent period","example":120},"rate":{"type":"number","description":"Calculated hourly rate (price / hours). Automatically computed.","example":83.33},"transferable":{"type":"boolean","description":"Whether unused hours can be transferred to the next period","example":false},"createdAt":{"type":"string","description":"ISO 8601 timestamp when the contingent was created","example":"2024-01-15T10:00:00Z"},"updatedAt":{"type":"string","description":"ISO 8601 timestamp when the contingent was last updated","example":"2024-01-20T14:30:00Z"}},"required":["id","projectId","title","fromDate","frequency","price","hours","rate","transferable","createdAt","updatedAt"]},"CreateSupportContingentDto":{"type":"object","properties":{"projectId":{"type":"string","description":"ID of the project this contingent belongs to (UUID)","example":"550e8400-e29b-41d4-a716-446655440001"},"title":{"type":"string","description":"Title or name of the support contingent plan","example":"Maintenance flatrate"},"fromDate":{"type":"string","description":"Start date of the contingent period (ISO 8601 date format)","example":"2025-01-01"},"toDate":{"type":"string","description":"End date of the contingent period (ISO 8601 date format). If not set, the contingent is active forever.","example":"2025-12-31"},"frequency":{"type":"number","description":"Frequency in months for the contingent period","example":12},"price":{"type":"number","description":"Total price for the contingent period","example":10000},"hours":{"type":"number","description":"Total hours allocated for the contingent period","example":120},"transferable":{"type":"boolean","description":"Whether unused hours can be transferred to the next period","example":false}},"required":["projectId","title","fromDate","frequency","price","hours"]},"UpdateSupportContingentDto":{"type":"object","properties":{"title":{"type":"string","description":"Title or name of the support contingent plan","example":"Maintenance flatrate"},"fromDate":{"type":"string","description":"Start date of the contingent period (ISO 8601 date format)","example":"2025-01-01"},"toDate":{"type":"string","description":"End date of the contingent period (ISO 8601 date format). If not set, the contingent is active forever.","example":"2025-12-31"},"frequency":{"type":"number","description":"Frequency in months for the contingent period","example":12},"price":{"type":"number","description":"Total price for the contingent period","example":10000},"hours":{"type":"number","description":"Total hours allocated for the contingent period","example":120},"transferable":{"type":"boolean","description":"Whether unused hours can be transferred to the next period","example":false}},"required":["title","fromDate","frequency","price","hours"]},"PatchSupportContingentDto":{"type":"object","properties":{"title":{"type":"string","description":"Title or name of the support contingent plan","example":"Maintenance flatrate"},"fromDate":{"type":"string","description":"Start date of the contingent period (ISO 8601 date format)","example":"2025-01-01"},"toDate":{"type":"string","description":"End date of the contingent period (ISO 8601 date format)","example":"2025-12-31"},"frequency":{"type":"number","description":"Frequency in months for the contingent period","example":12},"price":{"type":"number","description":"Total price for the contingent period","example":10000},"hours":{"type":"number","description":"Total hours allocated for the contingent period","example":120},"transferable":{"type":"boolean","description":"Whether unused hours can be transferred to the next period","example":false}}},"ImportsGridResponse":{"type":"object","properties":{"items":{"type":"array","description":"Array of import items in the current page. Each item represents a CSV import with its metadata and status.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the import"},"fileName":{"type":"string","nullable":true,"description":"Original name of the uploaded CSV file"},"status":{"type":"string","description":"Current status: \"Uploaded\" (ready), \"Processing\" (running), \"Completed\" (success), or \"Failed\" (error)"},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the import was created"},"importedAt":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601 timestamp when the import finished processing (null if not completed)"},"rowCount":{"type":"number","description":"Total number of data rows in the CSV file"},"columnCount":{"type":"number","description":"Total number of columns in the CSV file"}}}},"total":{"type":"number","description":"Total number of imports matching the current filters (across all pages)","example":42},"page":{"type":"number","description":"Current page number (1-based indexing)","example":1},"pageSize":{"type":"number","description":"Number of items per page in this response","example":100},"viewId":{"type":"string","description":"View identifier for saved grid configurations (e.g., \"all\", \"recent\", custom view name)","example":"all"}},"required":["items","total","page","pageSize","viewId"]},"UploadImportResponseDto":{"type":"object","properties":{"importId":{"type":"string","description":"Unique identifier (UUID) for the newly created import. Use this ID to fetch details, update mappings, or execute the import.","example":"d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"},"fileName":{"type":"string","description":"Original file name of the uploaded CSV file","example":"employees.csv"},"rowCount":{"type":"number","description":"Total number of data rows in the CSV file (excluding header row)","example":150},"columnCount":{"type":"number","description":"Total number of columns detected in the CSV file","example":12},"status":{"type":"string","description":"Current status of the import. Will be \"Uploaded\" immediately after upload, indicating the import is ready for mapping configuration.","example":"Uploaded","enum":["Uploaded","Processing","Completed","Failed"]},"mappings":{"type":"array","description":"AI-generated mapping suggestions in AI format. Each mapping specifies an entity type (e.g., \"Employee\", \"Project\") and suggested field mappings from CSV columns to entity fields. Review and modify these before executing the import.","items":{"type":"object","properties":{"type":{"type":"string","description":"Entity type to import: \"Employee\", \"Organization\", \"OrganizationMember\", \"Project\", \"Task\", or \"TaskComment\""},"fields":{"type":"object","description":"Field mappings object. Keys are entity field names, values contain mapTo (column UUID), optional defaultValue, and optional valueMappings for enums"},"customLookupFields":{"type":"array","items":{"type":"string"},"description":"Optional array of field names (including custom fields like \"customField_abc123\") to use for finding existing records. If not provided, uses entity default lookup fields."}}}},"columns":{"type":"array","description":"Metadata for each column in the CSV file, including column UUID (use this in mappings), name, detected data type, and sample values. Column UUIDs are required when creating field mappings."},"sampleRows":{"type":"array","description":"First 10 rows of data from the CSV file for preview. Useful for understanding the data structure and validating mappings."},"aiMappingSuccess":{"type":"boolean","description":"Indicates whether AI mapping generation completed successfully. If false, mappings array may be empty or incomplete, and you may need to manually configure mappings.","example":true}},"required":["importId","fileName","rowCount","columnCount","status","mappings","columns","sampleRows","aiMappingSuccess"]},"GetImportDetailsResponseDto":{"type":"object","properties":{"importId":{"type":"string","description":"Unique identifier (UUID) of the import","example":"d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"},"fileName":{"type":"object","description":"Original name of the uploaded CSV file","example":"employees.csv","nullable":true},"rowCount":{"type":"number","description":"Total number of data rows in the CSV file (excluding header)","example":150},"columnCount":{"type":"number","description":"Total number of columns detected in the CSV file","example":12},"status":{"type":"string","description":"Current status of the import: \"Uploaded\" (ready), \"Processing\" (running), \"Completed\" (success), or \"Failed\" (error). Check processedEntities vs totalToProcess to see progress during processing.","example":"Uploaded","enum":["Uploaded","Processing","Completed","Failed"]},"createdAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp when the import was created","example":"2024-01-15T10:30:00Z"},"importedAt":{"type":"object","description":"ISO 8601 timestamp when the import finished processing. Null if import has not completed yet.","example":"2024-01-15T10:35:00Z","nullable":true},"mappings":{"type":"array","description":"All current field mappings in AI format. Each mapping specifies entity type, field mappings (CSV column UUIDs to entity fields), value mappings, and custom lookup fields. Use these mappings to understand how CSV data will be imported."},"columns":{"type":"array","description":"Metadata for each CSV column including UUID (required for mappings), name, detected data type, and sample values. Column UUIDs are used in field mappings."},"sampleRows":{"type":"array","description":"First 10 rows of data from the CSV file for preview. Useful for understanding data structure and validating that mappings are correct."},"fileSize":{"type":"object","description":"Size of the uploaded CSV file in bytes","example":52480,"nullable":true},"mimeType":{"type":"object","description":"MIME type of the uploaded file (typically \"text/csv\", \"application/csv\", or \"text/plain\")","example":"text/csv","nullable":true},"processedEntities":{"type":"number","description":"Number of entities that have been processed so far. Compare with totalToProcess to calculate progress percentage. Only meaningful when status is \"Processing\" or \"Completed\".","example":100},"totalToProcess":{"type":"number","description":"Total number of entities that need to be processed. This is calculated based on the number of rows and mappings. Compare with processedEntities to track progress.","example":150},"totalCreatedEntities":{"type":"number","description":"Total number of new entities that were created during import execution. Only available after import completes.","example":80},"totalUpdatedEntities":{"type":"number","description":"Total number of existing entities that were updated during import execution. Only available after import completes.","example":15},"totalSkippedEntities":{"type":"number","description":"Total number of rows that were skipped during import execution (due to validation errors, missing required fields, etc.). Only available after import completes.","example":5}},"required":["importId","fileName","rowCount","columnCount","status","createdAt","importedAt","mappings","columns","sampleRows","fileSize","mimeType","processedEntities","totalToProcess","totalCreatedEntities","totalUpdatedEntities","totalSkippedEntities"]},"UpdateImportMappingsRequestDto":{"type":"object","properties":{"mappings":{"type":"array","description":"Array of mapping configurations in AI format. Each mapping specifies an entity type and how CSV columns map to entity fields. This replaces all existing mappings for the import.","items":{"type":"object","properties":{"type":{"type":"string","description":"Entity type to import: \"Employee\", \"Organization\", \"OrganizationMember\", \"Project\", \"Task\", or \"TaskComment\"","example":"Employee"},"fields":{"type":"object","description":"Field mappings object. Keys are entity field names (or \"customField_{fieldId}\" for custom fields). Values are objects with: mapTo (required, CSV column UUID), defaultValue (optional), and valueMappings (optional, for enum conversions).","example":{"firstName":{"mapTo":"d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"},"lastName":{"mapTo":"a3ff87f4-06e8-5c09-9e6e-09ed2gc80475"},"email":{"mapTo":"b4gg98g5-17f9-6d10-0f7f-10fe3hd91586"},"role":{"mapTo":"c5hh09h6-28g0-7e11-1g8g-21gf4ie02697","valueMappings":{"Manager":"manager","Developer":"developer"}},"customField_abc123":{"mapTo":"d6ii10i7-39h1-8f12-2h9h-32hg5jf13708"}}},"customLookupFields":{"type":"array","items":{"type":"string"},"description":"Optional array of field names to use for finding existing records. Can include built-in fields (e.g., \"email\", \"firstName\") or custom fields (e.g., \"customField_abc123\"). If a record matches on these fields, it will be updated; otherwise, a new record will be created. If not provided, uses the entity's default requiredToUpdate fields.","example":["email"]}}},"example":[{"type":"Employee","fields":{"firstName":{"mapTo":"d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"},"lastName":{"mapTo":"a3ff87f4-06e8-5c09-9e6e-09ed2gc80475"},"email":{"mapTo":"b4gg98g5-17f9-6d10-0f7f-10fe3hd91586"}},"customLookupFields":["email"]}]}},"required":["mappings"]},"UpdateImportMappingsResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the mapping update was successful. If true, all mappings have been saved and validated.","example":true},"mappings":{"type":"array","description":"Updated mappings in AI format, including any automatically added dependency mappings (e.g., Organization mapping if OrganizationMember was specified). Use these mappings to verify the final configuration."}},"required":["success","mappings"]},"ImportSummaryDto":{"type":"object","properties":{"totalRows":{"type":"number","description":"Total number of rows that were processed during the dry-run or execution","example":150},"willCreate":{"type":"number","description":"Number of new entities that will be created (for dry-run) or were created (for execution). These are rows where no matching existing record was found using the lookup fields.","example":100},"willUpdate":{"type":"number","description":"Number of existing entities that will be updated (for dry-run) or were updated (for execution). These are rows where a matching existing record was found using the lookup fields.","example":40},"willSkip":{"type":"number","description":"Number of rows that will be skipped (for dry-run) or were skipped (for execution). These rows had validation errors, missing required fields, or other issues that prevented processing.","example":10},"errors":{"type":"number","description":"Number of rows that have validation errors. These are included in willSkip but counted separately to highlight data quality issues. Check the errors array for detailed error messages.","example":5}},"required":["totalRows","willCreate","willUpdate","willSkip","errors"]},"DryRunResponseDto":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"Always true for dry-run operations. Indicates this is a preview simulation, not an actual execution.","example":true},"mappings":{"type":"array","description":"Detailed results for each entity type mapping. Each result includes lists of entities that will be created (toCreate), updated (toUpdate with old/new values), and skipped (ignored with reasons). Use this to understand exactly what will happen for each entity type."},"summary":{"description":"Summary statistics aggregating results across all mappings. Provides quick overview of total rows, create/update/skip counts, and error count.","allOf":[{"$ref":"#/components/schemas/ImportSummaryDto"}]},"errors":{"type":"array","description":"List of all rows that will be skipped due to errors, including row index, the data from that row, and the specific error message explaining why it will be skipped. Use this to identify and fix data quality issues before execution."}},"required":["dryRun","mappings","summary","errors"]},"ExecuteImportResponseDto":{"type":"object","properties":{"queued":{"type":"boolean","description":"Indicates whether the import has been successfully queued for background processing. If true, the import will start processing asynchronously. Use GET /{importId} to monitor progress.","example":true},"importId":{"type":"string","description":"The import ID (UUID) that was queued. Use this ID with GET /{importId} to check status and monitor progress during background processing.","example":"d2ee76e3-95d7-4b98-8d5d-98dc1fb79364"},"message":{"type":"string","description":"Human-readable message explaining the import status and next steps for tracking progress","example":"Import has been queued for processing. Use GET /{importId} to check status."}},"required":["queued","importId","message"]},"ProjectChartSheetDataDto":{"type":"object","properties":{"headers":{"description":"Column headers for the sheet","example":["Period","Period Label","Value","Cumulative Total"],"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"Data rows as array of objects, where keys match headers. Each row represents one data point.","items":{"type":"object"},"example":[{"Period":"2024-01","Period Label":"Jan 2024","Value":120.5,"Cumulative Total":120.5},{"Period":"2024-02","Period Label":"Feb 2024","Value":135.2,"Cumulative Total":255.7}]},"title":{"type":"object","description":"Sheet title information with main title and subtitle","example":{"main":"Project Insights: Project Name","subtitle":"Jan 2024 - Dec 2024, Time Series, By User, Months, Trend"}}},"required":["headers","rows","title"]},"ProjectChartDataStructuredResponseDto":{"type":"object","properties":{"summary":{"description":"Summary sheet data (wide/matrix format, like pivot table). Periods as rows, breakdown categories as columns.","allOf":[{"$ref":"#/components/schemas/ProjectChartSheetDataDto"}]},"detailed":{"description":"Detailed sheet data (long/tidy format, normalized). One row per period/breakdown combination.","allOf":[{"$ref":"#/components/schemas/ProjectChartSheetDataDto"}]},"metadata":{"type":"object","description":"Metadata about the query execution and results","example":{"queryExecutionTime":234,"totalTimeLogsProcessed":1000,"periodsGenerated":12,"hasMoreData":false}}},"required":["summary","detailed","metadata"]},"StaffChartSheetDataDto":{"type":"object","properties":{"headers":{"description":"Column headers for the sheet","example":["Period","Period Label","Employee","Hours"],"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"Data rows as array of objects, where keys match headers. Each row represents one data point.","items":{"type":"object"},"example":[{"Period":"2024-01","Period Label":"Jan 2024","Employee":"John Doe","Hours":160},{"Period":"2024-02","Period Label":"Feb 2024","Employee":"John Doe","Hours":175}]},"title":{"type":"object","description":"Sheet title information with main title and subtitle","example":{"main":"Staff Insights: John Doe","subtitle":"Comparison, Breakdown by Project, Jan 2024 - Dec 2024, By Months"}}},"required":["headers","rows","title"]},"StaffChartDataStructuredResponseDto":{"type":"object","properties":{"summary":{"description":"Summary sheet data. For COMPARISON model: wide format with periods/staff as rows and breakdown categories as columns. For TOTAL model: categories with hours and percentage.","allOf":[{"$ref":"#/components/schemas/StaffChartSheetDataDto"}]},"detailed":{"description":"Detailed sheet data. For COMPARISON model: long format (normalized) with one row per period/staff/breakdown combination. For TOTAL model: same as summary.","allOf":[{"$ref":"#/components/schemas/StaffChartSheetDataDto"}]},"metadata":{"type":"object","description":"Metadata about the query execution and results","example":{"queryExecutionTime":234,"totalTimeLogsProcessed":480,"periodsGenerated":12,"hasMoreData":false}}},"required":["summary","detailed","metadata"]},"TurnoverChartDataStructuredResponseDto":{"type":"object","properties":{"summary":{"description":"Summary sheet data (wide/matrix format, like pivot table). Layout depends on `model` and `breakdown` (e.g. comparison+byProject vs comparison+byRevenueType vs total).","allOf":[{"$ref":"#/components/schemas/ProjectChartSheetDataDto"}]},"detailed":{"description":"Detailed sheet data (long/tidy format, normalized). One row per period with project and/or revenue-type columns depending on model and breakdown.","allOf":[{"$ref":"#/components/schemas/ProjectChartSheetDataDto"}]},"forecast":{"description":"Forecast sheet data (only present when includeTrend=true and forecast data exists). Contains 6-month revenue forecast based on subscription billing and project deadlines.","allOf":[{"$ref":"#/components/schemas/ProjectChartSheetDataDto"}]},"metadata":{"type":"object","description":"Metadata about the query execution and results","example":{"queryExecutionTime":234,"totalInvoicesProcessed":120,"periodsGenerated":12,"hasMoreData":false}}},"required":["summary","detailed","metadata"]},"GoalChartSheetDataDto":{"type":"object","properties":{"headers":{"description":"Column headers for the sheet","example":["Employee","Attendance Goal","Attendance Actual","Booked Goal","Booked Actual","Billable Goal","Billable Actual"],"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"Data rows as array of objects, where keys match headers. Each row represents one employee or aggregated total.","items":{"type":"object"},"example":[{"Employee":"John Doe","Attendance Goal":160,"Attendance Actual":152,"Booked Goal":160,"Booked Actual":148,"Billable Goal":120,"Billable Actual":115},{"Employee":"Jane Smith","Attendance Goal":160,"Attendance Actual":160,"Booked Goal":160,"Booked Actual":160,"Billable Goal":120,"Billable Actual":125}]},"title":{"type":"object","description":"Sheet title information with main title and subtitle","example":{"main":"Goal Insights - Multiple Staff","subtitle":"This Month | Individual"}}},"required":["headers","rows","title"]},"GoalChartDataStructuredResponseDto":{"type":"object","properties":{"goalProgress":{"description":"Goal progress sheet data: Employee time tracking goals (attendance, booked, billable) with goals and actuals","allOf":[{"$ref":"#/components/schemas/GoalChartSheetDataDto"}]},"valueDistribution":{"description":"Value distribution sheet data: Breakdown of hours by value groups (A, B, C, D)","allOf":[{"$ref":"#/components/schemas/GoalChartSheetDataDto"}]},"metadata":{"type":"object","description":"Metadata about the query execution and results","example":{"queryExecutionTime":234,"totalEmployeesProcessed":2,"attendanceEnabled":true}}},"required":["goalProgress","valueDistribution","metadata"]},"WorkloadChartSheetDataDto":{"type":"object","properties":{"headers":{"description":"Column headers for the sheet","example":["Period Label","Tasks"],"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"Data rows as array of objects, where keys match headers. Each row represents one data point.","items":{"type":"object"},"example":[{"Period Label":"Jan 2024","Tasks":45},{"Period Label":"Feb 2024","Tasks":52}]},"title":{"type":"object","description":"Sheet title information with main title and subtitle","example":{"main":"Workload Insights: Project Name","subtitle":"Over Time, Breakdown by Task Type, Jan 2024 - Dec 2024, By Months"}}},"required":["headers","rows","title"]},"WorkloadChartDataStructuredResponseDto":{"type":"object","properties":{"summary":{"description":"Summary sheet data (simple format). Period labels as rows, task counts as columns.","allOf":[{"$ref":"#/components/schemas/WorkloadChartSheetDataDto"}]},"detailed":{"description":"Detailed sheet data (long/normalized format). One row per period/breakdown combination.","allOf":[{"$ref":"#/components/schemas/WorkloadChartSheetDataDto"}]},"metadata":{"type":"object","description":"Metadata about the query execution and results","example":{"queryExecutionTime":234,"totalTasksProcessed":1000,"periodsGenerated":12,"hasMoreData":false}}},"required":["summary","detailed","metadata"]},"EmailAccountStatus":{"type":"string","enum":["active","token_expired","smtp_error","imap_error","disconnected"],"description":"Current operational status of the account. Indicates whether the account is working correctly or has encountered issues."},"EmailAccountCapabilitiesDto":{"type":"object","properties":{"canEdit":{"type":"boolean","description":"Whether the account can be edited via API. This is `true` for IMAP accounts and `false` for OAuth accounts (Google, Office365) which must be managed through the web application for security reasons.","example":true},"canDelete":{"type":"boolean","description":"Whether the account can be deleted via API. This is `true` for all account types, including OAuth accounts.","example":true},"reason":{"type":"string","description":"Optional reason explaining why certain operations are restricted. This field is only present for OAuth accounts to explain why they cannot be created or updated via API.","example":"OAuth accounts can only be managed through the web application"}},"required":["canEdit","canDelete"]},"EmailAccountResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the email account","example":"123e4567-e89b-12d3-a456-426614174000","format":"uuid"},"email":{"type":"string","description":"Email address associated with this account. Used for sending and receiving emails.","example":"support@example.com"},"displayName":{"type":"object","description":"Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.","example":"Support Team"},"type":{"type":"string","description":"Type of email account. Determines how the account is authenticated and what operations are available via API.","enum":["imap","google","office365"],"example":"imap"},"status":{"description":"Current operational status of the account. Indicates whether the account is working correctly or has encountered issues.","example":"active","allOf":[{"$ref":"#/components/schemas/EmailAccountStatus"}]},"lastError":{"type":"object","description":"Most recent error message, if the account has encountered any issues. This helps diagnose connection or authentication problems.","example":"Failed to connect to SMTP server"},"createdAt":{"type":"string","description":"ISO 8601 timestamp indicating when the account was created","example":"2024-01-15T10:30:00Z","format":"date-time"},"editedAt":{"type":"string","description":"ISO 8601 timestamp indicating when the account was last modified","example":"2024-01-20T14:45:00Z","format":"date-time"},"capabilities":{"description":"Account capabilities indicating what operations can be performed via API. Includes restrictions for OAuth accounts.","allOf":[{"$ref":"#/components/schemas/EmailAccountCapabilitiesDto"}]}},"required":["id","email","type","status","createdAt","editedAt","capabilities"]},"CreateEmailAccountDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address for the account. Must be unique within the workspace and will be used for sending and receiving emails.","example":"support@example.com"},"displayName":{"type":"string","description":"Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.","example":"Support Team"},"imapsHost":{"type":"string","description":"IMAP server hostname for receiving emails. This is the server address where the email client connects to retrieve incoming emails (e.g., \"imap.gmail.com\" for Gmail, \"outlook.office365.com\" for Office365).","example":"imap.example.com"},"imapsPort":{"type":"number","description":"IMAP server port number. Typically 993 for SSL/TLS connections or 143 for unencrypted connections. Must be between 1-65535.","example":993,"minimum":1,"maximum":65535},"imapsUser":{"type":"string","description":"Username for authenticating with the IMAP server. This is typically the full email address, but may vary depending on your email provider.","example":"support@example.com"},"imapsPassword":{"type":"string","description":"Password for authenticating with the IMAP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.","example":"secure-password"},"smtpHost":{"type":"string","description":"SMTP server hostname for sending emails. This is the server address where the email client connects to send outgoing emails (e.g., \"smtp.gmail.com\" for Gmail, \"smtp.office365.com\" for Office365).","example":"smtp.example.com"},"smtpPort":{"type":"number","description":"SMTP server port number. Typically 587 for STARTTLS, 465 for SSL/TLS, or 25 for unencrypted connections. Must be between 1-65535.","example":587,"minimum":1,"maximum":65535},"smtpUser":{"type":"string","description":"Username for authenticating with the SMTP server. This is typically the full email address, but may vary depending on your email provider.","example":"support@example.com"},"smtpPassword":{"type":"string","description":"Password for authenticating with the SMTP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.","example":"secure-password"}},"required":["email","imapsHost","imapsPort","imapsUser","imapsPassword","smtpHost","smtpPort","smtpUser","smtpPassword"]},"UpdateEmailAccountDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address for the account. Must be unique within the workspace and will be used for sending and receiving emails.","example":"support@example.com"},"displayName":{"type":"string","description":"Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.","example":"Support Team"},"imapsHost":{"type":"string","description":"IMAP server hostname for receiving emails. This is the server address where the email client connects to retrieve incoming emails (e.g., \"imap.gmail.com\" for Gmail, \"outlook.office365.com\" for Office365).","example":"imap.example.com"},"imapsPort":{"type":"number","description":"IMAP server port number. Typically 993 for SSL/TLS connections or 143 for unencrypted connections. Must be between 1-65535.","example":993,"minimum":1,"maximum":65535},"imapsUser":{"type":"string","description":"Username for authenticating with the IMAP server. This is typically the full email address, but may vary depending on your email provider.","example":"support@example.com"},"imapsPassword":{"type":"string","description":"Password for authenticating with the IMAP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.","example":"secure-password"},"smtpHost":{"type":"string","description":"SMTP server hostname for sending emails. This is the server address where the email client connects to send outgoing emails (e.g., \"smtp.gmail.com\" for Gmail, \"smtp.office365.com\" for Office365).","example":"smtp.example.com"},"smtpPort":{"type":"number","description":"SMTP server port number. Typically 587 for STARTTLS, 465 for SSL/TLS, or 25 for unencrypted connections. Must be between 1-65535.","example":587,"minimum":1,"maximum":65535},"smtpUser":{"type":"string","description":"Username for authenticating with the SMTP server. This is typically the full email address, but may vary depending on your email provider.","example":"support@example.com"},"smtpPassword":{"type":"string","description":"Password for authenticating with the SMTP server. For some providers, you may need to use an app-specific password instead of your regular account password. This field is never returned in API responses for security reasons.","example":"secure-password"}},"required":["email","imapsHost","imapsPort","imapsUser","imapsPassword","smtpHost","smtpPort","smtpUser","smtpPassword"]},"PatchEmailAccountDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address for the account","example":"support@example.com"},"displayName":{"type":"string","description":"Optional display name for the email account. This name will be shown in the email account list and may be used as the sender name when sending emails.","example":"Support Team"},"imapsHost":{"type":"string","description":"IMAP server hostname","example":"imap.example.com"},"imapsPort":{"type":"number","description":"IMAP server port (typically 993 for SSL)","example":993},"imapsUser":{"type":"string","description":"IMAP username","example":"support@example.com"},"imapsPassword":{"type":"string","description":"IMAP password","example":"secure-password"},"smtpHost":{"type":"string","description":"SMTP server hostname","example":"smtp.example.com"},"smtpPort":{"type":"number","description":"SMTP server port (typically 587 for TLS or 465 for SSL)","example":587},"smtpUser":{"type":"string","description":"SMTP username","example":"support@example.com"},"smtpPassword":{"type":"string","description":"SMTP password","example":"secure-password"}}},"TestEmailSendingDto":{"type":"object","properties":{"testEmailAddress":{"type":"string","description":"Email address where the test email should be sent. This should be a valid email address that you can access to verify the test email was received.","example":"test@example.com"}},"required":["testEmailAddress"]},"TestEmailSendingResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the test email was sent successfully. `true` means the email was sent, `false` means there was an error.","example":true},"message":{"type":"string","description":"Human-readable message describing the test result. Includes success confirmation or error details explaining what went wrong.","example":"Test email sent successfully"}},"required":["success","message"]},"TestEmailReceivingResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates whether the test was successful. `true` means the connection was established and an email was retrieved, `false` means there was an error.","example":true},"message":{"type":"string","description":"Human-readable message describing the test result. Includes success confirmation or error details explaining what went wrong.","example":"Successfully connected and retrieved latest email"},"messageId":{"type":"string","description":"Message ID of the most recent email retrieved from the inbox. This is a unique identifier assigned by the email server.","example":""},"subject":{"type":"string","description":"Subject line of the most recent email retrieved from the inbox.","example":"Test Email Subject"},"from":{"type":"object","description":"Sender email address(es) of the most recent email. Multiple addresses are comma-separated if present.","example":"sender@example.com"},"date":{"type":"string","description":"ISO 8601 timestamp indicating when the most recent email was received.","example":"2024-01-20T10:30:00Z","format":"date-time"}},"required":["success","message"]},"VatRateResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the VAT rate. Use this ID to update or delete the rate. This ID is generated automatically when the rate is created.","example":"123e4567-e89b-12d3-a456-426614174000"},"vat":{"type":"number","description":"The VAT (Value Added Tax) rate percentage currently configured. This is a number between 0 and 100, where 21 represents 21% tax. This is the percentage that will be applied to invoices and quotes created on or after the effective date.","example":21},"dateFrom":{"type":"string","description":"The effective start date for this VAT rate in ISO 8601 format. This date determines when the rate becomes active. The system uses this date to select the correct VAT rate when creating invoices and quotes. The rate with the most recent dateFrom that is less than or equal to the document creation date is used.","example":"2024-01-01T00:00:00.000Z","format":"date-time"},"isDefault":{"type":"boolean","description":"Indicates whether this VAT rate is marked as the default rate for the workspace. Default rates cannot be deleted and typically serve as a fallback option. When true, this rate is protected from deletion operations.","example":false}},"required":["id","vat","dateFrom","isDefault"]},"CreateVatRateDto":{"type":"object","properties":{"vat":{"type":"number","description":"The VAT (Value Added Tax) rate percentage that will be applied to invoices and quotes. This is a number between 0 and 100, where 21 represents 21% tax. The system uses this rate for all documents created on or after the effective date (dateFrom).","example":21,"minimum":0,"maximum":100},"dateFrom":{"type":"string","description":"The effective start date for this VAT rate. This date determines when the rate becomes active. The system automatically applies this rate to all invoices and quotes created on or after this date. You can set a future date to plan ahead for tax law changes. The date must be provided in ISO 8601 format (YYYY-MM-DD). The system validates that this date does not overlap with existing VAT rate periods.","example":"2024-01-01","format":"date"},"isDefault":{"type":"boolean","description":"Whether this VAT rate is the default rate for the workspace. Default rates cannot be deleted and serve as a fallback. If not specified, defaults to false. Only one rate should typically be marked as default, though the system does not enforce this.","example":false,"default":false}},"required":["vat","dateFrom"]},"UpdateVatRateDto":{"type":"object","properties":{"vat":{"type":"number","description":"The VAT (Value Added Tax) rate percentage that will be applied to invoices and quotes. This is a number between 0 and 100, where 21 represents 21% tax. Updating this value changes the tax percentage for all future documents that use this rate.","example":21,"minimum":0,"maximum":100},"dateFrom":{"type":"string","description":"The effective start date for this VAT rate. This date determines when the rate becomes active. Updating this date changes which invoices and quotes will use this rate. The date must be provided in ISO 8601 format (YYYY-MM-DD). The system validates that the updated date does not overlap with other VAT rate periods.","example":"2024-01-01","format":"date"},"isDefault":{"type":"boolean","description":"Whether this VAT rate is the default rate for the workspace. Default rates cannot be deleted and serve as a fallback. If not specified, defaults to false. Only one rate should typically be marked as default, though the system does not enforce this.","example":false,"default":false}},"required":["vat","dateFrom"]},"HelpCenterSearchResultDto":{"type":"object","properties":{"id":{"type":"string","example":"65f8187b4cc7fe3ddf0f1a3a","description":"Gleap article identifier."},"title":{"type":"string","example":"What are task types?","description":"Localized article title returned by Gleap search."},"description":{"type":"string","example":"Learn how task types structure your workflows and required fields.","description":"Short article summary returned by Gleap search."},"helpcenterCollection":{"type":"string","example":"65f818364cc7fe3ddf0f195a","description":"Gleap help center collection identifier."},"docId":{"type":"number","example":1234,"description":"Human-friendly Gleap document number."},"relevanceScore":{"type":"number","example":12.345678,"description":"Search relevance score from Gleap."}},"required":["id","title","description","helpcenterCollection","docId","relevanceScore"]},"HelpCenterSearchResponseDto":{"type":"object","properties":{"searchTerm":{"type":"string","example":"task types","description":"Echo of the submitted search term."},"totalResults":{"type":"number","example":2,"description":"Number of returned search results."},"results":{"description":"Matching help center articles.","type":"array","items":{"$ref":"#/components/schemas/HelpCenterSearchResultDto"}}},"required":["searchTerm","totalResults","results"]},"HelpCenterArticleResponseDto":{"type":"object","properties":{"id":{"type":"string","example":"65f8187b4cc7fe3ddf0f1a3a","description":"Gleap article identifier."},"title":{"type":"string","example":"What are task types?","description":"Localized article title."},"description":{"type":"string","example":"Learn how task types structure your workflows and required fields.","description":"Localized article summary."},"content":{"type":"string","example":"Task types define the workflow, fields, and statuses used when creating tasks.","description":"Plain-text article body for the selected language."},"docId":{"type":"number","example":1234,"description":"Human-friendly Gleap document number."},"isDraft":{"type":"boolean","example":false,"description":"Whether the article is currently a draft in Gleap."},"tags":{"example":["tasks","workflow"],"description":"Article tags returned by Gleap.","type":"array","items":{"type":"string"}},"lastUpdated":{"type":"string","example":"2026-03-01T11:22:33.000Z","description":"Last update timestamp from Gleap."}},"required":["id","title","description","content","docId","isDraft","tags","lastUpdated"]},"QuestionOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Option ID (for updates)","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"title":{"type":"string","description":"Option title. For Checkbox questions, users can select multiple options. For Radio questions, users can select only one option.","example":"Option A"},"extraHours":{"type":"number","description":"Extra hours for this option. When this option is selected (for Checkbox/Radio questions), this value is added to the effort calculation.","example":2.5}},"required":["title"]},"QuestionConditionDto":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID (for updates)","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"type":{"type":"string","description":"Condition type. Conditions control when items or questions are visible/active:\n- **QuestionAnswered/QuestionNotAnswered**: Based on whether a question is answered\n- **QuestionAnswerEqual/QuestionAnswerDoesNotEqual**: Based on specific answer value\n- **QuestionAnswerContains/QuestionAnswerDoesNotContain**: Based on answer containing values\n- **TodoIsDone/TodoIsNotDone**: Based on todo completion status\n- **TestCasePassed/TestCaseFailed**: Based on test case evaluation","enum":["QuestionAnswered","QuestionNotAnswered","QuestionAnswerContains","QuestionAnswerDoesNotContain","QuestionAnswerEqual","QuestionAnswerDoesNotEqual","TodoIsDone","TodoIsNotDone","TestCasePassed","TestCaseFailed"],"example":"QuestionAnswered"},"targetQuestionId":{"type":"string","description":"Target question ID","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"targetTodoId":{"type":"string","description":"Target todo ID","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"targetTestCaseId":{"type":"string","description":"Target test case ID","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"targetValue":{"type":"string","description":"Target value","example":"Yes"},"containsType":{"type":"string","description":"Contains type","enum":["Some","All"],"example":"Some"}},"required":["type"]},"CreateQuestionDto":{"type":"object","properties":{"id":{"type":"string","description":"Question ID (for updates - if provided, updates existing question)","example":"e57dc37b-7693-4d06-b49c-17084b773aff"},"title":{"type":"string","description":"Question title/heading. Questions capture customer-specific requirements or project details. They make work packages flexible and reusable by allowing later individualization in projects.","example":"What is the expected performance?"},"question":{"type":"string","description":"The question text that will be displayed to users. This is the actual question being asked (e.g., \"Please specify the expected response time\").","example":"Please specify the expected response time"},"description":{"type":"string","description":"Question description (accepts HTML or Markdown, returns HTML)","example":"This question helps us understand performance requirements.
"},"type":{"type":"string","description":"Question type. Questions can be:\n- **ShortText**: Single-line text input\n- **Editor**: Formatted multi-line text\n- **Checkbox**: Yes/No selection (can impact effort)\n- **Radio**: Single choice from options (can impact effort)\n- **Files**: Upload files\n- **Datepicker**: Select a date\n- **Multiplier**: Dynamic calculation (quantity Γ duration per element)\n- **Person**: Select person(s) from team","enum":["ShortText","Editor","Checkbox","Radio","Files","Datepicker","Multiplier","Person"],"example":"ShortText"},"options":{"description":"Question options (required for Checkbox/Radio types, must have at least one option). Each option can have an extraHours value that affects effort calculation when selected.","type":"array","items":{"$ref":"#/components/schemas/QuestionOptionDto"}},"multiplierValue":{"type":"number","description":"Multiplier value (for Multiplier type). This is the duration per element (e.g., hours per page). When answered, the system calculates: Answer Γ multiplierValue = Total additional effort.","example":1.5},"conditions":{"description":"Question conditions that control visibility/behavior. Conditions can show/hide questions based on answers to other questions, todo completion, or test case status.","type":"array","items":{"$ref":"#/components/schemas/QuestionConditionDto"}}},"required":["title","question","type"]},"UpdateQuestionDto":{"type":"object","properties":{"title":{"type":"string","description":"Question title/heading. Questions capture customer-specific requirements or project details.","example":"What is the expected performance?"},"question":{"type":"string","description":"The question text that will be displayed to users.","example":"Please specify the expected response time"},"description":{"type":"string","description":"Question description (accepts HTML or Markdown, returns HTML)","example":"This question helps us understand performance requirements.
"},"type":{"type":"string","description":"Question type. Questions can be:\n- **ShortText**: Single-line text input\n- **Editor**: Formatted multi-line text\n- **Checkbox**: Yes/No selection (can impact effort)\n- **Radio**: Single choice from options (can impact effort)\n- **Files**: Upload files\n- **Datepicker**: Select a date\n- **Multiplier**: Dynamic calculation (quantity Γ duration per element)\n- **Person**: Select person(s) from team","enum":["ShortText","Editor","Checkbox","Radio","Files","Datepicker","Multiplier","Person"]},"options":{"description":"Question options (required for Checkbox/Radio types)","type":"array","items":{"$ref":"#/components/schemas/QuestionOptionDto"}},"multiplierValue":{"type":"number","description":"Multiplier value (for Multiplier type). This is the duration per element (e.g., hours per page). When answered, the system calculates: Answer Γ multiplierValue = Total additional effort.","example":1.5},"conditions":{"description":"Question conditions that control visibility/behavior. Conditions can show/hide questions based on answers to other questions, todo completion, or test case status.","type":"array","items":{"$ref":"#/components/schemas/QuestionConditionDto"}}}},"SortQuestionsDto":{"type":"object","properties":{"newSortOrder":{"description":"Array of question IDs in new order. All questions for the item must be included in the desired display order.","example":["e57dc37b-7693-4d06-b49c-17084b773aff","f68ed48c-8704-5e17-c5ad-28195c884b00"],"type":"array","items":{"type":"string"}}},"required":["newSortOrder"]},"CreateComponentDto":{"type":"object","properties":{"name":{"type":"string","description":"Component name","example":"User Authentication Module"},"icon":{"type":"object","description":"Icon identifier. Format: :icon_name: (e.g., :rocket:, :box:, :star:)","example":":box:","nullable":true},"description":{"type":"string","description":"Description (HTML or Markdown)","example":"This module handles user authentication and authorization.
"},"tags":{"description":"Tag UUIDs","example":["550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note (HTML or Markdown, optional)","example":"Internal implementation notes.
"}},"required":["name","description"]},"SaveComponentItemConditionDto":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID (optional, for updates)","example":"550e8400-e29b-41d4-a716-446655440013","nullable":true},"type":{"type":"string","description":"Condition type","enum":["QuestionAnswered","QuestionNotAnswered","QuestionAnswerContains","QuestionAnswerDoesNotContain","QuestionAnswerEqual","QuestionAnswerDoesNotEqual","TodoIsDone","TodoIsNotDone","TestCasePassed","TestCaseFailed"],"example":"QuestionAnswered"},"targetQuestionId":{"type":"string","description":"Target question ID (optional)","example":"550e8400-e29b-41d4-a716-446655440014","nullable":true},"targetTodoId":{"type":"string","description":"Target todo ID (optional)","example":"550e8400-e29b-41d4-a716-446655440015","nullable":true},"targetTestCaseId":{"type":"string","description":"Target test case ID (optional)","example":"550e8400-e29b-41d4-a716-446655440016","nullable":true},"targetValue":{"type":"string","description":"Target value (optional)","example":"option-value","nullable":true},"containsType":{"type":"string","description":"Contains type","enum":["Some","All"],"example":"Some"}},"required":["type","containsType"]},"CreateLibraryComponentItemDto":{"type":"object","properties":{"componentId":{"type":"string","description":"Parent component ID","example":"550e8400-e29b-41d4-a716-446655440000"},"parentId":{"type":"string","description":"Parent item ID (optional, for nested items)","example":null,"nullable":true},"type":{"type":"string","description":"Type of component item","enum":["Epic","WorkPackage","TodoList","TestSuite"],"example":"Epic"},"name":{"type":"string","description":"Name of the component item","example":"User Authentication Epic"},"icon":{"type":"object","description":"Icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:check:`, `:star:`). Optional.","example":":check:","nullable":true},"timeFrame":{"type":"number","description":"Time frame in hours (required for all types except Epic)","example":20},"description":{"type":"string","description":"Description in HTML or Markdown format (will be converted to IDoc)","example":"Epic description in HTML
"},"tags":{"description":"Array of tag UUIDs (optional)","example":["550e8400-e29b-41d4-a716-446655440020"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note in HTML or Markdown format (optional, will be converted to IDoc)","example":"Internal implementation notes
","nullable":true},"includeInSpecification":{"type":"boolean","description":"Whether to include in specification","example":true},"conditions":{"description":"Array of conditions (optional)","type":"array","items":{"$ref":"#/components/schemas/SaveComponentItemConditionDto"}}},"required":["componentId","type","name","description","includeInSpecification"]},"CreateLibraryComponentItemResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":true},"id":{"type":"string","description":"Created item ID","example":"550e8400-e29b-41d4-a716-446655440001"}},"required":["success","id"]},"ComponentTreeComponentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the component","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Name of the component","example":"User Authentication Module"},"icon":{"type":"object","description":"Icon identifier for the component (nullable). Format: :icon_name: (e.g., :rocket:, :box:, :star:)","example":":box:","nullable":true},"totalTimeFrame":{"type":"number","description":"Total time frame for the component","example":40}},"required":["id","name","icon","totalTimeFrame"]},"ComponentTreeItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the component item","example":"550e8400-e29b-41d4-a716-446655440001"},"name":{"type":"string","description":"Name of the component item","example":"Login Feature"},"icon":{"type":"object","description":"Icon identifier for the component item (nullable). Format: :icon_name: (e.g., :rocket:, :check:, :star:)","example":":check:","nullable":true},"type":{"type":"string","description":"Type of the component item. Items are the building blocks within components:\n- **Epic**: Groups related work packages around a common theme\n- **WorkPackage**: Self-contained task that delivers a tangible result\n- **TodoList**: Checklist of sub-steps or checkpoints\n- **TestSuite**: Formal acceptance tests with test cases","enum":["Epic","WorkPackage","TodoList","TestSuite"],"example":"Epic"},"componentId":{"type":"string","description":"ID of the parent component","example":"550e8400-e29b-41d4-a716-446655440000"},"parentId":{"type":"object","description":"ID of the parent item (nullable for top-level items)","example":null,"nullable":true},"conditionsValid":{"type":"boolean","description":"Whether all conditions are valid for this item","example":true},"failedConditionsIds":{"description":"Array of failed condition IDs","example":[],"type":"array","items":{"type":"string"}},"totalEstimate":{"type":"number","description":"Total time estimate for the item","example":20}},"required":["id","name","icon","type","componentId","parentId","conditionsValid","failedConditionsIds","totalEstimate"]},"ComponentLibraryTreeResponseDto":{"type":"object","properties":{"components":{"description":"List of components in the library","type":"array","items":{"$ref":"#/components/schemas/ComponentTreeComponentDto"}},"items":{"description":"List of items (Epics, Work Packages, Todo Lists, Test Suites) in the library. Items are the building blocks within components and can be nested to any depth.","type":"array","items":{"$ref":"#/components/schemas/ComponentTreeItemDto"}}},"required":["components","items"]},"ComponentChildrenShortItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier","example":"550e8400-e29b-41d4-a716-446655440001"},"name":{"type":"string","description":"Name of the item","example":"Login Feature"},"icon":{"type":"object","description":"Icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:check:`, `:star:`). Can be null if no icon is set.","example":":check:","nullable":true},"type":{"type":"string","description":"Type of the component item. Items are the building blocks within components:\n- **Epic**: Groups related work packages around a common theme\n- **WorkPackage**: Self-contained task that delivers a tangible result\n- **TodoList**: Checklist of sub-steps or checkpoints\n- **TestSuite**: Formal acceptance tests with test cases","enum":["Epic","WorkPackage","TodoList","TestSuite"],"example":"Epic"},"conditionsValid":{"type":"boolean","description":"Whether all conditions are valid","example":true},"entityUniqueId":{"type":"string","description":"Entity unique ID","example":"unique-id-123"},"taskId":{"type":"object","description":"Task ID if linked to a task","example":"550e8400-e29b-41d4-a716-446655440002","nullable":true},"taskShortNumber":{"type":"object","description":"Task short number if linked to a task","example":123,"nullable":true},"testCasesCount":{"type":"number","description":"Count of test cases","example":3},"todosCount":{"type":"number","description":"Count of todo items","example":5},"questionsCount":{"type":"number","description":"Count of questions","example":2},"children":{"description":"Nested children items","type":"array","items":{"$ref":"#/components/schemas/ComponentChildrenShortItemDto"}}},"required":["id","name","icon","type","conditionsValid","entityUniqueId","taskId","taskShortNumber","testCasesCount","todosCount","questionsCount","children"]},"ComponentDetailsResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the component","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Name of the component","example":"User Authentication Module"},"projectId":{"type":"object","description":"Project ID (null for library components)","example":null,"nullable":true},"icon":{"type":"object","description":"Icon identifier (nullable)","example":"faBox","nullable":true},"description":{"type":"string","description":"Component description in HTML format","example":"This module handles user authentication and authorization.
"},"tags":{"description":"Array of tags","example":["authentication","security"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note in HTML format","example":"Internal implementation notes.
"},"children":{"description":"Array of direct children items","type":"array","items":{"$ref":"#/components/schemas/ComponentChildrenShortItemDto"}},"discountAmount":{"type":"number","description":"Discount amount applied to this component. 0 means no discount.","example":10},"discountType":{"type":"string","description":"Type of discount: \"Fixed\" (fixed amount) or \"Percentage\" (percentage of total price)","enum":["Fixed","Percentage"],"example":"Percentage"}},"required":["id","name","projectId","icon","description","tags","internalNote","children","discountAmount","discountType"]},"PatchComponentDto":{"type":"object","properties":{"name":{"type":"string","description":"Component name","example":"User Authentication Module"},"description":{"type":"string","description":"Component description (HTML or Markdown)","example":"This component handles user authentication and authorization.
"},"icon":{"type":"object","description":"Icon identifier (can be set to null). Format: :icon_name: (e.g., :rocket:, :box:, :star:)","example":":box:","nullable":true},"tags":{"description":"Array of tag IDs","example":["550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note (HTML or Markdown)","example":"Implementation notes for the development team.
"}}},"ComponentTestCaseDto":{"type":"object","properties":{"id":{"type":"string","description":"Test case ID","example":"550e8400-e29b-41d4-a716-446655440010"},"title":{"type":"string","description":"Test case title","example":"Test login with valid credentials"},"description":{"type":"string","description":"Test case description in HTML format","example":"Verify that users can log in with valid credentials.
"},"steps":{"type":"string","description":"Test steps in HTML format","example":"- Navigate to login page
- Enter credentials
- Click login button
"},"expectedResult":{"type":"string","description":"Expected result in HTML format","example":"User is successfully logged in and redirected to dashboard.
"},"testComment":{"type":"string","description":"Test comment in HTML format (optional)","example":"Test passed successfully.
","nullable":true},"testStatus":{"type":"string","description":"Test status (optional)","enum":["Passed","PassedWithReservations","Failed"],"example":"Passed","nullable":true},"testedBy":{"type":"string","description":"User ID who tested (optional)","example":"550e8400-e29b-41d4-a716-446655440020","nullable":true},"testedAt":{"type":"string","description":"Date when tested (optional)","example":"2024-01-01T00:00:00.000Z","nullable":true}},"required":["id","title","description","steps","expectedResult"]},"ComponentTodoItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Todo item ID","example":"550e8400-e29b-41d4-a716-446655440011"},"title":{"type":"string","description":"Todo item title. Todos are checklist items used to track actionable tasks within component items. They are perfect for recurring processes, quality control checkpoints, and project preparation steps.","example":"Implement password reset"},"description":{"type":"string","description":"Todo item description in HTML format","example":"Add password reset functionality to the authentication module.
"},"isDone":{"type":"boolean","description":"Whether the todo is marked as done","example":false},"doneBy":{"type":"object","description":"User ID who marked as done (nullable)","example":"550e8400-e29b-41d4-a716-446655440020","nullable":true},"doneUpdatedAt":{"type":"object","description":"Date when marked as done (nullable)","example":"2024-01-01T00:00:00.000Z","nullable":true},"todoComment":{"type":"object","description":"Todo comment in HTML format (nullable)","example":"Completed ahead of schedule.
","nullable":true}},"required":["id","title","description","isDone","doneBy","doneUpdatedAt","todoComment"]},"ComponentQuestionOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Option ID","example":"550e8400-e29b-41d4-a716-446655440012"},"title":{"type":"string","description":"Option title","example":"Two-factor authentication"},"extraHours":{"type":"number","description":"Extra hours for this option (optional)","example":8,"nullable":true},"isSelected":{"type":"boolean","description":"Whether this option is selected (optional)","example":true,"nullable":true}},"required":["id","title"]},"ComponentQuestionDto":{"type":"object","properties":{"id":{"type":"string","description":"Question ID","example":"550e8400-e29b-41d4-a716-446655440017"},"title":{"type":"string","description":"Question title","example":"Security Features"},"question":{"type":"string","description":"Question text","example":"Which security features should be implemented?"},"description":{"type":"string","description":"Question description in HTML format","example":"Select all security features that apply.
"},"type":{"type":"string","description":"Question type","enum":["ShortText","Editor","Checkbox","Radio","Files","Datepicker","Multiplier","Person"],"example":"Checkbox"},"options":{"description":"Available options","type":"array","items":{"$ref":"#/components/schemas/ComponentQuestionOptionDto"}},"editorAnswer":{"type":"string","description":"Editor answer in HTML format (optional)","example":"Two-factor authentication is required.
","nullable":true},"isAnswered":{"type":"boolean","description":"Whether the question has been answered","example":true},"answeredBy":{"type":"string","description":"User ID who answered (optional)","example":"550e8400-e29b-41d4-a716-446655440020","nullable":true},"answeredAt":{"type":"string","description":"Date when answered (optional)","example":"2024-01-01T00:00:00.000Z","nullable":true}},"required":["id","title","question","description","type","options","isAnswered"]},"ComponentItemConditionDto":{"type":"object","properties":{"id":{"type":"string","description":"Condition ID (optional)","example":"550e8400-e29b-41d4-a716-446655440013","nullable":true},"type":{"type":"string","description":"Condition type","enum":["QuestionAnswered","QuestionNotAnswered","QuestionAnswerContains","QuestionAnswerDoesNotContain","QuestionAnswerEqual","QuestionAnswerDoesNotEqual","TodoIsDone","TodoIsNotDone","TestCasePassed","TestCaseFailed"],"example":"QuestionAnswered"},"targetQuestionId":{"type":"string","description":"Target question ID (optional)","example":"550e8400-e29b-41d4-a716-446655440014","nullable":true},"targetTodoId":{"type":"string","description":"Target todo ID (optional)","example":"550e8400-e29b-41d4-a716-446655440015","nullable":true},"targetTestCaseId":{"type":"string","description":"Target test case ID (optional)","example":"550e8400-e29b-41d4-a716-446655440016","nullable":true},"targetValue":{"type":"string","description":"Target value (optional)","example":"option-value","nullable":true},"containsType":{"type":"string","description":"Contains type","enum":["Some","All"],"example":"Some"}},"required":["type","containsType"]},"ComponentItemDetailsResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Item ID","example":"550e8400-e29b-41d4-a716-446655440001"},"entityUniqueId":{"type":"string","description":"Entity unique ID","example":"unique-id-123"},"name":{"type":"string","description":"Item name","example":"Login Feature"},"icon":{"type":"object","description":"Icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:check:`, `:star:`). Can be null if no icon is set.","example":":check:","nullable":true},"description":{"type":"string","description":"Item description in HTML format","example":"Feature for user authentication.
"},"tags":{"description":"Array of tags","example":["authentication","login"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note in HTML format","example":"Implementation notes.
"},"includeInSpecification":{"type":"boolean","description":"Whether to include in specification","example":true},"componentId":{"type":"string","description":"Parent component ID","example":"550e8400-e29b-41d4-a716-446655440000"},"parentId":{"type":"object","description":"Parent item ID (nullable for top-level items)","example":null,"nullable":true},"type":{"type":"string","description":"Item type","enum":["Epic","WorkPackage","TodoList","TestSuite"],"example":"Epic"},"testCases":{"description":"Test cases associated with this item. Test cases are individual test steps within a Test Suite that document formal review and approval criteria.","type":"array","items":{"$ref":"#/components/schemas/ComponentTestCaseDto"}},"todoItems":{"description":"Todo items associated with this item. Todos are checklist items that can be checked off individually and support comments.","type":"array","items":{"$ref":"#/components/schemas/ComponentTodoItemDto"}},"questions":{"description":"Questions associated with this item. Questions capture customer requirements and can affect effort calculation. In library components, questions are defined but not answered.","type":"array","items":{"$ref":"#/components/schemas/ComponentQuestionDto"}},"conditions":{"description":"Conditions for this item","type":"array","items":{"$ref":"#/components/schemas/ComponentItemConditionDto"}},"conditionsValid":{"type":"boolean","description":"Whether all conditions are valid","example":true},"failedConditionsIds":{"description":"Array of failed condition IDs","example":[],"type":"array","items":{"type":"string"}},"timeFrame":{"type":"number","description":"Time frame in hours","example":40},"children":{"description":"Nested children items","type":"array","items":{"$ref":"#/components/schemas/ComponentChildrenShortItemDto"}},"taskId":{"type":"object","description":"Task ID if linked to a task","example":"550e8400-e29b-41d4-a716-446655440002","nullable":true},"taskShortNumber":{"type":"object","description":"Task short number if linked to a task","example":123,"nullable":true}},"required":["id","entityUniqueId","name","icon","description","tags","internalNote","includeInSpecification","componentId","parentId","type","testCases","todoItems","questions","conditions","conditionsValid","failedConditionsIds","timeFrame","children","taskId","taskShortNumber"]},"CreateComponentTodoDto":{"type":"object","properties":{"title":{"type":"string","description":"Todo title","example":"Implement authentication"},"description":{"type":"string","description":"Todo description in HTML or Markdown format","example":"Add user login functionality
"}},"required":["title","description"]},"TodoOperationResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status","example":true},"id":{"type":"string","description":"ID of the updated todo","example":"550e8400-e29b-41d4-a716-446655440001"}},"required":["success"]},"UpdateComponentTodoDto":{"type":"object","properties":{"title":{"type":"string","description":"Todo title","example":"Implement authentication with 2FA"},"description":{"type":"string","description":"Todo description in HTML or Markdown format","example":"Add user login with two-factor authentication
"}}},"SortComponentTodosDto":{"type":"object","properties":{"newSortOrder":{"description":"Array of todo IDs in the new sort order","example":["550e8400-e29b-41d4-a716-446655440001","550e8400-e29b-41d4-a716-446655440002"],"type":"array","items":{"type":"string"}}},"required":["newSortOrder"]},"CreateComponentTestCaseDto":{"type":"object","properties":{"title":{"type":"string","description":"Test case title. Test cases are individual test steps within a Test Suite. They document formal review and approval criteria for project results.","example":"Test login with valid credentials"},"description":{"type":"string","description":"Test case description in HTML or Markdown format","example":"Verify that users can log in with valid credentials.
"},"steps":{"type":"string","description":"Test steps in HTML or Markdown format","example":"- Navigate to login page
- Enter credentials
- Click login button
"},"expectedResult":{"type":"string","description":"Expected result in HTML or Markdown format","example":"User is successfully logged in and redirected to dashboard.
"}},"required":["title","description","steps","expectedResult"]},"ComponentTestCaseResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Test case ID","example":"550e8400-e29b-41d4-a716-446655440010"},"title":{"type":"string","description":"Test case title","example":"Test login with valid credentials"},"description":{"type":"string","description":"Test case description in HTML format","example":"Verify that users can log in with valid credentials.
"},"steps":{"type":"string","description":"Test steps in HTML format","example":"- Navigate to login page
- Enter credentials
- Click login button
"},"expectedResult":{"type":"string","description":"Expected result in HTML format","example":"User is successfully logged in and redirected to dashboard.
"},"sort":{"type":"number","description":"Sort order","example":1},"testComment":{"type":"string","description":"Test comment in HTML format (optional)","example":"Test passed successfully.
","nullable":true},"testStatus":{"type":"string","description":"Test status (optional)","enum":["Passed","PassedWithReservations","Failed"],"example":"Passed","nullable":true},"testedBy":{"type":"string","description":"User ID who tested (optional)","example":"550e8400-e29b-41d4-a716-446655440020","nullable":true},"testedAt":{"type":"string","description":"Date when tested (optional)","example":"2024-01-01T00:00:00.000Z","nullable":true}},"required":["id","title","description","steps","expectedResult","sort"]},"UpdateComponentTestCaseDto":{"type":"object","properties":{"title":{"type":"string","description":"Test case title","example":"Test login with valid credentials"},"description":{"type":"string","description":"Test case description in HTML or Markdown format","example":"Verify that users can log in with valid credentials.
"},"steps":{"type":"string","description":"Test steps in HTML or Markdown format","example":"- Navigate to login page
- Enter credentials
- Click login button
"},"expectedResult":{"type":"string","description":"Expected result in HTML or Markdown format","example":"User is successfully logged in and redirected to dashboard.
"}}},"SortComponentTestCasesDto":{"type":"object","properties":{"newSortOrder":{"description":"Array of testcase IDs in desired order","example":["550e8400-e29b-41d4-a716-446655440010","550e8400-e29b-41d4-a716-446655440011","550e8400-e29b-41d4-a716-446655440012"],"type":"array","items":{"type":"string"}}},"required":["newSortOrder"]},"PatchLibraryComponentItemDto":{"type":"object","properties":{"componentId":{"type":"string","description":"ID of the component this item belongs to","example":"550e8400-e29b-41d4-a716-446655440000"},"parentId":{"type":"string","description":"ID of parent item for nested items","example":"550e8400-e29b-41d4-a716-446655440000"},"type":{"type":"string","description":"Type of item (Epic, WorkPackage, TodoList, TestSuite)","example":"WorkPackage","enum":["Epic","WorkPackage","TodoList","TestSuite"]},"name":{"type":"string","description":"Name of the item","example":"User Authentication Feature"},"icon":{"type":"object","description":"Icon identifier (can be set to null). Format: :icon_name: (e.g., :rocket:, :check:, :star:)","example":":check:","nullable":true},"timeFrame":{"type":"number","description":"Time frame in hours. Required for all types except Epic (when type is provided)","example":40},"description":{"type":"string","description":"Description in HTML or Markdown format (will be converted to IDoc if provided)","example":"Implement user authentication and authorization
"},"tags":{"description":"Array of tag UUIDs","example":["550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}},"internalNote":{"type":"string","description":"Internal note in HTML or Markdown format (will be converted to IDoc if provided)","example":"Implementation notes for the development team
"},"includeInSpecification":{"type":"boolean","description":"Whether to include in specification","example":true},"conditions":{"description":"Array of conditions (full array replaces existing conditions)","type":"array","items":{"$ref":"#/components/schemas/SaveComponentItemConditionDto"}}}},"DeleteComponentItemResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":true}},"required":["success"]},"SaveComponentsSortDto":{"type":"object","properties":{}},"DuplicateComponentResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"UUID of the newly created duplicate component","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["id"]},"TagResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier (UUID) of the tag. Use this ID when updating or deleting the tag.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"The display name of the tag. This is what users see when the tag is applied to tasks, projects, or components.","example":"urgent"},"color":{"type":"string","description":"The predefined color code assigned to the tag for visual organization. Null if no color has been set. Colors help users quickly identify tags in lists and cards.\n\n**Available color values:**\n- `default` - Light gray (default color)\n- `red` - Red\n- `yellow` - Yellow\n- `green` - Green\n- `blue` - Blue\n- `purple` - Purple\n- `fuchsia` - Fuchsia\n- `pink` - Pink\n- `magenta` - Magenta","enum":["default","red","yellow","green","blue","purple","fuchsia","pink","magenta",null],"example":"blue","nullable":true},"isDeleted":{"type":"boolean","description":"Indicates whether the tag has been soft-deleted. Soft-deleted tags are marked as deleted but not permanently removed from the database. They will not appear in list endpoints and are automatically removed from all associated entities.","example":false}},"required":["id","name","color","isDeleted"]},"CreateTagDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the tag to create. Must be unique within the tag type (case-insensitive). If a tag with this name already exists, the existing tag will be returned instead of creating a duplicate. Use descriptive names that clearly indicate the topic or process (e.g., \"Billing\", \"Support\", \"Onboarding\").","example":"urgent"}},"required":["name"]},"SaveTagDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier (UUID) of the tag to update. This identifies which existing tag you want to modify.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"The new name for the tag. Must be unique within the tag type (case-insensitive). If you change the name, all entities using this tag will automatically reflect the new name.","example":"urgent"},"color":{"type":"string","description":"Optional predefined color code for visual organization of the tag. Must be one of the predefined color values from the palette. Colors help visually distinguish tags in lists and cards. If not provided, the tag will have no color.\n\n**Available color values:**\n- `default` - Light gray (default color)\n- `red` - Red\n- `yellow` - Yellow\n- `green` - Green\n- `blue` - Blue\n- `purple` - Purple\n- `fuchsia` - Fuchsia\n- `pink` - Pink\n- `magenta` - Magenta","enum":["default","red","yellow","green","blue","purple","fuchsia","pink","magenta"],"example":"blue"}},"required":["id","name"]},"AttachTaskFormInstanceDto":{"type":"object","properties":{"templateId":{"type":"string","format":"uuid","description":"ID of the form template to attach. List templates (each includes `id`) via GET `/workspace/form-templates` or GET `/administration/form-templates-available`. Optional: inspect field definitions before attach with GET `/workspace/form-templates/{id}`."}},"required":["templateId"]},"PatchTaskFormInstanceDto":{"type":"object","properties":{"values":{"type":"object","additionalProperties":true,"description":"Map of field keys to submitted values. Each key must match the `valueKey` of a field on this instance (see GET `/tasks/{identifier}/form-instances` β `fields[].valueKey`). `valueKey` is the template field `key` when set, otherwise the field UUID. To learn types, required flags, and allowed options before editing, use GET `/workspace/form-templates/{templateId}` (use `templateId` from the instance) or read `fields` from the list response."}},"required":["values"]},"ProductSettingOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"UUID of the product option. This identifies which option (e.g., \"Color\", \"Size\", \"Support Level\") is being configured.","example":"d8d9f2c3-5e8a-4f6b-9c7d-3e4f5a6b7c8d"},"value":{"description":"Array of UUIDs representing the selected option values. For example, if the option is \"Color\", this array might contain IDs for \"Blue\" and \"Red\" if multiple selections are allowed. Each value ID must be a valid UUID.","example":["550e8400-e29b-41d4-a716-446655440005"],"type":"array","items":{"type":"string"}}},"required":["id","value"]},"ImportProductToTaskDto":{"type":"object","properties":{"productId":{"type":"string","description":"UUID of the product from your workspace product catalog. The product must exist in the catalog and not be already assigned to a task or project. This product will be copied into the task.","example":"550e8400-e29b-41d4-a716-446655440002"},"quantity":{"type":"number","description":"Number of units of this product to add to the task. Must be at least 1. For example, if importing a \"Workshop\" product, quantity 2 means two workshops.","example":2,"minimum":1},"activeVariantId":{"type":"object","description":"UUID of the variant to activate when importing. Optional - only needed if the product has multiple variants (e.g., Standard, Pro, Enterprise). If not provided, the first variant will be active by default.","example":"550e8400-e29b-41d4-a716-446655440003","nullable":true},"options":{"description":"Array of option selections for this product. Each option specifies which values are selected. For example, if a product has a \"Support Level\" option with values \"Basic\" and \"Premium\", you would include the option ID and select one or more value IDs. Required even if empty array.","example":[{"id":"550e8400-e29b-41d4-a716-446655440004","value":["550e8400-e29b-41d4-a716-446655440005"]}],"type":"array","items":{"$ref":"#/components/schemas/ProductSettingOptionDto"}},"activeFromType":{"type":"string","description":"Type of activation start for the product. Immediately means it starts right away, ProjectBilling means it starts with project billing, FixedDate means it starts on a specific date.","enum":["Immediately","ProjectBilling","FixedDate"],"example":"Immediately"},"activeFromFixedDate":{"type":"string","description":"Fixed start date when activeFromType is FixedDate. Format: ISO 8601 date (YYYY-MM-DD). Required when activeFromType is FixedDate.","example":"2024-01-01","nullable":true,"format":"date"},"customPrices":{"type":"object","description":"Custom price overrides for base product, variants, and options. Keys can be \"base\", \"variant_\", or \"option_\". Each value contains priceFixed, priceSubscription, and pricePerUnit overrides. These prices are applied to the product when saving. Note: Tasks only support priceFixed, so priceSubscription and pricePerUnit are ignored.","additionalProperties":{"$ref":"#/components/schemas/CustomPriceDto"},"example":{"base":{"priceFixed":100.5,"priceSubscription":null,"pricePerUnit":null},"variant_550e8400":{"priceFixed":150,"priceSubscription":null,"pricePerUnit":null}}}},"required":["productId","quantity","options","customPrices"]},"TaskProductVariantDto":{"type":"object","properties":{"id":{"type":"string","description":"UUID of the variant. Required when updating an existing variant. Omit or leave undefined when creating a new variant.","example":"550e8400-e29b-41d4-a716-446655440006"},"name":{"type":"string","description":"Display name of the variant. Examples: \"Standard\", \"Pro\", \"Enterprise\", \"Basic Package\", \"Premium Package\".","example":"Premium"},"description":{"type":"object","description":"Detailed description of the variant in HTML or Markdown format. This will be automatically converted to the internal document format. Can describe features, specifications, or what is included in this variant.","example":"Premium variant with additional features
"},"priceFixed":{"type":"object","description":"One-time fixed price for this variant. Task products only support fixed pricing. Set to null if this pricing model does not apply. Must be 0 or greater.","example":150,"nullable":true}},"required":["name"]},"TaskProductOptionValueDto":{"type":"object","properties":{"id":{"type":"string","description":"UUID of the option value. Required when updating an existing value. Omit or leave undefined when creating a new value.","example":"550e8400-e29b-41d4-a716-446655440008"},"name":{"type":"string","description":"Display name of the option value. Examples: \"Blue\", \"Red\", \"Premium Support\", \"Add Workshop\", \"Extra Storage\".","example":"Blue"},"extraPriceFixed":{"type":"object","description":"Additional fixed price charged when this option value is selected. Task products only support fixed pricing. For example, if selecting \"Premium Support\" adds 50 EUR one-time fee, set this to 50.0. Set to null if no extra fixed price applies. Must be 0 or greater.","example":10,"nullable":true}},"required":["name"]},"TaskProductOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"UUID of the product option. Required when updating an existing option. Omit or leave undefined when creating a new option.","example":"550e8400-e29b-41d4-a716-446655440007"},"name":{"type":"string","description":"Display name of the option. Examples: \"Color\", \"Size\", \"Support Level\", \"Additional Services\". This identifies what type of choice the customer is making.","example":"Color"},"isRequired":{"type":"boolean","description":"Whether this option must be selected. If true, customers must choose at least one value from this option. If false, the option is optional.","example":true},"isMultiple":{"type":"boolean","description":"Whether multiple values can be selected for this option. If true, customers can select multiple values (e.g., multiple colors). If false, only one value can be selected.","example":false},"values":{"description":"Array of available values for this option. Each value can have its own name and fixed pricing. Task products only support fixed pricing. For example, a \"Support Level\" option might have values: \"Basic\" (no extra cost), \"Premium\" (+50 EUR one-time), \"Enterprise\" (+200 EUR one-time).","type":"array","items":{"$ref":"#/components/schemas/TaskProductOptionValueDto"}}},"required":["name","isRequired","isMultiple","values"]},"PatchTaskProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the product. This is what appears in quotes, invoices, and task views. All fields in this DTO are optional - only provide fields you want to update.","example":"Updated Product"},"description":{"type":"string","description":"Product description in HTML or Markdown format. This will be automatically converted to the internal document format. Can include details about what the product includes, features, or specifications.","example":"Updated product description
"},"categoryId":{"type":"object","description":"UUID of the product category. Categories help organize products (e.g., \"Hardware\", \"Software\", \"Services\"). Set to null to remove category assignment.","example":"550e8400-e29b-41d4-a716-446655440010","nullable":true},"logoId":{"type":"object","description":"UUID of the logo image file. This image is displayed alongside the product in lists and views. Set to null to remove the logo.","example":"550e8400-e29b-41d4-a716-446655440011","nullable":true},"priceFixed":{"type":"object","description":"One-time fixed price for the product. Task products only support fixed pricing. Set to null if this pricing model does not apply. Must be 0 or greater.","example":100,"nullable":true},"variants":{"description":"Array of product variants. Variants allow different configurations or service levels (e.g., Standard, Pro, Enterprise). When updating, you must provide the complete variant structure - existing variants will be replaced. Task products only support fixed pricing.","type":"array","items":{"$ref":"#/components/schemas/TaskProductVariantDto"}},"options":{"description":"Array of product options. Options allow customers to add extra services or upgrades (e.g., \"Add workshop\", \"Enable premium support\"). When updating, you must provide the complete options structure - existing options will be replaced. Task products only support fixed pricing.","type":"array","items":{"$ref":"#/components/schemas/TaskProductOptionDto"}}}},"TaskProductSettingsDto":{"type":"object","properties":{"quantity":{"type":"number","description":"Number of units of this product. Must be at least 1. This affects the total price calculation when using per-unit pricing.","example":3,"minimum":1},"activeVariantId":{"type":"object","description":"UUID of the variant that should be active. Use this to switch between variants (e.g., from Standard to Pro). Set to null if the product has no variants or to deactivate variant selection.","example":"550e8400-e29b-41d4-a716-446655440006","nullable":true},"options":{"description":"Array of option selections. Each entry specifies which option is being configured and which values are selected. You must provide selections for all options defined on the product, even if no values are selected (use empty array for value). This updates the product configuration without changing product details like name or prices.","example":[{"id":"550e8400-e29b-41d4-a716-446655440004","value":["550e8400-e29b-41d4-a716-446655440007"]}],"type":"array","items":{"$ref":"#/components/schemas/ProductSettingOptionDto"}},"activeFromType":{"type":"string","description":"Type of activation start for the product. Immediately means it starts right away, ProjectBilling means it starts with project billing, FixedDate means it starts on a specific date.","enum":["Immediately","ProjectBilling","FixedDate"],"example":"Immediately"},"activeFromFixedDate":{"type":"string","description":"Fixed start date when activeFromType is FixedDate. Format: ISO 8601 date (YYYY-MM-DD). Required when activeFromType is FixedDate.","example":"2024-01-01","nullable":true,"format":"date"},"customPrices":{"type":"object","description":"Custom price overrides for base product, variants, and options. Keys can be \"base\", \"variant_\", or \"option_\". Each value contains priceFixed, priceSubscription, and pricePerUnit overrides. These prices are applied to the product when saving. Note: Tasks only support priceFixed, so priceSubscription and pricePerUnit are ignored.","additionalProperties":{"$ref":"#/components/schemas/CustomPriceDto"},"example":{"base":{"priceFixed":100.5,"priceSubscription":null,"pricePerUnit":null},"variant_550e8400":{"priceFixed":150,"priceSubscription":null,"pricePerUnit":null}}}},"required":["quantity","options","customPrices"]},"CreateExpressQuotationDto":{"type":"object","properties":{"contactUserId":{"type":"string","description":"UUID of the contact user who will receive the quotation. This user must exist in the workspace and will be the recipient when the quotation is sent via email.","example":"550e8400-e29b-41d4-a716-446655440000"},"language":{"type":"string","description":"Language code for the quotation (e.g., \"en\" for English, \"de\" for German). Used for formatting dates, numbers, and generating localized item descriptions. If not provided, the workspace default language is used.","example":"en"},"comment":{"type":"string","description":"Optional comment or notes for the quotation. Can be provided in HTML or Markdown format. The system will automatically detect the format and convert it to the internal IDoc format. This comment appears on the quotation document when sent to the contact.","example":"Please review this quotation and let us know if you have any questions.
"},"includeEstimate":{"type":"boolean","description":"If true, includes the task's estimated work time as the first quotation item. The estimated time is converted to an item with the task's hour rate. If false, only products from the task are included as items.","example":true}},"required":["contactUserId","includeEstimate"]},"ExpressQuotationItemOptionResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the option (UUID)","example":"550e8400-e29b-41d4-a716-446655440000"},"title":{"type":"string","description":"Display name or title of the option variant (e.g., \"Color: Red\", \"Size: Large\", \"Material: Premium\"). Options represent different variants or configurations of a quotation item.","example":"Color: Red"},"unitPrice":{"type":"number","description":"Price per unit for this option variant. This is the additional cost per unit when this option is selected.","example":5.99},"totalPrice":{"type":"number","description":"Total price for this option variant, calculated as `unitPrice * itemQuantity`. This represents the total additional cost when this option is selected for the item.","example":59.9}},"required":["id","title","unitPrice","totalPrice"]},"ExpressQuotationItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the quotation item (UUID)","example":"550e8400-e29b-41d4-a716-446655440000"},"title":{"type":"string","description":"Display title of the item. For time-based items, this typically includes the hours and rate (e.g., \"Work time: 1440 hours at 100 EUR each\"). For product items, this is the product name.","example":"Work time: 1440 hours at 100 EUR each"},"description":{"type":"string","description":"Detailed description of the item in HTML format. For time-based items, this may include the task summary. For product items, this is the product description. The content is converted from the internal IDoc format to HTML.","example":"Development and implementation of the new feature as described in the task requirements.
"},"unit":{"type":"string","description":"Unit of measurement for this item. Can be \"Hour\" for time-based billing or \"Piece\" for product-based items.","enum":["Piece","Hour"],"example":"Hour"},"quantity":{"type":"number","description":"Quantity of units for this item. For time-based items, this is the number of hours. For product items, this is the product quantity.","example":1440},"unitPrice":{"type":"number","description":"Price per unit for this item. For time-based items, this is the hourly rate. For product items, this is the product unit price.","example":100},"totalPrice":{"type":"number","description":"Total price for this item, calculated as `quantity * unitPrice`. This does not include option prices, which are added separately.","example":144000},"options":{"description":"Array of option variants available for this item. Options represent different configurations or variants (e.g., color, size, material) that can be selected, each with its own pricing. An empty array means no options are available.","type":"array","items":{"$ref":"#/components/schemas/ExpressQuotationItemOptionResponseDto"}}},"required":["id","title","description","unit","quantity","unitPrice","totalPrice","options"]},"ExpressQuotationResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the quotation (UUID)","example":"550e8400-e29b-41d4-a716-446655440000"},"taskId":{"type":"string","description":"UUID of the task this quotation is linked to. The quotation affects billing for this task when accepted.","example":"550e8400-e29b-41d4-a716-446655440000"},"shortNumber":{"type":"number","description":"Sequential quotation number within the task. The first quotation for a task is 1, the second is 2, etc. This provides a human-readable reference number for the quotation.","example":1},"status":{"type":"string","description":"Current status of the quotation. \"Pending\" means it has been created but not yet accepted or rejected. \"Accepted\" means it will be used for billing. \"Rejected\" means it will not be used for billing. Only one quotation per task can be Accepted at a time.","enum":["Pending","Accepted","Rejected"],"example":"Pending"},"contactUserId":{"type":"string","description":"UUID of the contact user who is the recipient of this quotation. This user receives the quotation when it is sent via email.","example":"550e8400-e29b-41d4-a716-446655440000"},"language":{"type":"object","description":"Language code used for this quotation (e.g., \"en\", \"de\"). Used for formatting and localization. Can be null if not specified, in which case the workspace default is used.","example":"en","nullable":true},"comment":{"type":"string","description":"Comment or notes for the quotation, formatted as HTML. This content is converted from the internal IDoc format and appears on the quotation document when sent to the contact.","example":"Please review this quotation and let us know if you have any questions.
"},"items":{"description":"Array of all items included in the quotation. Items are ordered by their `order` field. Each item can have multiple options (variants). Items are typically generated from task products and optionally include estimated work time.","type":"array","items":{"$ref":"#/components/schemas/ExpressQuotationItemResponseDto"}},"subTotal":{"type":"number","description":"Total amount for all items before tax is applied. This is the sum of all item total prices plus any option prices.","example":144000},"total":{"type":"number","description":"Final total amount including tax. Calculated as `subTotal + taxAmount`. This is the amount that will be billed if the quotation is accepted.","example":168480},"tax":{"type":"number","description":"Tax rate percentage applied to the quotation (e.g., 17 for 17% VAT). This is typically taken from the workspace or organization tax settings.","example":17},"taxAmount":{"type":"number","description":"Tax amount calculated from the subtotal and tax rate. Calculated as `(subTotal * tax) / 100`.","example":24480},"createdAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp when the quotation was created","example":"2024-01-01T00:00:00Z"},"updatedAt":{"format":"date-time","type":"string","description":"ISO 8601 timestamp when the quotation was last modified","example":"2024-01-01T00:00:00Z"},"sentAt":{"type":"object","description":"ISO 8601 timestamp when the quotation was sent via email to the contact user. Null if the quotation has not been sent yet.","example":"2024-01-01T00:00:00Z","nullable":true},"createdBy":{"type":"string","description":"UUID of the user who created this quotation","example":"550e8400-e29b-41d4-a716-446655440000"},"statusChangedBy":{"type":"string","description":"UUID of the user who last changed the quotation status (accepted or rejected). This tracks who made the decision on the quotation.","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["id","taskId","shortNumber","status","contactUserId","language","comment","items","subTotal","total","tax","taxAmount","createdAt","updatedAt","sentAt","createdBy","statusChangedBy"]},"BigPictureResponseDto":{"type":"object","properties":{"groups":{"description":"Array of task groups, where each group represents a task type (row) in the Big Picture view. Groups are sorted according to the configured task type order. Each group contains task items (cards) and statistics for that specific task type. Tasks without a recognized type are grouped into a special \"other\" category.","example":[{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","items":[{"id":"task-uuid-1","title":"Implement user authentication","status":"In Progress","priority":"High","typeId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","estimatedHours":8,"spentHours":4.5,"assignedUserId":"user-uuid-1","itemStatus":1,"isInPipeline":true,"lastComment":null}],"stats":{"resolvedCount":2,"totalEstimate":16,"totalSpent":8,"resolvedHours":4}}],"type":"array","items":{"type":"array"}},"stats":{"type":"object","description":"Overall statistics aggregated across all tasks in the project. These metrics provide a high-level view of project progress, time allocation, and completion status.","example":{"totalTasks":10,"resolvedCount":3,"totalEstimate":40,"totalSpent":20,"resolvedHours":10}}},"required":["groups","stats"]},"UpdateBigPictureOrderDto":{"type":"object","properties":{"projectId":{"type":"string","description":"UUID of the project containing the tasks to reorder. The project must exist, not be deleted, and belong to the authenticated user's workspace. The user must have BigPicture.canEdit permission and access to the project.","example":"7225cca9-ac5f-461d-9a9d-ad8d7ee1b597","format":"uuid"},"groupId":{"type":"string","description":"UUID of the task type group (row) within which to reorder tasks. This identifies which horizontal row in the Big Picture view contains the tasks you want to reorder. Must be a valid task type ID for the specified project.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","format":"uuid"},"newOrder":{"description":"Array of task UUIDs in the desired new order (left to right = highest to lowest priority). Must include all tasks currently in the specified group - you cannot omit any tasks. The first task ID in the array will appear leftmost (highest priority), the last will appear rightmost (lowest priority).","example":["f1a2b3c4-d5e6-7890-abcd-ef1234567890","a1b2c3d4-e5f6-7890-abcd-ef1234567890","b1c2d3e4-f5a6-7890-abcd-ef1234567890"],"items":{"type":"array"},"type":"array"}},"required":["projectId","groupId","newOrder"]},"UpdateBigPictureGroupOrderDto":{"type":"object","properties":{"projectId":{"type":"string","description":"UUID of the project containing the task type groups to reorder. The project must exist, not be deleted, and belong to the authenticated user's workspace. The user must have BigPicture.canEdit permission and access to the project.","example":"7225cca9-ac5f-461d-9a9d-ad8d7ee1b597","format":"uuid"},"newOrder":{"description":"Array of task type group UUIDs in the desired new order (top to bottom). Must include all task type groups currently in the specified project - you cannot omit any groups. The first group ID in the array will appear at the top of the Big Picture view, the last will appear at the bottom. Tasks without a recognized type are grouped into a special \"other\" category which can also be included in this array.","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b1c2d3e4-f5a6-7890-abcd-ef1234567890","c1d2e3f4-a5b6-7890-abcd-ef1234567890"],"items":{"type":"array"},"type":"array"}},"required":["projectId","newOrder"]},"PoolResponseDto":{"type":"object","properties":{"stats":{"type":"object","description":"Overall statistics for the entire pool, aggregating data from all projects and tasks filtered by the Accountable field (not the Assigned field). Only tasks where the accountableId user is set as the Accountable person are included. These statistics provide a high-level overview of workload and progress.","example":{"totalTasks":10,"resolvedCount":3,"totalEstimate":40,"totalSpent":20,"resolvedHours":10}},"projects":{"type":"array","description":"Array of projects, each containing groups of tasks organized by task type. Tasks are filtered by the Accountable field (not the Assigned field) - only tasks where the accountableId user is set as the Accountable person are included. Projects are sorted by custom order from PoolProjectOrder table. Each project row contains multiple task type groups (e.g., Feature, Bug, Task), which are sorted by custom order from PoolTypeProjectOrder table. Each group contains task items and group-level statistics.","example":[{"projectId":"550e8400-e29b-41d4-a716-446655440000","groups":[{"id":"6ba7b810-9dad-11d1-80b4-00c04fd430c8","items":[],"stats":{"resolvedCount":2,"totalEstimate":16,"totalSpent":8,"resolvedHours":4}}]}]}},"required":["stats","projects"]},"UpdatePoolOrderDto":{"type":"object","properties":{"accountableId":{"type":"string","description":"UUID of the accountable user whose pool task order should be updated. The user must exist in the same workspace and not be deleted. Access is controlled by Pool edit permissions (canEditAll, canEditOwnTeams, or canEditOwn).","example":"aff55c87-49c6-4d5d-9b0b-bf7478e2d504"},"newOrder":{"description":"Array of task UUIDs in the desired priority order. Tasks are displayed horizontally from left to right, with the first item in the array appearing on the left (highest priority). The array should contain all task IDs that need to be reordered. Each task ID must be a valid UUID of a task where the specified accountableId user is set as the Accountable person (filtered by Accountable field, not Assigned field).","example":["550e8400-e29b-41d4-a716-446655440000","6ba7b810-9dad-11d1-80b4-00c04fd430c8","6ba7b811-9dad-11d1-80b4-00c04fd430c8"],"type":"array","items":{"type":"string"}}},"required":["accountableId","newOrder"]},"UpdatePoolProjectOrderDto":{"type":"object","properties":{"accountableId":{"type":"string","description":"UUID of the accountable user whose pool project order should be updated. The user must exist in the same workspace and not be deleted. Access is controlled by Pool edit permissions (canEditAll, canEditOwnTeams, or canEditOwn).","example":"aff55c87-49c6-4d5d-9b0b-bf7478e2d504"},"newOrder":{"description":"Array of project UUIDs in the desired vertical order. Projects are displayed as rows in the pool view, with the first item in the array appearing at the top. The array should contain all project IDs that need to be reordered. Each project ID must be a valid UUID of a project in the same workspace.","example":["550e8400-e29b-41d4-a716-446655440000","6ba7b810-9dad-11d1-80b4-00c04fd430c8","6ba7b811-9dad-11d1-80b4-00c04fd430c8"],"type":"array","items":{"type":"string"}}},"required":["accountableId","newOrder"]},"UpdatePoolGroupOrderDto":{"type":"object","properties":{"accountableId":{"type":"string","description":"UUID of the accountable user whose pool group order should be updated. The user must exist in the same workspace and not be deleted. Access is controlled by Pool edit permissions (canEditAll, canEditOwnTeams, or canEditOwn).","example":"aff55c87-49c6-4d5d-9b0b-bf7478e2d504"},"projectId":{"type":"string","description":"UUID of the project within which the task type group order should be updated. The project must exist in the same workspace. Task type groups (e.g., Feature, Bug, Task) are displayed as columns within each project row in the pool view.","example":"550e8400-e29b-41d4-a716-446655440000"},"newOrder":{"description":"Array of task type UUIDs in the desired horizontal order. Task type groups are displayed as columns within the project row, with the first item in the array appearing on the left. The array should contain all task type IDs that need to be reordered. Each task type ID must be a valid UUID of a task type configured in the workspace.","example":["550e8400-e29b-41d4-a716-446655440000","6ba7b810-9dad-11d1-80b4-00c04fd430c8","6ba7b811-9dad-11d1-80b4-00c04fd430c8"],"type":"array","items":{"type":"string"}}},"required":["accountableId","projectId","newOrder"]},"StackColumnType":{"type":"string","enum":["toDo","getFeedback","giveFeedback","done","backlog"],"description":"Type of column indicating the workflow stage. Possible values: toDo (pipeline tasks in New/InProgress status), giveFeedback (tasks assigned to user in Feedback status), getFeedback (tasks NOT assigned to user in Feedback status), done (pipeline tasks in Closed/Resolved status), backlog (non-pipeline tasks assigned to user). **Note**: Pipeline tasks appear regardless of assignment. Non-pipeline tasks are filtered by Assigned field."},"TaskPriority":{"type":"string","enum":["Low","Normal","High"],"description":"Priority level of the task. Used for sorting: High > Normal > Low. Tasks with higher priority appear first in their column."},"StackTaskDetailsDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the task"},"title":{"type":"string","description":"Title or name of the task"},"icon":{"type":"object","description":"Icon identifier for the task. Can be null if no icon is set.","nullable":true},"shortNumber":{"type":"number","description":"Short number of the task within its workspace. Used for display and sorting purposes."},"color":{"type":"string","description":"Color code (hex format) representing the organization that owns the task. Used for visual identification."},"organizationShortName":{"type":"string","description":"Short name or abbreviation of the organization that owns the task"},"projectShortNumber":{"type":"object","description":"Short number of the project this task belongs to. Can be null if task is not associated with a project.","nullable":true},"statusId":{"type":"string","description":"UUID of the task status. The status determines which column the task appears in (toDo, giveFeedback, getFeedback, done, backlog)."},"summary":{"type":"object","description":"Optional summary or description of the task. Provides additional context about what needs to be done.","nullable":true},"priority":{"description":"Priority level of the task. Used for sorting: High > Normal > Low. Tasks with higher priority appear first in their column.","allOf":[{"$ref":"#/components/schemas/TaskPriority"}]},"typeId":{"type":"string","description":"UUID of the task type. Task types define workflows, fields, and statuses available for the task."},"projectId":{"type":"string","description":"UUID of the project this task belongs to"},"deadline":{"type":"object","description":"Deadline date in ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ). Can be null if no deadline is set.","nullable":true},"estimatedTime":{"type":"object","description":"Estimated time to complete the task, measured in hours. Can be null if no estimate is provided.","nullable":true},"spentTime":{"type":"object","description":"Total time already spent on the task, measured in hours. This field is only visible if the authenticated user has the Tasks.seeLoggedTime permission. Can be null if no time has been logged yet.","nullable":true},"commentsCount":{"type":"number","description":"Total number of comments on the task. Includes all comments from team members."},"accountableId":{"type":"object","description":"UUID of the user who is accountable for the task (responsible person). Can be null if no one is assigned as accountable.","nullable":true},"assignedToId":{"type":"object","description":"UUID of the user who is assigned to work on the task (Assigned field). Can be null if no one is assigned. **Important**: Non-pipeline tasks in the stack are filtered by this field (assignedToId). Pipeline tasks appear regardless of this field. This field determines which column the task appears in for feedback-related columns (giveFeedback vs getFeedback).","nullable":true},"orgName":{"type":"string","description":"Full name of the organization that owns the task. Provides human-readable context."},"tags":{"description":"Array of tag names associated with the task. Tags enable cross-project organization and filtering of tasks.","type":"array","items":{"type":"string"}}},"required":["id","title","icon","shortNumber","color","organizationShortName","projectShortNumber","statusId","summary","priority","typeId","projectId","deadline","estimatedTime","commentsCount","accountableId","assignedToId","orgName","tags"]},"StackColumnDto":{"type":"object","properties":{"type":{"description":"Type of column indicating the workflow stage. Possible values: toDo (pipeline tasks in New/InProgress status), giveFeedback (tasks assigned to user in Feedback status), getFeedback (tasks NOT assigned to user in Feedback status), done (pipeline tasks in Closed/Resolved status), backlog (non-pipeline tasks assigned to user). **Note**: Pipeline tasks appear regardless of assignment. Non-pipeline tasks are filtered by Assigned field.","allOf":[{"$ref":"#/components/schemas/StackColumnType"}]},"tasks":{"description":"Array of tasks in this column. Tasks are sorted by priority (descending) then shortNumber (ascending), with pipeline tasks appearing first.","type":"array","items":{"$ref":"#/components/schemas/StackTaskDetailsDto"}}},"required":["type","tasks"]},"StackResponseDto":{"type":"object","properties":{"columns":{"description":"Array of stack columns representing different workflow stages. Always includes all five column types (toDo, giveFeedback, getFeedback, done, backlog), even if some columns are empty. Columns appear in this order. **Task filtering**: Pipeline tasks (regardless of assignment) appear in toDo and done columns. Non-pipeline tasks filtered by Assigned field (assignedToId) appear in giveFeedback, getFeedback, and backlog columns. Tasks are sorted by priority and pipeline order.","type":"array","items":{"$ref":"#/components/schemas/StackColumnDto"}}},"required":["columns"]},"PipelineResponseDto":{"type":"object","properties":{"users":{"type":"object","description":"Object containing pipeline data for each user, keyed by userId. Each entry contains employee information, days array (work day data), items array (planned tasks), and reality array (time logs if enabled).","additionalProperties":{"type":"object","$ref":"#/components/schemas/PipelineUserRowDto"},"example":{"user-id-1":{"employeeId":"employee-id-1","userId":"user-id-1","name":"John Doe","days":[],"items":[],"reality":[]}}},"ready":{"type":"boolean","description":"Whether the pipeline week is marked as active/ready. When true, the planned tasks are visible in employee stacks. When false, the week is still in draft/planning mode.","example":true},"year":{"type":"number","description":"Year of the pipeline period start date (ISO week year)","example":2025},"week":{"type":"number","description":"ISO week number of the pipeline period start date","example":43}},"required":["users","ready","year","week"]},"ActivatePipelineDto":{"type":"object","properties":{"dateStart":{"type":"string","description":"Start date of the pipeline week in ISO format (YYYY-MM-DD). The week is determined from this date using ISO week numbering.","example":"2025-11-03"},"dateEnd":{"type":"string","description":"End date of the pipeline week in ISO format (YYYY-MM-DD). Should match the end of the week period (typically 1-2 weeks from dateStart based on workspace settings).","example":"2025-11-16"}},"required":["dateStart","dateEnd"]},"CreatePipelineItemDto":{"type":"object","properties":{"taskId":{"type":"string","description":"Unique identifier of the task to plan in the pipeline. The task must exist and the user must have access to view it.","example":"123e4567-e89b-12d3-a456-426614174000"},"userId":{"type":"string","description":"Unique identifier of the user/team member to assign this task to. Permission restrictions apply: users with Pipeline.canPlanOwnTeams can only assign to themselves or team members, while users with Pipeline.canPlanAll can assign to any user.","example":"123e4567-e89b-12d3-a456-426614174001"},"dateStart":{"type":"string","description":"Start date in ISO format (YYYY-MM-DDTHH:mm:ssZ). **IMPORTANT**: Only the date part (YYYY-MM-DD) is used - the time component is IGNORED. Use timeStart to specify the actual start time relative to work day start. Example: \"2025-11-04T00:00:00Z\" (the time part is ignored).","example":"2025-11-04T00:00:00Z"},"dateEnd":{"type":"string","description":"End date in ISO format (YYYY-MM-DDTHH:mm:ssZ). **IMPORTANT**: Only the date part (YYYY-MM-DD) is used - the time component is IGNORED. Use timeEnd to specify the actual end time relative to work day start. Maximum 2 weeks from dateStart. Example: \"2025-11-04T00:00:00Z\" (the time part is ignored).","example":"2025-11-04T00:00:00Z"},"timeStart":{"type":"number","description":"**CRITICAL**: Start time in MINUTES from the beginning of the work day (NOT from midnight, NOT absolute clock time). \n\n**Range**: 0 to workDayLength (typically 0-480 for an 8-hour day)\n**Format**: Must be in 15-minute increments: 0, 15, 30, 45, 60, 75, 90, 105, 120, etc.\n\n**Examples** (assuming 8-hour work day starting at 09:00):\n- `timeStart: 0` = 09:00 (start of work day)\n- `timeStart: 60` = 10:00 (1 hour after work day start)\n- `timeStart: 240` = 13:00 (4 hours after work day start = midday)\n- `timeStart: 480` = 17:00 (8 hours = end of work day)\n\n**Planning Multiple Tasks for One Day** (example with 8-hour work day starting at 09:00):\nTo schedule multiple tasks sequentially throughout the day, chain them together:\n- Task 1: `timeStart: 0, timeEnd: 75` = 09:00 to 10:15 (1.25 hours)\n- Task 2: `timeStart: 75, timeEnd: 150` = 10:15 to 11:30 (1.25 hours)\n- Task 3: `timeStart: 150, timeEnd: 240` = 11:30 to 13:00 (1.5 hours)\n- Task 4: `timeStart: 240, timeEnd: 330` = 13:00 to 14:30 (1.5 hours)\n- Task 5: `timeStart: 330, timeEnd: 480` = 14:30 to 17:00 (2.5 hours)\n\n**Calculation**: Actual time = workDayStartTime + (timeStart minutes)\n**Important**: This is NOT the same as hours since midnight. If your work day starts at 09:00, timeStart=0 means 09:00, not 00:00.","example":0,"minimum":0},"timeEnd":{"type":"number","description":"**CRITICAL**: End time in MINUTES from the beginning of the work day (NOT from midnight, NOT absolute clock time). \n\n**Range**: Must be greater than timeStart, up to workDayLength (typically 0-480 for an 8-hour day)\n**Format**: Must be in 15-minute increments: 0, 15, 30, 45, 60, 75, 90, 105, 120, etc.\n\n**Examples** (assuming 8-hour work day starting at 09:00):\n- `timeEnd: 240` = 13:00 (4 hours after work day start = midday)\n- `timeEnd: 330` = 14:30 (5.5 hours after work day start)\n- `timeEnd: 480` = 17:00 (8 hours = end of work day)\n\n**Planning Multiple Tasks for One Day** (example with 8-hour work day starting at 09:00):\nTo schedule multiple tasks sequentially throughout the day, chain them together:\n- Task 1: `timeStart: 0, timeEnd: 75` = 09:00 to 10:15 (1.25 hours)\n- Task 2: `timeStart: 75, timeEnd: 150` = 10:15 to 11:30 (1.25 hours)\n- Task 3: `timeStart: 150, timeEnd: 240` = 11:30 to 13:00 (1.5 hours)\n- Task 4: `timeStart: 240, timeEnd: 330` = 13:00 to 14:30 (1.5 hours)\n- Task 5: `timeStart: 330, timeEnd: 480` = 14:30 to 17:00 (2.5 hours)\n\n**Calculation**: Actual time = workDayStartTime + (timeEnd minutes)\n**Important**: This is NOT the same as hours since midnight. If your work day starts at 09:00, timeEnd=480 means 17:00, not 08:00. Must be greater than timeStart.","example":240,"minimum":0}},"required":["taskId","userId","dateStart","dateEnd","timeStart","timeEnd"]},"PipelineItemResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the created or updated pipeline item","example":"123e4567-e89b-12d3-a456-426614174002"},"taskId":{"type":"string","description":"Unique identifier of the task that was planned","example":"123e4567-e89b-12d3-a456-426614174000"},"userId":{"type":"string","description":"Unique identifier of the user/team member the task is assigned to","example":"123e4567-e89b-12d3-a456-426614174001"},"dateStart":{"type":"string","description":"Start date and time in ISO format (RESPONSE VALUE - this is different from input). **Note**: In the request, the time component of dateStart is IGNORED. In the response, the time component IS meaningful - it represents the calculated absolute time based on work day start + timeStart minutes. The date part (YYYY-MM-DD) represents the calendar day. When reading this response value, extract the time relative to work day start, not midnight. Example: If work day starts at 09:00 and timeStart was 30, this response will show 09:30 on the specified date.","example":"2025-11-04T09:30:00Z"},"dateEnd":{"type":"string","description":"End date and time in ISO format (RESPONSE VALUE - this is different from input). **Note**: In the request, the time component of dateEnd is IGNORED. In the response, the time component IS meaningful - it represents the calculated absolute time based on work day start + timeEnd minutes. The date part (YYYY-MM-DD) represents the calendar day. When reading this response value, extract the time relative to work day start, not midnight. Example: If work day starts at 09:00 and timeEnd was 330, this response will show 14:30 (5.5 hours from 09:00) on the specified date.","example":"2025-11-04T14:30:00Z"}},"required":["id","taskId","userId","dateStart","dateEnd"]},"UpdatePipelineItemDto":{"type":"object","properties":{"taskId":{"type":"string","description":"Unique identifier of the task to plan. Optional - if not provided, the existing taskId is preserved. The task must exist and the user must have access to view it.","example":"123e4567-e89b-12d3-a456-426614174000"},"userId":{"type":"string","description":"Unique identifier of the user/team member to assign this task to. Optional - if not provided, the existing userId is preserved. Permission restrictions apply: users with Pipeline.canPlanOwnTeams can only assign to themselves or team members, while users with Pipeline.canPlanAll can assign to any user.","example":"123e4567-e89b-12d3-a456-426614174001"},"dateStart":{"type":"string","description":"Start date in ISO format (YYYY-MM-DDTHH:mm:ssZ). **IMPORTANT**: Only the date part (YYYY-MM-DD) is used - the time component is IGNORED. Use timeStart to specify the actual start time relative to work day start. Optional - if not provided, the existing dateStart is preserved. Example: \"2025-11-04T00:00:00Z\" (the time part is ignored).","example":"2025-11-04T00:00:00Z"},"dateEnd":{"type":"string","description":"End date in ISO format (YYYY-MM-DDTHH:mm:ssZ). **IMPORTANT**: Only the date part (YYYY-MM-DD) is used - the time component is IGNORED. Use timeEnd to specify the actual end time relative to work day start. Maximum 2 weeks from dateStart. Optional - if not provided, the existing dateEnd is preserved. Example: \"2025-11-04T00:00:00Z\" (the time part is ignored).","example":"2025-11-04T00:00:00Z"},"timeStart":{"type":"number","description":"**CRITICAL**: Start time in MINUTES from the beginning of the work day (NOT from midnight, NOT absolute clock time). Optional - if not provided, the existing timeStart is preserved.\n\n**Range**: 0 to workDayLength (typically 0-480 for an 8-hour day)\n**Format**: Must be in 15-minute increments: 0, 15, 30, 45, 60, 75, 90, 105, 120, etc.\n\n**Examples** (assuming 8-hour work day starting at 09:00):\n- `timeStart: 0` = 09:00 (start of work day)\n- `timeStart: 60` = 10:00 (1 hour after work day start)\n- `timeStart: 240` = 13:00 (4 hours after work day start = midday)\n- `timeStart: 480` = 17:00 (8 hours = end of work day)\n\n**Planning Multiple Tasks for One Day** (example with 8-hour work day starting at 09:00):\nTo schedule multiple tasks sequentially throughout the day, chain them together:\n- Task 1: `timeStart: 0, timeEnd: 75` = 09:00 to 10:15 (1.25 hours)\n- Task 2: `timeStart: 75, timeEnd: 150` = 10:15 to 11:30 (1.25 hours)\n- Task 3: `timeStart: 150, timeEnd: 240` = 11:30 to 13:00 (1.5 hours)\n- Task 4: `timeStart: 240, timeEnd: 330` = 13:00 to 14:30 (1.5 hours)\n- Task 5: `timeStart: 330, timeEnd: 480` = 14:30 to 17:00 (2.5 hours)\n\n**Calculation**: Actual time = workDayStartTime + (timeStart minutes)\n**Important**: This is NOT the same as hours since midnight. If your work day starts at 09:00, timeStart=0 means 09:00, not 00:00.","example":0,"minimum":0},"timeEnd":{"type":"number","description":"**CRITICAL**: End time in MINUTES from the beginning of the work day (NOT from midnight, NOT absolute clock time). Optional - if not provided, the existing timeEnd is preserved.\n\n**Range**: Must be greater than timeStart, up to workDayLength (typically 0-480 for an 8-hour day)\n**Format**: Must be in 15-minute increments: 0, 15, 30, 45, 60, 75, 90, 105, 120, etc.\n\n**Examples** (assuming 8-hour work day starting at 09:00):\n- `timeEnd: 240` = 13:00 (4 hours after work day start = midday)\n- `timeEnd: 330` = 14:30 (5.5 hours after work day start)\n- `timeEnd: 480` = 17:00 (8 hours = end of work day)\n\n**Planning Multiple Tasks for One Day** (example with 8-hour work day starting at 09:00):\nTo schedule multiple tasks sequentially throughout the day, chain them together:\n- Task 1: `timeStart: 0, timeEnd: 75` = 09:00 to 10:15 (1.25 hours)\n- Task 2: `timeStart: 75, timeEnd: 150` = 10:15 to 11:30 (1.25 hours)\n- Task 3: `timeStart: 150, timeEnd: 240` = 11:30 to 13:00 (1.5 hours)\n- Task 4: `timeStart: 240, timeEnd: 330` = 13:00 to 14:30 (1.5 hours)\n- Task 5: `timeStart: 330, timeEnd: 480` = 14:30 to 17:00 (2.5 hours)\n\n**Calculation**: Actual time = workDayStartTime + (timeEnd minutes)\n**Important**: This is NOT the same as hours since midnight. If your work day starts at 09:00, timeEnd=480 means 17:00, not 08:00. Must be greater than timeStart.","example":240,"minimum":0}}},"TranslationDto":{"type":"object","properties":{"language":{"type":"string","description":"Language code (e.g., en, es, fr)"},"name":{"type":"string","description":"Translated name"},"description":{"type":"object","description":"Translated description"}},"required":["language","name"]},"TaskTypeDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the task type"},"name":{"type":"string","description":"Name of the task type (e.g., Bug, Feature, Support Request). Used for identification in the UI."},"icon":{"type":"string","description":"Icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:bug:`, `:star:`). Used for visual representation in task lists and views."},"type":{"type":"string","enum":["Feature","Bug"],"description":"Base type category: Feature (value-adding work) or Bug (bug fix, typically not billable)"},"sort":{"type":"number","description":"Sort order for displaying task types in lists. Lower numbers appear first."},"statuses":{"description":"Array of task status UUIDs that are valid for this task type. Defines the workflow states available for tasks of this type.","type":"array","items":{"type":"string"}},"customFields":{"description":"Array of custom field UUIDs associated with this task type. These custom fields appear when creating or editing tasks of this type.","type":"array","items":{"type":"string"}},"requiredFields":{"description":"Array of field names that are required when creating tasks of this type. Ensures essential information is always captured.","type":"array","items":{"type":"string"}},"translations":{"description":"Multilingual translations for the task type name. Supports displaying the type name in different languages based on user preferences.","type":"array","items":{"$ref":"#/components/schemas/TranslationDto"}},"deleted":{"type":"boolean","description":"Whether this task type has been soft-deleted. Deleted types are typically hidden from active use but retained for historical data."}},"required":["id","name","icon","type","sort","statuses","customFields","requiredFields","translations","deleted"]},"TaskStatusDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the task status"},"name":{"type":"string","description":"Name of the task status (e.g., New, In Progress, Feedback, Resolved, Closed, Backlog). Used for identification in the UI."},"icon":{"type":"string","description":"Icon identifier in the format `:icon_name:` (e.g., `:hourglass_flowing_sand:`, `:check_mark:`, `:x:`). Used for visual representation in task lists, Kanban boards, and status selectors."},"type":{"type":"string","enum":["New","InProgress","Feedback","Backlog","Resolved","Closed"],"description":"Base status type: New, InProgress, Feedback, Backlog, Resolved, or Closed. Defines the semantic meaning and behavior of the status."},"sort":{"type":"number","description":"Sort order for displaying task statuses in lists and dropdowns. Lower numbers appear first."},"translations":{"description":"Multilingual translations for the task status name. Supports displaying the status name in different languages based on user preferences.","type":"array","items":{"$ref":"#/components/schemas/TranslationDto"}},"deleted":{"type":"boolean","description":"Whether this task status has been soft-deleted. Deleted statuses are typically hidden from active use but retained for historical data."}},"required":["id","name","icon","type","sort","translations","deleted"]},"SelectOptionDto":{"type":"object","properties":{"value":{"type":"string","description":"Option value"},"translations":{"description":"Option translations","type":"array","items":{"$ref":"#/components/schemas/TranslationDto"}}},"required":["value","translations"]},"TaskCustomFieldDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the custom field"},"name":{"type":"string","description":"Name of the custom field (e.g., Risk Level, Affected Component, SLA Level). Used as the field label in forms."},"description":{"type":"object","description":"Optional description explaining what this custom field is used for and how to fill it out"},"type":{"type":"string","enum":["Text","Textarea","Number","Date","Checkbox","Select","MultiSelect","Currency","Url"],"description":"Type of the custom field: Text (short entries), TextArea (longer entries), Number (numeric values), Date (date selection), Checkbox (Yes/No), or Select (dropdown with predefined options)"},"sort":{"type":"number","description":"Sort order for displaying custom fields in forms. Lower numbers appear first."},"entity":{"type":"string","enum":["Task","Project","Organization","Object"],"description":"Entity this field belongs to. For task custom fields, this is always Task."},"translations":{"description":"Multilingual translations for the custom field name and description. Supports displaying field labels in different languages based on user preferences.","type":"array","items":{"$ref":"#/components/schemas/TranslationDto"}},"selectOptions":{"description":"Array of select options for dropdown (Select) type fields. Each option has a value and multilingual translations. Only populated for Select type fields.","type":"array","items":{"$ref":"#/components/schemas/SelectOptionDto"}}},"required":["id","name","type","sort","entity","translations","selectOptions"]},"TaskCustomFieldValueDto":{"type":"object","properties":{"fieldId":{"type":"string","description":"UUID of the custom field. Must be a custom field that is associated with the task type being used.","example":"550e8400-e29b-41d4-a716-446655440000"},"value":{"type":"string","description":"Value for the custom field. The format depends on the field type: Text/TextArea (string), Number (numeric string), Date (ISO 8601 date string), Checkbox (true/false string), Select (one of the predefined option values). Validation is performed based on the field type configuration.","example":"Custom value"}},"required":["fieldId","value"]},"CreateTaskDto":{"type":"object","properties":{"title":{"type":"string","description":"Task title or name. This is the main identifier shown in task lists and views.","example":"Implement new feature"},"projectId":{"type":"string","description":"UUID of the project this task belongs to. The project must exist and the user must have access to it.","example":"550e8400-e29b-41d4-a716-446655440000"},"typeId":{"type":"string","description":"UUID of the task type. The type defines the workflow, available statuses, and custom fields. Must be one of the task types allowed for this project (configured in the project settings). Use the GET /projects/:id endpoint to see which task types are available for the project.","example":"660e8400-e29b-41d4-a716-446655440001"},"statusId":{"type":"string","description":"UUID of the initial task status. The status must be valid for the selected task type. Common statuses include New, In Progress, Feedback, Resolved, Closed, and Backlog.","example":"770e8400-e29b-41d4-a716-446655440002"},"priority":{"type":"string","description":"Task priority level indicating urgency. Options: Low, Normal, High. Used for prioritization and filtering.","enum":["Low","Normal","High"],"example":"Normal"},"description":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**embedVideo**\nType: block\nEmbeds a third-party video in an iframe. The div carries data-video-embed with data-embed-url (iframe src) and data-original-url (canonical page URL).\n- embedUrl: Must be a real embed/iframe URL (e.g. YouTube embed) that matches originalUrl.\n- originalUrl: Human-facing link to the video page; keep it in sync with embedUrl. Do not leave placeholder URLs in final HTML if you claim a real video.\nAtts:\n- originalUrl: \n- embedUrl: \n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n","example":"Task description in HTML
"},"icon":{"type":"object","description":"Task icon identifier. Must be in the format `:icon_name:` (e.g., `:rocket:`, `:bug:`, `:memo:`, `:white_check_mark:`). Used for visual identification in task lists and views. Leave null to use the default icon from the task type.","example":":rocket:"},"assignedToId":{"type":"object","description":"UUID of the user assigned to work on this task. The assigned user receives notifications about task updates. Leave null if no one is assigned yet.","example":"880e8400-e29b-41d4-a716-446655440003","nullable":true},"accountableId":{"type":"object","description":"UUID of the user who is accountable for this task. The accountable person is responsible for ensuring the task is completed. This is separate from the assigned user. Leave null if no one is accountable yet.","example":"990e8400-e29b-41d4-a716-446655440004","nullable":true},"summary":{"type":"string","description":"Brief summary or short description of the task. This is a concise overview that appears in task cards and lists. Can be auto-generated by AI or manually entered.","example":"Brief summary of the task"},"estimatedTime":{"type":"number","description":"Estimated time to complete the task in hours (decimal allowed). Used for planning and capacity management. Example: 8 for 8 hours, 2.5 for 2.5 hours.","example":2.5},"deadline":{"type":"string","description":"Task deadline or due date in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Used for tracking deadlines and generating deadline warnings.","example":"2024-12-31T23:59:59Z"},"guestAccess":{"type":"object","description":"Whether organization members (guest users) can access this task. When true, guest users can view and interact with the task. When false, only workspace members can access it. Leave null to use the project default.","example":false,"nullable":true,"default":false},"customFields":{"description":"Array of custom field values. Each value must correspond to a custom field that is associated with the selected task type. The field value format depends on the field type (text, number, date, checkbox, select).","type":"array","items":{"$ref":"#/components/schemas/TaskCustomFieldValueDto"}},"tags":{"description":"Array of tag UUIDs to categorize this task. Tags enable cross-project organization and filtering. Tags can be automatically inherited from project components.","example":["aa0e8400-e29b-41d4-a716-446655440005"],"type":"array","items":{"type":"string"}},"subTasksIds":{"description":"Array of existing task UUIDs to add as subtasks. Subtasks allow breaking down complex tasks into smaller units. Each subtask must exist and be accessible. The parent-child relationship is established immediately.","example":["bb0e8400-e29b-41d4-a716-446655440006"],"type":"array","items":{"type":"string"}},"linkedObjectIds":{"description":"Object instance UUIDs to link to the new task via ObjectsOnTask. Requires the same permission as linking objects on an existing task (`objects.canEdit`). Invalid or inaccessible object IDs result in an error and the task is not created.","type":"array","items":{"type":"string"}},"products":{"description":"Array of product settings to associate products with this task. Used for billing and quotation purposes. Each product setting includes the product ID, quantity, variant, and options.","type":"array","items":{"$ref":"#/components/schemas/TaskProductSettingsDto"}},"componentItemEntityUniqueId":{"type":"object","description":"Component item entity unique ID if this task is related to a project component item. Used for linking tasks to specific components in project structures.","example":"unique-component-id"},"isChangeRequest":{"type":"boolean","description":"Whether this task is a change request. Change requests are typically billed separately and tracked differently in Single projects. Used for scope change management.","example":false},"enableSupportContingent":{"type":"boolean","description":"Enable support contingent for this task. This flag marks a task as eligible for support contingent billing. Only available for Support projects.","example":false}},"required":["title","projectId","typeId","statusId","priority","description"]},"TaskDetailsResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Task ID (UUID)"},"title":{"type":"string","description":"Task title"},"titleIsGenerating":{"type":"boolean","description":"Whether title is being generated by AI"},"icon":{"type":"object","description":"Task icon identifier in the format `:icon_name:` (e.g., `:rocket:`, `:bug:`, `:memo:`). Can be null if no custom icon is set."},"iconIsGenerating":{"type":"boolean","description":"Whether icon is being generated by AI"},"summaryIsGenerating":{"type":"boolean","description":"Whether summary is being generated by AI"},"createdAt":{"format":"date-time","type":"string","description":"Task creation timestamp"},"deadline":{"format":"date-time","type":"string","description":"Task deadline"},"priority":{"type":"object","description":"Task priority (TaskPriority enum)"},"projectId":{"type":"string","description":"Project ID"},"statusId":{"type":"string","description":"Task status ID"},"userId":{"type":"string","description":"Creator user ID"},"assignedToId":{"type":"string","description":"Assigned user ID"},"accountableId":{"type":"string","description":"Accountable user ID"},"summary":{"type":"string","description":"Task summary"},"typeId":{"type":"string","description":"Task type ID"},"shortNumber":{"type":"number","description":"Task short number (workspace-scoped)"},"estimatedTime":{"type":"number","description":"Estimated time in hours"},"description":{"type":"string","description":"Task description in HTML. May include embedded assets as elements such as `` (images), `appFile`, or `appVideo`βbinary content is not embedded; use GET `{appOrigin}/api/files/public/{fileId}` on the Leadtime web app host to retrieve the file for viewing or vision models."},"guestAccess":{"type":"boolean","description":"Guest access enabled for organization members"},"project":{"type":"object","description":"Project information"},"accountable":{"type":"object","description":"Accountable user details"},"assignedTo":{"type":"object","description":"Assigned user details"},"customFields":{"type":"object","description":"Custom fields values"},"history":{"description":"Task history entries","type":"array","items":{"type":"array"}},"comments":{"description":"Task comments; each `body` is HTML and may contain the same embedded `appImage` / `appFile` / `appVideo` divs with `fileId` as the task description. Fetch binaries via `/api/files/public/{fileId}` on the app origin when needed.","type":"array","items":{"type":"array"}},"quotations":{"description":"Express quotations","type":"array","items":{"type":"array"}},"spentTime":{"type":"number","description":"Total spent time in minutes"},"childSpentTime":{"type":"number","description":"Child tasks spent time in minutes"},"participantsCount":{"type":"number","description":"Number of participants"},"participantsList":{"description":"List of participant user IDs","type":"array","items":{"type":"array"}},"isParticipant":{"type":"boolean","description":"Whether current user is a participant"},"notificationSettings":{"type":"object","description":"Notification settings"},"tags":{"description":"Task tags","type":"array","items":{"type":"array"}},"parentTaskId":{"type":"object","description":"Parent task ID for subtasks"},"subTasksIds":{"description":"Child task IDs","type":"array","items":{"type":"array"}},"skipFromBilling":{"type":"boolean","description":"Skip from billing"},"billed":{"type":"boolean","description":"Whether task is billed"},"products":{"description":"Task products","type":"array","items":{"type":"array"}},"componentItemId":{"type":"object","description":"Component item ID"},"isChangeRequest":{"type":"boolean","description":"Whether task is a change request"},"emailDetails":{"type":"object","description":"Email details"},"emailSendError":{"type":"string","description":"Email send error message"},"emailSendErrorCode":{"type":"string","description":"Email send error code"},"emailSendFailedAt":{"format":"date-time","type":"string","description":"Email send failed timestamp"},"emailSendFailedTo":{"description":"Email send failed recipients","type":"array","items":{"type":"array"}},"enableSupportContingent":{"type":"boolean","description":"Enable support contingent"}},"required":["id","title","titleIsGenerating","iconIsGenerating","summaryIsGenerating","createdAt","priority","projectId","statusId","userId","typeId","shortNumber","description","guestAccess","project","customFields","history","comments","quotations","spentTime","childSpentTime","participantsCount","participantsList","isParticipant","notificationSettings","tags","subTasksIds","billed","products","isChangeRequest","enableSupportContingent"]},"PatchTaskDto":{"type":"object","properties":{"title":{"type":"string","description":"Task title or name. Updates the main identifier shown in task lists and views."},"icon":{"type":"object","description":"Task icon identifier. Must be in the format `:icon_name:` (e.g., `:rocket:`, `:bug:`, `:memo:`, `:white_check_mark:`). Used for visual identification. Set to null to remove the custom icon and use the task type default."},"description":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as
link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as
inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n\n```\n\n**variable**\nType: inline\nDocument/template variable token (span with data-type=\"variable\" and data-id).\n- id: Variable key, often scoped (e.g. currentUser.firstName, project.name). Only use keys that exist for the document type you are in; product docs list the allowed variable ids. Do not invent new variable names in HTML for production templates.\nAtts:\n- id: null\n```html\n\n```\n\n**embedVideo**\nType: block\nEmbeds a third-party video in an iframe. The div carries data-video-embed with data-embed-url (iframe src) and data-original-url (canonical page URL).\n- embedUrl: Must be a real embed/iframe URL (e.g. YouTube embed) that matches originalUrl.\n- originalUrl: Human-facing link to the video page; keep it in sync with embedUrl. Do not leave placeholder URLs in final HTML if you claim a real video.\nAtts:\n- originalUrl: \n- embedUrl: \n```html\n\n```\n\n### Marks\n\n**link**\nAtts:\n- href: null\n- target: _blank\n- rel: noopener noreferrer nofollow\n- class: null\n- title: null\n```html\nlink text example\n```\n\n**bold**\nAtts: none\n```html\nbold text example\n```\n\n**code**\nAtts: none\n```html\ncode text example\n```\n\n**italic**\nAtts: none\n```html\nitalic text example\n```\n\n**strike**\nAtts: none\n```html\nstrike text example\n```\n\n**underline**\nAtts: none\n```html\nunderline text example\n```\n"},"summary":{"type":"string","description":"Brief summary or short description of the task. Appears in task cards and lists. Can be auto-generated by AI or manually entered."},"priority":{"type":"string","enum":["Low","Normal","High"],"description":"Task priority level: Low, Normal, or High. Used for prioritization and filtering."},"statusId":{"type":"string","description":"UUID of the task status to change to. The status must be valid for the current task type. Changing status updates the task workflow state."},"typeId":{"type":"string","description":"UUID of the task type to change to. Changing the type may automatically update the status if the current status is not valid for the new type. Also updates available custom fields."},"projectId":{"type":"string","description":"UUID of the project to move the task to. Changing the project cascades to all subtasks and time logs, moving them to the new project as well. The user must have access to the new project."},"assignedToId":{"type":"object","description":"UUID of the user to assign the task to. The assigned user receives notifications about task updates. Set to null to unassign the task (remove the assignment)."},"accountableId":{"type":"object","description":"UUID of the user who is accountable for the task. The accountable person is responsible for ensuring completion. Set to null to remove accountability."},"estimatedTime":{"type":"number","description":"Estimated time to complete the task in hours (decimal allowed). Example: 8 for 8 hours, 2.5 for 2.5 hours.","example":2.5},"deadline":{"type":"string","description":"Task deadline or due date in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Used for tracking deadlines and generating deadline warnings. Set to null to remove the deadline."},"guestAccess":{"type":"boolean","description":"Whether organization members (guest users) can access this task. When true, guest users can view and interact with the task. When false, only workspace members can access it.","default":false},"tags":{"description":"Array of tag UUIDs to categorize this task. Replaces all existing tags. Tags enable cross-project organization and filtering. Use an empty array to remove all tags.","type":"array","items":{"type":"string"}},"customFields":{"type":"array","description":"Array of custom field values to update. Each value must correspond to a custom field associated with the task type. The field value format depends on the field type. Replaces all existing custom field values. Use an empty array to clear all custom fields.","items":{"type":"object","properties":{"fieldId":{"type":"string","format":"uuid","description":"Custom field ID (UUID)"},"value":{"type":"string","description":"Field value (format depends on field type)"}}}},"isChangeRequest":{"type":"boolean","description":"Whether this task is a change request. Change requests are typically billed separately and tracked differently in Single projects. Used for scope change management."},"subTasksIds":{"description":"Array of task UUIDs to set as subtasks. Replaces all existing subtasks. Each subtask must exist and be accessible. Use an empty array to remove all subtasks.","type":"array","items":{"type":"string"}},"enableSupportContingent":{"type":"boolean","description":"Enable support contingent for this task"}}},"AddTaskCommentDto":{"type":"object","properties":{"comment":{"type":"string","description":"Accepts Markdown or HTML for complex formatting. This content is rendered by the Leadtime rich editor, not by a plain Markdown viewer.\n\nFor quick/simple text, Markdown is acceptable. For polished user-facing content from an agent or integration, prefer structured HTML because it preserves editor blocks, links, and layout more predictably.\n\nUse only the nodes and marks documented below for this field. Supported editor features differ by endpoint and field. Choose formatting for readability, not decoration: use headings for real sections, paragraphs for narrative text, lists or tables for structured facts, blockquotes for quoted context, callouts for important outcomes/risks/notes when supported, and explicit anchors for links. Do not rely on bare URLs or Markdown links when the link must be clickable; use explicit anchors such as link text.\n\nIn HTML you can use:\n## Node Types and Marks\n\n### Nodes\n\n**paragraph**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nDefault paragraph. extraPlaceholder is an internal structure for the editor to show a ghost placeholder in empty βtemplateβ lines (ProseMirror JSON fragment or null). For normal agent output leave extraPlaceholder as null. Only set it if you are intentionally mirroring a field placeholder the user already has in the open editor; do not set random placeholder data for free-form answers.\nAtts:\n- extraPlaceholder: null\n```html\n\n```\n\n**heading**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nAtts:\n- level: 1\n```html\n\n```\n\n**bulletList**\nType: block list\nContent: listItem+\nAtts: none\n```html\n\n```\n\n**hardBreak**\nType: inline\nAtts: none\n```html\n
\n```\n\n**horizontalRule**\nType: block\nAtts: none\n```html\n
\n```\n\n**orderedList**\nType: block list\nContent: listItem+\nAtts:\n- start: 1\n- type: null\n```html\n
\n```\n\n**listItem**\nContent: (paragraph|list)* (paragraphs and/or lists, in any order)\nAtts: none\n```html\n\n```\n\n**blockquote**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n
\n```\n\n**codeBlock**\nType: block\nContent: text* (text only (plus marks if applicable), no block wrappers)\nAtts:\n- language: null\n```html\n
\n```\n\n**table**\nType: block\nContent: tableRow+\nAtts: none\n```html\n\n```\n\n**tableRow**\nContent: (tableCell | tableHeader)*\nAtts: none\n```html\n|
\n```\n\n**tableHeader**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**tableCell**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts:\n- colspan: 1\n- rowspan: 1\n- colwidth: null\n- align: null\n```html\n | \n```\n\n**callout**\nType: block\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nCallout / info box. The icon attr is an emoji shortcode (e.g. :information_source:, :warning:); it appears on the callout. Body is block content (paragraphs, lists, etc.) β use normal block HTML such as inside the callout
. data-type is \"callout\".\nAtts:\n- icon: :information_source:\n```html\n
\n```\n\n**condition**\nType: block\nContent: conditionBody (a single condition body block)\nThis node conditionally renders its content based on a set of rules. The rules are defined in the 'conditions' attribute. \n'conditions' is an object like: { type: 'and' | 'or', expressions: Array
}.\nAn 'Expression' is { field: string, operator: string, value: any }.\nA 'ConditionGroup' is a nested { type: 'and' | 'or', expressions: [...] }.\nExample for an expression: { field: 'invoice.total', operator: 'gt', value: 100 } means 'if invoice total is greater than 100'.\nSupported operators typically include: eq (equals), neq (not equals), gt (greater than), gte (greater than or equal to), lt (less than), lte (less than or equal to), contains, in, is_true, is_false, etc. Check editor UI for available fields and operators.\nALL FIELDS CAN ONLY BE EXISTING VARIABLES. DO NOT INVENT NEW FIELDS.\nAtts:\n- conditions: {\n \"type\": \"and\",\n \"expressions\": []\n}\n```html\n\n```\n\n**conditionBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nAtts: none\n```html\n\n```\n\n**emoji**\nType: inline\nInline emoji. icon is a colon shortcode (e.g. :thumbsup:, :white_check_mark:) stored in data-icon; body is often empty. Use names your emoji set supports; avoid inventing invalid shortcodes in final HTML if you need them to render.\nAtts:\n- icon: :smile:\n```html\n\n```\n\n**entity**\nType: inline\nInline link chip to a Leadtime entity (task, project, etc.), usually from the !-picker or by pasting a leadtime link. Display text is #title; data-type is \"entity\".\n- entityId: Stable id of the target entity (e.g. task or project id). Use ids from the Public API or the userβs context; do not fabricate ids.\n- type: What kind of entity is linked (e.g. task, project) β must be consistent with entityId in your workspace.\n- title: Shown as the visible #label after the chip; should match the real entity title.\n- data: Optional extra JSON the client provides (may be empty). Do not put secrets in HTML.\nIf the user has not given a real entity, use the API to search or createβdo not guess UUIDs or labels.\nAtts:\n- entityId: null\n- type: null\n- title: null\n- data: {}\n```html\n#null/some-value\n```\n\n**appFile**\nType: block\nBlock for a file attachment that already exists in the workspace.\n- fileId: Id from Leadtime file storage. Must be real; do not make up.\n- filename and size: Should match the stored file. Use the app upload or API to get a file id; do not embed arbitrary ids.\nAtts:\n- fileId: \n- filename: \n- size: 0\n```html\n\n```\n\n**appImage**\nType: block\nBlock for an image file already uploaded in Leadtime.\n- fileId: Id of the stored image. Must be a real uploaded file; do not invent.\n- filename: Display name; should match the file.\n- width, align, size: Layout as in the editor. If no file id is available, obtain one via upload/API before outputting this node with a fake id.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**mention**\nType: inline\nMentions a workspace member (inserted in the app via the @-picker). The visible label is @name.\n- id: Leadtime user/employee id for the mentioned person. Must match a real user in the workspace; do not invent idsβresolve people from context or the Public API.\n- name: Display name for the @mention label. Should match the user shown for id.\nHTML must keep data-type=\"mention\" with data-id and data-name in sync; plain text in the node is the visible @name.\nAtts:\n- id: null\n- name: null\n```html\n@null/some-value\n```\n\n**pageBreak**\nType: block\nPage break for PDF/print output (void element). Inserts a hard page break when exporting. Use sparingly where the user asked for a new printed page, not for normal on-screen line breaks (use hardBreak/paragraphs instead).\nAtts: none\n```html\n\n```\n\n**editorPlaceholder**\nType: block\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nUsed in task-type / template fields as a single editable βfieldβ slot. Renders as a block with inline* content (label/instructions) inside. Prefer normal paragraph nodes for free-form user content; use this when reproducing a structured template the user is editing, not for generic text.\nAtts: none\n```html\n\n```\n\n**appVideo**\nType: block\nBlock for a workspace video file already uploaded in Leadtime (not a generic external embed).\n- fileId: Id of the stored file. Must be a file that actually exists in the workspace after upload; do not fabricate.\n- filename: Display name; should match the file.\n- width, align, size: Layout hints as in the editor; keep realistic values. If you do not have a file id, use the file upload or Public API firstβdo not guess ids.\nAtts:\n- fileId: \n- filename: \n- width: 500\n- align: left\n- size: 0\n```html\n\n```\n\n**collapse**\nType: block\nContent: collapseTitle collapseBody (a collapse title node, then a collapse body)\nExpandable/collapsible section. Required structure: one collapseTitle (summary, inline) then one collapseBody (blocks) as direct children, matching data-type= collapseTitle / collapseBody tags under . Do not use title/body nodes outside of a collapse.\nAtts: none\n```html\n\n```\n\n**collapseBody**\nContent: block+ (one or more block child nodes (e.g. paragraph, list, β¦))\nExpandable body of a collapse. Only use as sibling of collapseTitle inside a collapse; holds the block content that shows when expanded.\nAtts: none\n```html\n\n```\n\n**collapseTitle**\nContent: inline* (inline only β do not use block tags such as inside; use e.g.
, , , β¦)\nClickable title row of a collapse block. Only use inside a collapse that also has collapseBody; content is the summary line shown when collapsed.\nAtts: none\n```html\n