Timers

Each stage has its own ordered list of timers. Use these endpoints to read, add, change, delete and reorder them. To run a timer, see Transport.

The timer object

Every endpoint on this page that returns a timer returns this object.

Name
_id
Type
string
Description
Unique id.
Name
_model
Type
string
Description
The type of this object. Always timer.
Name
_updated_at
Type
timestamp
Description
When it last changed.
Name
name
Type
string
Description
The name.
Name
speaker
Type
string
Description
The speaker's name.
Name
notes
Type
string
Description
A comment for the people running the show.
Name
label_ids
Type
array of strings
Description
Ids of room labels attached to this timer, in display order. At most 5.
Name
appearance
Type
string
Description
How the timer reads on the outputs. One of COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, COUNTUP_TOD.
Name
type
Type
string
Description
DURATION runs for a set time. FINISH_TIME runs until a set time of day. One of DURATION, FINISH_TIME.
Name
duration
Type
string
Description
Human-readable duration, e.g. "0:05:00".
Name
hours
Type
integer
Description
The hours part of the duration.
Name
minutes
Type
integer
Description
The minutes part of the duration.
Name
seconds
Type
integer
Description
The seconds part of the duration.
Name
wrap_up_yellow
Type
integer
Description
When the yellow warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up_red
Type
integer
Description
When the red warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up
Type
object or null
Description
This timer's own wrap-up settings. Null uses the room's.
Name
trigger
Type
string
Description
How the timer starts: MANUAL by hand, LINKED when the timer above reaches zero, SCHEDULED at start_time. You can't change it while the timer is running or paused. One of MANUAL, LINKED, SCHEDULED.
Name
start_time
Type
timestamp or null
Description
A fixed start time. Null means it's calculated from the timers above. A SCHEDULED timer needs one and starts by itself at that time. You can't change it while the timer is running or paused.
Name
finish_time
Type
timestamp or null
Description
When a FINISH_TIME timer ends.
Name
skipped
Type
boolean
Description
Whether the timer is out of the show. It takes no time in the schedule and can't be started, but keeps its settings.
Name
over_under
Type
string or null
Description
Which of this timer's over and under figures the Controller shows. Null follows the room. One of both, over, under, none.
Name
new_day
Type
boolean
Description
Whether a new day starts at this timer. Never on the first timer or a linked one.

GET/rooms/{room_id}/timers

List timers

Returns a stage's timers in show order.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….

Query parameters

Name
stage_id
Type
string
Description
Which stage (stage-1, stage-2); Stage #1 when omitted. One of stage-1, stage-2.

Request

GET

/rooms/{room_id}/timers

curl https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timers loaded",
  "data": {
    "list": [
      {
        "_id": "V1StGXR8Z5jd",
        "_model": "timer",
        "_updated_at": "2026-11-05T09:30:00.000Z",
        "name": "Opening keynote",
        "speaker": "Ada Lovelace",
        "notes": "Intro video first",
        "label_ids": [
          ""
        ],
        "appearance": "COUNTDOWN",
        "type": "DURATION",
        "duration": "0:05:00",
        "hours": 0,
        "minutes": 5,
        "seconds": 0,
        "wrap_up_yellow": 120,
        "wrap_up_red": 30,
        "wrap_up": null,
        "trigger": "MANUAL",
        "start_time": null,
        "finish_time": null,
        "skipped": false,
        "over_under": null,
        "new_day": false
      }
    ]
  }
}

POST/rooms/{room_id}/timers

Create a timer

Adds a timer to a stage: at the end, or at index if you send it. Every field is optional.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….

Query parameters

Name
stage_id
Type
string
Description
Which stage (stage-1, stage-2); Stage #1 when omitted. One of stage-1, stage-2.

Body

