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

# List realm notification rules

> Lists notification rules: the realm's rules with `realm_id` (optionally one team's with
`team_slug`; `effective: true` adds the organization rules that also apply), or the
organization-wide rules with only `org_id`.

Requires a signed-in user token; with `realm_id`, a realm member (or higher) on that realm; with `org_id`, membership in that organization. One of `realm_id` or `org_id` is required.



## OpenAPI

````yaml /openapi/hub-by-tag/hub-realms.yaml post /v1/realms/get_notification_rules
openapi: 3.0.3
info:
  title: 'CliqHub API: Realms'
  version: 1.0.0
  description: >-
    A realm groups daemons, the people who may use them, and the teams they
    should run. Its

    members have a role: member (can see), operator (can run and operate) or
    admin (can

    manage). Daemons join with a realm token, people with an invitation.


    A realm's **team list** is the set of teams its daemons should have: Add a
    team to a realm

    installs it on the realm's online daemons, and daemons that join later get
    it too. A realm

    can also have its own notification rules, and A2A access so outside agents
    can send it tasks.


    Several of these endpoints answer `{ ok: true, realm }`-style bodies rather
    than

    `{ ok: true, data }`; each page shows its exact shape.
servers:
  - url: https://{host}
    variables:
      host:
        default: cliqhub.io
        description: CliqHub host
security: []
tags:
  - name: Realms
    description: >-
      A realm groups daemons, the people who may use them, and the teams they
      should run. Its

      members have a role: member (can see), operator (can run and operate) or
      admin (can

      manage). Daemons join with a realm token, people with an invitation.


      A realm's **team list** is the set of teams its daemons should have: Add a
      team to a realm

      installs it on the realm's online daemons, and daemons that join later get
      it too. A realm

      can also have its own notification rules, and A2A access so outside agents
      can send it tasks.


      Several of these endpoints answer `{ ok: true, realm }`-style bodies
      rather than

      `{ ok: true, data }`; each page shows its exact shape.
paths:
  /v1/realms/get_notification_rules:
    post:
      tags:
        - Realms
      summary: List realm notification rules
      description: >-
        Lists notification rules: the realm's rules with `realm_id` (optionally
        one team's with

        `team_slug`; `effective: true` adds the organization rules that also
        apply), or the

        organization-wide rules with only `org_id`.


        Requires a signed-in user token; with `realm_id`, a realm member (or
        higher) on that realm; with `org_id`, membership in that organization.
        One of `realm_id` or `org_id` is required.
      operationId: POST_v1_realms_get_notification_rules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  type: string
                  format: uuid
                  description: >-
                    Organization this call targets. Required for account-scoped
                    channel/rule ops and inbox.
                realm_id:
                  type: string
                  minLength: 1
                  description: >-
                    When set, list realm (and optional team) rules; omit for
                    org-global rules
                team_slug:
                  type: string
                  minLength: 1
                  description: When set with realm_id, filter to team-scoped rules
                effective:
                  type: boolean
                  description: >-
                    When true with realm_id, merge org + realm tiers for what
                    actually fires
            examples:
              default:
                value:
                  realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b
                  effective: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                properties:
                  ok:
                    type: boolean
                    enum:
                      - true
                    description: Always `true` on success.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationRuleData'
              example:
                ok: true
                data:
                  - id: 4c5d6e7f-8091-4a2b-b3c4-d5e6f7a8b9c0
                    realm_id: 5b0c3a7e-2f4d-4b8e-9a51-7c1d2e3f4a5b
                    org_id: null
                    team_slug: null
                    event: run.failed
                    channel_id: 9a8b7c6d-5e4f-4321-8a0b-1c2d3e4f5a6b
                    priority: 0
                    created_at: 1759000000000
                    updated_at: 1759000000000
                    recipients: null
                    system_key: null
                    locked: false
                    lock_reason: null
        '400':
          description: '`bad_request`: Neither `realm_id` nor `org_id` was sent.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                bad_request:
                  summary: bad_request
                  value:
                    ok: false
                    error:
                      code: bad_request
                      message: realm_id or org_id is required
        '401':
          description: >-
            `unauthorized`: No `Authorization` header, or the token is
            malformed, expired or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                unauthorized:
                  summary: unauthorized
                  value:
                    ok: false
                    error:
                      code: unauthorized
                      message: Authentication required
        '403':
          description: >-
            `forbidden`: You can see the realm or organization but your role
            lacks the required permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                forbidden:
                  summary: forbidden
                  value:
                    ok: false
                    error:
                      code: forbidden
                      message: You do not have access to do this
        '404':
          description: >-
            `not_found`: The realm or organization you named does not exist or
            you cannot see it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                not_found:
                  summary: not_found
                  value:
                    ok: false
                    error:
                      code: not_found
                      message: Not found
        '422':
          description: '`invalid_params`: Neither `realm_id` nor `org_id` was sent.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                invalid_params:
                  summary: invalid_params
                  value:
                    ok: false
                    error: >-
                      org_id: org_id is required when listing org-global
                      notification rules
                    code: invalid_params
        '500':
          description: >-
            `internal_error`: An unexpected server fault. Retry later; if it
            persists, report it with the time of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubErr'
              examples:
                internal_error:
                  summary: internal_error
                  value:
                    ok: false
                    error: Internal server error
                    code: internal_error
      security:
        - BearerAuth: []
