8x8 Objects API

openapi: 3.2.0
info:
  version: 3.1.6
  title: Cloud Storage Service Public Objects API
  contact:
    name: Recordings Team
    email: ro-rec@8x8.com
  termsOfService: https://www.8x8.com/terms-and-conditions
  description: '8x8’s Cloud Storage Service (CSS) offers you a single point of access for Virtual Office PBX telephone, Virtual Contact Center call recordings, Virtual Contact Center screen recordings and Virtual Meetings. You can access and download these data objects for your further analysis and use. You can also embed your data in other interfaces without a requirement to copy or move the underlying data.


    For example:

    * Make collected data available to customers in your client portal

    * Integrate call recording data into CRM applications to associate with customer interaction records

    * Enable deletion of media (and or metadata) to allow customers to meet internal requirements to cap data retention based on workflows, policies, or compliance needs


    You can obtain your stored data by either:

    * Querying for, and then downloading individual data objects

    * Bulk downloading all of your data using a Zip file utility (Note that the limit on bulk file downloads is 2 GB.)

    ***Note: This page is in the Beta stage. Contact your [8x8 representative](mailto:ro-rec@8x8.com) for more information on API use.***

    # **Authentication**

    You can try out this API through request authentication using your client credentials. Refer to [Client Credentials](/analytics/docs/how-to-get-api-keys) on the [Getting Started](/tech-partner/docs/getting-started) page for more information.


    All requests must be made over HTTPS - calls made over HTTP will fail.

    # **Regions**

    API resources are available for each geographical region in which they are provisioned. The base URLs for select regions are:

    <table> <tr> <td><b>URL</b></td> <td><b>Region</b></td> </tr> <tr> <td><b><a href=''https://api.8x8.com/storage/us-west/v1''>https://api.8x8.com/storage/us-west/v1</a></b></td><td>Western US</td></tr><tr> <td><b><a href=''https://api.8x8.com/storage/us-east/v1''>https://api.8x8.com/storage/us-east/v1</a></b></td><td>Eastern US</td></tr><tr> <td><b><a href=''https://api.8x8.com/storage/uk/v1''>https://api.8x8.com/storage/uk/v1</a></b></td><td>United Kingdom</td></tr><tr> <td><b><a href=''https://api.8x8.com/storage/ap/v1''>https://api.8x8.com/storage/ap/v1</a></b></td><td>Australia</td> </tr> <tr> <td><b><a href=''https://api.8x8.com/storage/ca/v1''>https://api.8x8.com/storage/ca/v1</a></b></td><td>Canada</td> </tr> </table>'
servers:
- url: https://api.8x8.com/storage/{region}/{apiversion}/
  description: The Storage API Gateway Endpoint
  variables:
    region:
      enum:
      - us-west
      - us-east
      - uk
      - ap
      - ca
      default: us-west
    apiversion:
      default: v3
security:
- bearerAuth: []
tags:
- name: Objects
  description: Manage objects
