UrbanFox Metrics API

openapi: 3.1.0
info:
  title: UrbanFox Customer Cases Metrics API
  version: 2.0.0
  summary: Fraud case management, end-user accounts, and tenant operations for UrbanFox customers.
  description: 'REST API for UrbanFox tenants to manage fraud cases, end-user accounts, tenant

    metrics, and machine-to-machine credentials.


    ## Authentication


    JWT Bearer tokens, issued by `POST /v2/oauth/token` via the OAuth 2.0 client-credentials flow.


    ## Authorization


    Each protected operation declares its required scope in its OAuth 2.0 security requirement.

    Tokens missing the required scope receive a `403`.


    ## Versioning


    Versioned via the URL path (`/v2/...`).

    '
  contact:
    name: UrbanFox
  license:
    name: Proprietary - UrbanFox
servers:
- url: https://api.{tenant_slug}.urbanfox.io
  description: 'Per-tenant API host. The {tenant_slug} subdomain matches the {tenant_slug} path parameter on each operation. Example: a tenant with slug ''demo-retail'' calls https://api.demo-retail.urbanfox.io/v2/demo-retail/cases.'
  variables:
    tenant_slug:
      default: demo-retail
      description: Tenant DNS slug (lowercase, hyphenated).
security:
- oauth2: []
tags:
- name: Metrics
  description: Aggregated tenant metrics and time-series reporting.
paths:
  /v2/{tenant_slug}/metrics:
    get:
      summary: Get tenant metrics
      description: Retrieve tenant activity metrics for a selected date range.
      operationId: getMetricsAggregate
      parameters:
      - description: Tenant DNS slug (lowercase letters, digits, and hyphens; 3-100 characters).
        required: true
        schema:
          type: string
          maxLength: 100
          minLength: 3
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          title: Tenant Name
          description: Tenant DNS slug (lowercase letters, digits, and hyphens; 3-100 characters).
          examples:
          - demo-retail
        name: tenant_slug
        in: path
      - description: Inclusive start of the metrics query window (RFC 3339 / ISO 8601 UTC, milliseconds optional).
        required: true
        schema:
          type: string
          maxLength: 30
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$
          format: date-time
          title: Start Date
          description: Inclusive start of the metrics query window (RFC 3339 / ISO 8601 UTC, milliseconds optional).
          examples:
          - '2024-01-01T00:00:00Z'
        name: start_date
        in: query
      - description: Exclusive end of the metrics query window (RFC 3339 / ISO 8601 UTC, milliseconds optional). Events at exactly `end_date` are not included; must be strictly greater than `start_date`.
        required: true
        schema:
          type: string
          maxLength: 30
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$
          format: date-time
          title: End Date
          description: Exclusive end of the metrics query window (RFC 3339 / ISO 8601 UTC, milliseconds optional). Events at exactly `end_date` are not included; must be strictly greater than `start_date`.
          examples:
          - '2024-01-31T23:59:59Z'
        name: end_date
        in: query
      - description: 'Time bucket size for the returned series. Omit to receive raw, non-aggregated data points. When set, the response includes a data point for every interval in `[start_date, end_date)` (half-open: `start_date` inclusive, `end_date` exclusive), filling missing intervals with zero values. Range limits: `minute` requires `end_date - start_date <= 7 days`; `hour` requires `end_date - start_date <= 90 days`; `day`, `week`, `month`, `quarter`, `year` have no explicit limit.'
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/Aggregations'
          - type: 'null'
          title: Aggregation
          description: 'Time bucket size for the returned series. Omit to receive raw, non-aggregated data points. When set, the response includes a data point for every interval in `[start_date, end_date)` (half-open: `start_date` inclusive, `end_date` exclusive), filling missing intervals with zero values. Range limits: `minute` requires `end_date - start_date <= 7 days`; `hour` requires `end_date - start_date <= 90 days`; `day`, `week`, `month`, `quarter`, `year` have no explicit limit.'
        name: aggregation
        in: query
      - description: Specific metric to return (`timestamp`, `total_events`, `guest_sessions`, `non_guest_sessions`, `unique_sessions`, `unique_ids`, `session_starts`). Omit to receive every metric for each data point.
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/MetricsFields'
          - type: 'null'
          title: Metric
          description: Specific metric to return (`timestamp`, `total_events`, `guest_sessions`, `non_guest_sessions`, `unique_sessions`, `unique_ids`, `session_starts`). Omit to receive every metric for each data point.
        name: metric
        in: query
      responses:
        '422':
          description: Request Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: validation-error
                title: Request Validation Failed
                status: 422
                detail: One or more fields failed validation
                errors:
                - field: query.start_date
                  message: Validation failed
                  type: validation_error
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_MetricListResponse_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: bad-request
                title: Bad Request
                status: 400
                detail: Malformed request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication required
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: internal-error
                title: Internal Server Error
                status: 500
                detail: Internal server error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: item-not-found
                title: Application Error
                status: 404
                detail: 'Tenant not found with name: demo-retail'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: bad-gateway
                title: Bad Gateway
                status: 502
                detail: Failed to communicate with external service
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              example:
                type: forbidden
                title: Forbidden
                status: 403
                detail: Access denied
      tags:
      - Metrics
      security:
      - oauth2:
        - read:metrics
