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

# Suppression list

> The changes of the list of who may not be contacted, by purpose and channel, with each destination keyed by HMAC with this key's salt; without a cursor, everything in force today.



## OpenAPI

````yaml openapi/en/cell.json GET /v1/suppressions
openapi: 3.1.0
info:
  title: Niadra data API
  version: '1'
  description: >-
    Writing, context, history, objects, identity, privacy and governance of one
    space. Every space has a stable address, with the space and the region in
    its name.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: The space, which comes in the source key.
      region:
        default: us-east-2
        description: The region of the space, which also comes in the key.
security: []
paths:
  /v1/suppressions:
    get:
      tags:
        - coordination
      summary: Suppression list
      description: >-
        The suppression list for this key: a page of changes, oldest first, from
        `cursor`; without a cursor, every entry in force. Each entry carries the
        destination keyed with this key's salt (HMAC-SHA256 over its canonical
        form), the purpose, the channel (null for every channel), `since`,
        `until` and `removed`. Never a handle, a name or the reason. Read it
        again every 60 seconds, apply pages in order and keep the latest state
        per `id`; with `reset`, drop the copy first.


        **Authentication.** Source key: `Authorization: Bearer nia_sk_...`.
        Required scope: `coordinate`. It answers only in a space with the
        `coordination` feature on (the `features` document); in a space without
        it, 404.
      operationId: suppressions_v1_suppressions_get
      parameters:
        - in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 200
                type: string
              - type: 'null'
            title: Cursor
        - in: query
          name: limit
          required: false
          schema:
            default: 200
            maximum: 200
            minimum: 1
            title: Limit
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuppressionPage'
          description: A page of the list.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request does not match the contract.
      security:
        - sourceKey: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            # The local copy of the list, read by cursor and refreshed once a
            minute; it applies with Niadra down

            if niadra.may_contact(customer, "marketing", channel="whatsapp"):
                send(offer)
        - lang: typescript
          label: TypeScript
          source: >-
            // The local copy of the list, read by cursor and refreshed once a
            minute; it applies with Niadra down

            if (await niadra.mayContact(customer, "marketing", { channel:
            "whatsapp" })) await send(offer);
components:
  schemas:
    SuppressionPage:
      additionalProperties: false
      description: >-
        A page of changes, oldest first. With `reset`, the reader drops its copy
        before applying `items`:

        the salt changed, or the cursor is older than what the list keeps.
      properties:
        items:
          items:
            $ref: '#/components/schemas/Suppression'
          title: Items
          type: array
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        reset:
          default: false
          title: Reset
          type: boolean
        salt_id:
          maxLength: 512
          minLength: 1
          title: Salt Id
          type: string
      required:
        - salt_id
        - items
      title: SuppressionPage
      type: object
    Problem:
      additionalProperties: false
      description: RFC 9457 problem details; `code` comes from the versioned error catalog.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    Suppression:
      additionalProperties: false
      description: >-
        One entry of the suppression list: `key` is the subject's handle keyed
        with the reading source's salt

        (the suppression-list spec); `removed` takes the entry `id` out of the
        reader's copy. The reason stays

        with the producer: a vendor learns that it may not contact, never why.
      properties:
        channel:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Channel
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        key:
          pattern: ^[A-Za-z0-9_-]{43}$
          title: Key
          type: string
        purpose:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Purpose
          type: string
        removed:
          default: false
          title: Removed
          type: boolean
        since:
          format: date-time
          title: Since
          type: string
        until:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Until
      required:
        - id
        - key
        - purpose
        - since
      title: Suppression
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````