> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List notifications

> Lists the caller's notifications, newest first, a page at a time: the active ones unless status asks for others.

Use this tool when you need to:
- Show the caller's notification inbox: questions and plans waiting on them, task results and failures, submitted PR reviews
- Page back through the notifications the caller has resolved or dismissed

Examples:
- GET /user/notifications?status=active&limit=50
- GET /user/notifications?status=archive&cursor=eyJvY2N1cnJlZF9hdCI6IjIwMjYtMTAtMjVUMTQ6MDM6MTEuNTJaIiwiaWQiOiI2ZjFjMmE5ZS0zYjdkLTRjNTUtOWEyZS0wZDhiMWY0ZTdjMjEifQ

Hints:
- status is optional: active (the default), resolved, dismissed, archive (resolved and dismissed) or all. limit is optional, 1 to 100, default 50. A status or limit outside its schema is refused with 422 before the list is read.
- Ordered by occurred_at, newest first. Feed next_cursor back through cursor for the next page; next_cursor is null on the last. A malformed cursor is refused with 400; a cursor only marks a position, so one read under another status is accepted.
- Each item's kind (question_requested, plan_requested, task_response_ready, task_failed or pr_review_submitted) decides its payload; task carries the task's id, name, project_id and workspace_id.
- Notifications are read by recipient alone, across organizations, with no current membership checked; a task archived or hidden for the caller keeps none.
- Use dismissNotification instead to dismiss one, resolveTaskNotifications instead to clear a task's entries once it is viewed, and getWaitingTaskCount instead for the app icon badge.
- Any authenticated caller may read their own.



## OpenAPI

````yaml api-reference/openapi.json GET /user/notifications
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /user/notifications:
    get:
      tags:
        - notifications
      summary: List notifications
      description: >-
        Lists the caller's notifications, newest first, a page at a time: the
        active ones unless status asks for others.


        Use this tool when you need to:

        - Show the caller's notification inbox: questions and plans waiting on
        them, task results and failures, submitted PR reviews

        - Page back through the notifications the caller has resolved or
        dismissed


        Examples:

        - GET /user/notifications?status=active&limit=50

        - GET
        /user/notifications?status=archive&cursor=eyJvY2N1cnJlZF9hdCI6IjIwMjYtMTAtMjVUMTQ6MDM6MTEuNTJaIiwiaWQiOiI2ZjFjMmE5ZS0zYjdkLTRjNTUtOWEyZS0wZDhiMWY0ZTdjMjEifQ


        Hints:

        - status is optional: active (the default), resolved, dismissed, archive
        (resolved and dismissed) or all. limit is optional, 1 to 100, default
        50. A status or limit outside its schema is refused with 422 before the
        list is read.

        - Ordered by occurred_at, newest first. Feed next_cursor back through
        cursor for the next page; next_cursor is null on the last. A malformed
        cursor is refused with 400; a cursor only marks a position, so one read
        under another status is accepted.

        - Each item's kind (question_requested, plan_requested,
        task_response_ready, task_failed or pr_review_submitted) decides its
        payload; task carries the task's id, name, project_id and workspace_id.

        - Notifications are read by recipient alone, across organizations, with
        no current membership checked; a task archived or hidden for the caller
        keeps none.

        - Use dismissNotification instead to dismiss one,
        resolveTaskNotifications instead to clear a task's entries once it is
        viewed, and getWaitingTaskCount instead for the app icon badge.

        - Any authenticated caller may read their own.
      operationId: listNotifications
      parameters:
        - explode: false
          in: query
          name: status
          schema:
            enum:
              - active
              - resolved
              - dismissed
              - all
              - archive
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - explode: false
          in: query
          name: cursor
          schema:
            minLength: 1
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/UserNotification'
                    type: array
                  next_cursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - items
                  - next_cursor
                type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsErrorResponse'
          description: Internal Server Error