components:
  schemas:
    MetricDataPoint:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Start of the aggregation bucket this data point covers (RFC 3339 / ISO 8601 UTC)
          examples:
          - '2024-01-01T00:00:00Z'
          readOnly: true
        total_events:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Total Events
          description: Total events recorded in the bucket starting at `timestamp`
          examples:
          - 1250
          readOnly: true
        guest_sessions:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Guest Sessions
          description: Sessions for unauthenticated users in the bucket starting at `timestamp`
          examples:
          - 450
          readOnly: true
        non_guest_sessions:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Non Guest Sessions
          description: Sessions for authenticated users in the bucket starting at `timestamp`
          examples:
          - 800
          readOnly: true
        unique_sessions:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Unique Sessions
          description: Distinct session identifiers seen in the bucket starting at `timestamp`
          examples:
          - 1200
          readOnly: true
        unique_ids:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Unique Ids
          description: Distinct end-user identifiers seen in the bucket starting at `timestamp`
          examples:
          - 980
          readOnly: true
        session_starts:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Session Starts
          description: Session-start events recorded in the bucket starting at `timestamp`
          examples:
          - 1150
          readOnly: true
      additionalProperties: false
      type: object
      required:
      - timestamp
      title: MetricDataPoint
    APIResponse_MetricListResponse_:
      properties:
        data:
          $ref: '#/components/schemas/MetricListResponse'
          description: Response payload
          readOnly: true
      type: object
      required:
      - data
      title: APIResponse[MetricListResponse]
    ProblemDetail:
      properties:
        type:
          type: string
          title: Type
          description: URI reference (or identifier) for problem type
          default: about:blank
          examples:
          - validation-error
          readOnly: true
        title:
          type: string
          title: Title
          description: Short, human-readable summary
          examples:
          - Validation Failed
          readOnly: true
        status:
          type: integer
          maximum: 599.0
          minimum: 100.0
          title: Status
          description: HTTP status code
          examples:
          - 400
          readOnly: true
        detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Detail
          description: Human-readable explanation (MUST NOT contain PII or sensitive data)
          examples:
          - Request validation failed on one or more fields
          readOnly: true
        instance:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance
          description: URI reference identifying this specific occurrence (e.g., request ID)
          examples:
          - /v2/demo-retail/cases/case-abc123
          readOnly: true
        errors:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Errors
          description: Validation errors (extension member)
          examples:
          - - field: status
              message: Input should be 'OPEN' or 'CLOSED'
              type: enum
          readOnly: true
      type: object
      required:
      - title
      - status
      title: ProblemDetail
    MetricsFields:
      type: string
      enum:
      - timestamp
      - total_events
      - guest_sessions
      - non_guest_sessions
      - unique_sessions
      - unique_ids
      - session_starts
      title: MetricsFields
    Aggregations:
      type: string
      enum:
      - minute
      - hour
      - day
      - week
      - month
      - quarter
      - year
      title: Aggregations
    MetricListResponse:
      properties:
        metrics:
          items:
            $ref: '#/components/schemas/MetricDataPoint'
          type: array
          title: Metrics
          description: Array of time-series metric data points ordered by timestamp
          examples:
          - - guest_sessions: 450
              non_guest_sessions: 800
              session_starts: 1150
              timestamp: '2024-01-01T00:00:00Z'
              total_events: 1250
              unique_ids: 980
              unique_sessions: 1200
          readOnly: true
      additionalProperties: false
      type: object
      required:
      - metrics
      title: MetricListResponse
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 client-credentials flow. Request a token from `POST /v2/oauth/token` and send it as `Authorization: Bearer <access_token>`.'
      flows:
        clientCredentials:
          tokenUrl: https://api.demo-retail.urbanfox.io/v2/oauth/token
          scopes:
            create:enduseraccount: Create an end-user account
            delete:enduseraccount: Delete an end-user account
            read:case: Get a case
            read:cases: List cases
            read:enduseraccount: Get an end-user account
            read:enduseraccounts: List end-user accounts
            read:metrics: Get tenant metrics
            read:snippet: Get integration snippets
            read:tenant: Get tenant
            read:tenant_auth_secret: Get tenant OAuth client credentials
            update:case: Update a case
            update:enduseraccount: Update an end-user account
            update:tenant_auth_secret: Rotate tenant OAuth client secret