Unito Reports API

openapi: 3.2.0
info:
  title: Unito Embed Reports API
  version: 0.1.4
  description: 'Welcome to Unito Embed API documentation


    In order to be able to use that api, Unito must first create an embed entity for you and give you its api key.'
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'
      operationId: getEmbedsByEmbedIdReportsByReportType
      x-operation-id-source: derived
components:
  responses:
    '429':
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error
      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'
    '401':
      description: 'Unauthorized: API key is missing or invalid'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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
    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
    ReportType:
      description: What are the available report types an embed can query for ?
      type: string
      enum:
      - flows-usage
      - workspaces-usage
    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
    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
    PaginatedResult:
      description: A paginated result
      type: object
      properties:
        total:
          type: number
        pageSize:
          type: number
        hasNextPage:
          type: boolean
  parameters:
    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
    ReportTypeParam:
      in: path
      name: reportType
      description: The identifier of the embed
      required: true
      schema:
        $ref: '#/components/schemas/ReportType'
    EmbedIdParam:
      in: path
      name: embedId
      description: The identifier of the embed
      required: true
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key