Services: Reference

Purpose: User-friendly reference for all ChoreOps service actions used in automations and scripts.

---

Service Overview

ChoreOps currently provides 27 service actions in the choreops domain.

Note

Role field names are part of the API contract:

• Use user_name for the profile doing/receiving the action.
• Use approver_name for the profile approving/administering the action.
• Use scope: "user" when targeting one specific user in reset services.

Targeting a specific ChoreOps instance

All service actions support optional target fields:

• config_entry_id (canonical, recommended for automations)
• config_entry_title (convenience when titles are unique)

Routing behavior:

• If config_entry_id is provided, the service routes to that exact loaded instance.
• If omitted and exactly one ChoreOps instance is loaded, it auto-routes.
• If omitted and multiple instances are loaded, the call fails with an actionable ambiguity error.

Example with explicit instance targeting:

action: choreops.claim_chore
data:
  config_entry_id: "0123456789abcdef0123456789abcdef"
  user_name: "Sarah"
  chore_name: "Make Bed"

---

1) Workflow and economy

choreops.claim_chore

• Required: user_name, chore_name
• Purpose: Mark a chore as claimed.

action: choreops.claim_chore
data:
  user_name: "Sarah"
  chore_name: "Make Bed"

choreops.approve_chore

• Required: approver_name, user_name, chore_name
• Optional: points_awarded
• Purpose: Approve chore completion and award points.

choreops.disapprove_chore

• Required: approver_name, user_name, chore_name
• Purpose: Reject completion and return to pending.

choreops.redeem_reward

• Required: approver_name, user_name, reward_name
• Purpose: Submit reward redemption for review.

choreops.approve_reward

• Required: approver_name, user_name, reward_name
• Optional: cost_override
• Purpose: Approve reward and deduct points.

choreops.disapprove_reward

• Required: approver_name, user_name, reward_name
• Purpose: Reject reward redemption.

choreops.apply_penalty

• Required: approver_name, user_name, penalty_name
• Purpose: Apply a configured penalty.

choreops.apply_bonus

• Required: approver_name, user_name, bonus_name
• Purpose: Apply a configured bonus.

choreops.manual_adjust_points

• Required: amount, reason, and one of user_id or user_name
• Optional: approver_name
• Purpose: Apply a signed manual points adjustment and record the reason in ledger history.

Rules:

• amount must be a signed number with at most 2 decimal places and cannot be 0
• positive amount adds points
• negative amount deducts points
• reason is stored as ledger item_name

action: choreops.manual_adjust_points
data:
  config_entry_id: "0123456789abcdef0123456789abcdef"
  user_name: "Sarah"
  amount: -10.5
  reason: "Missed check-in"

choreops.generate_activity_report

• Optional: user_name, report_language, report_title, notify_service, output_format
• Purpose: Return a 7-day markdown/HTML activity report (response-first service).

action: choreops.generate_activity_report
data:
  user_name: "Alex"
  output_format: "both"
response_variable: report_response

---

2) Scheduling and resets

choreops.set_chore_due_date

• Required: chore_name
• Optional: due_date, user_name, user_id
• Purpose: Set/clear due date, optionally scoped to one assignee when supported.

choreops.skip_chore_due_date

• Required: one of chore_id or chore_name
• Optional: user_name, user_id, mark_as_missed
• Purpose: Advance a recurring chore to the next due slot.

choreops.reschedule_chores_after

• Required: after
• Optional: chore_ids, chore_names, user_ids, user_names, reschedule_shared, skip_non_recurring
• Purpose: Move one or more chores so their next due date lands after a boundary date and time.

Rules:

• chore_ids takes precedence over chore_names
• user_ids takes precedence over user_names
• recurring chores advance to the next scheduled occurrence after the boundary
• non-recurring chores move to the boundary unless skip_non_recurring: true
• shared and rotation chores are skipped unless reschedule_shared: true
• chores already after the boundary, or chores in claimed/approved in-flight states, are skipped and reported in the response payload
• this is a response-capable service and returns updated and skipped details

action: choreops.reschedule_chores_after
data:
  after: "2026-07-14T18:00:00Z"
  chore_names:
    - "Take Out Trash"
    - "Feed Cat"
  user_names:
    - "Alex"
  skip_non_recurring: true
response_variable: reschedule_result

choreops.reset_overdue_chores

• Optional: chore_id, chore_name, user_name
• Purpose: Reset overdue chores back to pending and reschedule.

choreops.reset_chores_to_pending_state

• Fields: none
• Purpose: Soft-reset all chores to pending.

choreops.reset_transactional_data

