HTTP Endpoints

The xTimer API enables you to remotely control your timer using scripts and external tools. The HTTP API provides endpoints for various timer operations including starting, stopping, and resetting timers, as well as managing messages and rooms.

Authentication

xTimer uses token-based authentication, requiring an API key. Authenticate by sending your API key using the api_key query parameter, or send it as a "bearer token" in the HTTP Authorization header. All API requests must be authenticated and made over HTTPS.

# Authenticate with query parameter
https://xtimer.app/api/rooms/ABC12345?api_key=your_api_key_here

# Authenticate with bearer token
Authorization: Bearer your_api_key_here

Base URL

All API endpoints are relative to the base URL:

https://xtimer.app/api

Room Endpoints

Generate a New Room PID

GET /rooms/generate-pid

Creates a new room with a unique PID and default 10-minute timer.

Query Parameters:

timezone (required): Timezone for the room
teamId (optional): Team ID for the room
view (optional): View type

Response:

{
  "pid": "ABC12345",
  "id": "room-id",
  "name": "Room Name",
  "timers": [
    {
      "id": "timer-id",
      "name": "10 Minute Timer",
      "duration": "600000"
    }
  ]
}

Get Room Information

GET /rooms/:pid

Retrieves all information for a specific room.

Path Parameters:

pid: Room PID

Query Parameters:

view (optional): View type (CONTROLLER, VIEWER, AGENDA, MODERATOR)
role (optional): Role type (alias for view)

Response:

{
  "timeset": {
    "deadlineWarped": null,
    "timerId": "timer-id",
    "running": false,
    "deadline": 1665123456789,
    "kickoff": 1665123456789,
    "lastStop": 1665123456789
  },
  "timers": {
    "items": [],
    "sorted": [],
    "active": {}
  },
  "messages": {
    "items": [],
    "sorted": [],
    "active": null
  },
  "settings": {}
}

Update Room Name

PATCH /rooms/:pid/name

Updates the name of a specific room.

Path Parameters:

pid: Room PID

Request Body:

{
  "name": "New Room Name"
}

Response:

{
  "id": "room-id",
  "pid": "ABC12345",
  "name": "New Room Name"
}

Timer Endpoints

Start a Timer

POST /rooms/:pid/timers/:timerId/start

Starts a specific timer in a room.

Path Parameters:

pid: Room PID
timerId: Timer ID

Response:

{
  "deadlineWarped": null,
  "timerId": "timer-id",
  "running": true,
  "deadline": 1665123456789,
  "kickoff": 1665123456789,
  "lastStop": 1665123456789
}

Stop a Timer

POST /rooms/:pid/timers/:timerId/stop

Stops a specific timer in a room.

Path Parameters:

pid: Room PID
timerId: Timer ID

Response:

{
  "deadlineWarped": null,
  "timerId": "timer-id",
  "running": false,
  "deadline": 1665123456789,
  "kickoff": 1665123456789,
  "lastStop": 1665123456789,
  "elapsedTime": 30000,
  "remainingTime": 570000
}

Reset a Timer

POST /rooms/:pid/timers/:timerId/reset

Resets a specific timer in a room.

Path Parameters:

pid: Room PID
timerId: Timer ID

Response:

{
  "deadlineWarped": null,
  "timerId": "timer-id",
  "running": false,
  "deadline": 1665123456789,
  "kickoff": 1665123456789,
  "lastStop": 1665123456789
}

Tweak a Timer

POST /rooms/:pid/timers/:timerId/tweak

Adjusts the time of a specific timer in a room.

Path Parameters:

pid: Room PID
timerId: Timer ID

Request Body:

{
  "amount": "+ 30s"  // Format: [+/-] [value][s/m/h]
}

Response:

{
  "deadlineWarped": null,
  "timerId": "timer-id",
  "running": true,
  "deadline": 1665123456789,
  "kickoff": 1665123456789,
  "lastStop": 1665123456789
}

Create a New Timer

POST /rooms/:pid/timers/create

Creates a new timer in the room.

Path Parameters:

pid: Room PID

Request Body:

{
  "name": "Presentation",
  "speaker": "John Doe",
  "notes": "Main points...",
  "hours": 0,
  "minutes": 20,
  "seconds": 0,
  "appearance": "COUNTDOWN",
  "showName": true,
  "showSpeaker": true,
  "showNotes": true
}

Response: Returns the created timer object.

Update Timer Settings

POST /rooms/:pid/timers/:timerId/settings

Unified endpoint to update any timer settings.

Path Parameters:

pid: Room PID
timerId: Timer ID

Request Body:

{
  "name": "Updated Name",
  "hours": 0,
  "minutes": 15,
  "seconds": 0,
  "appearance": "COUNTDOWN",
  "wrapUpYellow": 60,
  "wrapUpRed": 30
}

Response:

{
  "ok": true,
  "message": "Timer settings updated"
}

Message Endpoints

Create a New Message

POST /rooms/:pid/messages

Creates a new message in a room.

Path Parameters:

pid: Room PID

Request Body:

{
  "text": "Please wrap up in 2 minutes",
  "color": "YELLOW",
  "isVisible": false,
  "bold": true,
  "uppercase": false
}

Response:

{
  "messageId": "message-id",
  "text": "Please wrap up in 2 minutes",
  "color": "YELLOW",
  "showing": false,
  "bold": true,
  "uppercase": false,
  "index": 1
}

Toggle Message Visibility

POST /rooms/:pid/messages/:messageId/toggle

Shows or hides a specific message in a room.

Path Parameters:

pid: Room PID
messageId: Message ID

Response:

{
  "messageId": "message-id",
  "isVisible": true
}

Flash a Message

POST /rooms/:pid/messages/:messageId/flash

Flashes a specific message to call attention to it.

Path Parameters:

pid: Room PID
messageId: Message ID

Response:

{
  "success": true,
  "messageId": "message-id",
  "flashes": 3
}

Other Endpoints

Toggle Blackout Mode

POST /rooms/:pid/blackout

Toggles the blackout mode for the specified room.

Path Parameters:

pid: Room PID

Request Body:

{
  "enabled": true
}

Response:

{
  "success": true,
  "message": "Blackout mode enabled successfully",
  "blackoutEnabled": true
}

Synchronize Playback

POST /rooms/:pid/playback/sync

Synchronizes timer playback across all clients in the room.

Path Parameters:

pid: Room PID

Response:

{
  "success": true,
  "timerId": "timer-id",
  "running": true,
  "deadline": 1665123456789,
  "kickoff": 1665123456789,
  "lastStop": 1665123456789
}

HTTP Endpoints

On this page