Derive Notifications API

openapi: 3.2.0
info:
  title: Derive Notifications API
  version: 1.0.0
  description: 'Derive''s HTTP API. Every response shape here is the single source of truth for the web client — generated from the same Zod schemas that back this reference, so the docs never drift from the running API.


    **Auth:** a session cookie (browser) or a bearer token (agents and the CLI). Most write routes are scoped to the caller''s active workspace. The `/v1` paths are the stable product surface; `/openapi.json` serves this spec and `/docs` renders it.'
tags:
- name: Notifications
  description: The caller's in-app notification feed.
paths:
  /v1/notifications:
    get:
      tags:
      - Notifications
      summary: List the signed-in user's recent notifications and unread count
      responses:
        '200':
          description: The 50 most recent notifications and the current unread count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  notifications:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
                  unread:
                    type: number
                required:
                - notifications
                - unread
      operationId: getV1Notifications
      x-operation-id-source: derived
  /v1/notifications/read:
    post:
      tags:
      - Notifications
      summary: Mark notifications read (all, or a set of ids); returns the new unread count
      responses:
        '200':
          description: The unread count after marking.
          content:
            application/json:
              schema:
                type: object
                properties:
                  unread:
                    type: number
                required:
                - unread
      operationId: postV1NotificationsRead
      x-operation-id-source: derived
components:
  schemas:
    Notification:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
          description: The recipient this notification belongs to
        actor:
          type: string
          description: Who triggered it — a person's display name (their handle when they have none)
        kind:
          type: string
          enum:
          - mention
          - comment
          - share
          - follow
          - publish
          - review
          - access_request
          - job
          description: 'What happened: mention, comment, share, follow, publish, review, access_request (someone who cannot open the artifact is asking you to grant it), or job (an agent''s job needs you or finished; thread_id is the agent id, comment_id the job id, and the artifact fields name its report page when it has one)'
        artifact_id:
          type: string
        artifact_short_id:
          type: string
          description: The artifact's public short id for links; empty for follows (no anchor)
        artifact_title:
          type:
          - string
          - 'null'
          description: The artifact's title, or null if untitled or not artifact-anchored
        thread_id:
          type: string
          description: The comment thread anchor; empty when not comment-related
        comment_id:
          type: string
          description: The specific comment anchor; empty when not comment-related
        preview:
          type: string
          description: Short text preview shown in the notification bell
        org_id:
          type:
          - string
          - 'null'
          description: The workspace the row is about, when opening it means switching there first (a job row); null otherwise
        read:
          anyOf:
          - type: number
            enum:
            - 0
          - type: number
            enum:
            - 1
          description: 'Whether the user has read it: 0 unread, 1 read'
        created_at:
          type: string
      required:
      - id
      - user_id
      - actor
      - kind
      - artifact_id
      - artifact_short_id
      - artifact_title
      - thread_id
      - comment_id
      - preview
      - read
      - created_at