Roku projects API

openapi: 3.0.3
info:
  title: Roku External Control Protocol (ECP) Apps projects API
  version: '1.0'
  description: 'The External Control Protocol (ECP) is an HTTP-based API exposed on port 8060 of every Roku

    streaming device on the local network. It enables third-party applications, mobile remote-control

    apps, automated testing systems, and home-automation hubs to discover Roku devices via SSDP,

    inject simulated remote-control key presses, launch installed apps with deep-link parameters,

    query device state, and retrieve diagnostic information.


    The protocol is plain HTTP/1.1 (no TLS) and is intended for trusted local-network use only.

    Most control operations require the user to enable "Control by mobile apps" on the device.

    Additional diagnostic endpoints (chanperf, sgnodes, registry, etc.) are gated behind Roku

    Developer Mode.

    '
  contact:
    name: Roku Developer Program
    url: https://developer.roku.com
  x-generated-from: documentation
  x-source-url: https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md
servers:
- url: http://{rokuDeviceIp}:8060
  description: A Roku device on the local network
  variables:
    rokuDeviceIp:
      default: 192.168.1.100
      description: The IPv4 address of the Roku device, discovered via SSDP
tags:
- name: projects
paths:
  /api/v1/organisations/{organisation_id}/projects:
    get:
      tags:
      - projects
      summary: Roku List Projects
      operationId: projects-list_projects
      security:
      - Nabu Cloud: []
      parameters:
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: items
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000000
          description: The number of items per page. Use 0 for no limit.
          default: 100
          title: Items
        description: The number of items per page. Use 0 for no limit.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: The page number. Use 0 for the first page.
          default: 0
          title: Page
        description: The page number. Use 0 for the first page.
      - name: slug
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          description: The slug of the project, used in URLs
          title: Slug
        description: The slug of the project, used in URLs
      - name: name
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The name of the Project
          title: Name
        description: The name of the Project
      - name: description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 0
            maxLength: 4096
          - type: 'null'
          description: The description of the Project
          title: Description
        description: The description of the Project
      - name: billing_entity
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The billing entity of the Project
          title: Billing Entity
        description: The billing entity of the Project
      - name: max_devices
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Maximum number of devices in the project, 0 for organisation max
          title: Max Devices
        description: Maximum number of devices in the project, 0 for organisation max
      - name: max_snapshots
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Maximum number of snapshots in the project, 0 for organisation max
          title: Max Snapshots
        description: Maximum number of snapshots in the project, 0 for organisation max
      - name: max_runtime
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Maximum runtime of a device in the project, 0 for organisation max
          title: Max Runtime
        description: Maximum runtime of a device in the project, 0 for organisation max
      - name: created_at
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: The creation day of the project
          title: Created At
        description: The creation day of the project
      - name: include_personal_project
        in: query
        required: false
        schema:
          type: boolean
          description: Show private projects
          default: true
          title: Include Personal Project
        description: Show private projects
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectOut'
                title: Response Projects-List Projects
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - projects
      summary: Roku Create Project
      operationId: projects-create_project
      security:
      - Nabu Cloud: []
      parameters:
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organisations/{organisation_id}/projects/{project_id}:
    get:
      tags:
      - projects
      summary: Roku Get Project
      operationId: projects-get_project
      security:
      - Nabu Cloud: []
      parameters:
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - projects
      summary: Roku Update Project
      operationId: projects-update_project
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - projects
      summary: Roku Delete Project
      operationId: projects-delete_project
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: cascade_delete
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Deletes project, and everything associated with it, including snapshots!
          title: Cascade Delete
        description: Deletes project, and everything associated with it, including snapshots!
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organisations/{organisation_id}/projects/{project_id}/groups:
    get:
      tags:
      - projects
      summary: Roku List Project Groups
      operationId: projects-list_project_groups
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: items
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000000
          description: The number of items per page. Use 0 for no limit.
          default: 100
          title: Items
        description: The number of items per page. Use 0 for no limit.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: The page number. Use 0 for the first page.
          default: 0
          title: Page
        description: The page number. Use 0 for the first page.
      - name: project_role
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The name of the project role
          title: Project Role
        description: The name of the project role
      - name: added
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: The day the group was added
          title: Added
        description: The day the group was added
      - name: group_name
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The name of the Group
          title: Group Name
        description: The name of the Group
      - name: group_description
        in: query
        required: false
        schema:
          type: string
          minLength: 0
          maxLength: 4096
          description: The name of the Group
          title: Group Description
        description: The name of the Group
      - name: group_created_at
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: When the group was created
          title: Group Created At
        description: When the group was created
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectGroupOut'
                title: Response Projects-List Project Groups
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - projects
      summary: Roku Add Project Group
      operationId: projects-add_project_group
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectGroupAdd'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGroupOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organisations/{organisation_id}/projects/{project_id}/groups/{group_id}:
    get:
      tags:
      - projects
      summary: Roku Get Project Group
      operationId: projects-get_project_group
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGroupOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - projects
      summary: Roku Update Project Group
      operationId: projects-update_project_group
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectGroupUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGroupOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - projects
      summary: Roku Remove Project Group
      operationId: projects-remove_project_group
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: group_id
        in: path
        required: true
        schema:
          type: integer
          title: Group Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organisations/{organisation_id}/projects/{project_id}/members:
    get:
      tags:
      - projects
      summary: Roku List Project Members
      operationId: projects-list_project_members
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: items
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000000
          description: The number of items per page. Use 0 for no limit.
          default: 100
          title: Items
        description: The number of items per page. Use 0 for no limit.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: The page number. Use 0 for the first page.
          default: 0
          title: Page
        description: The page number. Use 0 for the first page.
      - name: project_role
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The name of the project role
          title: Project Role
        description: The name of the project role
      - name: added
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: When the user was added.
          title: Added
        description: When the user was added.
      - name: member_username
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
          description: The username of the member.
          title: Member Username
        description: The username of the member.
      - name: member_email
        in: query
        required: false
        schema:
          type: string
          description: The email of the member.
          format: email
          title: Member Email
        description: The email of the member.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectMemberOut'
                title: Response Projects-List Project Members
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - projects
      summary: Roku Add Project Member
      operationId: projects-add_project_member
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectMemberAdd'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMemberOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/organisations/{organisation_id}/projects/{project_id}/members/{user_id}:
    get:
      tags:
      - projects
      summary: Roku Get Project Member
      operationId: projects-get_project_member
      security:
      - Nabu Cloud: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMemberOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - projects
      summary: Roku Update Project Member
      operationId: projects-update_project_member
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      - name: project_role_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Role Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectMemberOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - projects
      summary: Roku Remove Project Member
      operationId: projects-remove_project_member
      security:
      - Nabu Cloud: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: organisation_id
        in: path
        required: true
        schema:
          type: integer
          title: Organisation Id
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: User Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProjectGroupOut:
      properties:
        group_id:
          type: integer
          title: Group Id
        group_name:
          type: string
          title: Group Name
        project_role_id:
          type: integer
          title: Project Role Id
        project_role_name:
          type: string
          title: Project Role Name
      type: object
      required:
      - group_id
      - group_name
      - project_role_id
      - project_role_name
      title: ProjectGroupOut
    ProjectGroupUpdate:
      properties:
        project_role_id:
          type: integer
          title: Project Role Id
      type: object
      required:
      - project_role_id
      title: ProjectGroupUpdate
    ProjectCreate:
      properties:
        slug:
          type: string
          maxLength: 255
          minLength: 3
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          title: Slug
          description: The slug of the project, used in URLs
        name:
          type: string
          maxLength: 255
          minLength: 3
          title: Name
          description: The name of the Project
        description:
          anyOf:
          - type: string
            maxLength: 4096
            minLength: 0
          - type: 'null'
          title: Description
          description: The description of the Project
        billing_entity:
          type: string
          maxLength: 255
          minLength: 3
          title: Billing Entity
          description: The billing entity of the Project
        max_devices:
          type: integer
          minimum: 0
          title: Max Devices
          description: Maximum number of devices in the project, 0 for organisation max
          default: 0
        max_snapshots:
          type: integer
          minimum: 0
          title: Max Snapshots
          description: Maximum number of snapshots in the project, 0 for organisation max
          default: 0
        max_runtime:
          type: integer
          minimum: 0
          title: Max Runtime
          description: Maximum runtime of a device in the project, 0 for organisation max
          default: 0
        private:
          type: boolean
          title: Private
          description: Whether the project is listed in search results
          default: false
      type: object
      required:
      - slug
      - name
      - billing_entity
      title: ProjectCreate
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ProjectOut:
      properties:
        id:
          type: integer
          minimum: 0
          title: Id
        slug:
          type: string
          maxLength: 255
          minLength: 3
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          title: Slug
          description: The slug of the project, used in URLs
        name:
          type: string
          maxLength: 255
          minLength: 3
          title: Name
          description: The name of the Project
        description:
          anyOf:
          - type: string
            maxLength: 4096
            minLength: 0
          - type: 'null'
          title: Description
          description: The description of the Project
        billing_entity:
          type: string
          maxLength: 255
          minLength: 3
          title: Billing Entity
          description: The billing entity of the Project
        max_devices:
          type: integer
          minimum: 0
          title: Max Devices
          description: Maximum number of devices in the project, 0 for organisation max
          default: 0
        max_snapshots:
          type: integer
          minimum: 0
          title: Max Snapshots
          description: Maximum number of snapshots in the project, 0 for organisation max
          default: 0
        max_runtime:
          type: integer
          minimum: 0
          title: Max Runtime
          description: Maximum runtime of a device in the project, 0 for organisation max
          default: 0
        private:
          type: boolean
          title: Private
          description: Whether the project is listed in search results
          default: false
        user_project:
          type: boolean
          title: User Project
          description: Whether the project is a user project
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the project was created
        current_devices:
          type: integer
          minimum: 0
          title: Current Devices
          default: 0
        current_snapshots:
          type: integer
          minimum: 0
          title: Current Snapshots
          default: 0
      type: object
      required:
      - id
      - slug
      - name
      - billing_entity
      - user_project
      - created_at
      title: ProjectOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProjectUpdate:
      properties:
        slug:
          type: string
          maxLength: 255
          minLength: 3
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          title: Slug
          description: The slug of the project, used in URLs
        name:
          type: string
          maxLength: 255
          minLength: 3
          title: Name
          description: The name of the Project
        description:
          anyOf:
          - type: string
            maxLength: 4096
            minLength: 0
          - type: 'null'
          title: Description
          description: The description of the Project
        billing_entity:
          type: string
          maxLength: 255
          minLength: 3
          title: Billing Entity
          description: The billing entity of the Project
        max_devices:
          type: integer
          minimum: 0
          title: Max Devices
          description: Maximum number of devices in the project, 0 for organisation max
        max_snapshots:
          type: integer
          minimum: 0
          title: Max Snapshots
          description: Maximum number of snapshots in the project, 0 for organisation max
        max_runtime:
          type: integer
          minimum: 0
          title: Max Runtime
          description: Maximum runtime of a device in the project, 0 for organisation max
        private:
          type: boolean
          title: Private
          description: Whether the project is listed in search results
      type: object
      title: ProjectUpdate
    ProjectGroupAdd:
      properties:
        group_id:
          type: integer
          title: Group Id
        project_role_id:
          type: integer
          title: Project Role Id
      type: object
      required:
      - group_id
      - project_role_id
      title: ProjectGroupAdd
    ProjectMemberAdd:
      properties:
        user_id:
          type: string
          format: uuid
          title: User Id
        project_role_id:
          type: integer
          title: Project Role Id
      type: object
      required:
      - user_id
      - project_role_id
      title: ProjectMemberAdd
    ProjectMemberOut:
      properties:
        user_id:
          type: string
          format: uuid
          title: User Id
        username:
          type: string
          title: Username
        project_role_id:
          type: integer
          title: Project Role Id
        project_role_name:
          type: string
          title: Project Role Name
      type: object
      required:
      - user_id
      - username
      - project_role_id
      - project_role_name
      title: ProjectMemberOut