> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/actions.md).

# Actions

Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora).

## List actions

> Returns all actions for the authenticated company, sorted from newest to oldest. Overdue in-progress actions are expired on-the-fly before the result is returned. All filter parameters are optional and combinable. Use \`planId\` to scope results to a specific plan, \`standaloneOnly=true\` to return only actions without a plan, or omit both to return all actions regardless of plan. \`standaloneOnly=true\` takes precedence over \`planId\` if both are provided.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions":{"get":{"tags":["Actions"],"summary":"List actions","description":"Returns all actions for the authenticated company, sorted from newest to oldest. Overdue in-progress actions are expired on-the-fly before the result is returned. All filter parameters are optional and combinable. Use `planId` to scope results to a specific plan, `standaloneOnly=true` to return only actions without a plan, or omit both to return all actions regardless of plan. `standaloneOnly=true` takes precedence over `planId` if both are provided.","operationId":"listActions","parameters":[{"name":"planId","in":"query","description":"Filter by parent action plan (omit to return all actions regardless of plan)","required":false,"schema":{"type":"string"}},{"name":"standaloneOnly","in":"query","description":"When true, returns only standalone actions (no parent plan). Takes precedence over planId.","required":false,"schema":{"type":"boolean","default":false}},{"name":"hierarchyId","in":"query","description":"Filter by area/hierarchy (matches any entry in the action's hierarchyIds)","required":false,"schema":{"type":"string"}},{"name":"assigneeId","in":"query","description":"Filter by assignee (matches any entry in the assignees list)","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Status filter","required":false,"schema":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]}},{"name":"focusType","in":"query","description":"Focus type filter (matches any focusItems entry)","required":false,"schema":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]}},{"name":"actionType","in":"query","description":"Action type filter","required":false,"schema":{"type":"string","enum":["MANAGER","COMPANY"]}},{"name":"q","in":"query","description":"Free-text search on action title and description (case-insensitive contains)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Actions returned (empty list when none match the filters)","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActionDTO"}}}}}}}}}}
```

## Create a new action

> Creates an action in DRAFT status anchored to one or more focus indicators. For MANAGER actions, assignees defaults to the authenticated user when omitted. For COMPANY actions, an explicit list of co-responsible manager IDs must be supplied.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionCreateRequestDTO":{"type":"object","description":"Request payload for creating a new action","properties":{"planId":{"type":"string","description":"Parent action plan this action belongs to. Omit to create a standalone action not attached to any plan."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: set defaultValue for the main language, add langValues for translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators the action is anchored to. Each item requires focusType and focusId.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]},"minItems":1},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty or omitted means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets. Optional.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets. Optional.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"assignees":{"type":"array","description":"Responsible manager IDs. For MANAGER actions, defaults to the authenticated user when omitted. For COMPANY actions, provide the list of co-responsible managers.","items":{"type":"string"}},"dueDate":{"type":"string","format":"date-time","description":"Expected completion date. Must be in the future."},"actionType":{"type":"string","description":"Scope of the action. Use MANAGER for individual manager actions, COMPANY for cross-team initiatives.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. Defaults to MANUAL when omitted.","enum":["MANUAL","SUGGESTION","AI","TEMPLATE"]},"sourceTemplateId":{"type":"string","description":"Template this action was created from. Provide when source=TEMPLATE."},"visibility":{"type":"string","description":"Visibility for the action. Defaults to PRIVATE when omitted.","enum":["PUBLIC","PRIVATE"]}},"required":["actionType","description","dueDate","focusItems","title"]},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions":{"post":{"tags":["Actions"],"summary":"Create a new action","description":"Creates an action in DRAFT status anchored to one or more focus indicators. For MANAGER actions, assignees defaults to the authenticated user when omitted. For COMPANY actions, an explicit list of co-responsible manager IDs must be supplied.","operationId":"createAction","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionCreateRequestDTO"}}},"required":true},"responses":{"200":{"description":"Action created successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"400":{"description":"Validation failed: missing required fields, empty focusItems, empty assignees, or invalid actionType","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}}}}}}}
```

## Change action lifecycle status

> Applies a lifecycle transition. Allowed transitions: DRAFT→IN\_PROGRESS, IN\_PROGRESS→COMPLETED|PARTIALLY\_COMPLETED|FAILED. The EXPIRED status is set automatically by the system and cannot be requested. Transitioning to IN\_PROGRESS records startedAt; transitioning to a terminal status records completedAt.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionChangeStatusRequestDTO":{"type":"object","description":"Request payload to apply a lifecycle transition to an action","properties":{"status":{"type":"string","description":"Target lifecycle status. Only the transitions described above are allowed.","enum":["IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED"]}},"required":["status"]},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions/{actionId}/status":{"post":{"tags":["Actions"],"summary":"Change action lifecycle status","description":"Applies a lifecycle transition. Allowed transitions: DRAFT→IN_PROGRESS, IN_PROGRESS→COMPLETED|PARTIALLY_COMPLETED|FAILED. The EXPIRED status is set automatically by the system and cannot be requested. Transitioning to IN_PROGRESS records startedAt; transitioning to a terminal status records completedAt.","operationId":"changeActionStatus","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionChangeStatusRequestDTO"}}},"required":true},"responses":{"200":{"description":"Status changed successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"400":{"description":"Transition not allowed from the current status, or status value is invalid","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"404":{"description":"Action not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}}}}}}}
```

