Sonetel Filemgr API

openapi: 3.2.0
info:
  title: Sonetel Filemgr API
  version: 1.0.0
  contact:
    name: Sonetel API Support
    url: https://sonetel.com/en/developer/help/
    email: api.support@sonetel.com
  termsOfService: https://sonetel.com/en/help/help-topics/terms-conditions/terms-conditions/
  description: 'Operations tagged Filemgr across 2 of this provider''s published API definitions: 15_ai_filemanager.yaml, sonetel-ai-file-manager-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public-api.sonetel.com
  description: Production
security:
- {}
tags:
- name: Filemgr
paths:
  /filemgr/upload:
    post:
      summary: Upload file
      description: 'Upload a single file.


        Some file meta data is automatically inferred and set from the uploaded file, such as file size.


        Specify file name with extension (e.g. `my-file.jpg`)and optionally description which gets set in the meta data including the extension.


        Maximum file size supported via this method is 10MB.


        To upload files larger than 10MB use the /filemgr/upload-url endpoint to get a URL where larger files can be uploaded.'
      operationId: post-filemgr-upload
      requestBody:
        $ref: '#/components/requestBodies/post-upload'
      responses:
        '200':
          $ref: '#/components/responses/FileWithId'
        '413':
          description: Payload Too Large
        '415':
          description: Unsupported Media Type. The server does not support the content-type of the uploaded file.
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /filemgr/upload-url:
    post:
      summary: Create upload URLs
      description: 'Get a list of URLs to upload one or more files. Use this method to upload file(s) more than 10MB.

        A file Id and upload URL is created for each file and returned in the response.'
      operationId: post-filemgr-upload-url
      requestBody:
        $ref: '#/components/requestBodies/post-upload-url'
      responses:
        '200':
          $ref: '#/components/responses/post-upload-url-rsp'
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /filemgr/upload-url/complete:
    post:
      summary: Complete multi-part upload
      description: 'Complete a multi-part upload by submitting details of the parts uploaded

        This endpoint must be called only in case of multi-part uploads.'
      operationId: post-filemgr-upload-url-complete
      requestBody:
        $ref: '#/components/requestBodies/post-upload-complete'
      responses:
        '200':
          $ref: '#/components/responses/FileWithId'
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /filemgr/file/{file_id}:
    get:
      summary: Fetch file content
      description: 'Fetch file content.

        File content is returned in response body. You also get limited file information in the `content-disposition` including name, type, size and storage

        To get file meta data, use `GET /filemgr/file/{file_id}/meta-data endpoint`'
      operationId: get-filemgr-file_id
      parameters:
      - name: file_id
        in: path
        description: The file Id of the file
        required: true
        schema:
          type: string
          examples:
          - 5ykju4
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                contentMediaType: application/octet-stream
          headers:
            Content-Disposition:
              schema:
                type: string
                example: '"name":"my-file.mp4","type":"uploaded","storage":"file-mgr"'
              description: Basic file meta data including name, type and storage
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    delete:
      summary: Delete a file
      description: Delete a file based on `file_id`
      operationId: delete-filemgr-file-file_id
      parameters:
      - name: service
        in: query
        description: 'Optional service '
        schema:
          type: string
      - name: file_id
        in: path
        description: The file Id of the file
        required: true
        schema:
          type: string
          examples:
          - 5ykju4
      responses:
        '200':
          description: OK
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      x-internal: true
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /filemgr/file/{file_id}/meta-data:
    get:
      summary: Fetch file meta data
      description: 'Fetch meta data of a file based on `file_id`.


        You may optionally specify what fields are returned. `file_id`, `name`, `type` and `size` are returned by default'
      operationId: get-filemgr-file-file_id-meta-data
      parameters:
      - name: fields
        in: query
        description: List of fields that should be returned. Specify all if all fields are required. `file_id`, `name`, `type`, `size` are always returned. `all` returns all fields. `temp_url` returns a temporary URl where file can be accessed. `account` returns `account_id`, `user_id` and `business_id`. `in_use_with` returns details about services files is in use with
        schema:
          type: string
          enum:
          - all
          - temp_url
          - account
          - in_use_with
      - name: file_id
        in: path
        description: The file Id of the file
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/FileWithId'
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    put:
      summary: Update file meta data
      description: Update meta-data and settings related to service usage for a file
      operationId: put-filemgr-file-file_id-meta-data
      parameters:
      - name: file_id
        in: path
        description: The file Id of the file
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/put-file-meta-data'
      responses:
        '200':
          $ref: '#/components/responses/FileWithId'
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /filemgr/file:
    get:
      summary: List files
      description: List files based on search criteria. A list of files with meta-data is returned
      operationId: get-filemgr-file
      parameters:
      - name: type
        in: query
        description: List files of this type
        schema:
          type: string
          enum:
          - audio
          - video
          - image
          - text
          - other
          examples:
          - audio
        examples:
          default:
            value: audio
      - name: create_date
        in: query
        description: List files based on file's creation date. Use `gte` or `lte` prefix to specify greater than or less than.
        schema:
          type: string
          examples:
          - create_date__gte'2019-08-24T14:15:22Z'
      - name: modify_date
        in: query
        description: List files based on modification date of the file meta-data. Use `gte` or `lte` prefix to specify greater than or less than.
        schema:
          type: string
          examples:
          - modify_date__gte'2019-08-24T14:15:22Z'
      - name: size
        in: query
        description: List files based on size of the file. Use `gt` or `lt` prefix to specify greater than or less than.
        schema:
          type: string
          examples:
          - size__gte1000
      - name: name
        in: query
        description: List files based on the file name. Use wildcard `*` to match any character(s).
        schema:
          type: string
          examples:
          - my_file*
        examples:
          default:
            value: my_file*
      - name: storage
        in: query
        description: List files based on the storage of the file
        schema:
          type: string
          enum:
          - file-mgr
          - sonetel-call-recording
          - sonetel-voicemail
          - google-drive
          - dropbox
          - one-drive
          examples:
          - google-drive
        examples:
          default:
            value: google-drive
      - name: extension
        in: query
        description: List files based on the file extension
        schema:
          type: string
          examples:
          - pdf
        examples:
          default:
            value: pdf
      - name: visibility
        in: query
        description: List files based on its visibility setting
        schema:
          type: string
          enum:
          - public
          - private
          examples:
          - public
        examples:
          default:
            value: public
      - name: user_id
        in: query
        description: List files based on Sonetel `user_id`
        schema:
          type: string
          examples:
          - Hn4ytr
      - name: business_id
        in: query
        description: List files based on Sonetel `business_id`
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileWithID'
      security:
      - Sonetel: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Filemgr
    servers:
    - url: https://public-api.sonetel.com
      description: Production
