openapi: 3.0.1
info:
  title: Reports
  description: >
    Usage, sharing, download, view, and login activity reports for Canto
    DAM content and tenants, tenant operation logs, top-data summaries, and
    a self-describing list of every API endpoint.
  version: 1.0.0
servers:
  - url: "https://{tenantSubdomain}.{region}/api/v1"
    variables:
      tenantSubdomain:
        default: demo
      region:
        default: canto.com
        enum:
          - canto.com
          - canto.global
          - canto.de
          - au.canto.com
          - ca.canto.com
security:
  - cantoOAuth2: []
  - bearerAuth: []
tags:
  - name: Reports
    description: Usage, activity, operation, and top-data reports.
paths:
  /usagehistory/{scheme}/{id}:
    get:
      tags:
        - Reports
      summary: Get specified content Usage History report
      operationId: get_v1_usagehistory_scheme_id
      description: >
        Returns the usage history report for a specific content item, the
        same detail shown on its asset detail page in the Canto UI. Paged
        via `marker`: leave it unset on the first call, then pass the
        `nextMarker` value from the previous response to get the next
        page. The absence of `nextMarker` in a response means there is no
        further page.
      parameters:
        - name: scheme
          in: path
          required: true
          schema:
            type: string
            enum: [image, video, audio, document, presentation, other]
        - name: id
          in: path
          required: true
          description: The content id.
          schema:
            type: string
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: marker
          in: query
          required: false
          description: Pagination marker from a previous response's nextMarker. Leave unset on the first call.
          schema:
            type: string
      responses:
        "200":
          description: A page of usage history events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/activity_report_page"
  /shareactivity/{scheme}/{id}:
    get:
      tags:
        - Reports
      summary: Get specified content Share Activity report
      operationId: get_v1_shareactivity_scheme_id
      description: >
        Returns the share activity report for a specific content item, the
        same detail shown on its asset detail page in the Canto UI. Paged
        the same way as Get specified content Usage History report.
      parameters:
        - name: scheme
          in: path
          required: true
          schema:
            type: string
            enum: [image, video, audio, document, presentation, other]
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: marker
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: A page of share activity events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/activity_report_page"
  /downloadactivity/{scheme}/{id}:
    get:
      tags:
        - Reports
      summary: Get specified content Download Activity report
      operationId: get_v1_downloadactivity_scheme_id
      description: >
        Returns the download activity report for a specific content item,
        the same detail shown on its asset detail page in the Canto UI.
        Paged the same way as Get specified content Usage History report.
        Also covers what is sometimes referred to as the "View Activity"
        report for a content item -- there is no separate View Activity
        endpoint; this report covers both.
      parameters:
        - name: scheme
          in: path
          required: true
          schema:
            type: string
            enum: [image, video, audio, document, presentation, other]
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: marker
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: A page of download activity events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/activity_report_page"
  /operationlogs:
    get:
      tags:
        - Reports
      summary: Get tenant operation Log data
      operationId: get_v1_operationlogs
      description: >
        Returns the tenant's operation log as CSV, for the given date
        range. Although `startDate`/`endDate` are optional, omitting both
        returns a 400 -- in practice, supply both.
      parameters:
        - name: startDate
          in: query
          required: false
          description: 'Format: yyyyMMdd. In practice required -- omitting both startDate and endDate returns a 400.'
          schema:
            type: string
            example: "20210101"
        - name: endDate
          in: query
          required: false
          description: 'Format: yyyyMMdd. In practice required -- omitting both startDate and endDate returns a 400.'
          schema:
            type: string
            example: "20210101"
      responses:
        "200":
          description: The operation log as CSV, with columns User, Operation, Location, Date, Content.
          content:
            text/csv:
              schema:
                type: string
              example: |
                User,Operation,Location,Date,Content
                Canto Support,Deleted File on Main Library,Main Library,2021-06-22 20:25,File.jpg(48.24KB)
        "400":
          description: Returned when neither startDate nor endDate is supplied.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              example:
                code: 2110
                message: Invalid input.
  /tenantreport/{type}:
    get:
      tags:
        - Reports
      summary: Get tenant history report
      operationId: get_v1_tenantreport_type
      description: >
        Returns one of five tenant-wide history reports, selected by
        `type`: `uploadhistory`/`downloadhistory` (upload or download
        activity across the tenant), `sharehistory` (link and email
        sharing activity), `share3rdpartyhistory` (sharing to social
        media/third-party channels), or `loginhistory` (user logins). The
        response shape differs per type, documented in the examples below.


        `loginhistory` may return a 500 under some conditions (see the
        500 response below) rather than the report data.


        For download entries: if the user was logged in, `email` holds
        their address and `location` holds the source (e.g. "Main
        Library"). For an anonymous download via a common share link,
        `email` holds the share link's 5-digit internal id and `location`
        holds the source. Via an album/folder share link, `email` is
        "anonymous" and `location` contains "Share Link:" plus an
        internal id longer than 8 digits. Via a public portal, `email` is
        "anonymous" and `location` contains "Portal:" plus the portal
        name.
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [uploadhistory, downloadhistory, sharehistory, share3rdpartyhistory, loginhistory]
        - name: from
          in: query
          required: false
          description: 'Report start time. Format: yyyyMMdd.'
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: 'Report end time. Format: yyyyMMdd.'
          schema:
            type: string
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: marker
          in: query
          required: false
          description: >
            Pagination marker. Not needed on the first request; pass the
            previous response's nextMarker to get the next page.
          schema:
            type: string
      responses:
        "200":
          description: The requested tenant history report.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
              examples:
                uploadhistory:
                  summary: type=uploadhistory
                  value:
                    results:
                      - action: Upload Content
                        email: support@canto.com
                        user: one one
                        time: "20210906155201"
                        location: "Workspace: new work"
                        content:
                          name: C02-19-1286.jpg
                          scheme: image
                          id: <content-id>
                        albumName: album name 1
                        applicationName: Canto Web App
                        locationName: new work
                        locationUrl: newwork
                        locationType: Workspace
                    nextMarker: <marker>
                    limit: 3
                    sortBy: time
                    sortDirection: descending
                downloadhistory:
                  summary: type=downloadhistory
                  value:
                    results:
                      - action: Download Content
                        email: support@canto.com
                        user: one one
                        time: "20211118004801"
                        location: "Workspace: new work"
                        content:
                          name: C02-19-1286.jpg
                          scheme: image
                          id: <content-id>
                        albumName: "album path 1, album path 2"
                        groups: group1
                        locationName: new work
                        locationUrl: newwork
                        locationType: Workspace
                    nextMarker: <marker>
                    limit: 2
                    sortBy: time
                    sortDirection: descending
                sharehistory:
                  summary: type=sharehistory
                  value:
                    results:
                      - action: Email Share
                        email: support@canto.com
                        user: one one
                        time: "20211101"
                        accessTime: "20211101"
                        expiresOn: "20211130"
                        shareContent: "File: C02-19-1286.jpg"
                        location: "Main library"
                        sharedTo: someone@example.com
                        description: share message
                        shareName: share name
                        size: 1
                        url: "https://demo.canto.com/s/<share-id>"
                        locationName: Main library
                    nextMarker: <marker>
                    limit: 2
                    sortBy: time
                    sortDirection: descending
                share3rdpartyhistory:
                  summary: type=share3rdpartyhistory
                  value:
                    results:
                      - action: 3rd Party Share
                        email: support@canto.com
                        user: Canto Support
                        time: "20211101"
                        content:
                          - name: sample.mp4
                            scheme: video
                            id: <content-id>
                        location: "Main library"
                        sharedTo: Dropbox
                        description: share message
                        locationName: Main library
                    nextMarker: <marker>
                    limit: 2
                    sortBy: time
                    sortDirection: descending
                loginhistory:
                  summary: type=loginhistory
                  value:
                    results:
                      - userId: support@canto.com
                        loginTime: "20211031202901"
                        logoutTime: "20211108013602"
                        clientType: Windows Chrome
                        location: newwork
                        locationName: new work
                        locationUrl: newwork
                        locationType: Workspace
                    nextMarker: <marker>
        "500":
          description: An unexpected server error, seen for `type=loginhistory`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              example:
                code: 3000
                message: Sorry, we ran into an unknown issue. Please send us a screenshot of this screen to https://support.canto.com.
  /top/{type}:
    get:
      tags:
        - Reports
      summary: Get the top data of the specified type
      operationId: get_v1_top_type
      description: >
        Returns the top values for a given data type, ranked by frequency.
        If `type` is empty, all types are queried; if `location` is empty,
        all locations are queried; if `limit` is empty, all matching data
        is returned.
      parameters:
        - name: type
          in: path
          required: true
          description: keyword, tag, smart_tag, or commentedFiles. Empty queries all types.
          schema:
            type: string
            enum: [keyword, tag, smart_tag, commentedFiles]
        - name: location
          in: query
          required: false
          description: portal, workspace, styleGuide, or uploadLink. Empty queries all locations.
          schema:
            type: string
            enum: [portal, workspace, styleGuide, uploadLink]
        - name: limit
          in: query
          required: false
          description: Maximum number of top values to return. Empty returns all.
          schema:
            type: integer
      responses:
        "200":
          description: The top values for the requested type(s), as a map of value to count.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  oneOf:
                    - type: integer
                    - type: string
              examples:
                topKeyword:
                  summary: type=keyword
                  value:
                    Unkeyworded: 45
                    Landmark: 10
                    Capital: 10
                topTag:
                  summary: type=tag
                  value:
                    Untagged: 41
                    cool: 6
                    beach: 3
                topCommentedFiles:
                  summary: type=commentedFiles
                  value:
                    file.jpg: "1"
                    image.jpg: "1"
  /tenantreport/assetview:
    get:
      tags:
        - Reports
      summary: Get asset preview reports
      operationId: get_v1_tenantreport_assetview
      description: Returns a report of asset preview events across the tenant, for the given date range.
      parameters:
        - name: from
          in: query
          required: false
          description: 'Format: yyyyMMdd.'
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: 'Format: yyyyMMdd.'
          schema:
            type: string
        - name: scheme
          in: query
          required: false
          description: File type. Empty queries all schemes.
          schema:
            type: string
            enum: [image, video, audio, document, presentation, other]
        - name: user
          in: query
          required: false
          description: 'User email. @ must be URL-encoded as %40. Empty queries all users.'
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum: [ascending, descending]
            default: descending
        - name: lastKey
          in: query
          required: false
          description: >
            Pagination marker. Not needed on the first request; pass the
            previous response's nextMarker to get the next page.
          schema:
            type: string
      responses:
        "200":
          description: A page of asset preview events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/asset_preview_report_page"
  /:
    get:
      tags:
        - Reports
      summary: List all API endpoints
      operationId: get_v1
      description: >
        Returns every API endpoint as a machine-readable URI template, with
        its method, description, parameters, exceptions, and a sample
        result.
      security: []
      responses:
        "200":
          description: Every documented endpoint, as URI templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/endpoint_descriptor"
              example:
                - path: /api/v1/user
                  method: GET
                  description: get user info
                  parameters: []
                  exceptions: []
                  return:
                    type: user
                    description: user info
                    sampleResult:
                      userId: someone@example.com
                      firstName: first name
                      lastName: last name
components:
  securitySchemes:
    cantoOAuth2:
      type: oauth2
      description: >
        Authorize against your own Canto account. Choose the tenant and its
        region in the portal first; the portal fills in the application
        identifier for that region and pre-fills your account name on
        Canto's sign-in page. This is a public-client PKCE flow: no client
        secret is used, and none is held by the portal.
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.canto.com/oauth/api/oauth2/universal2/authorize
          tokenUrl: https://oauth.canto.com/oauth/api/oauth2/universal2/token
          scopes: {}
          x-usePkce: plain
          x-tokenName: accessToken
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AccessToken
      description: >
        Paste a Target-API OAuth Token obtained out-of-band. Use the
        Authorize button instead to obtain one interactively.
  schemas:
    error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    activity_event:
      type: object
      properties:
        actionName:
          type: string
        email:
          type: string
        user:
          type: string
        actionTime:
          type: string
    activity_report_page:
      type: object
      properties:
        limit:
          type: integer
        sortBy:
          type: string
        sortDirection:
          type: string
        nextMarker:
          type: string
          description: Present when a further page is available.
        results:
          type: array
          items:
            $ref: "#/components/schemas/activity_event"
    asset_preview_event:
      type: object
      properties:
        time:
          type: string
        action:
          type: string
          enum: [PREVIEW]
        email:
          type: string
        user:
          type: string
        location:
          type: string
        locationType:
          type: string
        locationUrl:
          type: string
          nullable: true
        locationName:
          type: string
          nullable: true
        content:
          type: object
          properties:
            scheme:
              type: string
            id:
              type: string
            Name:
              type: string
    asset_preview_report_page:
      type: object
      properties:
        nextMarker:
          type: string
        sortDirection:
          type: string
        limit:
          type: integer
        sortBy:
          type: string
        results:
          type: array
          items:
            $ref: "#/components/schemas/asset_preview_event"
    endpoint_descriptor:
      type: object
      properties:
        path:
          type: string
        method:
          type: string
        description:
          type: string
        parameters:
          type: array
          items: {}
        exceptions:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              description:
                type: string
        return:
          type: object
          properties:
            type:
              type: string
            description:
              type: string
            sampleResult:
              type: object
              additionalProperties: true