## List action notes (paginated)

> Returns a paginated slice of the execution log for an action, ordered by creation date ascending (oldest first). Only notes visible to the caller are counted and returned: admins see all notes; managers see shared notes plus their own private ones. \`from\` / \`to\` are zero-based offset / exclusive end index applied after the visibility filter.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"PaginableGenericResultListActionNoteDTO":{"type":"object","properties":{"from":{"type":"integer","format":"int32"},"to":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"result":{"type":"array","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions/{actionId}/notes":{"get":{"tags":["Actions"],"summary":"List action notes (paginated)","description":"Returns a paginated slice of the execution log for an action, ordered by creation date ascending (oldest first). Only notes visible to the caller are counted and returned: admins see all notes; managers see shared notes plus their own private ones. `from` / `to` are zero-based offset / exclusive end index applied after the visibility filter.","operationId":"listActionNotes","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","description":"Zero-based start index (default 0)","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"to","in":"query","description":"Exclusive end index (default 20)","required":false,"schema":{"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"Notes page returned (empty result when none match)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaginableGenericResultListActionNoteDTO"}}}},"404":{"description":"Action not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaginableGenericResultListActionNoteDTO"}}}}}}}}}
```

## Add a note to the action log

> Appends a note to the action execution log (bitácora). The author is always the authenticated user. Notes with PRIVATE visibility are only visible to their author; SHARED notes are visible to all action participants.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionAddNoteRequestDTO":{"type":"object","description":"Request payload to append a note to the action execution log","properties":{"content":{"type":"string","description":"Note body text describing progress, blockers or context updates","minLength":1},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants. Defaults to PRIVATE.","enum":["PRIVATE","SHARED"]}},"required":["content"]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions/{actionId}/notes":{"post":{"tags":["Actions"],"summary":"Add a note to the action log","description":"Appends a note to the action execution log (bitácora). The author is always the authenticated user. Notes with PRIVATE visibility are only visible to their author; SHARED notes are visible to all action participants.","operationId":"addActionNote","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionAddNoteRequestDTO"}}},"required":true},"responses":{"200":{"description":"Note created and returned","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"400":{"description":"Content is blank or action not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"404":{"description":"Action not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionNoteDTO"}}}}}}}}}
```

## Trigger impact capture for a closed action

> Manually triggers the closure snapshot capture for an action that was closed before the impact measurement feature was deployed (backfill). This is idempotent: calling it on an action that already has an impact document is a no-op. Requires the action to be in a terminal status (COMPLETED, PARTIALLY\_COMPLETED or FAILED).

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/actions/{actionId}/impact/capture":{"post":{"tags":["Actions"],"summary":"Trigger impact capture for a closed action","description":"Manually triggers the closure snapshot capture for an action that was closed before the impact measurement feature was deployed (backfill). This is idempotent: calling it on an action that already has an impact document is a no-op. Requires the action to be in a terminal status (COMPLETED, PARTIALLY_COMPLETED or FAILED).","operationId":"triggerImpactCapture","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capture triggered (or was already present — idempotent)"},"400":{"description":"Action not found or not in a terminal status"}}}}}}
```

## Export action to Excel

> Triggers an asynchronous Excel export of this action. The workbook will be delivered to your e-mail address as a download link. The response is empty — the file arrives via e-mail within seconds.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/actions/{actionId}/excel":{"post":{"tags":["Actions"],"summary":"Export action to Excel","description":"Triggers an asynchronous Excel export of this action. The workbook will be delivered to your e-mail address as a download link. The response is empty — the file arrives via e-mail within seconds.","operationId":"exportActionToExcel","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Export triggered — file will be sent by e-mail"}}}}}}
```

## Generate AI action suggestions

> Analyses engagement score data for the requested period and returns up to 3 ready-to-use action suggestions generated by the AI. Each suggestion includes a fully populated title, description, focus indicators, scope (actionType), suggested due date and a rationale explaining the recommendation.\
> \
> \*\*Date window:\*\* controlled by \`from\`/\`to\` in the request body — defaults to the last 30 days when omitted.\
> \
> \*\*Team scope:\*\* when \`teamId\` is provided, metric queries are filtered to that team's hierarchy so the AI reasons about team-specific data rather than company-wide averages.\
> \
> \*\*Context hint:\*\* free-text field for situation context (e.g. "Two people left last month").\
> \
> The client can send the suggestion directly to the create-action endpoint (POST /v1/company/actions) with source=AI after the user confirms or adjusts the fields. Note: this call invokes an external LLM and may take a few seconds.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionSuggestRequestDTO":{"type":"object","description":"Optional parameters that narrow the AI action suggestion context","properties":{"teamId":{"type":"string","description":"Restrict score analysis to a specific team/hierarchy. When omitted, company-wide data is used."},"from":{"type":"string","format":"date-time","description":"Start of the measurement window (inclusive). When omitted, defaults to 30 days before 'to' (or before now if 'to' is also omitted)."},"to":{"type":"string","format":"date-time","description":"End of the measurement window (inclusive). Defaults to the current date/time when omitted."},"hint":{"type":"string","description":"Free-text hint that gives the AI additional context about the current situation. Max 500 characters."},"language":{"type":"string","default":"es","description":"BCP-47 language code for the suggestion text. Defaults to 'es' when omitted."}}},"ActionSuggestionDTO":{"type":"object","description":"AI-generated action suggestion — all fields pre-filled and ready for user review. Can be forwarded directly to POST /v1/company/actions after confirmation.","properties":{"title":{"type":"string","description":"Short title describing the suggested action"},"description":{"type":"string","description":"Detailed execution plan: how, when, and why this action addresses the focus indicator"},"focusItems":{"type":"array","description":"Focus indicators that motivated this suggestion, including the AI-suggested target value. Use them as-is in the create-action call.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"actionType":{"type":"string","description":"Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.","enum":["MANAGER","COMPANY"]},"dueDate":{"type":"string","format":"date-time","description":"Suggested target completion date. Map this directly to the dueDate field when creating the action."},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action is pre-scoped to. Pre-populated from the teamId in the suggestion request; empty for company-wide suggestions.","items":{"type":"string"},"uniqueItems":true},"assignees":{"type":"array","description":"Responsible managers. Empty — must be filled by the user before confirming.","items":{"type":"string"}},"currentValue":{"type":"number","format":"double","description":"Current measured value of the focus indicator at the time the suggestion was generated. Provides context to show the user the baseline the action targets (e.g. 4.3 for a score on a 0–10 scale, or 62 for HI on a 0–100 scale). Null when the measurement was unavailable for the requested period."},"rationale":{"type":"string","description":"Brief explanation of why the model recommends this action, based on the data analysed."},"source":{"type":"string","description":"Always AI for suggestions generated by this endpoint.","enum":["AI"]}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]}}},"paths":{"/api/v1/company/actions/suggest":{"post":{"tags":["Actions"],"summary":"Generate AI action suggestions","description":"Analyses engagement score data for the requested period and returns up to 3 ready-to-use action suggestions generated by the AI. Each suggestion includes a fully populated title, description, focus indicators, scope (actionType), suggested due date and a rationale explaining the recommendation.\n\n**Date window:** controlled by `from`/`to` in the request body — defaults to the last 30 days when omitted.\n\n**Team scope:** when `teamId` is provided, metric queries are filtered to that team's hierarchy so the AI reasons about team-specific data rather than company-wide averages.\n\n**Context hint:** free-text field for situation context (e.g. \"Two people left last month\").\n\nThe client can send the suggestion directly to the create-action endpoint (POST /v1/company/actions) with source=AI after the user confirms or adjusts the fields. Note: this call invokes an external LLM and may take a few seconds.","operationId":"suggestActions","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionSuggestRequestDTO"}}}},"responses":{"200":{"description":"Suggestions generated (may be an empty list if no engagement data is available)","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}}},"400":{"description":"Request validation failed","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}}},"500":{"description":"AI service unavailable or returned an unparseable response","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}}}}}}}}
```

## Generate an action from an employee idea

> Converts an employee comment (idea or suggestion) into a single ready-to-use action. The original comment text is preserved as the seed for the action description — the AI polishes it into professional language while keeping the employee's intent intact. The AI also generates the title, picks the most relevant focus indicator from the engagement catalog, and suggests scope (actionType) and due date. The result can be sent directly to POST /v1/company/actions with source=AI once the user confirms. Note: this call invokes an external LLM and may take a few seconds.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionSuggestionDTO":{"type":"object","description":"AI-generated action suggestion — all fields pre-filled and ready for user review. Can be forwarded directly to POST /v1/company/actions after confirmation.","properties":{"title":{"type":"string","description":"Short title describing the suggested action"},"description":{"type":"string","description":"Detailed execution plan: how, when, and why this action addresses the focus indicator"},"focusItems":{"type":"array","description":"Focus indicators that motivated this suggestion, including the AI-suggested target value. Use them as-is in the create-action call.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"actionType":{"type":"string","description":"Recommended action scope. MANAGER for individual-team actions; COMPANY for cross-team initiatives.","enum":["MANAGER","COMPANY"]},"dueDate":{"type":"string","format":"date-time","description":"Suggested target completion date. Map this directly to the dueDate field when creating the action."},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action is pre-scoped to. Pre-populated from the teamId in the suggestion request; empty for company-wide suggestions.","items":{"type":"string"},"uniqueItems":true},"assignees":{"type":"array","description":"Responsible managers. Empty — must be filled by the user before confirming.","items":{"type":"string"}},"currentValue":{"type":"number","format":"double","description":"Current measured value of the focus indicator at the time the suggestion was generated. Provides context to show the user the baseline the action targets (e.g. 4.3 for a score on a 0–10 scale, or 62 for HI on a 0–100 scale). Null when the measurement was unavailable for the requested period."},"rationale":{"type":"string","description":"Brief explanation of why the model recommends this action, based on the data analysed."},"source":{"type":"string","description":"Always AI for suggestions generated by this endpoint.","enum":["AI"]}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]}}},"paths":{"/api/v1/company/actions/suggest/from-comment/{commentId}":{"post":{"tags":["Actions"],"summary":"Generate an action from an employee idea","description":"Converts an employee comment (idea or suggestion) into a single ready-to-use action. The original comment text is preserved as the seed for the action description — the AI polishes it into professional language while keeping the employee's intent intact. The AI also generates the title, picks the most relevant focus indicator from the engagement catalog, and suggests scope (actionType) and due date. The result can be sent directly to POST /v1/company/actions with source=AI once the user confirms. Note: this call invokes an external LLM and may take a few seconds.","operationId":"suggestFromComment","parameters":[{"name":"commentId","in":"path","description":"Comment (idea) identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Action suggestion generated from the comment","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}},"404":{"description":"Comment not found in this company, or comment has no text","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}},"500":{"description":"AI service unavailable or returned an unparseable response","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionSuggestionDTO"}}}}}}}}}
```

## Get action details

> Returns the full action aggregate. Overdue in-progress actions are expired on-the-fly before the response.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions/{actionId}":{"get":{"tags":["Actions"],"summary":"Get action details","description":"Returns the full action aggregate. Overdue in-progress actions are expired on-the-fly before the response.","operationId":"getAction","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Action found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"404":{"description":"Action not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}}}}}}}
```

## Delete an action

> Permanently removes an action. Only the action creator or an admin can delete; legacy actions without a recorded creator are deletable by any authorised caller. Returns 204 on success, 403 when the caller is not allowed, 404 when not found.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}}},"paths":{"/api/v1/company/actions/{actionId}":{"delete":{"tags":["Actions"],"summary":"Delete an action","description":"Permanently removes an action. Only the action creator or an admin can delete; legacy actions without a recorded creator are deletable by any authorised caller. Returns 204 on success, 403 when the caller is not allowed, 404 when not found.","operationId":"deleteAction","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Action deleted"},"403":{"description":"Caller is not the creator or an admin"},"404":{"description":"Action not found in this company"}}}}}}
```

## Patch mutable action fields

> Applies a partial update to an action. Only non-null fields are updated. Cannot be applied to actions in a terminal status (COMPLETED, PARTIALLY\_COMPLETED, FAILED, EXPIRED). Immutable fields (focusItems, actionType) are ignored even if provided.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionUpdateRequestDTO":{"type":"object","description":"Partial update payload for an existing action. Only non-null fields are applied.","properties":{"title":{"$ref":"#/components/schemas/MultiLanguage","description":"New title (multilingual). Replaces the existing one when non-null."},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"New description (multilingual). Replaces the existing one when non-null."},"dueDate":{"type":"string","format":"date-time","description":"Extended due date. Must not be earlier than the action creation date."},"source":{"type":"string","description":"Updated action origin.","enum":["MANUAL","SUGGESTION","AI"]},"assignees":{"type":"array","description":"Replaces the full assignees list when non-null. Use this to add or remove co-responsible managers. Must be non-empty if provided.","items":{"type":"string"}},"planId":{"type":"string","description":"Moves the action to the specified plan when non-null. The plan must belong to the same company. Omit (or send null) to leave the current plan unchanged."},"visibility":{"type":"string","description":"New visibility. Null means no change.","enum":["PUBLIC","PRIVATE"]}}},"MultiLanguage":{"type":"object","properties":{"defaultValue":{"type":"string","minLength":1},"langValues":{"type":"object","additionalProperties":{"type":"string"}},"valid":{"type":"boolean"}},"required":["defaultValue"]},"ActionDTO":{"type":"object","description":"Complete action payload returned by the API","properties":{"id":{"type":"string","description":"Unique action identifier"},"companyId":{"type":"string","description":"Company that owns this action"},"planId":{"type":"string","description":"Parent action plan identifier. Null when the action is standalone."},"plan":{"$ref":"#/components/schemas/PlanSummary","description":"Lightweight plan summary (id, title, description). Null when the action is standalone."},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Short title describing the action (multilingual: defaultValue = main language, langValues = translations)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Detailed execution plan describing how and when (multilingual)"},"focusItems":{"type":"array","description":"One or more focus indicators this action is anchored to. At least one is always present.","items":{"oneOf":[{"$ref":"#/components/schemas/ActionFocusItem"},{"$ref":"#/components/schemas/ENPSFocusItem"},{"$ref":"#/components/schemas/FactorFocusItem"},{"$ref":"#/components/schemas/HIFocusItem"},{"$ref":"#/components/schemas/QuestionFocusItem"},{"$ref":"#/components/schemas/ScoreFocusItem"}]}},"assigneeStatuses":{"type":"array","description":"Per-assignee lifecycle states. Each entry tracks one manager's individual progress. The global status field is the aggregate of all entries.","items":{"$ref":"#/components/schemas/AssigneeStatusDTO"}},"hierarchyIds":{"type":"array","description":"Areas/hierarchies this action targets. Empty means company-wide scope.","items":{"type":"string"},"uniqueItems":true},"groupIds":{"type":"array","description":"Groups this action targets.","items":{"type":"string"},"uniqueItems":true},"characteristics":{"type":"array","description":"Employee characteristic segments this action targets.","items":{"oneOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBoolean"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueDate"},{"$ref":"#/components/schemas/EmployeeCharacteristicValueList"}]},"uniqueItems":true},"actionType":{"type":"string","description":"Scope of the action. MANAGER = individual manager action; COMPANY = cross-team action initiated by an admin.","enum":["MANAGER","COMPANY"]},"source":{"type":"string","description":"How the action was originated. MANUAL = created by the user; SUGGESTION = proposed by a company action; AI = generated by the AI assistant.","enum":["MANUAL","SUGGESTION","AI"]},"visibility":{"type":"string","description":"Visibility scope — PUBLIC means readable by any company manager; PRIVATE restricts to assignees/creator.","enum":["PUBLIC","PRIVATE"]},"status":{"type":"string","description":"Aggregate lifecycle status (computed from all assignee states).","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"completionPercent":{"type":"integer","format":"int32","description":"Percentage of assignees who have individually reached COMPLETED status (0–100). Computed on-the-fly from assigneeStatuses; never stored."},"dueDate":{"type":"string","format":"date-time","description":"Target completion date"},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when the first assignee moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when all assignees reached a terminal status"},"createdBy":{"type":"string","description":"User who created this action"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last modification timestamp"},"notes":{"type":"array","description":"Execution log notes (bitácora). Visibility-filtered: PRIVATE notes are only returned when the caller is the author. Not populated in list responses — only in single-action detail (GET /actions/{id}).","items":{"$ref":"#/components/schemas/ActionNoteDTO"}}}},"PlanSummary":{"type":"object","description":"Lightweight plan reference — id, title and description only","properties":{"id":{"type":"string","description":"Plan identifier"},"title":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan title (multilingual)"},"description":{"$ref":"#/components/schemas/MultiLanguage","description":"Plan goal description (multilingual)"}}},"ActionFocusItem":{"type":"object","discriminator":{"propertyName":"focusType"},"properties":{"focusType":{"type":"string","enum":["SCORE","FACTOR","QUESTION","ENPS","HI"]},"focusId":{"type":"string"},"targetValue":{"type":"number","format":"double"},"targetTimestamp":{"type":"string","format":"date-time"}}},"ENPSFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"FactorFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"HIFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"QuestionFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"ScoreFocusItem":{"allOf":[{"$ref":"#/components/schemas/ActionFocusItem"}]},"AssigneeStatusDTO":{"type":"object","description":"Per-assignee lifecycle state within an action","properties":{"assigneeId":{"type":"string","description":"Assignee (manager) identifier"},"status":{"type":"string","description":"This assignee's current lifecycle status","enum":["DRAFT","IN_PROGRESS","COMPLETED","PARTIALLY_COMPLETED","FAILED","EXPIRED"]},"startedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee first moved to IN_PROGRESS"},"completedAt":{"type":"string","format":"date-time","description":"Timestamp when this assignee reached a terminal status"}}},"EmployeeCharacteristicValueBoolean":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"boolean"}}}]},"EmployeeCharacteristicValueBase":{"type":"object","description":"Base class for employee characteristic values","discriminator":{"propertyName":"questionType","mapping":{"LIST":"#/components/schemas/EmployeeCharacteristicValueList","DATE":"#/components/schemas/EmployeeCharacteristicValueDate","BOOLEAN":"#/components/schemas/EmployeeCharacteristicValueBoolean"}},"properties":{"characteristicId":{"type":"string"},"id":{"type":"string"},"questionType":{"$ref":"#/components/schemas/CharacteristicType"}}},"CharacteristicType":{"type":"string","description":"Type of segmentation characteristic","enum":["DATE","LIST","BOOLEAN"]},"EmployeeCharacteristicValueDate":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"value":{"type":"string"}}}]},"EmployeeCharacteristicValueList":{"allOf":[{"$ref":"#/components/schemas/EmployeeCharacteristicValueBase"},{"type":"object","properties":{"value":{"type":"string"}}}]},"ActionNoteDTO":{"type":"object","description":"A single note appended to the action execution log","properties":{"id":{"type":"string","description":"Note identifier (unique within the parent action)"},"authorId":{"type":"string","description":"User who wrote the note"},"content":{"type":"string","description":"Note body text"},"visibility":{"type":"string","description":"Who can see this note. PRIVATE = only the author; SHARED = all action participants.","enum":["PRIVATE","SHARED"]},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/api/v1/company/actions/{actionId}":{"patch":{"tags":["Actions"],"summary":"Patch mutable action fields","description":"Applies a partial update to an action. Only non-null fields are updated. Cannot be applied to actions in a terminal status (COMPLETED, PARTIALLY_COMPLETED, FAILED, EXPIRED). Immutable fields (focusItems, actionType) are ignored even if provided.","operationId":"patchAction","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionUpdateRequestDTO"}}},"required":true},"responses":{"200":{"description":"Action updated successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"400":{"description":"Invalid field values, dueDate before creation date, or action is already closed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}},"404":{"description":"Action not found in this company","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionDTO"}}}}}}}}}
```