components:
  schemas:
    UserNotification:
      discriminator:
        mapping:
          permission_requested: '#/components/schemas/PermissionRequestedNotification'
          plan_requested: '#/components/schemas/PlanRequestedNotification'
          pr_review_submitted: '#/components/schemas/PRReviewSubmittedNotification'
          question_requested: '#/components/schemas/QuestionRequestedNotification'
          task_failed: '#/components/schemas/TaskFailedNotification'
          task_response_ready: '#/components/schemas/TaskResponseReadyNotification'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/QuestionRequestedNotification'
        - $ref: '#/components/schemas/PlanRequestedNotification'
        - $ref: '#/components/schemas/TaskResponseReadyNotification'
        - $ref: '#/components/schemas/TaskFailedNotification'
        - $ref: '#/components/schemas/PRReviewSubmittedNotification'
        - $ref: '#/components/schemas/PermissionRequestedNotification'
    NotificationsErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - bad_gateway
            - bad_request
            - conflict
            - forbidden
            - gateway_timeout
            - gone
            - internal_error
            - method_not_allowed
            - not_acceptable
            - not_found
            - not_implemented
            - payment_required
            - precondition_failed
            - rate_limited
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - unauthenticated
            - unsupported_media_type
            - validation_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    PermissionRequestedNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - permission_requested
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/PermissionRequestedNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    PlanRequestedNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - plan_requested
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/PlanRequestedNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    PRReviewSubmittedNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - pr_review_submitted
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/PRReviewSubmittedNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    QuestionRequestedNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - question_requested
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/QuestionRequestedNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    TaskFailedNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - task_failed
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/TaskResultNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    TaskResponseReadyNotification:
      additionalProperties: false
      properties:
        created_at:
          format: date-time
          type: string
        dismissed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        id:
          format: uuid
          type: string
        kind:
          enum:
            - task_response_ready
          type: string
        occurred_at:
          format: date-time
          type: string
        payload:
          $ref: '#/components/schemas/TaskResultNotificationPayload'
        pr_url:
          anyOf:
            - type: string
            - type: 'null'
        preview_text:
          anyOf:
            - type: string
            - type: 'null'
        project_name:
          type: string
        project_repo_url:
          anyOf:
            - type: string
            - type: 'null'
        resolved_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
        status:
          enum:
            - active
            - resolved
            - dismissed
          type: string
        task:
          $ref: '#/components/schemas/NotificationTask'
        title:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - kind
        - status
        - task
        - project_repo_url
        - pr_url
        - title
        - preview_text
        - payload
        - occurred_at
        - resolved_at
        - dismissed_at
        - created_at
        - updated_at
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    PermissionRequestedNotificationPayload:
      additionalProperties: false
      properties:
        chat_id:
          format: uuid
          type: string
        chat_name:
          type:
            - string
            - 'null'
        command:
          minLength: 1
          type: string
        computer_name:
          minLength: 1
          type: string
        prompt_id:
          format: uuid
          type: string
        tool_name:
          minLength: 1
          type: string
      required:
        - prompt_id
        - chat_id
        - chat_name
        - computer_name
        - tool_name
        - command
      type: object
    NotificationTask:
      additionalProperties: false
      properties:
        id:
          format: uuid
          type: string
        name:
          type: string
        project_id:
          format: uuid
          type: string
        workspace_id:
          format: uuid
          type:
            - string
            - 'null'
      required:
        - id
        - project_id
        - workspace_id
      type: object
    PlanRequestedNotificationPayload:
      additionalProperties: false
      properties:
        input:
          additionalProperties: true
          properties:
            plan:
              type: string
            summary:
              type: string
          required:
            - summary
            - plan
          type: object
        plan:
          type: string
        summary:
          type: string
        tool_id:
          minLength: 1
          type: string
      required:
        - tool_id
        - summary
        - plan
        - input
      type: object
    PRReviewSubmittedNotificationPayload:
      additionalProperties: false
      properties:
        message:
          type: string
        pr_number:
          format: int64
          minimum: 1
          type: integer
        review_run:
          type: boolean
        review_url:
          minLength: 1
          type: string
        reviewer_login:
          minLength: 1
          type: string
        verdict:
          enum:
            - approved
            - changes_requested
            - commented
          type: string
      required:
        - verdict
        - reviewer_login
        - review_run
        - review_url
        - pr_number
      type: object
    QuestionRequestedNotificationPayload:
      additionalProperties: false
      properties:
        input:
          additionalProperties: true
          properties:
            questions:
              items:
                $ref: '#/components/schemas/AskUserQuestion'
              minItems: 1
              type: array
          required:
            - questions
          type: object
        tool_id:
          minLength: 1
          type: string
      required:
        - tool_id
        - input
      type: object
    TaskResultNotificationPayload:
      additionalProperties: false
      properties:
        message:
          type: string
        message_label:
          type: string
        message_timestamp:
          type:
            - string
            - 'null'
        task_status:
          enum:
            - awaiting_input
            - errored
          type: string
      required:
        - task_status
        - message_timestamp
      type: object
    AskUserQuestion:
      additionalProperties: false
      properties:
        header:
          type: string
        id:
          type: string
        multi_select:
          type: boolean
        options:
          items:
            $ref: '#/components/schemas/AskUserQuestionOption'
          type: array
        question:
          minLength: 1
          pattern: \S
          type: string
      required:
        - question
        - options
      type: object
    AskUserQuestionOption:
      additionalProperties: false
      properties:
        description:
          type: string
        label:
          minLength: 1
          pattern: \S
          type: string
        preview:
          type: string
      required:
        - label
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.