Decide a Hover Suggested Action

POST https://app.hover.team/api/v1/hover/spaces/{space_id}/generated-items/{generated_item_id}/suggested-action/decisions

Atomically approve a pending Suggested Action into one active Todo, mark it as Not an action, or restore a dismissed proposal. The caller must be an active confirmed Contributor or Subscriber in the exact launched Space. Request IDs make retries idempotent and expected versions prevent reordered clients from overwriting newer decisions.

Changes: New in Zulip 12.0 (feature level ZF-82baeb).

Usage examples

curl

The -u line implements HTTP Basic authentication. See the Authorization header documentation for how to get those credentials for Zulip users and bots.

curl -sSX POST https://app.hover.team/api/v1/hover/spaces/2/generated-items/3/suggested-action/decisions \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode decision=approve \
    --data-urlencode request_id=e3437e2d-a109-4676-a3f6-6d45ea16e131 \
    --data-urlencode expected_version=1 \
    --data-urlencode 'reason=Already handled by the venue team.' \
    --data-urlencode 'wording=Confirm the venue booking.' \
    --data-urlencode assignee_user_id=9 \
    --data-urlencode due_date=2026-08-31

Parameters

space_id integer required in path

Example: 2

The ID of the Hover Space containing the generated item.

generated_item_id integer required in path

Example: 3

The ID of the generated item whose suggested action should be decided.

decision string required

Example: "approve"

The decision to apply to the Suggested Action. Must be one of: "approve", "not_action", "restore".

request_id string required

Example: "e3437e2d-a109-4676-a3f6-6d45ea16e131"

A unique idempotency key for this decision.

expected_version string required

Example: "1"

The current Suggested Action version expected by the caller.

reason string | null optional

Example: "Already handled by the venue team."

Optional only for not_action.

wording string | null optional

Example: "Confirm the venue booking."

Reviewed wording to confirm with approve.

assignee_user_id string | null optional

Example: "9"

Confirmed Space member to assign, or null to leave unassigned.

due_date string | null optional

Example: "2026-08-31"

Due date to confirm with approve, or null to clear it.

Response

Return values

changed: boolean

The changed value. * suggested_action: object

The suggested_action value. * id: integer
```
The `id` value.
```
- state: string
  
  The state value. * version: integer
  
  The version value. * wording: string
  
  The wording value. * source_proposal: object
  
  The source_proposal value. * assignee_ref: string | null
```
The `assignee_ref` value.
```
  - assignee_display_name: string | null
    
    The assignee_display_name value. * assignee: object | null
  The assignee value. * user_id: integer
```
The `user_id` value.
```
  - full_name: string
    
    The full_name value. * assignable_users: (object)[]
  The assignable_users value. * user_id: integer
```
The `user_id` value.
```
  - full_name: string
    
    The full_name value. * due_date: string | null
  The due_date value. * history_count: integer
  
  The history_count value. * recent_transitions: (object)[]
  
  The recent_transitions value. * id: integer
```
The `id` value.
```
  - kind: string
    
    The kind value. * from_state: string
    
    The from_state value. * to_state: string
    
    The to_state value. * actor_id: integer
    
    The actor_id value. * actor_name: string
    
    The actor_name value. * occurred_at: string
    
    The occurred_at value. * reason: string
    
    The reason value. * todo: unknown
  The todo value.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "changed": true,
    "msg": "",
    "result": "success",
    "suggested_action": {
        "assignable_users": [],
        "assignee": null,
        "due_date": null,
        "history_count": 0,
        "id": 1,
        "recent_transitions": [],
        "source_proposal": {
            "assignee_display_name": null,
            "assignee_ref": null
        },
        "state": "pending",
        "todo": null,
        "version": 1,
        "wording": "Confirm venue"
    }
}

The current Suggested Action returned after a stale decision request.

{
    "msg": "The Suggested Action has changed.",
    "result": "error",
    "suggested_action": {
        "assignable_users": [],
        "assignee": null,
        "due_date": null,
        "history_count": 0,
        "id": 1,
        "recent_transitions": [],
        "source_proposal": {
            "assignee_display_name": null,
            "assignee_ref": null
        },
        "state": "pending",
        "todo": null,
        "version": 2,
        "wording": "Confirm venue"
    }
}

API documentation home

Messages

Hover

Scheduled messages

Message reminders

Drafts

Navigation views

Channels

Users

Invitations

Server & organizations

Real-time events

Interactive bots