paths:
  /objects:
    get:
      x-publish-public: true
      description: "\n**Tagging**\nThe CSS API features a generic tagging methodology.  The tags  on each object are determined either systematically or by customer definition.  Systematic tags are generated by the underlying provider system.  \nThe following object types are supported:\n\n* **`callrecording`**\n* **`callcenterrecording`**\n* **`screenrecording`**\n* **`meeting`**\n\nThe tag types vary depending on the provider. \n**`callrecording`**\n\n   * **pbxname** The human readable name of the PBX system.\n   * **extensionId** The machine readable ID of the telephone extension which generated the object.\n   * **pbxId** The machine readable ID of the PBX system.\n   * **callId** The ID which describes the voice interaction.\n   * **direction** The direction of the interaction.\n   * **relativePath** The relative path of the object in storage.\n   * **callerId** The calling line ID generated by the telecom provider.\n   * **startTime** The date/time stamp when the voice interaction was established.\n   * **duration** The duration of the voice interaction in milliseconds.\n   * **extensionNumber** The human readable PBX extension number.\n   * **endTime** The date/time stamp when the voice interaction was terminated.\n\n**`callcenterrecording`**\n\n   * **direction** The direction of the interaction.\n   * **agentId** The agent identifier.\n   * **callId** The call identifier.\n   * **callSnippetId** The identification call for snippets.\n   * **callerId** The caller's phone number.\n   * **calleeId** The called phone number.\n   * **callerName** The caller name.\n   * **calleeName** The called name.\n   * **address** The called phone number.\n   * **queueNumber** The VCC queue number.\n   * **queueName** The VCC queue name.\n   * **channelName** The VCC channel name.\n   * **transactionId** VCC transaction identifier.\n   * **holdDuration** The hold duration.\n   * **billingTelephoneNumber** The phone number used for billing (internal use).\n   * **startTime** The interaction start time.\n   * **duration** The duration of the voice interaction in seconds.\n   * **ipbxid** The PBX name.\n   * **agentName** The agent name.\n   * **tenantId** The tenant identifier.\n   * **extensionNumber** The agent extension number (e.g., 1000).\n   * **mediaUrl** The NFS file name (internal use).\n   * **branchId** The branch (site) identifier.\n\n**`screenrecording`**\n   * **agentId** The agent identifier.\n   * **callId** The call identifier.\n   * **startTime** The call start time.\n   * **tenantId** The tenant identifier.\n   * **transactionId** The VCC transaction identifier.\n\n**`meeting`**\n\n   * **duration** The duration of the meeting in milliseconds.\n   * **meetingUrl** The URL which was used for the meeting.\n   * **sessionId** The unique machine readable session ID of the meeting."
      tags:
      - Objects
      summary: The list of all objects that meet the filter rule criteria.
      operationId: searchobject
      parameters:
      - name: Content-Type
        in: header
        description: This parameter indicates the type of content.  Currently only `application/json` is supported.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: application/json
      - name: filter
        in: query
        description: '

          This API is designed with filtering capabilities using Feed Item Query Language (FIQL) filter expressions. <br> FIQL introduces simple and composite operators which can be used to build basic and complex queries. <br> If the *filter* is not specified, all objects are returned.

          The following are basic FIQL operators:

          * **`==`** - Equal to

          * **`!=`** - Not equal to

          * **`=gt=`** - Greater than

          * **`=ge=`** - Greater or equal to

          * **`=lt=`** - Less than

          * **`=le=`** - Less or equal to

          These six operators can be used to different types of simple queries. For example:

          * **`name==MyRecording**` - Finds all items with name **`MyRecording`**

          * **`type!=callrecording`** - Finds all items which are not **`callrecording`**

          * **`size=gt=1024`** - Finds all items with size bigger than 1024

          * **`size=le=1024`** - Finds all items with size smaller or equal with 1024

          FIQL joining operators consist of the following:

          * **`;`** = AND

          * **`,`** = OR

          These two operators can be used to join simple queries and build more complex queries. For example:

          * **`name==MyRecording,name==YourRecording`** - Find all items with name **`MyRecording`** or with name **`YourRecording`**

          * **`type==callrecording;size=gt=1024`** - Find all **`callrecording`** items with size greather than 1024

          * **`type==callrecording;(name==MyRecording,name==YourRecording)`** - Find all **`callrecording`** items with name **`MyRecording`** or with name **`YourRecording`**

          '
        style: form
        explode: true
        schema:
          type: string
          example: type!=callrecording
      - name: pageKey
        in: query
        description: This parameter indicates the page number to begin your query.
        style: form
        explode: true
        schema:
          type: number
          format: integer
          example: 1
      - name: limit
        in: query
        description: This parameter indicates the page size to begin your query with.  A value between 1 and 100 is supported.
        style: form
        explode: true
        schema:
          type: number
          format: integer
          example: 10
      - name: sortField
        in: query
        description: The field used for sorting. Content and Tag fields are supported.
        style: form
        explode: true
        schema:
          type: string
          example: objectId
      - name: sortDirection
        in: query
        description: This field describes the sorting direction. Sorting can be specified as 'ASC' for ascending or 'DESC' for descending.
        style: form
        explode: true
        schema:
          type: string
          example: DESC
      responses:
        '200':
          description: Returns the filtered or unfiltered list of object metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResponsePage'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '405':
          $ref: '#/components/responses/methodNotAllowed'
        default:
          $ref: '#/components/responses/internalServerError'
      deprecated: false
  /objects/{objectId}:
    get:
      x-publish-public: true
      description: Use this method to retrieve an object by its ID.
      tags:
      - Objects
      summary: Find an object by it's ID.
      operationId: getobject
      parameters:
      - name: objectId
        in: path
        description: Use this parameter to specify the object ID to return.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the requested object record details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '405':
          $ref: '#/components/responses/methodNotAllowed'
        default:
          $ref: '#/components/responses/internalServerError'
      deprecated: false
  /objects/{objectId}/metadata:
    get:
      x-publish-public: true
      description: This method retrieves an object using the objectId specification for a given record.
      tags:
      - Objects
      summary: Download content for the given metadata.
      operationId: downloadmetadata
      parameters:
      - name: objectId
        in: path
        description: This parameter obtains the ID for the returned object.
        required: true
        schema:
          type: string
          example: FKC4RF6OXNMGGUW4LIFSWVLEIVJ54JBTVAD3SQYKNFK2ATUQCMAA----
      responses:
        '200':
          description: Returns the requested object record details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponse'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '405':
          $ref: '#/components/responses/methodNotAllowed'
        default:
          $ref: '#/components/responses/internalServerError'
      deprecated: false
  /objects/{objectId}/content:
    get:
      x-publish-public: true
      description: This method retrieves an object using the **`objectId`** specification for a given record.
      tags:
      - Objects
      summary: Download content for the given metadata.
      operationId: downloadobject
      parameters:
      - name: objectId
        in: path
        description: This parameter obtains the ID for the returned object.
        required: true
        schema:
          type: string
          example: FKC4RF6OXNMGGUW4LIFSWVLEIVJ54JBTVAD3SQYKNFK2ATUQCMAA----
      - name: presignUrl
        in: query
        description: By specifying this parameter option, the object content which is associated with the metadata record is returned as a **`presignedUrl`** instead of a machine-readable ID.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The object stream download.
          content:
            application/json:
              schema:
                type: string
                format: byte
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '405':
          $ref: '#/components/responses/methodNotAllowed'
        default:
          $ref: '#/components/responses/internalServerError'
      deprecated: false