Name
name
Type
string
Description
On create, defaults to Timer N (N = the 1-based position it's inserted at). At most 100 characters.
Name
speaker
Type
string
Description
The speaker's name. At most 100 characters.
Name
notes
Type
string
Description
A comment for the people running the show. At most 200 characters.
Name
label_ids
Type
array of strings
Description
Ids of room labels attached to this timer, in display order.
Name
appearance
Type
string
Description
How the timer reads on the outputs. One of COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, COUNTUP_TOD.
Name
type
Type
string
Description
DURATION runs for a set time. FINISH_TIME runs until a set time of day. One of DURATION, FINISH_TIME.
Name
hours
Type
integer
Description
The hours part of the duration.
Name
minutes
Type
integer
Description
The minutes part of the duration.
Name
seconds
Type
integer
Description
The seconds part of the duration.
Name
wrap_up_yellow
Type
integer
Description
When the yellow warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up_red
Type
integer
Description
When the red warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up
Type
object or null
Description
This timer's own wrap-up settings. Null uses the room's.
Name
trigger
Type
string
Description
How the timer starts: MANUAL by hand, LINKED when the timer above reaches zero, SCHEDULED at start_time. You can't change it while the timer is running or paused. One of MANUAL, LINKED, SCHEDULED.
Name
start_time
Type
timestamp or null
Description
A fixed start time. Null means it's calculated from the timers above. A SCHEDULED timer needs one and starts by itself at that time. You can't change it while the timer is running or paused.
Name
finish_time
Type
timestamp or null
Description
When a FINISH_TIME timer ends.
Name
skipped
Type
boolean
Description
Whether the timer is out of the show. It takes no time in the schedule and can't be started, but keeps its settings.
Name
over_under
Type
string or null
Description
Which of this timer's over and under figures the Controller shows. Null follows the room. One of both, over, under, none.
Name
new_day
Type
boolean
Description
Whether a new day starts at this timer. Never on the first timer or a linked one.
Name
index
Type
integer
Description
The 0-based position to insert the timer at. Left out, it goes at the end.

Request

POST

/rooms/{room_id}/timers

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Opening keynote","speaker":"Ada Lovelace","minutes":20}'

Response 201

{
  "ok": true,
  "message": "Timer created",
  "data": {
    "_id": "V1StGXR8Z5jd",
    "_model": "timer",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Opening keynote",
    "speaker": "Ada Lovelace",
    "notes": "Intro video first",
    "label_ids": [
      ""
    ],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:05:00",
    "hours": 0,
    "minutes": 5,
    "seconds": 0,
    "wrap_up_yellow": 120,
    "wrap_up_red": 30,
    "wrap_up": null,
    "trigger": "MANUAL",
    "start_time": null,
    "finish_time": null,
    "skipped": false,
    "over_under": null,
    "new_day": false
  }
}

GET/rooms/{room_id}/timers/{timer_id}

Get a timer

Returns one timer.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
timer_id
Type
string
Required
Description
The timer to act on.

Request

GET

/rooms/{room_id}/timers/{timer_id}

curl https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers/TIMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer loaded",
  "data": {
    "_id": "V1StGXR8Z5jd",
    "_model": "timer",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Opening keynote",
    "speaker": "Ada Lovelace",
    "notes": "Intro video first",
    "label_ids": [
      ""
    ],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:05:00",
    "hours": 0,
    "minutes": 5,
    "seconds": 0,
    "wrap_up_yellow": 120,
    "wrap_up_red": 30,
    "wrap_up": null,
    "trigger": "MANUAL",
    "start_time": null,
    "finish_time": null,
    "skipped": false,
    "over_under": null,
    "new_day": false
  }
}

PATCH/rooms/{room_id}/timers/{timer_id}

Update a timer

Changes only the fields you send.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
timer_id
Type
string
Required
Description
The timer to act on.

Body

