Losant Files API

openapi: 3.2.0
info:
  title: Platform Files API
  version: 1.31.0
  description: User API for accessing platform data
servers:
- url: https://api.losant.com
security:
- bearerAuth: []
tags:
- name: Files
paths:
  /applications/{applicationId}/file/{fileId}:
    get:
      operationId: file.get
      summary: Retrieves information on a file
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: fileId
        in: path
        required: true
        description: ID associated with the file
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec76c7ae143cd83dc4a96
      responses:
        '200':
          description: File information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - file.get
    patch:
      operationId: file.patch
      summary: Reupload a file
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: fileId
        in: path
        required: true
        description: ID associated with the file
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec76c7ae143cd83dc4a96
      responses:
        '200':
          description: Successfully updated file and the information needed to upload the file content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileUploadPostResponse'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/filePatch'
        description: Updated information about the file
      x-losant-auth-scopes:
      - file.patch
    delete:
      operationId: file.delete
      summary: Deletes a file or directory, if directory all the contents that directory will…
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: fileId
        in: path
        required: true
        description: ID associated with the file
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec76c7ae143cd83dc4a96
      responses:
        '200':
          description: If file was successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - file.delete
  /applications/{applicationId}/file/{fileId}/move:
    post:
      operationId: file.move
      summary: Move a file or the entire contents of a directory
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: fileId
        in: path
        required: true
        description: ID associated with the file
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec76c7ae143cd83dc4a96
      - name: name
        in: query
        required: false
        description: The new name of the file or directory
        schema:
          type: string
        example: fileA
      - name: parentDirectory
        in: query
        required: false
        description: The new parent directory for the file or directory to move into.
        schema:
          type: string
        example: /new/location/here
      responses:
        '201':
          description: Returns a new file or directory that was created by the move, if a directory a job will kick off to move all the directory's children.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - file.move
  /applications/{applicationId}/file/{fileId}/upload:
    post:
      operationId: file.upload
      summary: Uploads the file
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: fileId
        in: path
        required: true
        description: ID associated with the file
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec76c7ae143cd83dc4a96
      responses:
        '200':
          description: Updated file content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/file'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if file was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - file.upload
  /applications/{applicationId}/files:
    get:
      operationId: files.get
      summary: Returns the files for an application
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      - name: sortField
        in: query
        required: false
        description: Field to sort the results by
        schema:
          type: string
          enum:
          - lastUpdated
          - type
          - name
          - creationDate
          default: lastUpdated
        example: name
      - name: sortDirection
        in: query
        required: false
        description: Direction to sort the results by
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        example: asc
      - name: page
        in: query
        required: false
        description: Which page of results to return
        schema:
          type: string
          default: 0
        example: 0
      - name: perPage
        in: query
        required: false
        description: How many items to return per page
        schema:
          type: string
          default: 100
        example: 10
      - name: filterField
        in: query
        required: false
        description: Field to filter the results by. Blank or not provided means no filtering.
        schema:
          type: string
          enum:
          - name
        example: name
      - name: filter
        in: query
        required: false
        description: Filter to apply against the filtered field. Supports globbing. Blank or not provided means no filtering.
        schema:
          type: string
        example: myFile
      - name: type
        in: query
        required: false
        description: Limit by the type (file or directory) of the file
        schema:
          type: string
        example: file
      - name: status
        in: query
        required: false
        description: Limit the result to only files of this status
        schema:
          type: string
          enum:
          - completed
          - pending
        example: completed
      - name: directory
        in: query
        required: false
        description: Get files that are inside of this directory
        schema:
          type: string
        example: /a/path/
      responses:
        '200':
          description: Collection of files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if application was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - files.get
    post:
      operationId: files.post
      summary: Create a new file for an application
      tags:
      - Files
      parameters:
      - name: applicationId
        in: path
        required: true
        description: ID associated with the application
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec8687ae143cd83dc4a97
      responses:
        '201':
          description: Successfully created file and the information needed to upload the file content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fileUploadPostResponse'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if application was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/filePost'
        description: New file information
      x-losant-auth-scopes:
      - files.post
components:
  schemas:
    file:
      title: File
      description: Schema for a single public or private file
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        applicationId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        creationDate:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        authorId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        authorType:
          type: string
          enum:
          - flow
          - user
          - device
          - apiToken
          - notebook
        status:
          type: string
          enum:
          - pending
          - moving
          - deleting
          - completed
        name:
          type: string
          minLength: 1
          maxLength: 1024
        parentDirectory:
          type: string
          maxLength: 1024
        type:
          type: string
          enum:
          - file
          - directory
        fileSize:
          type: number
        s3etag:
          type: string
        contentType:
          type: string
          maxLength: 1024
        fileDimensions:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
        moveIntoId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        url:
          type: string
    error:
      title: Error
      description: Schema for errors returned by the API
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        validationErrors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              validationMessage:
                type: string
    files:
      title: Files
      description: Schema for a collection of public or private files
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/file'
        count:
          type: integer
        totalCount:
          type: integer
        perPage:
          type: integer
        page:
          type: integer
        filter:
          type: string
        filterField:
          type: string
        sortField:
          type: string
        sortDirection:
          type: string
          enum:
          - asc
          - desc
          - ASC
          - DESC
          - ''
        applicationId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        parentExists:
          type: boolean
    success:
      title: Success
      description: Schema for reporting a successful operation
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
    filePatch:
      title: File Patch
      description: Schema to patch a public or private file
      type: object
      properties:
        fileSize:
          type: number
        contentType:
          type: string
          maxLength: 1024
        fileDimensions:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
    filePost:
      title: File Post
      description: Schema to create a single public or private file or directory
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 1024
        parentDirectory:
          type: string
          maxLength: 1024
        type:
          type: string
          enum:
          - file
          - directory
        fileSize:
          type: number
        contentType:
          type: string
          maxLength: 1024
        fileDimensions:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
          additionalProperties: false
      additionalProperties: false
      required:
      - name
      - type
    fileUploadPostResponse:
      title: File Upload Post Response
      description: Schema with the information needed to upload public or private file contents
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        applicationId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        creationDate:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        authorId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        authorType:
          type: string
          enum:
          - flow
          - user
          - device
          - apiToken
          - notebook
        status:
          type: string
          enum:
          - pending
          - moving
          - deleting
          - completed
        name:
          type: string
          minLength: 1
          maxLength: 1024
        parentDirectory:
          type: string
          maxLength: 1024
        type:
          type: string
          enum:
          - file
          - directory
        fileSize:
          type: number
        s3etag:
          type: string
        contentType:
          type: string
          maxLength: 1024
        fileDimensions:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
        moveIntoId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        url:
          type: string
        upload:
          type: object
          properties:
            url:
              type: string
            fields:
              type: object
              patternProperties:
                ^.*$:
                  type: string
              properties:
                key:
                  type: string
                bucket:
                  type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-derived-from:
  format: bravado 1.0
  by: all/0-working/bravado-to-openapi.py (roadmap#799)
  note: 'every action keeps its own path: resource.path + action.path'