• Required: confirm_destructive: true
• Optional: scope, user_name, item_type, item_name
• Purpose: Reset transactional/runtime data with optional targeting.

Valid scope values:

• "global" (all profiles)
• "user" (single profile)

Valid item_type values:

• points, chores, rewards, badges, achievements, challenges, penalties, bonuses

action: choreops.reset_transactional_data
data:
  confirm_destructive: true
  scope: "user"
  user_name: "Sarah"
  item_type: "chores"

choreops.remove_awarded_badges

• Optional: user_name, badge_name
• Purpose: Remove badge awards globally or for one assignee.

choreops.manage_ui_control

• Required: ui_control_action, and one of user_id or user_name
• Optional: key, value
• Purpose: Create, update, or remove a persisted per-user dashboard UI control value.

Rules:

• Valid actions are create, update, and remove
• key uses slash-delimited paths such as gamification/rewards/header_collapse
• value is used for create and update
• A blank key is allowed only with remove, which clears all stored UI preferences for the targeted user

action: choreops.manage_ui_control
data:
  user_name: "Sarah"
  ui_control_action: "create"
  key: "gamification/rewards/header_collapse"
  value: true

---

3) Reward CRUD

choreops.create_reward

• Required: name, cost
• Optional: description, icon, labels
• Returns: reward_id

choreops.update_reward

• Required: one of id or name to identify target
• Optional: cost, description, icon, labels
• Returns: reward_id

choreops.delete_reward

• Required: one of id or name
• Returns: deleted reward confirmation

---

4) Chore CRUD

choreops.create_chore

• Required: name, assigned_user_names
• Optional: points, description, icon, labels, frequency, applicable_days, completion_criteria, approval_reset_type, pending_claims, overdue_handling, chore_claim_lock_until_window, auto_approve, due_date, due_window_offset, due_reminder_offset
• Returns: chore_id

choreops.update_chore

• Required: one of id or name to identify target
• Optional: same mutable fields as create (except immutable model constraints)
• Returns: chore_id

Note

For rotation chores, the order of names you provide in assigned_user_names is preserved and becomes the rotation order. If you also want the new first person to become the active turn immediately, follow update_chore with choreops.set_rotation_turn or choreops.reset_rotation.

Warning

completion_criteria is immutable after creation. To change it, create a new chore item.

choreops.delete_chore

• Required: one of id or name
• Purpose: Delete chore and associated references.

---

5) Rotation controls

choreops.set_rotation_turn

• Required: one of chore_id or chore_name, and one of user_id or user_name
• Purpose: Set who has the current turn in a rotation chore.

choreops.reset_rotation

• Required: one of chore_id or chore_name
• Purpose: Reset rotation to the first assigned profile.

choreops.open_rotation_cycle

• Required: one of chore_id or chore_name
• Purpose: Temporarily allow any assigned profile to claim regardless of turn.

---

Quick examples

Approve chore with optional points override

action: choreops.approve_chore
data:
  approver_name: "Mom"
  user_name: "Alex"
  chore_name: "Wash Dishes"
  points_awarded: 6

Approve reward with free grant

action: choreops.approve_reward
data:
  approver_name: "Dad"
  user_name: "Sarah"
  reward_name: "Movie Night"
  cost_override: 0

Manual points adjustment

action: choreops.manual_adjust_points
data:
  user_id: "018f1c2a-1234-4f8a-9b6d-123456789abc"
  amount: 15
  reason: "Proactive help"

Skip recurring chore due date

action: choreops.skip_chore_due_date
data:
  chore_name: "Daily Reading"
  user_name: "Sarah"
  mark_as_missed: true

Reschedule chores after a return date

action: choreops.reschedule_chores_after
data:
  after: "2026-07-21T18:00:00Z"
  chore_ids:
    - "018f1c2a-1234-4f8a-9b6d-123456789abc"
  reschedule_shared: true
  skip_non_recurring: true
response_variable: reschedule_result

---

Troubleshooting

not_authorized_action

• Cause: Caller context is not authorized for the requested operation.
• Fix: Use an admin/authorized HA user and verify profile-role mapping in ChoreOps configuration.

chore_not_found / reward_not_found / assignee_not_found

• Cause: Name or ID does not match current records.
• Fix: Verify spelling and confirm the item exists in configuration.

insufficient_points

• Cause: Assignee balance is below reward cost.
• Fix: Check the profile’s points sensor before calling redeem_reward.

date_in_past

• Cause: Due date is earlier than now.
• Fix: Send a future timestamp.

---

Related docs

• Configuration:-Users
• Configuration:-Points
• Technical:-Users
• Technical:-Chores
• Technical:-Points
• Technical:-Troubleshooting