Kloksi
ru

Transport

These endpoints do what the transport buttons in the Controller do. Unless you name a timer, they act on the active timer of the cued stage.

The playback status object

Most transport endpoints return this object. All its times are in milliseconds since the Unix epoch.

  • Name
    _model
    Type
    string
    Description

    The type of this object. Always playback_status.

  • Name
    _updated_at
    Type
    timestamp
    Description

    When it last changed.

  • Name
    timer_id
    Type
    string
    Description

    Empty string when no timer is active.

  • Name
    running
    Type
    boolean
    Description

    Whether the timer is running. false when it's paused, or when no timer is active.

  • Name
    start
    Type
    integer
    Description

    The start of the current run, moved forward by any pauses, so start plus the duration gives the finish. 0 if no timer is active.

  • Name
    first_started
    Type
    integer
    Description

    When the run was first started. Pausing, resuming and jumping don't change it. 0 if no timer is active.

  • Name
    finish
    Type
    integer
    Description

    Epoch ms when the current run will finish. 0 if inactive.

  • Name
    pause
    Type
    integer
    Description

    Epoch ms when paused. 0 if not paused.

  • Name
    server_time
    Type
    integer
    Description

    The server's clock when it answered. Compare it with your own clock to correct for any difference.

GET/rooms/{room_id}/playback_status

Get playback status

Returns a stage's playback: which timer is on stage, whether it's running and when it finishes.

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}/playback_status
curl https://app.kloksi.com/api/v1/rooms/ROOM_ID/playback_status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Playback status loaded",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/start_timer

Start a timer

Starts the active timer of the cued stage, or the timer in timer_id. A paused timer resumes.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    timer_id
    Type
    string
    Description

    The timer to act on.

Request

POST
/rooms/{room_id}/start_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/start_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer started at 0:05:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/stop_timer

Pause a timer

Pauses the running timer and keeps its elapsed time.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Request

POST
/rooms/{room_id}/stop_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/stop_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer stopped at 0:04:12",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/toggle_timer

Start or pause a timer

Pauses the timer if it's running, and starts it if it's paused or idle. Acts on the active timer of the cued stage, or the timer in timer_id.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    timer_id
    Type
    string
    Description

    The timer to act on.

Request

POST
/rooms/{room_id}/toggle_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/toggle_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer started at 0:05:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/reset_timer

Reset a timer

Puts the timer back to its full duration. Acts on the active timer of the cued stage, or the timer in timer_id.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    timer_id
    Type
    string
    Description

    The timer to act on.

Request

POST
/rooms/{room_id}/reset_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/reset_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer reset to 0:05:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/next_timer

Go to the next timer

Moves to the next timer that isn't skipped. If the stage is running, that timer starts right away. Otherwise it's only selected.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Request

POST
/rooms/{room_id}/next_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/next_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Next timer _Panel discussion_ started (0:30:00)",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/previous_timer

Go to the previous timer

Moves to the previous timer that isn't skipped. If the stage is running, that timer starts right away. Otherwise it's only selected.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Request

POST
/rooms/{room_id}/previous_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/previous_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Previous timer _Opening keynote_ started (0:20:00)",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/add_time

Add time

Adds time to the active timer of the cued stage.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    seconds
    Type
    integer
    Required
    Description

    The seconds part of the duration.

Request

POST
/rooms/{room_id}/add_time
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/add_time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds":60}'

Response 200

