openapi: 3.0.1
info:
  title: Tend
  description: Ask questions about your website visitors
  version: 'v1'
servers:
  - url: https://tend.io
paths:
  /api/v1/visits:
    get:
      operationId: getVisits
      summary: Get the website visits for both identified and anonymous contacts
      parameters:
        - in: query
          name: contact
          schema:
            type: string
          description: The contact name or email associated with the visits
        - in: query
          name: pathname
          schema:
            type: string
            format: string
          description: The pathname or url of the visit
        - in: query
          name: referrer
          schema:
            type: string
            format: string
          description: The HTTP referrer of the visit
        - in: query
          name: parameter_name
          schema:
            type: string
            format: string
          description: The URL parameter name (utm_campaign, utm_term, utm_medium, utm_source, utm_content, campaignid, adgroupid, network, creative, or keyword) associated with the visit
        - in: query
          name: parameter_value
          schema:
            type: string
            format: string
          description: The URL parameter value associated with the visit
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getVisitsResponse'
  /api/v1/reports/referrer:
    get:
      operationId: getReferrerReport
      summary: Get the HTTP referrers organized be visit count
      parameters:
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getReferrerReportResponse'
  /api/v1/reports/page:
    get:
      operationId: getPageReport
      summary: Get the page name of the most visited pages organized be visit count
      parameters:
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPageReportResponse'
  /api/v1/reports/entrypage:
    get:
      operationId: getEntryPageReport
      summary: Get the first page vistied by a visitor organized be visit count
      parameters:
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getEntrypageReportResponse'
  /api/v1/reports/parameter:
    get:
      operationId: getParameterReport
      summary: Get the url parameters (utm_campaign, utm_term, utm_medium, utm_source, utm_content, campaignid, adgroupid, network, creative, or keyword) of visited pages organized by visit count
      parameters:
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getParameterReportResponse'
  /api/v1/reports/device:
    get:
      operationId: getDeviceReport
      summary: Get the devices used organized by count
      parameters:
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: The start date for the range of visits
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: The end date for the range of visits
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getDeviceReportResponse'
  # /api/v1/contacts:
      #  get:
      #    operationId: getContacts
      #    summary: Get the contacts
        #    responses:
          #      "200":
          #        description: OK
            #         content:
              #          application/json:
                #            schema:
  #              $ref: '#/components/schemas/getContactsResponse'
components:
  schemas:
    getVisitsResponse:
      type: object
      properties:
        id:
          type: integer
          example: 305482945
        email:
          type: string
          example: "john.doe@example.com"
          description: The email address of the identified visitor. If the visitor is anonymous, the email will be "anonymous"
        domain:
          type: string
          example: "test.com"
          description: the domain of the visit
        page:
          type: string
          example: "/lp/get-revenge"
          description: the pathname of the visit
        url:
          type: string
          example: "test.com/lp/get-revenge?parameter=1"
          description: the full url of the visit
        referrer:
          type: string
          example: "google.com"
          description: the HTTP referrer of the visit
        device:
          type: string
          example: "Windows"
          description: the device type of the visit
        ip:
          type: string
          example: "127.0.0.1"
          description: the IP address of the visit
        params:
          type: object
          properties:
            campaignid:
              type: array
              items:
                type: string
              example: ['123']
              description: the campaignids url parameter of the visit
            adgroupid:
              type: array
              items:
                type: string
              example: ['123']
              description: the adgroupid url parameter of the visit
            network:
              type: array
              items:
                type: string
              example: ['network']
              description: the network parameter of the visit
            creative:
              type: array
              items:
                type: string
              example: ['creative']
              description: the creative parameter of the visit
            keyword:
              type: array
              items:
                type: string
              example: ['keyword']
              description: the keyword parameter of the visit
            utm_campaign:
              type: array
              items:
                type: string
              example: ['the campaign']
              description: the utm_campaign parameter of the visit
            utm_term:
              type: array
              items:
                type: string
              example: ['term']
              description: the utm_term parameter of the visit
            utm_medium:
              type: array
              items:
                type: string
              example: ['medium']
              description: the utm_medium parameter of the visit
            utm_source:
              type: array
              items:
                type: string
              example: ['source']
              description: the utm_source parameter of the visit
            utm_content:
              type: array
              items:
                type: string
              example: ['content']
              description: the utm_content parameter of the visit
        history:
          type: array
          description: the historical pathnames visited by this visitor
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
                example: "2023-03-13T13:47:46"
                description: the date of the visit
              page:
                type: string
                example: "/blog/top-10-divorce-tactics"
                description: the pathname of the visit
        date:
          type: string
          format: date-time
          example: "2023-03-13T08:52:52-05:00"
    getReferrerReportResponse:
      type: object
      properties:
        name:
          type: string
          example: "google"
          description: The name of the http referrer or direct
        visit_count:
          type: integer
          example: 162
          description: The number of visits from the referrer
        contact_count:
          type: integer
          example: 6
          description: The number of identified contacts from this referrer
    getPageReportResponse:
      type: object
      properties:
        url:
          type: string
          example: "tend.io"
          description: The URL of the page visited.
        name:
          type: string
          example: "/home"
          description: The name or path of the page visited.
        visit_count:
          type: integer
          example: 162
          description: The number of visits to the entry page.
        contact_count:
          type: integer
          example: 6
          description: The number of identified contacts associated with the page visits.
    getEntrypageReportResponse:
      type: object
      properties:
        url:
          type: string
          example: "tend.io"
          description: The URL of the page visited.
        name:
          type: string
          example: "/home"
          description: The name or path of the page visited.
        visit_count:
          type: integer
          example: 162
          description: The number of visits to the entry page.
        contact_count:
          type: integer
          example: 6
          description: The number of identified contacts associated with the page visits.
    getParameterReportResponse:
      type: object
      properties:
        name:
          type: string
          example: "utm_source"
          description: The name of the url parameter.
        value:
          type: string
          example: "google"
          description: The value of the url parameter.
        visit_count:
          type: integer
          example: 162
          description: The number of visits associated with the url parameter.
        contact_count:
          type: integer
          example: 6
          description: The number of identified contacts associated with the url parameter.
    getDeviceReportResponse:
      type: object
      properties:
        name:
          type: string
          example: "iPhone"
          description: The name of the device used.
        count:
          type: integer
          example: 162
          description: The number of visits associated with the device.
    getContactsResponse:
      type: object
      properties:
        todos:
          type: array
          items:
            type: string
          description: The list of contacts.