components:
  requestBodies:
    put-file-meta-data:
      description: File meta data to be updated
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                description: The file name with extension
                examples:
                - my-file.pdf
              description:
                type: string
                description: Textual description of the file
              visibility:
                type: string
                description: File visibility - `public` or `private`. `public` files are visible on the internet with a public URL
              in_use_with:
                $ref: '#/components/schemas/InUseWith'
    post-upload:
      description: File and meta data for upload
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              data:
                type: string
                description: The file content
                contentMediaType: application/octet-stream
              name:
                type: string
                description: The file name with extension
                examples:
                - my-file.pdf
              description:
                type: string
                description: Textual description of the file
              visibility:
                type: string
                enum:
                - public
                - private
                description: File visibility - `public` or `private`. `public` files are visible on the internet with a public URL
                default: private
                examples:
                - private
              account_id:
                type: string
                description: The Sonetel account Id that owns the file
                examples:
                - ty4653
              user_id:
                type: string
                description: The Sonetel user Id that owns the file
                examples:
                - H64yut
              business_id:
                type: string
                description: The Sonetel business Id to which the file is associated
                examples:
                - rhY4563
    post-upload-complete:
      description: Upload complete request with upload Id and parts information for multi-part upload
      content:
        application/json:
          schema:
            type: object
            properties:
              upload_id:
                type: string
                description: 'The upload Id of the multi-part upload received while creating multi-part upload URLs '
                examples:
                - thy3tyi
              parts:
                type: array
                description: The list of parts uploaded and their details.
                items:
                  type: object
                  properties:
                    part_number:
                      type: integer
                      description: Part number of the uploaded part associated with the corresponding etag.
                      format: int32
                      examples:
                      - 3
                    etag:
                      type: string
                      description: Entity tag that identifies the newly created object's data. Entity tag is returned when you upload a specific part
                  required:
                  - part_number
                  - etag
              file_id:
                type: string
                description: The unique file Id of the uploaded file
            required:
            - upload_id
            - parts
            - file_id
    post-upload-url:
      description: Request to create File Ids and URLs
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
                description: The number of upload URLs required. Maxium of 10 URLs can be requested in a single request
                minimum: 1
                maximum: 10
              visibility:
                type: string
                enum:
                - public
                - private
                description: The file visibility for the files being uploaded. Can be `public` or `private`. Public files are available on the internet via their public URL
                default: private
                examples:
                - public
              account_id:
                type: string
                description: The Sonetel account Id that owns the file
                examples:
                - ty4653
              user_id:
                type: string
                description: The Sonetel user Id that owns the file
                examples:
                - H64yut
              business_id:
                type: string
                description: The Sonetel business Id to which the file is associated
                examples:
                - rhY4563
              meta_data:
                type: array
                description: List of optional meta-data. The items in the array must match the `count` of URLs requested
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: File name
                    multi_parts:
                      type: integer
                      description: 'The number of parts that the file would be uploaded in

                        If this isn''t specified, a single upload URL for the file is returned

                        If this is specified with any number greater than 1, a list of multi-part upload URLs is specified along with an upload Id.

                        If multiple parts are uploaded, the [upload-url/complete](reference/15_ai_filemanager.yaml/components/requestBodies/post-upload-complete) endpoint must be called after uploading all parts'
                      format: int32
                      minimum: 1
                      default: 1
                      examples:
                      - 3
            required:
            - count
  schemas:
    AudioMetaData:
      type: object
      title: AudioMetaData
      description: Meta data for audio files
      properties:
        duration:
          type: integer
          description: The audio length in seconds
          format: int32
          examples:
          - 32
        codec:
          type: string
          description: The [audio codec](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) used
          examples:
          - pcma
        bitrate:
          type: integer
          description: The audio bitrate in kbps
          examples:
          - 128
        sampling_rate:
          enum:
          - 44.1
          - 48
          - 22.05
          - 32
          - 88.2
          - 96
          description: Sampling rate of the audio
          examples:
          - 48
    FileWithID:
      type: object
      description: File meta data
      properties:
        file_id:
          type: string
          description: The unique ID of the file
          readOnly: true
        name:
          type: string
          description: The file name with extension
          examples:
          - my-file.txt
        type:
          type: string
          enum:
          - audio
          - video
          - image
          - text
          - other
          description: The type of file - audio, video, image, text or other. The file type is automatically detected during upload by the file manager
          readOnly: true
        size:
          type: integer
          description: The size of the file in bytes
          format: int64
          readOnly: true
          examples:
          - 7565
        storage:
          type: string
          enum:
          - file-mgr
          - sonetel-call-recording
          - sonetel-voicemail
          - google-drive
          - one-drive
          - dropbox
          description: The storage type of the file. A file may be stored in storage managed by file manager, or storage managed by other services such as Sonetel's call recording, or external cloud storage services such as Google or Microsoft one-drive or dropbox.
          readOnly: true
          examples:
          - file-mgr
        extension:
          type: string
          description: The file name extension such as `jpg`, `mp4` etc.
          readOnly: true
        mime_type:
          type: string
          description: The [standard IANA mime type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the file
          readOnly: true
        public_url:
          type: string
          description: The public URL of the file for files that have visibility set to `public`
          format: uri-reference
          readOnly: true
        description:
          type: string
          description: Textual description of the file
        create_date:
          type: string
          description: The create date/time of the file
          format: date-time
          readOnly: true
        modify_date:
          type: string
          description: The last modified date of the file meta data. File content cannot be modified
          format: date-time
          readOnly: true
        visibility:
          type: string
        image_meta_data:
          $ref: '#/components/schemas/ImageMetaData'
          description: Image specific meta data for image files
        video_meta_data:
          $ref: '#/components/schemas/VideoMetaData'
          description: Video specific meta data for video files
        audio_meta_data:
          $ref: '#/components/schemas/AudioMetaData'
          description: Audio specific meta data for audio files
        account_id:
          type: string
          description: The Sonetel account Id that owns the file
          readOnly: true
          examples:
          - ty4653
        user_id:
          type: string
          description: The Sonetel user Id that owns the file
          readOnly: true
          examples:
          - H64yut
        business_id:
          type: string
          description: The Sonetel business Id to which the file is associated
          examples:
          - rhY4563
        in_use_with:
          $ref: '#/components/schemas/InUseWith'
          description: List of services the file is in use with and expiry timestamp for each
        temp_url:
          type: string
          description: A secure temporary URL that expires in 180 seconds.
          format: uri
          examples:
          - https://files.sonetel.com/yh4yth208656Hn5uj3876ki3jj2j
        created_by:
          type: string
          enum:
          - ai-meeting-mins
          - user
          - ai-photo-finder
          - sonetel-call-recording
          description: 'The service that created this file. In case a user has created this, this value is set to `user` and the `user_id` field carries the `user_id `of the user that created this '
          examples:
          - user
        store_obj_id:
          type: string
          description: Reference Id of the file in the object storage
    VideoMetaData:
      type: object
      title: VideoMetaData
      description: Meta data for video files
      properties:
        duration:
          type: integer
          description: The length in seconds of the video file
          examples:
          - 32
        codec:
          type: string
          description: The [video codec](https://www.iana.org/assignments/media-types/media-types.xhtml#video) used
        resolution:
          type: string
          enum:
          - 480p
          - 576p
          - 720p
          - 1080p
          - 1440p
          - 4K
          - 8K
          description: The video resolution
        bitrate:
          type: integer
          description: The video bitrate in kbps
          format: int32
          examples:
          - 8000
        frame_rate:
          type: integer
          description: The frame rate in frames per second (fps)
          format: int32
          examples:
          - 60
        audio_codec:
          type: string
          description: The [audio code](https://www.iana.org/assignments/media-types/media-types.xhtml#audio) used
          examples:
          - pcma
        audio_channels:
          type: integer
          description: The number of audio channels in the video
          format: int32
        language:
          type: string
          description: The language of the audio. [2 char ISO](https://en.wikipedia.org/wiki/ISO_639-1) or [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag)
          examples:
          - en
    ImageMetaData:
      type: object
      title: ImageMetaData
      description: Meta data for image files
      properties:
        resolution:
          type: string
          description: The image resolution
          format: regex
          pattern: ^\d{3,4}x\d{3,4}$
          examples:
          - 1920x1080
        color_space:
          type: string
          description: The color space of the image such as `RGB` or `CMYK`
          examples:
          - RGB
        image_format:
          type: string
          enum:
          - jpg
          - png
          - gif
          - bmp
          - tiff
          - svg
          description: The image format such as `jpg`, `png`
          examples:
          - jpg
        bit_depth:
          type: integer
          description: The bit depth of the image
          format: int32
          examples:
          - 32
    InUseWith:
      type: array
      title: InUseWith
      description: Information about services file is in use with
      items:
        type: object
        properties:
          service:
            type: string
            enum:
            - ai-meeting-minutes
            - ai-call-summary
            - ai-vmail-summary
            description: The service the file is in use with
            examples:
            - ai-meeting-minutes
          auto_expire:
            type: string
            description: 'Automatic expiry timestamp when the file is no longer required by the service

              An empty value implies that the file is never automatically deleted'
            format: date-time
  responses:
    FileWithId:
      description: File meta data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FileWithID'
    post-upload-url-rsp:
      description: List of file Ids and upload URLs
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                file_id:
                  type: string
                  description: The file Id of the file to be uploaded
                upload_url:
                  type: string
                  description: The upload URL where the file should be uploaded. The URL is valid for 90 secs
                  format: uri-reference
                name:
                  type: string
                  description: The file name
                upload_id:
                  type: string
                  description: 'Unique upload Id used in the case of multi-part uploads.

                    For single file uploads, this field is not sent'
                  examples:
                  - thy3tyi
                upload_urls:
                  type: array
                  description: 'A list of upload URLs where the file should be uploaded.

                    Each URL is valid for 10 mins

                    A single URL is returned for a single part '
                  items:
                    type: string
                    format: uri
  securitySchemes:
    Sonetel:
      type: oauth2
      flows:
        password:
          refreshUrl: https://api.sonetel.com/SonetelAuth/beta
          tokenUrl: https://api.sonetel.com/SonetelAuth/beta
          scopes: {}
x-refined-from:
- 15_ai_filemanager.yaml
- sonetel-ai-file-manager-openapi.yml