{"openapi":"3.0.0","info":{"title":"Afineo Webservices API — tasks","description":"Module `tasks` of the Afineo API v3 (5 endpoints).\n\nTasks operations\n\nFull specification: https://api.afineo.io/openapi.json","version":"3.0.0","contact":{"name":"Afineo Solutions","url":"https://www.afineo.com"},"x-logo":{"url":"./logo.png","altText":"Afineo - Powerful Data, Powerful People"}},"servers":[{"url":"https://{instance}.afineo.io","description":"Afineo instance","variables":{"instance":{"description":"Your Afineo instance name","default":"client"}}}],"tags":[{"name":"tasks","description":"Tasks operations"}],"paths":{"/api/v3/tasks/create/":{"post":{"tags":["tasks"],"summary":"create — Create a task","description":"## Purpose\n\nCreates a task and returns it in full.\n\nOnly the title is required; every other field may be set in the same call.\n\n## Attachment\n\nA task is visible to its creator, its assignee, its subscribers, the contributors of one of its task projects, and administrators. Being attached to a record does not change that: a participant who cannot see the record still sees the task, with the record label only.\n\nWith `class_id` plus `node_id` (project) or `fiche_id` (outside any project), the task is attached to that record. The caller must be able to see that record.\n\n## Atomicity\n\nEvery field is written in the transaction that creates the task. A rejected value cancels the whole creation rather than leaving a half-filled task.\n\n## Errors\n\nMessages coming from the Tasks service are translated into the caller language; their English text is given below.\n\n- `2` : a parameter is missing, of the wrong type, outside the allowed values, or a nested property is malformed (see the request schema)\n- `2` : `The title is required`\n- `2` : `The parameter \"class_id\" is required together with \"node_id\" or \"fiche_id\"`\n- `2` : `The parameter \"class_id\" requires either \"node_id\" or \"fiche_id\"`\n- `2` : `The field \"…\" is not a custom field: use the parameter of the same name instead` (a native field such as title or deadline sent in custom_fields)\n- `2` : `The date entered is invalid.` (deadline not formatted YYYY-MM-DD, or not a real date)\n- `2` : `The requested attribute cannot be found.` (unknown code in custom_fields)\n- `2` : `The attribute value is invalid.` (value refused by an additional field, for example an unknown option)\n- `2` : `This person cannot be selected for this task.` (responsible or subscriber not returned by the users endpoint)\n- `997` : `The tasks extension is not active on this instance`\n- `997` : `The tasks workspace is not enabled on this instance`\n- `997` : `You don't have the rights to do this action` (no « Accès aux tâches » permission, or no right on the task itself)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The created task","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"result":{"type":"object","properties":{"id":{"type":"integer","example":12,"description":"Task identifier"},"title":{"type":"string","example":"Check the supplier sheet","description":"Task title"},"status":{"type":"string","example":"open","description":"Completion status: open or completed"},"deadline":{"type":"string","example":"2026-10-15","description":"Due date, YYYY-MM-DD, empty when not set"},"responsible":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Assignee, null when unassigned","nullable":true},"description":{"type":"string","example":"Check before publishing.","description":"Task description. Detailed field."},"start_date":{"type":"string","example":"2026-09-22","description":"Start date of the task, empty until set in the Tasks workspace (distinct from the creation date). Read only through the API. Detailed field."},"creator":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who created the task. Detailed field."},"subscribers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}}},"description":"Users notified of the activity. Detailed field."},"project_ids":{"type":"array","items":{"type":"integer"},"description":"Task projects the task belongs to. Detailed field."},"group_ids":{"type":"array","items":{"type":"integer"},"description":"Groups of task projects the task belongs to. Detailed field."},"custom_fields":{"type":"object","example":{"priority":2},"description":"Additional field values, keyed by their stable code. Detailed field."},"context":{"type":"object","nullable":true,"description":"Record the task is attached to, null when the task is free. Detailed field.","properties":{"class_id":{"type":"integer","example":4,"description":"Library of the record"},"node_id":{"type":"integer","example":0,"description":"Project node, 0 outside any project"},"fiche_id":{"type":"integer","example":205,"description":"Record identifier"},"label":{"type":"string","example":"Chaise Bertille","description":"Record label"},"class_label":{"type":"string","example":"Produits","description":"Library label"}}},"permissions":{"type":"object","description":"What the caller may do with this task. Detailed field.","properties":{"view":{"type":"boolean","example":true,"description":"May read the task"},"edit":{"type":"boolean","example":true,"description":"May update the task"},"share":{"type":"boolean","example":true,"description":"May change the subscribers"},"delete":{"type":"boolean","example":true,"description":"May delete the task"},"comment":{"type":"boolean","example":true,"description":"May comment the task"},"reopen":{"type":"boolean","example":false,"description":"Completed task the user may reopen: a completed task is read only, only its reopening (status open) is accepted"}}},"comments":{"type":"array","description":"Comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":87,"description":"Comment identifier"},"body":{"type":"string","example":"Sheet checked.","description":"Comment text"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Comment author"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Creation date"},"updated_at":{"type":"string","nullable":true,"example":null,"description":"Last edition date, null when never edited"}}}},"activity":{"type":"array","description":"Recorded events other than comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":86,"description":"Event identifier"},"kind":{"type":"string","example":"updated","description":"Event kind: created or updated"},"label":{"type":"string","example":"Mise à jour","description":"Event label in the caller language"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who caused the event"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Event date"}}}},"notification_failed":{"type":"boolean","example":false,"description":"True when the write succeeded but its notification could not be delivered. Update endpoint only."}}},"status_message":{"type":"string","example":"Task created","description":"Status message"}}}]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Task title, up to 1000 characters.","example":"Check the supplier sheet"},"description":{"type":"string","description":"Task description, up to 100000 characters. An empty string clears it.","example":"Check the supplier sheet before publishing."},"deadline":{"type":"string","description":"Due date, formatted YYYY-MM-DD. An empty string clears it.","example":"2026-10-15"},"responsible":{"type":"integer","description":"User the task is assigned to. 0 leaves it unassigned. The user must be allowed to see the task.","example":42},"subscribers":{"type":"array","description":"Users notified of the task activity. Replaces the current list. Every user must be allowed to see the task.","example":[42,57],"items":{"type":"integer"}},"custom_fields":{"type":"object","description":"Additional fields, keyed by their stable code (for example priority, advancement). Call this endpoint list with detail_level=full to get the available codes, their type and their allowed options.","example":{"priority":2}},"class_id":{"type":"integer","description":"Library of the record the task is attached to. Required together with node_id or fiche_id. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"node_id":{"type":"integer","description":"Project node the task is attached to. Leave empty or 0 to target a record outside any project.","example":0},"fiche_id":{"type":"integer","description":"Record the task is attached to, outside any project. With node_id, leave it empty: when both are given, fiche_id must be the record at that node, otherwise the call is refused.","example":205}},"required":["title"]}}}}}},"/api/v3/tasks/delete/":{"post":{"tags":["tasks"],"summary":"delete — Delete a task","description":"## Purpose\n\nDeletes a task (logical deletion) and removes it from the index and from the record it was attached to. Its attachments, comments and activity are kept in the database.\n\nSend `ids` (up to 200) instead of `id` to delete several tasks at once: each one is deleted as by a single call, a refused task does not stop the others, and the result lists `deleted` (identifiers) and `refused` (`id`, `message`).\n\nWhoever sees the task may delete it, completed or not: its creator, its assignee, one of its subscribers, a contributor of one of its task projects, or an administrator.\n\n## Concurrency\n\nThe deletion applies to the task as it stands. A deletion colliding with another write in the very same instant is refused on `2`: retry the call.\n\n## Errors\n\nMessages coming from the Tasks service are translated into the caller language; their English text is given below.\n\n- `2` : a parameter is missing, of the wrong type, outside the allowed values, or a nested property is malformed (see the request schema)\n- `2` : `This task has been modified in the meantime. Reload its current version before trying again.` (another write landed at the same instant, rare: retry)\n- `3` : `This task cannot be found.` (unknown or deleted task)\n- `997` : `The tasks extension is not active on this instance`\n- `997` : `The tasks workspace is not enabled on this instance`\n- `997` : `You don't have the rights to do this action` (no « Accès aux tâches » permission, or no right on the task itself)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"result":{"type":"object","properties":{"id":{"type":"integer","example":12,"description":"Identifier of the deleted task"},"deleted":{"type":"boolean","example":true,"description":"Always true when the call succeeds"}}},"status_message":{"type":"string","example":"Task deleted","description":"Status message"}}}]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Task to delete. Use POST /api/v3/tasks/list to get identifiers. Required unless ids is sent.","example":12},"ids":{"type":"array","description":"Several tasks to delete at once (up to 200), instead of id.","example":[12,13],"items":{"type":"integer"}}}}}}}}},"/api/v3/tasks/list/":{"post":{"tags":["tasks"],"summary":"list — Search tasks with filters and pagination","description":"## Purpose\n\nReturns the tasks the authenticated user is allowed to see, with filters, sorting and pagination.\n\nA task is visible to its creator, its assignee, its subscribers, the contributors of one of its task projects, and administrators. Being attached to a record does not change that: a participant who cannot see the record still sees the task, with the record label only. No filter ever widens that visibility.\n\n## Level of detail\n\n- `summary` (default): identifier, title, status, deadline and assignee. Enough to build a list.\n- `full`: every field of each task, plus `custom_fields_schema` describing the additional fields available on this instance.\n\nPass `id` to return a single task. Its comments and activity are then included, whatever the level of detail.\n\n## Scope\n\n- `all` (default): every task the caller may see.\n- `mine`: tasks assigned to the caller, plus the ones they created that are still unassigned.\n- `created`: tasks created by the caller, whoever their assignee.\n\n## Pagination\n\nUse `num_page` and `results_per_page` together. Results per page: 10-1000, 50 by default.\n\n## Errors\n\nMessages coming from the Tasks service are translated into the caller language; their English text is given below.\n\n- `2` : a parameter is missing, of the wrong type, outside the allowed values, or a nested property is malformed (see the request schema)\n- `2` : `The parameters \"num_page\" and \"results_per_page\" must be filled together`\n- `2` : `The parameter \"class_id\" is required together with \"node_id\" or \"fiche_id\"`\n- `2` : `The parameter \"class_id\" requires either \"node_id\" or \"fiche_id\"`\n- `2` : `The field \"…\" is not a custom field: use the parameter of the same name instead` (a native field such as title or deadline sent in custom_fields)\n- `2` : `The selected filter is invalid.` (unknown code in custom_fields)\n- `3` : `No tasks found`\n- `3` : `This task cannot be found.` (with `id`: unknown or deleted task)\n- `997` : `The tasks extension is not active on this instance`\n- `997` : `The tasks workspace is not enabled on this instance`\n- `997` : `You don't have the rights to do this action` (no « Accès aux tâches » permission, or no right on the task itself)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Matching tasks","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"result":{"type":"object","properties":{"tasks":{"type":"array","description":"Matching tasks, ordered by the requested sort","items":{"type":"object","properties":{"id":{"type":"integer","example":12,"description":"Task identifier"},"title":{"type":"string","example":"Check the supplier sheet","description":"Task title"},"status":{"type":"string","example":"open","description":"Completion status: open or completed"},"deadline":{"type":"string","example":"2026-10-15","description":"Due date, YYYY-MM-DD, empty when not set"},"responsible":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Assignee, null when unassigned","nullable":true},"description":{"type":"string","example":"Check before publishing.","description":"Task description. Detailed field."},"start_date":{"type":"string","example":"2026-09-22","description":"Start date of the task, empty until set in the Tasks workspace (distinct from the creation date). Read only through the API. Detailed field."},"creator":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who created the task. Detailed field."},"subscribers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}}},"description":"Users notified of the activity. Detailed field."},"project_ids":{"type":"array","items":{"type":"integer"},"description":"Task projects the task belongs to. Detailed field."},"group_ids":{"type":"array","items":{"type":"integer"},"description":"Groups of task projects the task belongs to. Detailed field."},"custom_fields":{"type":"object","example":{"priority":2},"description":"Additional field values, keyed by their stable code. Detailed field."},"context":{"type":"object","nullable":true,"description":"Record the task is attached to, null when the task is free. Detailed field.","properties":{"class_id":{"type":"integer","example":4,"description":"Library of the record"},"node_id":{"type":"integer","example":0,"description":"Project node, 0 outside any project"},"fiche_id":{"type":"integer","example":205,"description":"Record identifier"},"label":{"type":"string","example":"Chaise Bertille","description":"Record label"},"class_label":{"type":"string","example":"Produits","description":"Library label"}}},"permissions":{"type":"object","description":"What the caller may do with this task. Detailed field.","properties":{"view":{"type":"boolean","example":true,"description":"May read the task"},"edit":{"type":"boolean","example":true,"description":"May update the task"},"share":{"type":"boolean","example":true,"description":"May change the subscribers"},"delete":{"type":"boolean","example":true,"description":"May delete the task"},"comment":{"type":"boolean","example":true,"description":"May comment the task"},"reopen":{"type":"boolean","example":false,"description":"Completed task the user may reopen: a completed task is read only, only its reopening (status open) is accepted"}}},"comments":{"type":"array","description":"Comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":87,"description":"Comment identifier"},"body":{"type":"string","example":"Sheet checked.","description":"Comment text"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Comment author"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Creation date"},"updated_at":{"type":"string","nullable":true,"example":null,"description":"Last edition date, null when never edited"}}}},"activity":{"type":"array","description":"Recorded events other than comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":86,"description":"Event identifier"},"kind":{"type":"string","example":"updated","description":"Event kind: created or updated"},"label":{"type":"string","example":"Mise à jour","description":"Event label in the caller language"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who caused the event"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Event date"}}}},"notification_failed":{"type":"boolean","example":false,"description":"True when the write succeeded but its notification could not be delivered. Update endpoint only."}}}},"total":{"type":"integer","example":128,"description":"Total number of matching tasks, all pages included"},"num_page":{"type":"integer","example":1,"description":"Returned page number"},"results_per_page":{"type":"integer","example":50,"description":"Applied page size"},"custom_fields_schema":{"type":"array","description":"Additional fields available on this instance. Only with detail_level=full.","items":{"type":"object","properties":{"code":{"type":"string","example":"priority","description":"Stable code, used as the key in custom_fields"},"label":{"type":"string","example":"Priorité","description":"Label in the caller language"},"type":{"type":"string","example":"dropdown_items","description":"Value type: short_text, long_text, integer, decimal, date, boolean, dropdown_items, multi_dropdown_items (dropdown for older single-choice fields)"},"options":{"type":"array","description":"Allowed values, for list types only","items":{"type":"object","properties":{"id":{"type":"integer","example":2,"description":"Option identifier, to send in custom_fields"},"label":{"type":"string","example":"Haute","description":"Option label"}}}},"archived":{"type":"boolean","example":false,"description":"An archived field is still readable but can no longer be written or filtered on"}}}}}},"status_message":{"type":"string","example":"Tasks list","description":"Status message"}}}]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Return this single task, with its comments and activity.","example":12},"scope":{"type":"string","description":"Which tasks to search: mine (assigned to the caller, or created and unassigned), created (created by the caller), all. Default: all.","enum":["mine","created","all"],"example":"all"},"status":{"type":"string","description":"Filter on the completion status. Default: open.","enum":["open","completed","all"],"example":"open"},"search":{"type":"string","description":"Free text searched in the title and the description. Each word must appear, in any order, ignoring case and accents (up to 8 words).","example":"supplier"},"responsible":{"type":"integer","description":"Filter on the assignee. 0 returns the unassigned tasks.","example":42},"project_id":{"type":"integer","description":"Filter on a task project: tasks linked to the project or to one of its groups.","example":12},"group_id":{"type":"integer","description":"Filter on a group of a task project.","example":14},"due":{"type":"string","description":"Filter on the due date: overdue (past and still open), today (due today), week (today and the next seven days), none (no due date).","enum":["overdue","today","week","none"],"example":"overdue"},"custom_fields":{"type":"object","description":"Filter on additional fields, keyed by their stable code. Call this endpoint with detail_level=full to get the available codes.","example":{"priority":2}},"sort":{"type":"string","description":"Sort key and direction. Default: deadline_asc.","enum":["deadline_asc","deadline_desc","title_asc","title_desc","responsible_asc","responsible_desc","status_asc","status_desc","created_asc","created_desc","updated_asc","updated_desc"],"example":"deadline_asc"},"num_page":{"type":"integer","description":"Page number. Must be used together with results_per_page.","example":1},"results_per_page":{"type":"integer","description":"Number of results per page (between 10 and 1000). Must be used together with num_page.","example":50},"detail_level":{"type":"string","description":"Richness of each returned task. Default: summary.","enum":["summary","full"],"example":"summary"},"class_id":{"type":"integer","description":"Library of the record the task is attached to. Required together with node_id or fiche_id. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"node_id":{"type":"integer","description":"Project node the task is attached to. Leave empty or 0 to target a record outside any project.","example":0},"fiche_id":{"type":"integer","description":"Record the task is attached to, outside any project. With node_id, leave it empty: when both are given, fiche_id must be the record at that node, otherwise the call is refused.","example":205}}}}}}}},"/api/v3/tasks/update/":{"post":{"tags":["tasks"],"summary":"update — Update a task","description":"## Purpose\n\nUpdates the provided fields of a task and returns it in full. Fields left out are untouched.\n\nThe caller must be able to see the task: its creator, its assignee, one of its subscribers, a contributor of one of its task projects, or an administrator.\n\n## Several tasks at once\n\nSend `ids` (up to 200) instead of `id`, with exactly one of `status`, `responsible` or `deadline`. Each task is updated as by a single call, with the same rules and notifications; a refused task (no right, completed task…) does not stop the others. The result lists `updated` (identifiers) and `refused` (`id`, `message`).\n\n## Comment\n\n`comment` adds a comment as the caller, alone or together with field changes. `comment_mentions` lists the users to mention (identifiers from POST /api/v3/tasks/users): a mention is kept when « @Name » appears in the text, and « @Name » is added at the start of the comment when it does not. The author and the mentioned users become subscribers; the assignee and the subscribers are notified of the comment, the mentioned users receive a mention notification instead. The created comment is returned in `comment`.\n\nOn a completed task, a comment is accepted together with `status` = `open` (the task is reopened first); with `status` = `completed`, the comment is added before the task is completed.\n\nA completed task is read-only: only reopening it (`status` = `open`) is accepted; any other field is refused on `2`.\n\n## Concurrency\n\nThe write applies to the task as it stands: the last writer wins. A user editing the same task from the interface is still protected, since their own save is refused when the task changed under them, and they are asked to reload.\n\nTwo writes landing in the very same instant are still refused, on `2`: retry the call.\n\n## Attachment\n\n`class_id` with `node_id` or `fiche_id` attaches the task to that record; on a task already attached, the new record replaces the former one. The caller must see both records. Detaching a task is not available through the API.\n\n## Restrictions\n\n- Whoever sees a task may change its fields and its subscribers.\n- The creator is set at creation and cannot be changed. `start_date` is empty until set in the Tasks workspace.\n- An empty title is refused (code `2`): to delete a task, use the delete endpoint.\n\n## Errors\n\nMessages coming from the Tasks service are translated into the caller language; their English text is given below.\n\n- `2` : a parameter is missing, of the wrong type, outside the allowed values, or a nested property is malformed (see the request schema)\n- `2` : `The title is required`\n- `2` : `The parameter \"class_id\" is required together with \"node_id\" or \"fiche_id\"`\n- `2` : `The parameter \"class_id\" requires either \"node_id\" or \"fiche_id\"`\n- `2` : `The field \"…\" is not a custom field: use the parameter of the same name instead` (a native field such as title or deadline sent in custom_fields)\n- `2` : `The date entered is invalid.` (deadline not formatted YYYY-MM-DD, or not a real date)\n- `2` : `The requested attribute cannot be found.` (unknown code in custom_fields)\n- `2` : `The attribute value is invalid.` (value refused by an additional field, for example an unknown option)\n- `2` : `This person cannot be selected for this task.` (responsible or subscriber not returned by the users endpoint)\n- `2` : `The due date cannot be earlier than the start date.`\n- `2` : `This task is completed: reopen it to edit it.` (any change other than status = open on a completed task, comment included)\n- `2` : `The comment must contain between 1 and 20,000 characters.`\n- `2` : `This person cannot be mentioned in this task.` (comment_mentions: user absent from POST /api/v3/tasks/users)\n- `2` : `This task has been modified in the meantime. Reload its current version before trying again.` (another write landed at the same instant, rare: retry)\n- `3` : `This task cannot be found.` (unknown or deleted task)\n- `997` : `The tasks extension is not active on this instance`\n- `997` : `The tasks workspace is not enabled on this instance`\n- `997` : `You don't have the rights to do this action` (no « Accès aux tâches » permission, or no right on the task itself)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The updated task","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"result":{"type":"object","properties":{"id":{"type":"integer","example":12,"description":"Task identifier"},"title":{"type":"string","example":"Check the supplier sheet","description":"Task title"},"status":{"type":"string","example":"open","description":"Completion status: open or completed"},"deadline":{"type":"string","example":"2026-10-15","description":"Due date, YYYY-MM-DD, empty when not set"},"responsible":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Assignee, null when unassigned","nullable":true},"description":{"type":"string","example":"Check before publishing.","description":"Task description. Detailed field."},"start_date":{"type":"string","example":"2026-09-22","description":"Start date of the task, empty until set in the Tasks workspace (distinct from the creation date). Read only through the API. Detailed field."},"creator":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who created the task. Detailed field."},"subscribers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}}},"description":"Users notified of the activity. Detailed field."},"project_ids":{"type":"array","items":{"type":"integer"},"description":"Task projects the task belongs to. Detailed field."},"group_ids":{"type":"array","items":{"type":"integer"},"description":"Groups of task projects the task belongs to. Detailed field."},"custom_fields":{"type":"object","example":{"priority":2},"description":"Additional field values, keyed by their stable code. Detailed field."},"context":{"type":"object","nullable":true,"description":"Record the task is attached to, null when the task is free. Detailed field.","properties":{"class_id":{"type":"integer","example":4,"description":"Library of the record"},"node_id":{"type":"integer","example":0,"description":"Project node, 0 outside any project"},"fiche_id":{"type":"integer","example":205,"description":"Record identifier"},"label":{"type":"string","example":"Chaise Bertille","description":"Record label"},"class_label":{"type":"string","example":"Produits","description":"Library label"}}},"permissions":{"type":"object","description":"What the caller may do with this task. Detailed field.","properties":{"view":{"type":"boolean","example":true,"description":"May read the task"},"edit":{"type":"boolean","example":true,"description":"May update the task"},"share":{"type":"boolean","example":true,"description":"May change the subscribers"},"delete":{"type":"boolean","example":true,"description":"May delete the task"},"comment":{"type":"boolean","example":true,"description":"May comment the task"},"reopen":{"type":"boolean","example":false,"description":"Completed task the user may reopen: a completed task is read only, only its reopening (status open) is accepted"}}},"comments":{"type":"array","description":"Comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":87,"description":"Comment identifier"},"body":{"type":"string","example":"Sheet checked.","description":"Comment text"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Comment author"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Creation date"},"updated_at":{"type":"string","nullable":true,"example":null,"description":"Last edition date, null when never edited"}}}},"activity":{"type":"array","description":"Recorded events other than comments, oldest first. Only when a single task is requested by id.","items":{"type":"object","properties":{"id":{"type":"integer","example":86,"description":"Event identifier"},"kind":{"type":"string","example":"updated","description":"Event kind: created or updated"},"label":{"type":"string","example":"Mise à jour","description":"Event label in the caller language"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"User who caused the event"},"created_at":{"type":"string","example":"2026-09-20 11:04:12","description":"Event date"}}}},"notification_failed":{"type":"boolean","example":false,"description":"True when the write succeeded but its notification could not be delivered. Update endpoint only."},"comment":{"type":"object","nullable":true,"description":"The comment created by the comment parameter. Update endpoint only, when comment was sent.","properties":{"id":{"type":"integer","example":87,"description":"Comment identifier"},"body":{"type":"string","example":"@Camille Ducret I am on it.","description":"Comment text as saved"},"author":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"}},"description":"Comment author"},"created_at":{"type":"string","example":"2026-10-20 11:04:12","description":"Creation date"},"updated_at":{"type":"string","nullable":true,"example":null,"description":"Always null for a new comment"}}}}},"status_message":{"type":"string","example":"Task updated","description":"Status message"}}}]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Task to update. Use POST /api/v3/tasks/list to get identifiers. Required unless ids is sent.","example":12},"ids":{"type":"array","description":"Several tasks to update at once (up to 200), instead of id. Send exactly one of status, responsible or deadline with it.","example":[12,13],"items":{"type":"integer"}},"title":{"type":"string","description":"Task title, up to 1000 characters. Must not be empty.","example":"Check the supplier sheet"},"status":{"type":"string","description":"Completion status of the task.","enum":["open","completed"],"example":"completed"},"comment":{"type":"string","description":"Comment to add as the caller, plain text, up to 20000 characters.","example":"I am on it."},"comment_mentions":{"type":"array","description":"Users mentioned in the comment, by identifier (POST /api/v3/tasks/users). Requires comment.","example":[42],"items":{"type":"integer"}},"description":{"type":"string","description":"Task description, up to 100000 characters. An empty string clears it.","example":"Check the supplier sheet before publishing."},"deadline":{"type":"string","description":"Due date, formatted YYYY-MM-DD. An empty string clears it.","example":"2026-10-15"},"responsible":{"type":"integer","description":"User the task is assigned to. 0 leaves it unassigned. The user must be allowed to see the task.","example":42},"subscribers":{"type":"array","description":"Users notified of the task activity. Replaces the current list. Every user must be allowed to see the task.","example":[42,57],"items":{"type":"integer"}},"custom_fields":{"type":"object","description":"Additional fields, keyed by their stable code (for example priority, advancement). Call this endpoint list with detail_level=full to get the available codes, their type and their allowed options.","example":{"priority":2}},"class_id":{"type":"integer","description":"Library of the record the task is attached to. Required together with node_id or fiche_id. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"node_id":{"type":"integer","description":"Project node the task is attached to. Leave empty or 0 to target a record outside any project.","example":0},"fiche_id":{"type":"integer","description":"Record the task is attached to, outside any project. With node_id, leave it empty: when both are given, fiche_id must be the record at that node, otherwise the call is refused.","example":205}}}}}}}},"/api/v3/tasks/users/":{"post":{"tags":["tasks"],"summary":"users — List the users a task may be assigned to","description":"## Purpose\n\nReturns the users that can be set as `responsible` or in `subscribers` on the create and update endpoints: administrators, and users holding the « Accès aux tâches » permission, among the accounts placed in the users tree. It is the list the Tasks workspace proposes.\n\nThe caller is flagged with `me` = true, so that « assign it to me » can be resolved without knowing their identifier. `caller` always gives the caller identifier and whether they can be named at all: when `assignable` is false, no user is flagged and the caller cannot be set as responsible or subscriber.\n\n## Search\n\n`search` keeps the users whose name contains the text, ignoring case and accents. Without it, every eligible user is returned.\n\n## Errors\n\n- `2` : a parameter is missing, of the wrong type, outside the allowed values, or a nested property is malformed (see the request schema)\n- `3` : `No users found`\n- `997` : `The tasks extension is not active on this instance`\n- `997` : `The tasks workspace is not enabled on this instance`\n- `997` : `You don't have the rights to do this action` (no « Accès aux tâches » permission)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Eligible users","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"result":{"type":"object","properties":{"users":{"type":"array","description":"Eligible users, ordered by name","items":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"User identifier, to send in responsible or subscribers"},"label":{"type":"string","example":"Camille Ducret","description":"User display name"},"me":{"type":"boolean","example":false,"description":"True for the caller"}}}},"total":{"type":"integer","example":12,"description":"Number of returned users"},"caller":{"type":"object","description":"The authenticated user, whatever the search","properties":{"id":{"type":"integer","example":42,"description":"Caller identifier"},"assignable":{"type":"boolean","example":true,"description":"False when the caller cannot be set as responsible or subscriber"}}}}},"status_message":{"type":"string","example":"Users list","description":"Status message"}}}]},{"$ref":"#/components/schemas/ErrorResponse"}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Part of the user name, case and accents ignored.","example":"morestin"}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token generated with /api/v3/token/get/"}},"schemas":{"SuccessEnvelope":{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","enum":[1],"example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"}},"required":["status_code","status_message","result"]},"ErrorResponse":{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (0 = the action does not exist, 2 = parameter error, 3 = no result, 997 = unauthorized action, 998 = invalid token, 999 = connection error)"},"status_message":{"type":"string","example":"Class not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]},"ExportPage":{"type":"object","properties":{"results_total":{"type":"integer","example":15,"description":"Total number of items"},"items":{"type":"array","items":{"type":"object"},"description":"Export data"},"num_page":{"type":"integer","nullable":true,"example":1,"description":"Current page number"},"nb_pages":{"type":"integer","nullable":true,"example":15,"description":"Total number of pages"},"results_per_page":{"type":"integer","nullable":true,"example":100,"description":"Number of results per page"}},"required":["results_total","items"],"description":"Export result"},"ExportJobQueued":{"type":"object","properties":{"queue_id":{"type":"integer","example":47593,"description":"Queue ID for async file retrieval via export/get-file"}},"required":["queue_id"],"description":"Queue information"},"ImportAutoResult":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"mapping":{"type":"object","properties":{"resolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":1,"description":"Column index (1-based)"},"header":{"type":"string","example":"reference*","description":"Original column header from file"},"attribute_id":{"type":"integer","nullable":true,"example":145,"description":"Matched attribute ID. Null if mapped to a system field."},"attribute_code":{"type":"string","example":"reference","description":"Portable attribute code (ROLE_XML), stable across environments (the auto-incremented id is not). Only present for attribute mappings."},"attribute_label":{"type":"string","example":"Reference","description":"Matched attribute label. Only present for attribute mappings."},"system_field":{"type":"string","nullable":true,"example":"[ID_FICHE]","description":"System field identifier. Only present for system field mappings. Full list: [ID_FICHE], [ID_NODE], [ID_TYPE], [CODE_TYPE], [LABEL_TYPE], [ID_STATUT], [CODE_STATUT], [LABEL_STATUT], [STATUT] (legacy synonym of [LABEL_STATUT]), [ID_WFITEMS], [CODE_WFITEMS], [LABEL_WFITEMS], [ORDRE], [PARENT], [PAGENUM]. The [CODE_*] forms are the portable ones: they are stable across environments, unlike the ids, and not translated, unlike the labels."},"is_key":{"type":"boolean","example":true,"description":"Whether this column is marked as a key column (header ends with *)"}}},"description":"Columns successfully mapped to attributes or system fields"},"unresolved":{"type":"array","items":{"type":"object","properties":{"column":{"type":"integer","example":3,"description":"Column index (1-based)"},"header":{"type":"string","example":"unknown_column","description":"Column header that could not be matched to any attribute"}}},"description":"Columns that could not be mapped (no matching uname or label found in the class)"}},"description":"Mapping information"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":1500,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1200,"description":"Number of assets created"},"updated":{"type":"integer","example":300,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","description":"Row number"},"message":{"type":"string","description":"Error message"}}},"description":"List of row-level errors"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log. Can be used to track or reference this import operation."}},"required":["success","mapping","stats","errors"],"description":"Import result"},"ImportJsonResult":{"type":"object","properties":{"success":{"type":"boolean","example":true,"description":"Import success status"},"stats":{"type":"object","properties":{"total_rows":{"type":"integer","example":2,"description":"Total number of data rows processed"},"created":{"type":"integer","example":1,"description":"Number of assets created"},"updated":{"type":"integer","example":1,"description":"Number of assets updated"},"excluded":{"type":"integer","example":0,"description":"Number of rows excluded (no key value)"},"errors":{"type":"integer","example":0,"description":"Number of rows with errors"}},"required":["total_rows","created","updated","excluded","errors"],"description":"Import statistics"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","example":3,"description":"Row number where error occurred"},"message":{"type":"string","example":"Invalid attribute ID: 999","description":"Error message describing the issue"}}},"example":[{"row":3,"message":"Invalid attribute ID: 999"}],"description":"List of row-level errors encountered during import"},"history_id":{"type":"integer","example":12345,"description":"ID of the import action in the history log"},"mapping":{"type":"object","additionalProperties":true,"description":"Column-to-attribute mapping actually applied, always returned : the JSON endpoints share executeAutoImport() with the auto_* endpoints. Same shape as ImportAutoResult.mapping (resolved[] / unresolved[])."}},"required":["success","mapping","stats","errors"],"description":"Import result"},"PermissionGroup":{"type":"object","properties":{"id":{"type":"integer","example":15,"description":"Group ID"},"label":{"type":"string","example":"My group","description":"Group label"},"parent_id":{"type":"integer","example":1511,"description":"Parent group ID"},"parent_label":{"type":"string","example":"My group parent","description":"Parent group label"},"configuration":{"type":"object","properties":{"langs":{"type":"object","additionalProperties":true,"example":{"all_versions":true},"description":"Multilingual"},"default_display_mask":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":1032,"description":"Mask ID"},"code":{"type":"string","example":"mask_purchasing","description":"Portable mask code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"A mask","description":"Mask label"}},"description":"Default display mask of the group. Use `code` rather than `id` to replay this configuration on another environment."},"profiles":{"type":"object","description":"Profiles of the group, one per type. Use `code` rather than `id` to replay this configuration on another environment.","properties":{"asset":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":35,"description":"Profile ID"},"code":{"type":"string","example":"profile_full_rights","description":"Portable profile code"},"label":{"type":"string","example":"Full rights","description":"Profile label"}},"description":"Asset profile"},"general":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":33,"description":"Profile ID"},"code":{"type":"string","example":"profile_full_rights","description":"Portable profile code"},"label":{"type":"string","example":"Full rights","description":"Profile label"}},"description":"General profile"},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":34,"description":"Profile ID"},"code":{"type":"string","example":"profile_full_rights","description":"Portable profile code"},"label":{"type":"string","example":"Full rights","description":"Profile label"}},"description":"Project profile"}}},"status":{"type":"array","items":{"type":"object","properties":{"class_id":{"type":"integer","example":2,"description":"Class ID"},"class_code":{"type":"string","example":"lib_products","description":"Portable library code, stable across environments (the auto-incremented id is not)"},"class_label":{"type":"string","example":"DAM","description":"Class label"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":1093,"description":"Status ID"},"code":{"type":"string","example":"status_active","description":"Portable status code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Active","description":"Status label"}},"required":["id","code","label"]},"description":"Statuses granted to the group for this library. Use `code` rather than `id` to replay this configuration on another environment."}},"required":["class_id","class_code","class_label","items"]},"description":"Status list"},"overload_by_status":{"type":"array","items":{"type":"object","properties":{"class_id":{"type":"integer","example":2,"description":"Class ID"},"class_code":{"type":"string","example":"lib_products","description":"Portable library code, stable across environments (the auto-incremented id is not)"},"class_label":{"type":"string","example":"DAM","description":"Class label"},"items":{"type":"array","items":{"type":"object","properties":{"status":{"type":"object","properties":{"id":{"type":"integer","example":1111,"description":"Status ID"},"code":{"type":"string","example":"status_proposed","description":"Portable status code, stable across environments"},"label":{"type":"string","example":"Proposed","description":"Status label"}},"required":["id","code","label"],"description":"Status the overload applies to"},"profile_asset":{"type":"object","properties":{"id":{"type":"integer","example":53,"description":"Profile ID, 0 when the overload does not set a profile"},"code":{"type":"string","example":"profile_contributor","description":"Portable profile code, empty when the overload does not set a profile"},"label":{"type":"string","example":"Profile test","description":"Profile label, \"Default\" when the overload does not set a profile"}},"description":"Overloaded asset profile"},"mask":{"type":"object","properties":{"id":{"type":"integer","example":1064,"description":"Mask ID, 0 when the overload does not set a mask"},"code":{"type":"string","example":"mask_full_display","description":"Portable mask code, empty when the overload does not set a mask"},"label":{"type":"string","example":"Full display mask","description":"Mask label, \"Default\" when the overload does not set a mask"}},"description":"Overloaded display mask"}},"required":["status","profile_asset","mask"]},"description":"Overloads defined for this library"}},"required":["class_id","class_code","class_label","items"]},"description":"Overloaded by status"}},"required":["langs","default_display_mask","profiles","status","overload_by_status"],"description":"Group configuration (langs, default display mask, profiles, statuses and overload by status)"},"users":{"type":"object","additionalProperties":{"type":"string"},"example":{"2187":"login@company.com"},"description":"Users in group"}},"required":["id","label","parent_id","parent_label","configuration","users"]},"DisplayMask":{"type":"object","properties":{"id":{"type":"integer","example":1025,"description":"Mask ID"},"code":{"type":"string","example":"code_1025","description":"Portable mask code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Standard mask","description":"Mask label"},"class_id":{"type":"integer","example":2,"description":"Class ID"},"class_code":{"type":"string","example":"lib_products","description":"Portable library code, stable across environments (the auto-incremented id is not)"},"class_label":{"type":"string","example":"DAM","description":"Class label"},"attributes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":123,"description":"Attribute ID"},"code":{"type":"string","example":"product_name","description":"Portable attribute code (ROLE_XML), stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Product name","description":"Attribute label"},"hidden":{"type":"boolean","example":false,"description":"Whether attribute is hidden"},"read":{"type":"boolean","example":true,"description":"Whether attribute is readable"},"write":{"type":"boolean","example":true,"description":"Whether attribute is writable"},"locally_editable":{"type":"boolean","example":false,"description":"Whether attribute is locally editable (asset share)"}},"required":["id","code","label","hidden","read","write","locally_editable"]},"description":"Attributes configuration for the class"}},"required":["id","code","label","class_id","class_code","class_label","attributes"]},"WorkflowSummary":{"type":"object","properties":{"id":{"type":"integer","example":15,"description":"Workflow ID"},"code":{"type":"string","example":"","description":"Workflow code"},"label":{"type":"string","example":"Workflow validation","description":"Workflow label"},"class_id":{"type":"integer","example":4,"description":"Class ID"},"project_node_id":{"type":"integer","example":1234,"description":"Project node ID (0 for the repository project)"},"project_label":{"type":"string","example":"My Project","description":"Project label (\"Repository Project\" for the repository)"},"tags":{"type":"array","items":{"type":"string"},"example":["validation","review"],"description":"Array of tags (can be empty)"},"supertype":{"type":"object","properties":{"id":{"type":"integer","example":3,"description":"Supertype ID"},"label":{"type":"string","example":"Products","description":"Supertype label"}},"required":["id","label"],"description":"Supertype information"},"types":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"type_product","description":"Portable type code, stable across environments (the auto-incremented id is not)"},"id":{"type":"integer","example":42,"description":"Type ID"},"label":{"type":"string","example":"Product","description":"Type label"}},"required":["id","code","label"]},"description":"Array of asset types associated with this workflow"}},"required":["id","code","label","class_id","project_node_id","project_label","tags","supertype","types"],"description":"Workflow information without its steps"},"WorkflowSummaryList":{"type":"object","properties":{"results_total":{"type":"integer","example":2,"description":"Total number of workflows returned"},"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowSummary"},"description":"Array of workflow objects"}},"required":["results_total","items"]},"Workflow":{"type":"object","properties":{"id":{"type":"integer","example":15,"description":"Workflow ID"},"code":{"type":"string","example":"","description":"Workflow code"},"label":{"type":"string","example":"Workflow validation","description":"Workflow label"},"tags":{"type":"array","items":{"type":"string"},"example":["validation","review"],"description":"Array of tags (can be empty)"},"class_id":{"type":"integer","example":4,"description":"Associated class ID"},"project_node_id":{"type":"integer","example":1234,"description":"Project node ID (0 for repository project)"},"project_label":{"type":"string","example":"My Project","description":"Project label"},"started":{"type":"boolean","example":true,"description":"Whether the workflow is started"},"filters":{"type":"array","nullable":true,"items":{"type":"object","properties":{"attribute_id":{"type":"integer","example":123,"description":"Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes."},"attribute_code":{"type":"string","example":"product_name","description":"Portable attribute code (ROLE_XML), stable across environments (the auto-incremented id is not)"},"attribute_label":{"type":"string","example":"Status","description":"Attribute label"},"value":{"type":"string","example":"active","description":"Filter value"}}},"description":"Workflow filters (array of filter objects or null)"},"supertype":{"type":"object","properties":{"id":{"type":"integer","example":3,"description":"Supertype ID"},"label":{"type":"string","example":"Products","description":"Supertype label"}},"required":["id","label"],"description":"Supertype information"},"types":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"type_product","description":"Portable type code, stable across environments (the auto-incremented id is not)"},"id":{"type":"integer","example":42,"description":"Type ID"},"label":{"type":"string","example":"Product","description":"Type label"}},"required":["id","code","label"]},"description":"Array of asset types associated with this workflow"},"configuration":{"type":"object","properties":{"step_groups":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStepGroup"},"description":"Array of step groups containing steps with their nested data"}},"required":["step_groups"],"description":"Workflow configuration containing step groups hierarchy"}},"required":["id","code","label","class_id","project_node_id","project_label","tags","supertype","types","started","configuration"],"description":"Complete workflow information with hierarchical structure"},"WorkflowStepGroup":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Step group ID"},"code":{"type":"string","example":"group_validation","description":"Portable step group code. Unique within the workflow (not across the platform)."},"label":{"type":"string","example":"Validation","description":"Step group label"},"order":{"type":"integer","example":1,"description":"Display order"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowStep"},"description":"Array of steps in this group"}},"required":["id","code","label","order","steps"]},"WorkflowStep":{"type":"object","properties":{"id":{"type":"integer","example":101,"description":"Step ID"},"code":{"type":"string","example":"step_draft","description":"Portable step code. Unique within the workflow (not across the platform). This is the value expected in the \"wf-{workflowCode}-{stepCode}\" format used to force a workflow step."},"label":{"type":"string","example":"Draft","description":"Step label"},"order":{"type":"integer","example":1,"description":"Display order"},"color":{"type":"string","nullable":true,"example":"#28a745","description":"Step color"},"start":{"type":"boolean","example":false,"description":"Whether this is a start step"},"notification":{"type":"object","nullable":true,"properties":{"mail_template_id":{"type":"integer","example":5,"description":"Mail template ID"},"mail_template_code":{"type":"string","example":"code_5","description":"Portable code of the mail template, stable across environments (the auto-incremented id is not)"},"mail_template_label":{"type":"string","example":"Validation notification","description":"Mail template label"}},"description":"Notification configuration (null if not configured)"},"delay_days":{"type":"integer","nullable":true,"example":7,"description":"Delay in days for the step"},"workflow_action_on_arrival":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":536,"description":"Process ID triggered when an asset reaches this step"},"code":{"type":"string","example":"code_536","description":"Portable process code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Create vendor component","description":"Process label"}},"required":["id","code","label"],"description":"Process triggered on arrival at this step (null if none)"},"contributors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":5,"description":"Contributor group ID"},"code":{"type":"string","example":"group_validators","description":"Portable contributor group code. Unique within the project (not across the platform)."},"label":{"type":"string","example":"Validation Group","description":"Contributor group label"}},"required":["id","code","label"]},"description":"Array of contributors for this step"},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":201,"description":"Action ID"},"code":{"type":"string","example":"action_validate","description":"Portable action (button) code. Unique within the workflow (not across the platform)."},"label":{"type":"string","example":"Validate","description":"Action label"},"goto_step":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":102,"description":"Destination step ID"},"code":{"type":"string","example":"step_validated","description":"Portable step code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Validated","description":"Destination step label"}},"required":["id","code","label"],"description":"Destination step (null if no destination)"},"mode":{"type":"string","enum":["send_the_brief","submit","reject","validate"],"example":"validate","description":"Action mode (send_the_brief, submit, reject or validate)"},"display_if_completeness":{"type":"boolean","example":false,"description":"Display button only if all completeness attributes are filled"}},"required":["id","code","label","mode","display_if_completeness"]},"description":"Array of actions for this step"},"completeness":{"type":"object","nullable":true,"properties":{"attributes":{"type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"integer","example":1547,"description":"Attribute ID"},"code":{"type":"string","example":"component_commercial_name","description":"Portable attribute code (ROLE_XML), stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Component commercial name","description":"Attribute label"}},"required":["id","code","label"]},"description":"Attributes taken into account for completeness"},"automate_goto_step":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":102,"description":"Automatic transition step ID when complete"},"code":{"type":"string","example":"step_validate","description":"Portable step code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Validate","description":"Automatic transition step label when complete"}},"required":["id","code","label"],"description":"Automatic step transition when completeness is reached"}},"description":"Completeness configuration (null if not configured)"},"hotfolder":{"type":"object","nullable":true,"properties":{"action_on_update":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":201,"description":"Action ID to execute on update"},"code":{"type":"string","example":"action_validate","description":"Portable action code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","example":"Validate","description":"Action label"}},"required":["id","code","label"],"description":"Action to execute when hotfolder is updated (null for no automatic step change)"},"create_version":{"type":"boolean","example":true,"description":"Whether to create a version on update"}},"description":"Hotfolder configuration (null if not configured or not active)"},"status_piloting_view":{"type":"object","properties":{"status":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":1234,"description":"Status id"},"code":{"type":"string","example":"status_active","description":"Portable status code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","nullable":true,"example":"Admin Status","description":"Status label"}},"required":["id","code"],"description":"Status configuration (null if not configured)"},"default_view":{"type":"string","nullable":true,"enum":["default","completeness","list"],"example":"completeness","description":"Default view mode (default, completeness, or list)"},"children_piloting":{"$ref":"#/components/schemas/WorkflowChildrenPiloting"}},"description":"Status, piloting and view configuration"},"reminder":{"type":"object","nullable":true,"properties":{"days_before":{"type":"integer","example":7,"description":"Days before deadline to send notification"},"recurrence_days":{"type":"integer","nullable":true,"example":1,"description":"Recurrence interval in days for notifications"}},"description":"Reminder configuration (null if not configured)"}},"required":["id","code","label","order","start","contributors","actions","status_piloting_view"]},"WorkflowChildrenPiloting":{"type":"object","nullable":true,"oneOf":[{"type":"object","title":"Workflow Type","properties":{"type":{"type":"string","enum":["workflow"],"example":"workflow","description":"Children piloting type"},"items":{"type":"array","items":{"type":"object","properties":{"workflow":{"type":"object","properties":{"id":{"type":"integer","example":15,"description":"Target workflow ID"},"code":{"type":"string","example":"code_15","description":"Portable workflow code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","nullable":true,"example":"Child Workflow","description":"Target workflow label"}},"required":["id","code"]},"step":{"type":"object","properties":{"id":{"type":"integer","example":101,"description":"Target step ID"},"code":{"type":"string","example":"step_draft","description":"Portable step code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","nullable":true,"example":"Draft","description":"Target step label"}},"required":["id","code"]}},"required":["workflow","step"]},"description":"Array of workflow step configurations"}},"required":["type","items"]},{"type":"object","title":"Status Type","properties":{"type":{"type":"string","enum":["status"],"example":"status","description":"Children piloting type"},"items":{"type":"array","items":{"type":"object","properties":{"status":{"type":"object","properties":{"id":{"type":"integer","example":123,"description":"Status ID"},"code":{"type":"string","example":"status_active","description":"Portable status code, stable across environments (the auto-incremented id is not)"},"label":{"type":"string","nullable":true,"example":"Active","description":"Status label"}},"required":["id","code"]},"supertypes":{"type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"integer","example":3,"description":"Supertype ID"},"label":{"type":"string","nullable":true,"example":"Products","description":"Supertype label"}},"required":["id"]},"description":"Array of supertypes (null if not configured)"},"types":{"type":"array","nullable":true,"items":{"type":"object","properties":{"code":{"type":"string","example":"type_product","description":"Portable type code, stable across environments (the auto-incremented id is not)"},"id":{"type":"integer","example":42,"description":"Type ID"},"label":{"type":"string","nullable":true,"example":"Product","description":"Type label"}},"required":["id","code"]},"description":"Array of types (null if not configured)"}},"required":["status"]},"description":"Array of status configurations"}},"required":["type","items"]}],"description":"Children piloting configuration (null if not configured)"},"WorkflowList":{"type":"object","properties":{"results_total":{"type":"integer","example":2,"description":"Total number of workflows returned"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"},"description":"Array of workflow objects with complete information"}},"required":["results_total","items"]}}}}