## Get impact measurement

> Returns the impact document for a closed action, containing metric readings at three points in time: baseline (creation), at-closure, and the most recent periodic re-evaluation.\
> \
> \*\*Scope:\*\* managers receive their own area-scoped snapshot; admins receive the global company-wide snapshot. Admins can also request a specific manager's scoped snapshot via the optional \`assigneeId\` parameter.\
> \
> Returns 404 when the action has never been closed or the impact capture has not completed yet (it runs asynchronously after closure).

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[{"name":"Actions","description":"Create and manage team improvement actions anchored to focus indicators. Supports lifecycle transitions, multi-assignee company actions, and execution notes (bitácora)."}],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"ActionImpactDTO":{"type":"object","description":"Impact measurement for a closed action, showing how the focus indicators evolved before, at and after the action was executed","properties":{"id":{"type":"string","description":"Impact document identifier"},"actionId":{"type":"string","description":"Related action identifier"},"assigneeId":{"type":"string","description":"Manager this snapshot is scoped to. Null for the global company-wide snapshot."},"closureStatus":{"type":"string","description":"Terminal state that triggered impact capture","enum":["COMPLETED","PARTIALLY_COMPLETED","FAILED"]},"closedAt":{"type":"string","format":"date-time","description":"When the action reached its terminal state"},"baseline":{"type":"array","description":"Baseline readings — metric values at action creation time (one entry per focus indicator)","items":{"$ref":"#/components/schemas/ActionImpactEntryDTO"}},"atClosure":{"type":"array","description":"Readings captured immediately at action closure (delta relative to baseline)","items":{"$ref":"#/components/schemas/ActionImpactEntryDTO"}},"latest":{"type":"array","description":"Most recent periodic re-evaluation readings (updated daily until windowEndsAt)","items":{"$ref":"#/components/schemas/ActionImpactEntryDTO"}},"windowEndsAt":{"type":"string","format":"date-time","description":"When the measurement window closes — no more re-evaluations after this date (closedAt + windowDays)"},"evaluationCount":{"type":"integer","format":"int32","description":"Number of periodic re-evaluations performed so far"},"lastEvaluatedAt":{"type":"string","format":"date-time","description":"Timestamp of the most recent periodic re-evaluation"}}},"ActionImpactEntryDTO":{"type":"object","description":"Metric reading for one focus indicator at a specific point in time","properties":{"focusType":{"type":"string","description":"Focus indicator type","enum":["SCORE","FACTOR","QUESTION"]},"focusId":{"type":"string","description":"Identifier of the score, factor or question"},"value":{"type":"number","format":"double","description":"Aggregated metric value at measurement time (0–10 for scores and factors)"},"delta":{"type":"number","format":"double","description":"Difference relative to the baseline value. Positive means improvement, negative means decline. Null for baseline entries themselves."},"participantCount":{"type":"integer","format":"int32","description":"Number of respondents included in this measurement"},"measuredAt":{"type":"string","format":"date-time","description":"When this reading was taken"}}}}},"paths":{"/api/v1/company/actions/{actionId}/impact":{"get":{"tags":["Actions"],"summary":"Get impact measurement","description":"Returns the impact document for a closed action, containing metric readings at three points in time: baseline (creation), at-closure, and the most recent periodic re-evaluation.\n\n**Scope:** managers receive their own area-scoped snapshot; admins receive the global company-wide snapshot. Admins can also request a specific manager's scoped snapshot via the optional `assigneeId` parameter.\n\nReturns 404 when the action has never been closed or the impact capture has not completed yet (it runs asynchronously after closure).","operationId":"getActionImpact","parameters":[{"name":"actionId","in":"path","description":"Action identifier","required":true,"schema":{"type":"string"}},{"name":"assigneeId","in":"query","description":"Admin only: request a specific manager's scoped impact snapshot instead of the global one","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Impact document found and returned","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionImpactDTO"}}}},"404":{"description":"No impact document for this action","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ActionImpactDTO"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.myhappyforce.com/docs/api-reference/actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.