openapi: 3.0.0
info:
  version: 1.0.3
  title: AppEditor API
  contact:
    email: info@vuframe.com
    name: Vuframe® c/o Vu3D Software GmbH
  description: >-
    The VUFRAME® Public API offers a number of endpoint to view, create and edit different types of content within the VUFRAME® platform. The public API can be accessed by any VUFRAME® Studio user. This specific API controls the [AppEditor](https://docs.vuframe.com/studio/), where you create standalone, white-label apps for any operating system & for VR headsets and manage its content.


    The base URL for all the endpoints listed below is
    
    
    https://api.vuframe.com/public/v1
    
    
    **Authentication**

      In order to integrate the VUFRAME® Public API into your own application, you will first need to register an SSO app by contacting us directly. After your app is set up, you will receive a unique SSO app token that allows you to communicate with the VUFRAME® Public API.
      
      In addition to the SSO app token, all requests to the VUFRAME® Public API need to be authenticated with an authentication token that is bound to an active VUFRAME® Studio account. The required authentication mechanism is Basic Auth with the following credentials:
      
      Username: SSO_APP_TOKEN Password: USER_AUTH_TOKEN
  termsOfService: 'https://www.vuframe.com/terms-of-service/'
paths:
  /sso/{app_token}/create_token:
    post:
      tags:
        - Authentication
      summary: Create an SSO Auth Token for a VUFRAME® Studio User
      description: |-
        Creates an authentication token for a VUFRAME® Studio user. This token can then be used to access the various endpoints of the VUFRAME® Public API. If the user already has a valid auth token for the given SSO app, the existing token will be returned instead of creating a new one. 

        This endpoint uses Basic Auth with the following Credentials:

        Username: STUDIO_EMAIL Password: STUDIO_PASSWORD

        Replace STUDIO_EMAIL with the e-mail address of a valid VUFRAME® Studio user and STUDIO_PASSWORD with the password associated with that account.
      operationId: createToken
      responses:
        '200':
          description: "Returns the newly created auth token in the displayed format."
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    description: "success indicator"
                    type: boolean
                  token:
                    description: "API Token"
                    type: string
        '405':
          description: Invalid input
      security:
        - basicAuth: []
      parameters:
        - in: path
          name: app_token
          description: "Token of an App"
          required: true
          schema:
            type: string
  /apps:
      get:
        tags:
          - Apps
        summary: Get a list of all apps
        description: >-
          Returns a list of all apps the current user has access to.
        operationId: getApps
        responses:
          '200':
            description: successful operation
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: '#/components/schemas/App'
          '400':
            description: Invalid value
        security:
          - basicAuth: []
  '/apps/{app_token}':
    get:
      tags:
        - Apps
      summary: Get a single App
      description: |
        Get an existing app by its token with all top-level pages.

      operationId: getApp
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '405':
          description: Invalid input
      security:
        - basicAuth: []
  '/apps/{app_token}/pages':
    get:
      tags:
        - Pages
      summary: Get all Pages of an App
      description: |
        Get all pages of an existing app by its token.

      operationId: getPages
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
        '405':
          description: Invalid input
      security:
        - basicAuth: []
  '/apps/{app_token}/pages/{page_token}':
    get:
      tags:
        - Pages
      summary: Get single Page of a specific App
      description: |
        Get all pages of an existing app by its token.

      operationId: getPage
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
        - name: page_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '405':
          description: Invalid input
      security:
        - basicAuth: []
    patch:
      tags:
        - Pages
      summary: Patch single Page of a specific App
      description: |
        Patch specific page of an existing app by its token.
      operationId: patchPage
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
        - name: page_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      requestBody:
        description: >-
          Example request body for updating the SmartVu Share Code list of a collection page. It will add the given ShareCodes to the Page. If one of these ShareCodes is already added, the api won't attach it to this page. Currently it is not possible to delete or overwrite the list of share codes. This will be implemented in a next version.
        
        
          Find more about Share Codes at [Vuframe Wiki - Shared SmartVu](https://docs.vuframe.com/viewer/concepts/share-pages)
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                additional_fields:
                  type: object
                  properties:
                    smartvus:
                      type: array
                      description: Array of Share Codes of shared SmartVu's
                      items:
                        type: string
              example:   # Sample object
                additional_fields: 
                  smartvus: ["ShareCode"]
      responses:
        '204':
          description: successful operation
        '405':
          description: Invalid input
      security:
        - basicAuth: []
    put:
      tags:
        - Pages
      summary: Put values to single Page of a specific App
      description: |
        Replace values of a specific page of an existing app by its token.
      operationId: putPage
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
        - name: page_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      requestBody:
        description: >-
          Example request body for replacing the SmartVu Share Code list of a collection page. It will replace the existing Share Codes with the given ones.
        
          Find more about Share Codes at [Vuframe Wiki - Shared SmartVu](https://docs.vuframe.com/viewer/concepts/share-pages)
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                additional_fields:
                  type: object
                  properties:
                    smartvus:
                      type: array
                      description: Array of Share Codes of shared SmartVu's
                      items:
                        type: string
              example:   # Sample object
                additional_fields: 
                  smartvus: ["ShareCode"]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPageResponse'
        '405':
          description: Invalid input
      security:
        - basicAuth: []

  '/apps/{app_token}/publish/{platform_identifier}':
    post:
      tags:
        - Apps
      summary: Publish single platform of app
      description: |
        Publishes a single platfrom by its identifier. Be careful with this request, as it publishes a new version for each call, when the platfrom is not already in the publishing process.
      operationId: publishAppWithIdentifier
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
        - name: platform_identifier
          in: path
          description: Identifier of a specific platform (distribution form of an app)
          required: true
          schema:
            type: string
        - name: force
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppPublishSingle'
        '406':
          description: Invalid Operation, when Platform is already in publishing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
      security:
        - basicAuth: []  
  '/apps/{app_token}/publish':
    post:
      tags:
        - Apps
      summary: Publish all platforms of single app
      description: |
        Publishes all platforms of a single app by its token. Be careful with this request, as it publishes a new version for each call. This request only works by setting the force query parameter to true.
      operationId: publishApp
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
        - name: force
          in: query
          required: true
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppPublishMultiple'
        '405':
          description: Invalid input
      security:
        - basicAuth: []    
    get:
      tags:
        - Apps
      summary: Status of publishing status of App
      description: |
        This request will return the current status of the publishing process for all platfroms initiated by a POST /publish beforehand.
      operationId: publishAppStatus
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppPublishStatus'
        '405':
          description: Invalid input
      security:
        - basicAuth: []
  '/apps/{app_token}/platforms':
    post:
      tags:
        - Apps
      summary: List of platforms of an App
      description: |
        List of platforms that are used by this app.
      operationId: AppPlattforms
      parameters:
        - name: app_token
          in: path
          description: Token of an App
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlatformStatus'
        '405':
          description: Invalid input
      security:
        - basicAuth: []
components:
  schemas:
    App:
      type: object
      properties:
        token: 
          description: "Token of App"
          type: string
        title: 
          description: "Title of App"
          type: string
        description:
          description: "Description of App"
          type: string
        type:
          description: "Type of App"
          type: string
        version: 
          description: "Version of App"
          type: string
        space:
          description: "Token of the space that contains this app."
          type: string
        company:
          description: "Name of the company that contains this app, if it exists."
          type: string
        pages:
          description: "All pages of an app."
          type: array
          items:
            $ref: '#/components/schemas/Page'
    AppPublishSingle:
      type: object
      properties:
        platform:
          $ref: '#/components/schemas/PlatformStatus'
    AppPublishMultiple:
      type: object
      properties:
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/PlatformStatus'
    AppPublishStatus:
      type: object
      properties:
        token:
          type: string
          description: Token of App
        title:
          type: string
          description: Title of App
        status:
          type: string
          description: Publishing Status of App
        publish_ready:
          type: boolean
          description: Is ready for Publishing and has unpublished changes?
        public_version:
          type: string
          description: Current public version
    PlatformStatus:
      type: object
      description: The status property refers to the current release. 'unpublished_changes' is refering to the upcoming release.
      properties:
        title:
          description: "Title of Platform"
          type: string
        identifier:
          description: "Identifier of Platform"
          type: string
        release:
          description: "Release Number of Platform"
          type: string
        status:
          description: "Status of Publishing"
          type: string
        unpublished_changes:
          description: "Are there unpublished changes for this platform?"
          type: boolean
    Page:
      type: object
      properties:
        token:
          description: "Token of Page"
          type: string
        title:
          description: "Title of Page"
          type: string
        description:
          description: "Description of Page"
          type: string
        version:
          description: "Version of Page"
          type: string
        space:
          description: "Token of space that contains the app of this page."
          type: string
        additional_fields:
          description: "Additional fields that are specific to a type of page."
          type: array
          items:
            type: object
    PutPageResponse:
      type: object
      properties:
        token:
          description: "Token of Page"
          type: string
        title:
          description: "Title of Page"
          type: string
        version:
          description: "Version of Page"
          type: string
        additional_fields:
          description: "Additional fields that are specific to a type of page."
          type: array
          items:
            type: object
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error Message
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security: 
  - basicAuth: []
servers:
  - description: Production SmartVu API
    url: https://api.vuframe.com/public/v1
tags:
  - name: Authentication