Довідник API ендпоінтів

Повна документація всіх доступних REST API ендпоінтів.

Організація та інтроспекція

Отримайте інформацію про Ваш поточний API контекст та організацію.

Отримати поточний контекст

GET /api/v1/me

Повертає інформацію про Ваш API ключ, організацію, ліміти запитів та доступні функції. Цей ендпоінт не враховується в ліміті запитів.

Приклад запиту:

curl -X GET "https://www.screenzzie.com/api/v1/me" \
  -H "Authorization: Bearer sk_live_xxx"

Приклад відповіді:

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "uuid",
      "name": "My API Key",
      "keyPrefix": "sk_live_abc123",
      "scopes": ["screens:read", "screens:write", "playlists:read"],
      "expiresAt": null,
      "lastUsedAt": "2024-01-15T10:30:00Z"
    },
    "organization": {
      "id": "uuid",
      "name": "My Company",
      "planId": "growth",
      "subscriptionStatus": "active",
      "trialEndsAt": null,
      "maxScreensAllowed": 50,
      "activeScreensCount": 12
    },
    "rateLimits": {
      "limit": 100000,
      "used": 45,
      "remaining": 99955,
      "resetAtMs": 1704153600000
    },
    "features": {
      "sequences": true,
      "schedules": true,
      "api": true
    }
  }
}

Список організацій

GET /api/v1/organizations

Повертає організації, доступні з Вашим API ключем. Наразі кожен API ключ належить рівно одній організації.

Параметри запиту:

Приклад запиту:

curl -X GET "https://www.screenzzie.com/api/v1/organizations" \
  -H "Authorization: Bearer sk_live_xxx"

Приклад відповіді:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "My Company",
        "planId": "growth",
        "subscriptionStatus": "active",
        "maxScreensAllowed": 50,
        "activeScreensCount": 12,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

---

Екрани

Керуйте екранами цифрових вивісок.

Список екранів

GET /api/v1/screens

Параметри запиту:

Приклад запиту:

curl -X GET "https://www.screenzzie.com/api/v1/screens?isOnline=true&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"

Приклад відповіді:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Lobby Display",
        "description": "Main entrance screen",
        "isActive": true,
        "isOnline": true,
        "lastSeenAt": "2024-01-01T12:00:00Z",
        "orientation": "landscape",
        "rotation": "0",
        "timezone": "Europe/Madrid",
        "location": "Building A, Floor 1",
        "cityName": "Madrid",
        "latitude": 40.4168,
        "longitude": -3.7038,
        "workspaceId": "uuid",
        "screenGroupId": null,
        "currentPlaylistId": "uuid",
        "currentSequenceId": null,
        "defaultPlaylistId": "uuid",
        "defaultSequenceId": null,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasMore": true
    }
  }
}

Отримати екран

GET /api/v1/screens/:screenId

Параметри шляху:

Приклад відповіді:

Повертає один об'єкт екрана з тією ж структурою, що й у відповіді списку.

Створити екран

POST /api/v1/screens

Тіло запиту:

Приклад запиту:

curl -X POST "https://www.screenzzie.com/api/v1/screens" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Conference Room A",
    "orientation": "landscape",
    "rotation": "0",
    "timezone": "Europe/Madrid",
    "location": "Building B, Room 101"
  }'

Приклад відповіді:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Conference Room A",
    "description": null,
    "isActive": true,
    "isOnline": false,
    "lastSeenAt": null,
    "orientation": "landscape",
    "rotation": "0",
    "timezone": "Europe/Madrid",
    "location": "Building B, Room 101",
    "cityName": null,
    "latitude": null,
    "longitude": null,
    "workspaceId": null,
    "screenGroupId": null,
    "currentPlaylistId": null,
    "currentSequenceId": null,
    "defaultPlaylistId": null,
    "defaultSequenceId": null,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Оновити екран

PATCH /api/v1/screens/:screenId

Усі поля опціональні. Включайте тільки поля, які хочете оновити.

Тіло запиту:

Приклад запиту:

curl -X PATCH "https://www.screenzzie.com/api/v1/screens/abc123" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Display Name",
    "currentPlaylistId": "playlist-uuid"
  }'

---

Плейлисти

Керуйте контент-плейлистами для Ваших екранів.

Список плейлистів

GET /api/v1/playlists

