ASAP Notifications API

openapi: 3.2.0
info:
  title: ASAP Platform Notifications API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: Notifications
  description: Web Push device subscriptions and the in-app notification feed.
paths:
  /v1/notifications:
    get:
      tags:
      - Notifications
      summary: GET /v1/notifications
      operationId: listNotifications
      parameters:
      - name: limit
        in: query
        description: Page size, 1..=100 (defaults to 50).
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
          minimum: 0
      - name: cursor
        in: query
        description: Opaque cursor from a previous page's `meta.next_cursor`.
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: Page of notifications (newest first).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationView'
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Invalid limit or cursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/notifications/preferences:
    get:
      tags:
      - Notifications
      summary: GET /v1/notifications/preferences
      description: '# Errors


        [`AuthRouteError::Unauthenticated`] without a session user,

        [`AuthRouteError::Internal`] on a database failure.'
      operationId: getNotificationPreferences
      responses:
        '200':
          description: The notification matrix.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferencesView'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
    put:
      tags:
      - Notifications
      summary: PUT /v1/notifications/preferences
      description: '# Errors


        [`AuthRouteError::Validation`] for an unknown token, a locked category or a

        cell that does not exist; [`AuthRouteError::Unauthenticated`] without a

        session user; [`AuthRouteError::Internal`] on a database failure.'
      operationId: updateNotificationPreference
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePreferenceRequest'
        required: true
      responses:
        '200':
          description: The matrix after the change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferencesView'
        '401':
          description: Not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Unknown, locked or unavailable cell.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/notifications/read-all:
    post:
      tags:
      - Notifications
      summary: POST /v1/notifications/read-all
      operationId: markAllNotificationsRead
      responses:
        '204':
          description: All unread notifications marked read.
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/notifications/subscribe:
    post:
      tags:
      - Notifications
      summary: POST /v1/notifications/subscribe
      operationId: subscribePush
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeRequest'
        required: true
      responses:
        '204':
          description: Subscription stored or refreshed.
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
    delete:
      tags:
      - Notifications
      summary: DELETE /v1/notifications/subscribe
      operationId: unsubscribePush
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeRequest'
        required: true
      responses:
        '204':
          description: Subscription removed (idempotent).
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/notifications/vapid-public-key:
    get:
      tags:
      - Notifications
      summary: GET /v1/notifications/vapid-public-key
      operationId: getVapidPublicKey
      responses:
        '200':
          description: The VAPID public key (empty when push is not configured).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VapidKeyResponse'
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/notifications/{id}/read:
    post:
      tags:
      - Notifications
      summary: POST /v1/notifications/{id}/read
      operationId: markNotificationRead
      parameters:
      - name: id
        in: path
        description: Notification identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Notification marked read (idempotent).
        '401':
          description: No authenticated user or active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/public/notifications/unsubscribe:
    get:
      tags:
      - Notifications
      summary: GET /v1/public/notifications/unsubscribe
      description: 'Renders a confirmation form and changes nothing: mail clients and link

        scanners prefetch links, and a `GET` that unsubscribed would opt people out

        without a click.'
      operationId: notificationUnsubscribePage
      parameters:
      - name: token
        in: query
        description: Signed token from the email link.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Confirmation form.
          content:
            text/html: {}
        '400':
          description: Invalid token.
          content:
            text/html: {}
    post:
      tags:
      - Notifications
      summary: POST /v1/public/notifications/unsubscribe
      description: 'The RFC 8058 one-click target (`List-Unsubscribe-Post`) and the form

        submit of [`unsubscribe_page`]. Turns the email channel off for the

        token''s category; idempotent.'
      operationId: notificationUnsubscribe
      parameters:
      - name: token
        in: query
        description: Signed token from the email link.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Unsubscribed.
          content:
            text/html: {}
        '400':
          description: Invalid token.
          content:
            text/html: {}
        '503':
          description: Could not be recorded; nothing changed.
