openapi: 3.0.3
info:
  title: Yodeck REST API (Modeled)
  description: >-
    Programmatic management of a Yodeck digital signage account - media, playlists,
    layouts, screens (monitors), schedules, shows, and workspaces. Yodeck publishes
    a REST API whose interactive reference lives at https://app.yodeck.com/api-docs/
    and is available to Premium and Enterprise plans. Access uses a named,
    role-scoped API token generated under Account Settings > Advanced Settings >
    API Tokens; the token acts as a user and inherits the permissions of the role
    assigned to it.


    IMPORTANT: The live Yodeck API reference is behind an account login, so this
    document is MODELED from Yodeck's publicly documented resource set and product
    pages, not copied from an official machine-readable spec. Base path, exact
    field names, pagination, and the precise Authorization header format should be
    confirmed against the live reference at app.yodeck.com/api-docs before relying
    on this specification. Endpoints here are illustrative of the documented
    capabilities (CRUD over media, playlists, layouts, screens, schedules, shows,
    workspaces) rather than verbatim.
  version: '1.0'
  contact:
    name: Yodeck
    url: https://www.yodeck.com
    email: support@yodeck.com
  x-modeled: true
  x-modeled-note: >-
    Endpoints and schemas modeled from Yodeck's documented resource set; the
    authoritative reference is login-gated at https://app.yodeck.com/api-docs/.
servers:
  - url: https://app.yodeck.com/api/v1
    description: Yodeck REST API (base path modeled; confirm against live reference)
security:
  - tokenAuth: []
tags:
  - name: Media
    description: Images, videos, documents, web pages, and app content assets.
  - name: Playlists
    description: Ordered sequences of media with per-item duration and transitions.
  - name: Layouts
    description: Multi-zone screen layouts that split a display into regions.
  - name: Screens
    description: Screens (monitors/players), their status, and remote control.
  - name: Schedules
    description: Time-based rules controlling what plays where and when.
  - name: Shows
    description: Reusable groupings of media, playlists, and layouts.
  - name: Workspaces
    description: Separate environments with their own users, permissions, and content.