Параметри запиту:

Приклад відповіді:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Main Content",
        "description": "Primary playlist for lobby screens",
        "itemCount": 5,
        "totalDuration": 120,
        "workspaceId": null,
        "createdBy": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Отримати плейлист

GET /api/v1/playlists/:playlistId

Повертає плейлист з його елементами. Елементи завжди включені у відповідь.

Параметри шляху:

Приклад відповіді:

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Main Content",
    "description": "Primary playlist for lobby screens",
    "itemCount": 2,
    "totalDuration": 45,
    "workspaceId": null,
    "createdBy": "user-uuid",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T12:00:00Z",
    "items": [
      {
        "id": "item-uuid-1",
        "position": 0,
        "duration": 15,
        "itemType": "media",
        "mediaId": "media-uuid",
        "config": null,
        "createdAt": "2024-01-01T00:00:00Z"
      },
      {
        "id": "item-uuid-2",
        "position": 1,
        "duration": 30,
        "itemType": "website",
        "mediaId": null,
        "config": { "url": "https://example.com" },
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Створити плейлист

POST /api/v1/playlists

Тіло запиту:

Приклад запиту:

curl -X POST "https://www.screenzzie.com/api/v1/playlists" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday Promotions",
    "description": "Seasonal content for December"
  }'

Оновити плейлист

PATCH /api/v1/playlists/:playlistId

Тіло запиту:

Видалити плейлист

DELETE /api/v1/playlists/:playlistId

Повертає 204 No Content при успіху.

---

Медіа

Доступ та реєстрація медіафайлів у Вашій бібліотеці.

Список медіа

GET /api/v1/media

Параметри запиту:

Приклад відповіді:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "promo-video.mp4",
        "type": "video",
        "fileUrl": "https://...",
        "thumbnailUrl": "https://...",
        "fileSize": 15728640,
        "duration": 30,
        "folderId": null,
        "workspaceId": null,
        "uploadedBy": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Отримати медіа

GET /api/v1/media/:mediaId

Повертає один об'єкт медіа з тією ж структурою, що й у відповіді списку.

Зареєструвати медіа

POST /api/v1/media

Реєструє медіафайл, який вже завантажено до сховища. Цей ендпоінт не обробляє завантаження файлів безпосередньо — використовуйте веб-панель для завантаження файлів.

Тіло запиту:

Приклад запиту:

curl -X POST "https://www.screenzzie.com/api/v1/media" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Logo",
    "type": "image",
    "fileUrl": "https://your-storage.com/logo.png",
    "thumbnailUrl": "https://your-storage.com/logo-thumb.png",
    "fileSize": 102400
  }'

Видалити медіа

DELETE /api/v1/media/:mediaId

Повертає 204 No Content при успіху.

---

Розклади

Плануйте контент для відтворення у конкретний час.

Список розкладів

GET /api/v1/schedules

Параметри запиту:

Приклад відповіді:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Weekend Promotions",
        "playlistId": "playlist-uuid",
        "sequenceId": null,
        "screenId": null,
        "screenGroupId": null,
        "targetType": "all_screens",
        "dayOfWeek": [0, 6],
        "startTime": "09:00",
        "endTime": "21:00",
        "startDate": null,
        "endDate": null,
        "priority": 10,
        "isActive": true,
        "color": "#3B82F6",
        "workspaceId": null,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

Отримати розклад

GET /api/v1/schedules/:scheduleId

Повертає один об'єкт розкладу з тією ж структурою, що й у відповіді списку.

Створити розклад

POST /api/v1/schedules

Тіло запиту:

*Для планування контенту слід надати playlistId або sequenceId.

Умовні вимоги типу цілі:

Приклад запиту:

curl -X POST "https://www.screenzzie.com/api/v1/schedules" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Promotions",
    "playlistId": "abc123",
    "targetType": "all_screens",
    "dayOfWeek": [0, 6],
    "startTime": "09:00",
    "endTime": "21:00",
    "priority": 10,
    "color": "#3B82F6"
  }'

Оновити розклад

PATCH /api/v1/schedules/:scheduleId

Усі поля опціональні. Використовує ті ж визначення полів, що й Створити розклад.

Видалити розклад

DELETE /api/v1/schedules/:scheduleId

Повертає 204 No Content при успіху.

---

HTTP статус коди