Unito Reports API

openapi: 3.0.3
info:
  title: Unito Embed Reports API
  version: 0.1.4
  description: '<h2>Welcome to Unito Embed API documentation</h2> <p>In order to be able to use that api, Unito must first create an embed entity for you and give you its api key. <br>Once you have access to an embed, there are 2 main resources for  you to interact with </p> <p> <b>Workspaces - </b> Allow you to give us information about the entity (workspaces, organization, group, ... ) that the user accessing the embed belongs to. <br> Its unique identifier <i>externalWorkspaceId</i> is the value that you pass in the iframe URL. <br> The information provided regarding the status of that entity will allow us to keep up to date the status of the Unito''s workspace subscription. </p>

    <p> <b>Reports - </b> You can select froma list of pre-made reports that our data team has been building in order to help you better understand how your users benefit from Unito, how many flows did they create, with which other tools did they connect and how big is their usage (changes synced, items in sync, ... ) </p>'
servers:
- url: http://localhost:9080
  description: local
- url: https://staging-api.unito.io
  description: staging
- url: https://api.unito.io
  description: production
  variables:
    embedId:
      default: wrike
security:
- ApiKeyAuth: []
tags:
- name: Reports
paths:
  /embeds/{embedId}/reports/{reportType}:
    get:
      summary: Get a full usage report on your flows
      x-eov-operation-id: show
      x-eov-operation-handler: reports
      description: 'Return a complete usage report for each individual flow created within all workspaces of your embed.

        Workspaces with a status of "disabled" are excluded.

        Data is refreshed every few hours, at most every 24h.

        '
      tags:
      - Reports
      parameters:
      - $ref: '#/components/parameters/PaginationParam'
      - $ref: '#/components/parameters/EmbedIdParam'
      - $ref: '#/components/parameters/ReportTypeParam'
      responses:
        '200':
          $ref: '#/components/responses/Report'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    ReportType:
      description: What are the available report types an embed can query for ?
      type: string
      enum:
      - flows-usage
      - workspaces-usage
    WorkspaceUsage:
      type: object
      required:
      - updatedAt
      - externalWorkspaceId
      - workspaceId
      - workspaceCreatedAt
      - itemsKeptInSyncCount
      - changesSyncedLast30d
      - daysWithChangesSyncedLast30d
      - tools
      - flowsCount
      - activeFlowsCount
      - flowsEverCreatedCount
      - toolPairStats
      properties:
        updatedAt:
          description: The timestamp at which this report record was last updated.
          type: string
          format: date-time
        externalWorkspaceId:
          type: string
        workspaceId:
          type: string
        workspaceCreatedAt:
          type: string
          format: date-time
        itemsKeptInSyncCount:
          description: The number of items (tasks, issues, card, deal, etc) that are being kept in sync by Unito. If any of those items change, and there's an active flow monitoring them, then Unito will sync the change over.
          type: integer
        changesSyncedLast30d:
          description: How many changes were detected and synced across in the last 30 days.
          type: integer
        daysWithChangesSyncedLast30D:
          description: How many of the last 30 days had sync activity.
          type: integer
        tools:
          description: The list of unique tools used across current flows. Note that some tools have mutiple variants, like "jiracloud" and "jira" with the second representing the on-premise server version of jira.
          type: array
          items:
            type: string
          example:
          - ToolX
          - ToolY
          - ToolZ
        flowsCount:
          description: A flow is a sync configuration between 2 tools.
          type: number
        activeFlowsCount:
          description: A flow is a sync configuration between 2 tools. A flow is active whenever it has access to tools and is monitoring for changes. A flow may be active but have not detected or synced any changes in a while. It will still scan for them, possibly indefinitely.
          type: number
        flowsEverCreatedCount:
          description: A flow is a sync configuration between 2 tools. This count returns how many flows were created at any point, including those later deleted.
          type: number
        toolPairsStats:
          type: object
          additionalProperties:
            type: object
            required:
            - activeFlowsCount
            - changesSyncedLast30d
            - flowsCount
            - flowsEverCreatedCount
            properties:
              activeFlowsCount:
                type: number
              changesSyncedLast30d:
                type: number
              flowsCount:
                type: number
              flowsEverCreatedCount:
                type: number
          example:
            ToolX-ToolY:
              activeFlowsCount: 0
              changesSyncedLast30d: 0
              flowsCount: 0
              flowsEverCreatedCount: 0
            ToolX-ToolZ:
              activeFlowsCount: 0
              changesSyncedLast30d: 0
              flowsCount: 0
              flowsEverCreatedCount: 0
    FlowUsage:
      type: object
      required:
      - updatedAt
      - flowId
      - flowCreatedAt
      - externalWorkspaceId
      - workspaceId
      - workspaceCreatedAt
      - isActive
      - mappedFieldsCount
      - changesSyncedLast30d
      - daysWithChangesSyncedLast30d
      - tools
      properties:
        updatedAt:
          description: The timestamp at which this report record was last updated.
          type: string
          format: date-time
        flowId:
          type: string
        flowCreatedAt:
          type: string
          format: date-time
        externalWorkspaceId:
          type: string
        workspaceId:
          type: string
        workspaceCreatedAt:
          type: string
          format: date-time
        isActive:
          description: Active flows CAN sync changes. It might or might not have done so recently. A flow becomes inactive when deleted by a user or when an issue prevents it from syncing (such as loosing access to a tool).
          type: boolean
        mappedFieldsCount:
          description: How many data fields are mapped to sync between the two tools.
          type: integer
        changesSyncedLast30d:
          description: How many changes were detected and synced across in the last 30 days.
          type: integer
        daysWithChangesSyncedLast30D:
          description: How many of the last 30 days had sync activity.
          type: integer
        tools:
          description: An array of always exactly 2 items, one per tool in the flow configuration. Order is undefined.
          type: array
          minItems: 2
          maxItems: 2
          items:
            $ref: '#/components/schemas/ToolInFlow'
          example:
          - name: ToolX
            itemType: Task
            externalContainerId: string
            canCreateItems: true
            canUpdateItems: true
          - name: ToolY
            itemType: Issue
            externalContainerId: string
            canCreateItems: false
            canUpdateItems: false
    ToolInFlow:
      type: object
      required:
      - externalContainerId
      - canCreateItems
      - canUpdateItems
      properties:
        name:
          type: string
        itemType:
          type: string
          description: What kind of item is being synced. E.g. a task, card, contact, opportunity, row, etc.
        externalContainerId:
          type: string
        canCreateItems:
          type: boolean
          description: whether the flow can create new items of itemType in externalContainerId
        canUpdateItems:
          type: boolean
          description: whether the flow can update existing items of itemType in externalContainerId
    Error:
      description: An error is returned from the API when a request fails to execute.
      type: object
      required:
      - message
      properties:
        message:
          description: The message of the error.
          type: string
        details:
          description: The details of the error.
          type: object
          additionalProperties: true
    PaginatedResult:
      description: A paginated result
      type: object
      properties:
        total:
          type: number
        pageSize:
          type: number
        hasNextPage:
          type: boolean
  responses:
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Report:
      description: 'The usage report for either: - all workspaces created from your embed. - each individual flow created within all workspaces of your embed'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/PaginatedResult'
            - description: A lisf of reports on flows.
              type: object
              required:
              - data
              properties:
                data:
                  description: The reports.
                  type: array
                  items:
                    anyOf:
                    - $ref: '#/components/schemas/WorkspaceUsage'
                    - $ref: '#/components/schemas/FlowUsage'
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: 'Unauthorized: API key is missing or invalid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    EmbedIdParam:
      in: path
      name: embedId
      description: The identifier of the embed
      required: true
      schema:
        type: string
    ReportTypeParam:
      in: path
      name: reportType
      description: The identifier of the embed
      required: true
      schema:
        $ref: '#/components/schemas/ReportType'
    PaginationParam:
      in: query
      name: pagination
      description: Details to paginate the results.
      required: false
      schema:
        type: object
        additionalProperties: false
        properties:
          offset:
            type: integer
            description: Number of 'first results' to skip
            default: 0
            minimum: 0
            maximum: 1000000000
          limit:
            type: integer
            description: Maximum number of results after the offset
            default: 1000
            minimum: 0
            maximum: 10000
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key