Name
name
Type
string
Description
On create, defaults to Timer N (N = the 1-based position it's inserted at). At most 100 characters.
Name
speaker
Type
string
Description
The speaker's name. At most 100 characters.
Name
notes
Type
string
Description
A comment for the people running the show. At most 200 characters.
Name
label_ids
Type
array of strings
Description
Ids of room labels attached to this timer, in display order.
Name
appearance
Type
string
Description
How the timer reads on the outputs. One of COUNTDOWN, COUNTUP, TOD, COUNTDOWN_TOD, COUNTUP_TOD.
Name
type
Type
string
Description
DURATION runs for a set time. FINISH_TIME runs until a set time of day. One of DURATION, FINISH_TIME.
Name
hours
Type
integer
Description
The hours part of the duration.
Name
minutes
Type
integer
Description
The minutes part of the duration.
Name
seconds
Type
integer
Description
The seconds part of the duration.
Name
wrap_up_yellow
Type
integer
Description
When the yellow warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up_red
Type
integer
Description
When the red warning starts, in seconds before the end. 0 while the timer uses the room's wrap-ups.
Name
wrap_up
Type
object or null
Description
This timer's own wrap-up settings. Null uses the room's.
Name
trigger
Type
string
Description
How the timer starts: MANUAL by hand, LINKED when the timer above reaches zero, SCHEDULED at start_time. You can't change it while the timer is running or paused. One of MANUAL, LINKED, SCHEDULED.
Name
start_time
Type
timestamp or null
Description
A fixed start time. Null means it's calculated from the timers above. A SCHEDULED timer needs one and starts by itself at that time. You can't change it while the timer is running or paused.
Name
finish_time
Type
timestamp or null
Description
When a FINISH_TIME timer ends.
Name
skipped
Type
boolean
Description
Whether the timer is out of the show. It takes no time in the schedule and can't be started, but keeps its settings.
Name
over_under
Type
string or null
Description
Which of this timer's over and under figures the Controller shows. Null follows the room. One of both, over, under, none.
Name
new_day
Type
boolean
Description
Whether a new day starts at this timer. Never on the first timer or a linked one.

Request

PATCH

/rooms/{room_id}/timers/{timer_id}

curl -X PATCH https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers/TIMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minutes":25}'

Response 200

{
  "ok": true,
  "message": "Timer updated",
  "data": {
    "_id": "V1StGXR8Z5jd",
    "_model": "timer",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Opening keynote",
    "speaker": "Ada Lovelace",
    "notes": "Intro video first",
    "label_ids": [
      ""
    ],
    "appearance": "COUNTDOWN",
    "type": "DURATION",
    "duration": "0:05:00",
    "hours": 0,
    "minutes": 5,
    "seconds": 0,
    "wrap_up_yellow": 120,
    "wrap_up_red": 30,
    "wrap_up": null,
    "trigger": "MANUAL",
    "start_time": null,
    "finish_time": null,
    "skipped": false,
    "over_under": null,
    "new_day": false
  }
}

DELETE/rooms/{room_id}/timers/{timer_id}

Delete a timer

Deletes a timer. The timers after it move up.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….
Name
timer_id
Type
string
Required
Description
The timer to act on.

Request

DELETE

/rooms/{room_id}/timers/{timer_id}

curl -X DELETE https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers/TIMER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 204

204 No Content

POST/rooms/{room_id}/timers/reorder

Reorder timers

Sets the order of a stage's timers. Send the id of every timer on the stage, in the new order.

Path parameters

Name
room_id
Type
string
Required
Description
The room's id, from its address: /o/ROOM_ID/….

Body

Name
ordered_ids
Type
array of strings
Required
Description
The id of every timer on the stage, in the new order.

Request

POST

/rooms/{room_id}/timers/reorder

curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/timers/reorder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ordered_ids":["TIMER_ID_2","TIMER_ID_1"]}'

Response 200

{
  "ok": true,
  "message": "Timers reordered",
  "data": {
    "list": [
      {
        "_id": "V1StGXR8Z5jd",
        "_model": "timer",
        "_updated_at": "2026-11-05T09:30:00.000Z",
        "name": "Opening keynote",
        "speaker": "Ada Lovelace",
        "notes": "Intro video first",
        "label_ids": [
          ""
        ],
        "appearance": "COUNTDOWN",
        "type": "DURATION",
        "duration": "0:05:00",
        "hours": 0,
        "minutes": 5,
        "seconds": 0,
        "wrap_up_yellow": 120,
        "wrap_up_red": 30,
        "wrap_up": null,
        "trigger": "MANUAL",
        "start_time": null,
        "finish_time": null,
        "skipped": false,
        "over_under": null,
        "new_day": false
      }
    ]
  }
}