components:
  schemas:
    PreferencesView:
      type: object
      description: Response of the preferences endpoints.
      required:
      - categories
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryPreference'
          description: Every category with its channels.
    VapidKeyResponse:
      type: object
      description: Response of `GET /v1/notifications/vapid-public-key`.
      required:
      - public_key
      properties:
        public_key:
          type: string
          description: VAPID public key (base64url), or empty when push is not configured.
    SubscriptionKeys:
      type: object
      description: The `keys` object of a `PushSubscription` (`subscription.toJSON().keys`).
      required:
      - p256dh
      - auth
      properties:
        auth:
          type: string
          description: Client auth secret (base64url).
        p256dh:
          type: string
          description: Client P-256 public key (base64url).
    NotificationView:
      type: object
      description: Public projection of a notification feed row.
      required:
      - id
      - kind
      - title
      - data
      - read
      - created_at
      properties:
        app:
          type:
          - string
          - 'null'
          description: 'Slug of the app this notification came from, when known.


            Lets the client badge that app and show its icon in the feed. `null`

            for rows written before notifications were attributed, so a reader must

            render them without an app rather than guessing one.'
        body:
          type:
          - string
          - 'null'
          description: Optional body.
        created_at:
          type: string
          description: RFC3339 creation timestamp.
        data:
          description: Free-form structured payload (e.g. a deep link target).
        id:
          type: string
          format: uuid
          description: Stable identifier.
        kind:
          type: string
          description: Machine token describing the notification class.
        read:
          type: boolean
          description: Whether the user has read it.
        read_at:
          type:
          - string
          - 'null'
          description: RFC3339 read timestamp, when read.
        title:
          type: string
          description: Title.
    ChannelPreference:
      type: object
      description: One cell of the matrix.
      required:
      - channel
      - offered
      - enabled
      properties:
        channel:
          type: string
          description: '`email`, `push` or `in_app`.'
        enabled:
          type: boolean
          description: Whether it is delivered.
        offered:
          type: boolean
          description: 'Whether ASAP sends this category over this channel at all. When

            `false` the cell does not exist and `enabled` is `false`.'
    UnsubscribeRequest:
      type: object
      description: Body of `DELETE /v1/notifications/subscribe`.
      required:
      - endpoint
      properties:
        endpoint:
          type: string
          description: Push service endpoint URL to remove.
    SubscribeRequest:
      type: object
      description: Body of `POST /v1/notifications/subscribe`.
      required:
      - endpoint
      - keys
      properties:
        endpoint:
          type: string
          description: Push service endpoint URL.
        keys:
          $ref: '#/components/schemas/SubscriptionKeys'
          description: Encryption keys handed back by the browser.
    UpdatePreferenceRequest:
      type: object
      description: Body of `PUT /v1/notifications/preferences`.
      required:
      - category
      - channel
      - enabled
      properties:
        category:
          type: string
          description: Category token.
        channel:
          type: string
          description: Channel token.
        enabled:
          type: boolean
          description: Deliver (`true`) or not (`false`).
    ErrorBody:
      type: object
      description: 'Generic error body returned by API handlers when they fail. `code` is a

        stable machine-readable token; `message` is human-friendly and meant for

        surfacing to end users.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine token (e.g. `invalid_credentials`).
        field:
          type:
          - string
          - 'null'
          description: Offending request field for validation errors, when known.
        message:
          type: string
          description: Human-readable message.
    CategoryPreference:
      type: object
      description: One row of the matrix.
      required:
      - category
      - locked
      - channels
      properties:
        category:
          type: string
          description: '`security`, `invoices`, `signatures` or `marketing`.'
        channels:
          type: array
          items:
            $ref: '#/components/schemas/ChannelPreference'
          description: One entry per channel, in display order.
        locked:
          type: boolean
          description: '`true` when the category cannot be turned off (security).'
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session