Append a Hover Todo event

POST https://app.hover.team/api/v1/hover/spaces/{space_id}/todos/{todo_id}/events

Assign, reassign, complete, or reopen the canonical Todo. Every change appends actor/time history. Request IDs make retries idempotent and expected versions reject stale clients.

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/todos/1/events \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode operation=assign \
    --data-urlencode request_id=4f437c7e-03a9-4c3b-8246-c770bdf1efc7 \
    --data-urlencode expected_version=1 \
    --data-urlencode assignee_user_id=9 \
    --data-urlencode 'reason=Assigning the venue follow-up.'

Parameters

space_id integer required in path

Example: 2

The ID of the Hover Space containing the To-do.

todo_id integer required in path

Example: 1

The ID of the To-do whose event should be appended.

operation string required

Example: "assign"

The Todo state transition to append. Must be one of: "assign", "complete", "reopen".

request_id string required

Example: "4f437c7e-03a9-4c3b-8246-c770bdf1efc7"

A unique idempotency key for this Todo command.

expected_version string required

Example: "1"

The current Todo version expected by the caller.

assignee_user_id string | null optional

Example: "9"

Required only for assign.

reason string | null optional

Example: "Assigning the venue follow-up."

Optional audit reason for the transition.

Response

Return values

changed: boolean

The changed value. * todo: object

The todo value. * id: integer
```
The `id` value.
```
- state: string
  
  The state value. * version: integer
  
  The version value. * wording: string
  
  The wording value. * due_date: string | null
  
  The due_date value. * completed_at: string | null
  
  The completed_at value. * assignee: unknown
  
  The assignee value. * space: object
  
  The space value. * id: integer
```
The `id` value.
```
  - name: string
    
    The name value. * generated_item: object
  The generated_item value. * id: integer
```
The `id` value.
```
  - message_id: integer
    
    The message_id value. * evidence_count: integer
    
    The evidence_count value. * evidence_url: string | null
    
    The evidence_url value. * approval: object | null
  The approval value. * transition_id: integer
```
The `transition_id` value.
```
  - actor: object
    
    The actor value. * user_id: integer
```
The `user_id` value.
```
    - full_name: string
      
      The full_name value. * occurred_at: string
    The occurred_at value. * assignable_users: (object)[]
  The assignable_users value. * user_id: integer
```
The `user_id` value.
```
  - full_name: string
    
    The full_name value. * history_count: integer
  The history_count value. * recent_events: (object)[]
  
  The recent_events value. * id: integer
```
The `id` value.
```
  - kind: string
    
    The kind value. * actor: object
    
    The actor value. * user_id: integer
```
The `user_id` value.
```
    - full_name: string
      
      The full_name value. * occurred_at: string
    The occurred_at value. * previous_state: string
    
    The previous_state value. * new_state: string
    
    The new_state value. * previous_assignee: unknown
    
    The previous_assignee value. * new_assignee: unknown
    
    The new_assignee value. * reason: string
    
    The reason value. * notification_message_id: integer | null
    
    The notification_message_id 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",
    "todo": {
        "approval": null,
        "assignable_users": [],
        "assignee": null,
        "completed_at": null,
        "due_date": null,
        "generated_item": {
            "evidence_count": 0,
            "evidence_url": null,
            "id": 3,
            "message_id": 4
        },
        "history_count": 1,
        "id": 1,
        "recent_events": [],
        "space": {
            "id": 2,
            "name": "Launch"
        },
        "state": "active",
        "version": 1,
        "wording": "Confirm venue"
    }
}

The current To-do returned after a stale transition request.

{
    "msg": "The Todo has changed.",
    "result": "error",
    "todo": {
        "approval": null,
        "assignable_users": [],
        "assignee": null,
        "completed_at": null,
        "due_date": null,
        "generated_item": {
            "evidence_count": 0,
            "evidence_url": null,
            "id": 3,
            "message_id": 4
        },
        "history_count": 1,
        "id": 1,
        "recent_events": [],
        "space": {
            "id": 2,
            "name": "Launch"
        },
        "state": "active",
        "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