components:
  schemas:
    NotificationRuleData:
      type: object
      properties:
        id:
          type: string
          description: Rule UUID
        realm_id:
          type: string
          nullable: true
          description: Realm scope, or null for org-global rules
        org_id:
          type: string
          nullable: true
          description: Owning org for org-global rules
        team_slug:
          type: string
          nullable: true
          description: Team slug under the realm, or null for realm/org-wide
        event:
          type: string
          description: Event selector (exact, family wildcard, or *)
        channel_id:
          type: string
          description: Target channel id
        priority:
          type: number
          description: Priority within the tier
        created_at:
          type: number
          description: Create time (unix ms)
        updated_at:
          type: number
          description: Last update time (unix ms)
        tier:
          type: string
          enum:
            - global
            - realm
          description: Present when listing effective (org + realm) rules
        recipients:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Who receives it: invitee | org_owners | inviter | user | user ids;
            null = the channel destinations
        system_key:
          type: string
          nullable: true
          description: >-
            Stable key of a rule CliqHub seeded (e.g. invite.sent.invitee), else
            null
        locked:
          type: boolean
          description: True when the rule cannot be changed or removed (409 locked)
        lock_reason:
          type: string
          nullable: true
          description: Why the rule is locked
      required:
        - id
        - realm_id
        - team_slug
        - event
        - channel_id
        - priority
        - created_at
        - updated_at
        - recipients
        - system_key
        - locked
        - lock_reason
    HubErr:
      type: object
      required:
        - ok
        - error
      description: >-
        Every failure. Route-policy denials (401/403/404, and 400 when neither
        realm_id nor org_id was sent) answer `error` as `{ code, message }`;
        errors raised by the endpoint answer `error` as the message with the
        code beside it in `code`. Every error has a code. See
        [Errors](/hub-api/errors).
      properties:
        ok:
          type: boolean
          description: Always false on error
        error:
          description: The message, or `{ code, message }` for an access denial.
          oneOf:
            - type: string
            - type: object
              required:
                - code
                - message
              properties:
                code:
                  type: string
                message:
                  type: string
        code:
          type: string
          description: Stable error code of an endpoint error.
        details:
          type: object
          additionalProperties: true
          description: Structured detail, when there is some.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cliq_tok_* | cliq_dt_*
      description: >-
        User PAT (`cliq_tok_…`, including session-scoped) or realm token
        (`cliq_dt_…`).

````

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