paths:
  /media/:
    get:
      operationId: listMedia
      tags: [Media]
      summary: List media assets
      description: Lists media assets in the account or workspace.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of media assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createMedia
      tags: [Media]
      summary: Create or upload a media asset
      description: >-
        Creates a media asset. Media can be uploaded directly or ingested from an
        external URL for automated sync.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaInput'
      responses:
        '201':
          description: Media asset created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Media'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /media/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getMedia
      tags: [Media]
      summary: Retrieve a media asset
      responses:
        '200':
          description: A media asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Media'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateMedia
      tags: [Media]
      summary: Update a media asset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MediaInput'
      responses:
        '200':
          description: Media asset updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Media'
    delete:
      operationId: deleteMedia
      tags: [Media]
      summary: Delete a media asset
      responses:
        '204':
          description: Media asset deleted.
  /playlists/:
    get:
      operationId: listPlaylists
      tags: [Playlists]
      summary: List playlists
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paginated list of playlists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaylistList'
    post:
      operationId: createPlaylist
      tags: [Playlists]
      summary: Create a playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaylistInput'
      responses:
        '201':
          description: Playlist created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
  /playlists/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getPlaylist
      tags: [Playlists]
      summary: Retrieve a playlist
      responses:
        '200':
          description: A playlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
    patch:
      operationId: updatePlaylist
      tags: [Playlists]
      summary: Update a playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaylistInput'
      responses:
        '200':
          description: Playlist updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
    delete:
      operationId: deletePlaylist
      tags: [Playlists]
      summary: Delete a playlist
      responses:
        '204':
          description: Playlist deleted.
  /layouts/:
    get:
      operationId: listLayouts
      tags: [Layouts]
      summary: List layouts
      responses:
        '200':
          description: A paginated list of layouts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutList'
    post:
      operationId: createLayout
      tags: [Layouts]
      summary: Create a layout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutInput'
      responses:
        '201':
          description: Layout created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layout'
  /layouts/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getLayout
      tags: [Layouts]
      summary: Retrieve a layout
      responses:
        '200':
          description: A layout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layout'
    patch:
      operationId: updateLayout
      tags: [Layouts]
      summary: Update a layout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutInput'
      responses:
        '200':
          description: Layout updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layout'
    delete:
      operationId: deleteLayout
      tags: [Layouts]
      summary: Delete a layout
      responses:
        '204':
          description: Layout deleted.
  /monitors/:
    get:
      operationId: listScreens
      tags: [Screens]
      summary: List screens (monitors)
      description: Lists screens. Yodeck refers to a screen/player as a monitor.
      responses:
        '200':
          description: A paginated list of screens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenList'
    post:
      operationId: createScreen
      tags: [Screens]
      summary: Register a screen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenInput'
      responses:
        '201':
          description: Screen registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screen'
  /monitors/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getScreen
      tags: [Screens]
      summary: Retrieve a screen
      responses:
        '200':
          description: A screen with status and assigned content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screen'
    patch:
      operationId: updateScreen
      tags: [Screens]
      summary: Update a screen
      description: Update screen settings or the content (media, playlist, layout, or show) assigned to it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScreenInput'
      responses:
        '200':
          description: Screen updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screen'
    delete:
      operationId: deleteScreen
      tags: [Screens]
      summary: Delete a screen
      responses:
        '204':
          description: Screen deleted.
  /monitors/{id}/reboot/:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: rebootScreen
      tags: [Screens]
      summary: Reboot a screen (modeled action)
      description: >-
        Triggers a remote reboot of the player. Modeled from Yodeck's documented
        remote screen control and monitoring capability; confirm the exact action
        path against the live reference.
      responses:
        '202':
          description: Reboot requested.
  /schedules/:
    get:
      operationId: listSchedules
      tags: [Schedules]
      summary: List schedules
      responses:
        '200':
          description: A paginated list of schedules.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleList'
    post:
      operationId: createSchedule
      tags: [Schedules]
      summary: Create a schedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleInput'
      responses:
        '201':
          description: Schedule created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
  /schedules/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getSchedule
      tags: [Schedules]
      summary: Retrieve a schedule
      responses:
        '200':
          description: A schedule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
    patch:
      operationId: updateSchedule
      tags: [Schedules]
      summary: Update a schedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleInput'
      responses:
        '200':
          description: Schedule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
    delete:
      operationId: deleteSchedule
      tags: [Schedules]
      summary: Delete a schedule
      responses:
        '204':
          description: Schedule deleted.
  /shows/:
    get:
      operationId: listShows
      tags: [Shows]
      summary: List shows
      responses:
        '200':
          description: A paginated list of shows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowList'
    post:
      operationId: createShow
      tags: [Shows]
      summary: Create a show
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShowInput'
      responses:
        '201':
          description: Show created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
  /shows/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getShow
      tags: [Shows]
      summary: Retrieve a show
      responses:
        '200':
          description: A show.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
    patch:
      operationId: updateShow
      tags: [Shows]
      summary: Update a show
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShowInput'
      responses:
        '200':
          description: Show updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
    delete:
      operationId: deleteShow
      tags: [Shows]
      summary: Delete a show
      responses:
        '204':
          description: Show deleted.
  /workspaces/:
    get:
      operationId: listWorkspaces
      tags: [Workspaces]
      summary: List workspaces
      responses:
        '200':
          description: A paginated list of workspaces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceList'
    post:
      operationId: createWorkspace
      tags: [Workspaces]
      summary: Create a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceInput'
      responses:
        '201':
          description: Workspace created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
  /workspaces/{id}/:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getWorkspace
      tags: [Workspaces]
      summary: Retrieve a workspace
      responses:
        '200':
          description: A workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
    patch:
      operationId: updateWorkspace
      tags: [Workspaces]
      summary: Update a workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceInput'
      responses:
        '200':
          description: Workspace updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
    delete:
      operationId: deleteWorkspace
      tags: [Workspaces]
      summary: Delete a workspace
      responses:
        '204':
          description: Workspace deleted.
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Named, role-scoped API token generated in the Yodeck console (Account
        Settings > Advanced Settings > API Tokens). The token acts as a user with
        the permissions of its assigned role. Send it in the Authorization header.
        The exact header value format (for example "Token name:secret") is
        documented in the login-gated reference and should be confirmed there.
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The numeric identifier of the resource.
      schema:
        type: integer
    Page:
      name: page
      in: query
      required: false
      description: Page number for paginated results (modeled).
      schema:
        type: integer
    PageSize:
      name: page_size
      in: query
      required: false
      description: Number of results per page (modeled).
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
    MediaList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Media'
    Media:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        media_type:
          type: string
          description: Type of media (image, video, document, webpage, app, etc.).
        source_url:
          type: string
          description: External URL for media ingested by URL sync.
        duration:
          type: integer
          description: Default display duration in seconds.
        created_at:
          type: string
          format: date-time
    MediaInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        media_type:
          type: string
        source_url:
          type: string
        duration:
          type: integer
    PlaylistList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Playlist'
    Playlist:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        items:
          type: array
          description: Ordered media items with durations and transitions.
          items:
            type: object
            properties:
              media_id:
                type: integer
              duration:
                type: integer
              order:
                type: integer
    PlaylistInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              media_id:
                type: integer
              duration:
                type: integer
              order:
                type: integer
    LayoutList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Layout'
    Layout:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        zones:
          type: array
          description: Regions of the screen, each with its own content.
          items:
            type: object
            properties:
              name:
                type: string
              x:
                type: number
              y:
                type: number
              width:
                type: number
              height:
                type: number
              content_type:
                type: string
              content_id:
                type: integer
    LayoutInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        zones:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              x:
                type: number
              y:
                type: number
              width:
                type: number
              height:
                type: number
              content_type:
                type: string
              content_id:
                type: integer
    ScreenList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Screen'
    Screen:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string
          description: Player connectivity/health status.
        default_show:
          type: integer
          nullable: true
        content_type:
          type: string
          description: Type of content assigned (media, playlist, layout, or show).
        content_id:
          type: integer
          nullable: true
        last_seen:
          type: string
          format: date-time
    ScreenInput:
      type: object
      properties:
        name:
          type: string
        content_type:
          type: string
        content_id:
          type: integer
    ScheduleList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Schedule'
    Schedule:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        rules:
          type: array
          description: Recurring dayparting or date-range rules.
          items:
            type: object
            properties:
              start:
                type: string
              end:
                type: string
              days_of_week:
                type: array
                items:
                  type: string
              content_type:
                type: string
              content_id:
                type: integer
    ScheduleInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        rules:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
              end:
                type: string
              days_of_week:
                type: array
                items:
                  type: string
              content_type:
                type: string
              content_id:
                type: integer
    ShowList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Show'
    Show:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        items:
          type: array
          description: Grouped media, playlists, and layouts.
          items:
            type: object
            properties:
              content_type:
                type: string
              content_id:
                type: integer
              order:
                type: integer
    ShowInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              content_type:
                type: string
              content_id:
                type: integer
              order:
                type: integer
    WorkspaceList:
      type: object
      properties:
        count:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
    Workspace:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
    WorkspaceInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string