REST API

Introduction

PalcoTimer's REST API allows you to create, read, update and delete resources programmatically. The API base URL is:

https://app.palcotimer.com/api/v1

All responses are in JSON. For development environments, use

Authentication

Most endpoints require authentication via Bearer Token. Include the token in the header of each request:

Authorization: Bearer seu_token_aqui

Get your token by logging into the platform. The token is returned on the login endpoint and stored automatically by the frontend.

Rooms

List your rooms

GET /auth/rooms

# Resposta
[
  {
    "id": "uuid",
    "short_code": "ABC123",
    "name": "Minha Sala",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

Create room

POST /rooms
Content-Type: application/json

{
  "name": "Nome da Sala"
}

# Resposta
{
  "id": "uuid",
  "short_code": "ABC123"
}

Get room by ID or short_code

GET /rooms/{roomId}

# Resposta
{
  "id": "uuid",
  "short_code": "ABC123",
  "name": "Minha Sala",
  "settings": {...},
  "created_at": "2024-01-01T00:00:00Z"
}

Update room

PUT /rooms/{roomId}
Content-Type: application/json

{
  "name": "Novo Nome",
  "settings": {
    "color_normal": "#22c55e",
    "color_yellow": "#eab308",
    "color_red": "#ef4444"
  }
}

Timers

List timers of a room

GET /rooms/{roomId}/timers

# Resposta
[
  {
    "id": "uuid",
    "room_id": "uuid",
    "position": 0,
    "name": "Abertura",
    "speaker": "João Silva",
    "duration_ms": 300000,
    "appearance": "COUNTDOWN",
    "wrap_yellow_ms": 120000,
    "wrap_red_ms": 30000
  }
]

Create timer

POST /rooms/{roomId}/timers
Content-Type: application/json

{
  "name": "Palestra 1",
  "speaker": "Maria Santos",
  "duration_ms": 600000,
  "appearance": "COUNTDOWN",
  "wrap_yellow_ms": 120000,
  "wrap_red_ms": 30000
}

Update timer

PUT /rooms/{roomId}/timers/{timerId}
Content-Type: application/json

{
  "name": "Novo Nome",
  "duration_ms": 900000
}

Delete timer

DELETE /rooms/{roomId}/timers/{timerId}

Messages

List messages

GET /rooms/{roomId}/messages

# Resposta
[
  {
    "id": "uuid",
    "text": "Faltam 5 minutos",
    "color": "yellow",
    "bold": true,
    "visible": false
  }
]

Create message

POST /rooms/{roomId}/messages
Content-Type: application/json

{
  "text": "Finalize agora",
  "color": "red",
  "bold": true,
  "uppercase": true
}

Show/Hide message

PUT /rooms/{roomId}/messages/{messageId}
Content-Type: application/json

{
  "visible": true
}

Playback Control

To control timer playback (play, pause, stop, etc.), use the WebSocket connection. See the

Error Codes