{
  "ok": true,
  "message": "Added 60s to timer. New countdown: 0:06:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/subtract_time

Subtract time

Takes time off the active timer of the cued stage. It stops at zero.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    seconds
    Type
    integer
    Required
    Description

    The seconds part of the duration.

Request

POST
/rooms/{room_id}/subtract_time
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/subtract_time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds":60}'

Response 200

{
  "ok": true,
  "message": "Subtracted 60s from timer. New countdown: 0:04:00",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/jump

Jump within a timer

Moves the timer on stage forward or back without changing its duration. Positive values jump forward.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    milliseconds
    Type
    integer
    Required
    Description

    How far to jump. Positive goes forward, leaving less time. Negative goes back. It can't be zero, and it stops at the timer's start and end.

Request

POST
/rooms/{room_id}/jump
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/jump \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"milliseconds":30000}'

Response 200

{
  "ok": true,
  "message": "Jumped forward 30s. New countdown: 0:04:30",
  "data": {
    "_model": "playback_status",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "timer_id": "V1StGXR8Z5jd",
    "running": true,
    "start": 1793871000000,
    "first_started": 1793871000000,
    "finish": 1793871300000,
    "pause": 0,
    "server_time": 1793871060000
  }
}
POST/rooms/{room_id}/highlight_timer

Set the active timer

Makes a timer the active one on its stage without starting it. Transport endpoints then act on it.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    timer_id
    Type
    string
    Required
    Description

    The timer to act on.

Request

POST
/rooms/{room_id}/highlight_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/highlight_timer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timer_id":"TIMER_ID"}'

Response 200

{
  "ok": true,
  "message": "Timer highlighted",
  "data": {
    "_id": "x7kp2mqa",
    "_model": "room",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Annual Conference",
    "date": "2026-11-05",
    "blackout": false,
    "dim": 0,
    "focus_message": false,
    "on_air": false,
    "logo": "",
    "timezone": "Europe/Berlin",
    "language": "en",
    "team_id": "6f2c1e9ab04d7c3e8a5b1d20",
    "accepting_questions": false,
    "questionnaire": {
      "logo": {
        "mode": "kloksi"
      },
      "title": "",
      "subtitle": "",
      "question_label": "",
      "name_label": "",
      "hide_name": false
    },
    "protected_outputs": [
      "controller"
    ],
    "archived": false,
    "cue_stage_id": "stage-1",
    "stages": [
      {
        "_id": "x7kp2mqa",
        "name": "Annual Conference",
        "active_timer_id": "V1StGXR8Z5jd",
        "timers_count": 1,
        "end_of_show": null,
        "end_of_show_trigger": "MANUAL",
        "end_of_show_loops": 2,
        "end_of_show_new_day": false,
        "show_run": null
      }
    ]
  }
}
POST/rooms/{room_id}/unhighlight_timer

Clear the active timer

Clears the active timer of the cued stage.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Request

POST
/rooms/{room_id}/unhighlight_timer
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/unhighlight_timer \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Timer unhighlighted",
  "data": {
    "_id": "x7kp2mqa",
    "_model": "room",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Annual Conference",
    "date": "2026-11-05",
    "blackout": false,
    "dim": 0,
    "focus_message": false,
    "on_air": false,
    "logo": "",
    "timezone": "Europe/Berlin",
    "language": "en",
    "team_id": "6f2c1e9ab04d7c3e8a5b1d20",
    "accepting_questions": false,
    "questionnaire": {
      "logo": {
        "mode": "kloksi"
      },
      "title": "",
      "subtitle": "",
      "question_label": "",
      "name_label": "",
      "hide_name": false
    },
    "protected_outputs": [
      "controller"
    ],
    "archived": false,
    "cue_stage_id": "stage-1",
    "stages": [
      {
        "_id": "x7kp2mqa",
        "name": "Annual Conference",
        "active_timer_id": "V1StGXR8Z5jd",
        "timers_count": 1,
        "end_of_show": null,
        "end_of_show_trigger": "MANUAL",
        "end_of_show_loops": 2,
        "end_of_show_new_day": false,
        "show_run": null
      }
    ]
  }
}
POST/rooms/{room_id}/cue_stage

Cue a stage

Gives a stage the room's cue, so transport endpoints act on it. A stage needs at least one timer to take the cue.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Body

  • Name
    stage_id
    Type
    string
    Required
    Description

    The stage. One of stage-1, stage-2.

Request

POST
/rooms/{room_id}/cue_stage
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/cue_stage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id":"stage-2"}'

Response 200

{
  "ok": true,
  "message": "Stage cued",
  "data": {
    "_id": "x7kp2mqa",
    "_model": "room",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Annual Conference",
    "date": "2026-11-05",
    "blackout": false,
    "dim": 0,
    "focus_message": false,
    "on_air": false,
    "logo": "",
    "timezone": "Europe/Berlin",
    "language": "en",
    "team_id": "6f2c1e9ab04d7c3e8a5b1d20",
    "accepting_questions": false,
    "questionnaire": {
      "logo": {
        "mode": "kloksi"
      },
      "title": "",
      "subtitle": "",
      "question_label": "",
      "name_label": "",
      "hide_name": false
    },
    "protected_outputs": [
      "controller"
    ],
    "archived": false,
    "cue_stage_id": "stage-1",
    "stages": [
      {
        "_id": "x7kp2mqa",
        "name": "Annual Conference",
        "active_timer_id": "V1StGXR8Z5jd",
        "timers_count": 1,
        "end_of_show": null,
        "end_of_show_trigger": "MANUAL",
        "end_of_show_loops": 2,
        "end_of_show_new_day": false,
        "show_run": null
      }
    ]
  }
}
POST/rooms/{room_id}/start_fresh

Start fresh

Resets the timer on the cued stage, clears the recorded run and makes the first timer active.

Path parameters

  • Name
    room_id
    Type
    string
    Required
    Description

    The room's id, from its address: /o/ROOM_ID/….

Request

POST
/rooms/{room_id}/start_fresh
curl -X POST https://app.kloksi.com/api/v1/rooms/ROOM_ID/start_fresh \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "ok": true,
  "message": "Started fresh",
  "data": {
    "_id": "x7kp2mqa",
    "_model": "room",
    "_updated_at": "2026-11-05T09:30:00.000Z",
    "name": "Annual Conference",
    "date": "2026-11-05",
    "blackout": false,
    "dim": 0,
    "focus_message": false,
    "on_air": false,
    "logo": "",
    "timezone": "Europe/Berlin",
    "language": "en",
    "team_id": "6f2c1e9ab04d7c3e8a5b1d20",
    "accepting_questions": false,
    "questionnaire": {
      "logo": {
        "mode": "kloksi"
      },
      "title": "",
      "subtitle": "",
      "question_label": "",
      "name_label": "",
      "hide_name": false
    },
    "protected_outputs": [
      "controller"
    ],
    "archived": false,
    "cue_stage_id": "stage-1",
    "stages": [
      {
        "_id": "x7kp2mqa",
        "name": "Annual Conference",
        "active_timer_id": "V1StGXR8Z5jd",
        "timers_count": 1,
        "end_of_show": null,
        "end_of_show_trigger": "MANUAL",
        "end_of_show_loops": 2,
        "end_of_show_new_day": false,
        "show_run": null
      }
    ]
  }
}