components:
  responses:
    internalServerError:
      description: An internal server error has occurred. Please contact your 8x8 support resource.
    forbidden:
      description: The authentication was successful, but the authenticated user does not have access to the resource.
    notFound:
      description: The requested resource was not found.
    unauthorized:
      description: 'Unauthorized: Invalid or no authentication details were provided.'
    methodNotAllowed:
      description: This method is not allowed or a validation exception has occurred.
    badRequest:
      description: The received request was malformed resulting in form validation errors.
  schemas:
    TagResponse:
      type: object
      description: Tags are either systematically generated or are user created. This allows for flexibility in creating filterable, descriptive labels.
      properties:
        id:
          type: string
          description: The tag identifier.
          example: '100'
        key:
          type: string
          description: A label which is either systematically assigned by the content creator or manually assigned by the CSS user.
          example: callerId
        value:
          type: string
          description: The key data value.
          example: '15615551212'
      title: Tag Response
    ObjectResponse:
      type: object
      description: The information associated with the stored object.
      properties:
        id:
          type: string
          description: The unique identifier of the object.
          example: 0ca4c747-6256-4023-a335-53a46449871a
        bucketId:
          type: string
          description: The unique 8x8 system generated bucket ID.
          example: 3314J06662K7SOEQD5
        customerId:
          type: string
          description: The unique 8x8 customer account identifier.
          example: 0012J00002K7SOFQA3
        userId:
          type: string
          description: The unique 8x8 system user identifier.
          example: b4ZRdTEnToOh6vRAq79U_g
        type:
          type: string
          description: The source system which created this object.
          enum:
          - callrecording
          - callcenterrecording
          - meeting
          example: callrecording
        mimeType:
          type: string
          description: The MIME (Multipurpose Internet Mail Extensions) type of the object content associated with this object.
          example: audio/mpeg
        objectName:
          type: string
          description: The filename of the associated object.
          example: ipbx:demo:callrecording:users:1000:1554901130738-1553527036518-x1000u1-15617142314_E.mp3
        objectState:
          type: string
          description: "\nThe current state of the object.  Only `AVAILABLE` objects can be downloaded.\n\n The following states are supported:\n \n | State     | Description                                                         |\n |-----------|---------------------------------------------------------------------|\n | PENDING   | The operation is pending.  Check back shortly for an updated state. |\n | AVAILABLE | The object is available and ready for use.                          |\n | REVOKED   | The object has been deleted.                                        |\n | DELETED   | The object has been purged from the system.                         |\n | FAILED    | Requested operation has failed.                                     |\n"
          enum:
          - PENDING
          - AVAILABLE
          - REVOKED
          - DELETED
          - FAILED
          example: AVAILABLE
        createdTime:
          type: string
          example: '2019-05-11T00:55:24'
          description: The ISO 8601 timestamp when this object record was created.
        updatedTime:
          type: string
          format: int64
          description: The UNIX time for when the object record was last updated.
          example: '2019-05-11T00:55:24'
        storedBytes:
          type: string
          description: The size of the data stored in bytes.
          example: 23661
        checksum:
          type: string
          description: The computed checksum value of the object.
          example: 3dda71c7a10536f6a59c17a4062163b6
        checksumType:
          type: string
          example: MD5
          description: This API uses MD5 checksum values to ensure data integrity.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagResponse'
      title: Object Response.
    ResponsePage:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ObjectResponse'
        lastPage:
          type: boolean
          description: This response indicates if this page is the last one in the set.
          example: true
        pageKey:
          type: integer
          format: int64
          description: This response indicates the page number of the current page in the set.
          example: 0
        pageSize:
          type: integer
          format: int64
          description: This response indicates the number of records per page. A value of 0 to 100 is supported.
          example: 100
        total:
          type: integer
          format: int64
          description: This response indicates the total number of available pages for the request.
          example: 100
      title: Response Page.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
x-readme:
  explorer-enabled: true
  proxy-enabled: true