pricklymails-com Notifications API

openapi: 3.2.0
info:
  title: Pricklymails Com Notifications API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged notifications 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: Notifications
  description: What happened on your account, as a read-only history.
paths:
  /api/notifications:
    get:
      tags:
      - Notifications
      summary: Lists the authenticated account's notifications, newest first
      operationId: list_notifications
      parameters:
      - name: limit
        in: query
        description: Number of events to return. Values outside 1 to 96 are clamped into that range; defaults to 24.
        required: false
        schema:
          type: integer
          format: int64
      - name: cursor
        in: query
        description: 'Opaque token from a previous page''s `next_cursor`. Absent starts at the newest event.


          A malformed cursor is a client error rather than a silent restart, so a stale token cannot quietly turn a

          "load more" into a return to page one.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A page of the account's notifications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotificationsResponse'
        '400':
          description: Malformed cursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
  /api/notifications/seen:
    post:
      tags:
      - Notifications
      summary: Advances the account's cursor, so everything up to `up_to` stops reading as new
      description: 'Idempotent, and never moves the cursor backwards: a stamp that resolves after a newer one does not rewind it.'
      operationId: mark_notifications_seen
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkNotificationsSeenRequest'
        required: true
      responses:
        '200':
          description: The cursor now in effect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkNotificationsSeenResponse'
        '400':
          description: Missing or malformed body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
components:
  schemas:
    MarkNotificationsSeenResponse:
      type: object
      description: '`POST /api/notifications/seen` response.'
      required:
      - last_seen_at
      properties:
        last_seen_at:
          type: string
          format: date-time
          description: The cursor now in effect.
    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.
    MarkNotificationsSeenRequest:
      type: object
      description: '`POST /api/notifications/seen` request.'
      required:
      - up_to
      properties:
        up_to:
          type: string
          format: date-time
          description: 'The `occurred_at` of the newest notification the client displayed, as an RFC 3339 timestamp.


            Everything up to this instant stops counting as new. The stored cursor never moves backwards, and an instant

            later than the server''s clock is treated as the server''s clock.'
    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.'
    ListNotificationsResponse:
      type: object
      description: '`GET /api/notifications` response.'
      required:
      - notifications
      - has_more
      - unseen_count
      properties:
        has_more:
          type: boolean
          description: Whether older events follow this page.
        last_seen_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The caller's stored cursor, or `null` when it has never been advanced.
        next_cursor:
          type:
          - string
          - 'null'
          description: The token to pass back as `cursor` to read the next page, present only when `has_more` is true.
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/NotificationResponse'
          description: The page, newest first.
        unseen_count:
          type: integer
          format: int64
          description: How many events are newer than the caller's cursor.
    NotificationResponse:
      type: object
      description: One notification line.
      required:
      - id
      - event_type
      - translation_key
      - family
      - severity
      - params
      - occurred_at
      properties:
        event_type:
          type: string
          description: The event's slug, which doubles as the page's filter value.
        family:
          type: string
          description: The group the event is filed under, for the family filter.
        id:
          type: string
          format: uuid
          description: The event's UUID, so a client can key a rendered line.
        occurred_at:
          type: string
          format: date-time
          description: When the event was recorded.
        params:
          type: object
          description: 'The values the event''s text interpolates: a flat object of strings and whole numbers, empty when the text has

            none.'
        severity:
          type: string
          description: How loudly the event presents itself, driving its accent.
        translation_key:
          type: string
          description: 'The dashboard locale key carrying this event''s text.


            The API ships the key and never a rendered sentence, so a reader who switches language reads past events in

            their new language rather than in whatever was current when they happened.'
  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