pricklymails-com Stats API

openapi: 3.2.0
info:
  title: Pricklymails Com Stats API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged stats across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Stats
  description: Your usage statistics, and the public service figures.
paths:
  /api/stats/overview:
    get:
      tags:
      - Stats
      summary: 'Returns the caller''s usage overview: verdict breakdown, activity series, check…'
      description: Accepts optional `granularity` (`"hour"` | `"day"` | `"week"` | `"month"`, default `"day"`) and `days` (the window length, default 28, clamped to 1..=364) query params. Authenticated with a dashboard session, or an API key or agent token holding the `usage:read` scope.
      operationId: get_stats_overview
      parameters:
      - name: granularity
        in: query
        description: 'Bucket width for the activity time series: `hour`, `day`, `week`, or `month` (default `day`).'
        required: false
        schema:
          type: string
      - name: days
        in: query
        description: 'Number of whole buckets the activity window covers at the chosen granularity, ending with the current, still-open bucket (default 28, clamped to 1..=364): 8 at `day` gives 8 buckets, 1 at `hour` gives 24, 364 at `month` gives 12.'
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: Verdict breakdown, activity series, check usage, and totals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsOverviewResponse'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `usage:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/stats/summary:
    get:
      tags:
      - Stats
      summary: Returns the public service figures
      description: 'Public and unauthenticated: the all-time total verification count, the average check latency, and its 90th-percentile latency, refreshed at most once every 24 hours.'
      operationId: get_public_stats
      responses:
        '200':
          description: All-time public verification stats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStatsResponse'
components:
  schemas:
    StatsOverviewResponse:
      type: object
      description: JSON response body for `GET /api/stats/overview`.
      required:
      - verdict_breakdown
      - recommendations
      - activity
      - activity_previous
      - check_usage
      - totals
      properties:
        activity:
          type: array
          items:
            $ref: '#/components/schemas/ActivityPointResponse'
          description: Zero-filled activity time series for the requested window.
        activity_previous:
          type: array
          items:
            $ref: '#/components/schemas/ActivityPointResponse'
          description: Zero-filled activity time series for the immediately preceding, equal-length window.
        check_usage:
          type: array
          items:
            $ref: '#/components/schemas/CheckUsageResponse'
          description: Per-check usage counts for the requested window.
        recommendations:
          $ref: '#/components/schemas/RecommendationBreakdownResponse'
          description: Per-recommendation-bucket counts for the requested window.
        totals:
          $ref: '#/components/schemas/StatsTotalsResponse'
          description: At-a-glance totals for the requested window.
        verdict_breakdown:
          $ref: '#/components/schemas/VerdictBreakdownResponse'
          description: Per-status verdict counts for the requested window.
    CheckUsageResponse:
      type: object
      description: A single check-usage count in the response body.
      required:
      - check
      - count
      properties:
        check:
          type: string
          description: Check name (e.g. `"syntax"`, `"mx"`, `"smtp"`).
        count:
          type: integer
          format: int32
          description: Number of verifications for which this check ran.
          minimum: 0
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    RecommendationBreakdownResponse:
      type: object
      description: 'Per-recommendation-bucket counts in the response body: the 3-bucket "what to do with this address" grouping,

        orthogonal to the raw verdict breakdown above.

        Supports an honest "sendable" rate (`send / (remove + send + review)`), since the raw verdict breakdown still lumps

        catch-all and role-based addresses into `risky` despite normally being worth sending to.'
      required:
      - remove
      - send
      - review
      properties:
        remove:
          type: integer
          format: int32
          description: Count of verifications recommended for removal from the list.
          minimum: 0
        review:
          type: integer
          format: int32
          description: Count of verifications recommended for manual review.
          minimum: 0
        send:
          type: integer
          format: int32
          description: Count of verifications recommended to send to.
          minimum: 0
    StatsTotalsResponse:
      type: object
      description: At-a-glance totals in the response body.
      required:
      - verifications_in_range
      - avg_score
      - deliverable_pct
      properties:
        avg_score:
          type: number
          format: double
          description: Average quality score (0-100) across the window's verifications.
        deliverable_pct:
          type: number
          format: double
          description: Percentage (0-100) of the window's verifications that resolved `valid`.
        verifications_in_range:
          type: integer
          format: int32
          description: Number of verifications performed within the selected window.
          minimum: 0
    ActivityPointResponse:
      type: object
      description: A single time-bucketed activity point in the response body.
      required:
      - date
      - count
      properties:
        count:
          type: integer
          format: int32
          description: Number of verifications recorded in this bucket.
          minimum: 0
        date:
          type: string
          description: 'Start of the bucket, as an RFC3339 timestamp.

            Carrying the full timestamp (rather than a date-only string) preserves the hour for the `"hour"` granularity,

            where a date-only string would collapse every bucket in a day to the same value.'
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
    VerdictBreakdownResponse:
      type: object
      description: Per-status verdict counts in the response body.
      required:
      - valid
      - risky
      - invalid
      - unknown
      properties:
        invalid:
          type: integer
          format: int32
          description: Count of `invalid` verifications.
          minimum: 0
        risky:
          type: integer
          format: int32
          description: Count of `risky` verifications.
          minimum: 0
        unknown:
          type: integer
          format: int32
          description: Count of `unknown` verifications.
          minimum: 0
        valid:
          type: integer
          format: int32
          description: Count of `valid` verifications.
          minimum: 0
    PublicStatsResponse:
      type: object
      description: JSON response body for `GET /api/stats/summary`.
      required:
      - total_verifications
      properties:
        avg_latency_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Average recorded check duration in milliseconds, rounded to the nearest millisecond.

            `null` when no verification has recorded a duration yet.'
        p90_latency_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: '90th-percentile recorded check duration in milliseconds: an actual observed duration at or under which at

            least 90% of results land. `null` when no verification has recorded a duration yet.'
        total_verifications:
          type: integer
          format: int64
          description: All-time total number of verification results recorded, across every customer.
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml