> ## 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.

# List assertions

> The immutable log that says which handles belong to the same subject, and why.



## OpenAPI

````yaml openapi/en/cell.json GET /v1/identity/assertions
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-1
        description: The region of the space, which also comes in the key.
security: []
paths:
  /v1/identity/assertions:
    get:
      tags:
        - identity
      summary: List assertions
      description: >-
        The immutable identity log: which handles were stated to belong to the
        same subject, by which method, with which evidence, and whether the
        assertion was applied, is pending or was rejected. Filter by profile or
        by state.


        **Authentication.** Console person token with the `security`,
        `integration` role (or admin), or a source key with the `admin` scope.
      operationId: list_assertions_v1_identity_assertions_get
      parameters:
        - in: query
          name: profile_id
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Profile Id
          description: Only the assertions of this profile.
          example: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e01
        - in: query
          name: state
          required: false
          schema:
            anyOf:
              - enum:
                  - applied
                  - pending
                  - rejected
                type: string
              - type: 'null'
            title: State
          description: >-
            `applied`, `pending` (waiting for the merge outside the request) or
            `rejected`.
        - in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Cursor
          description: Opaque cursor from `next_cursor`.
        - in: query
          name: limit
          required: false
          schema:
            default: 50
            maximum: 200
            minimum: 1
            title: Limit
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_AssertionOut_'
              example:
                items:
                  - assertion_id: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e06
                    handle_a: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e02
                    handle_b: 0192f7a1-5b10-7c3a-8e21-4d2f8a4c0e03
                    method: same_event
                    confidence: 0.99
                    level_at_capture: V1
                    origin_event_id: 0192f7a1-6a2b-7d11-9c3e-1a2b3c4d5e05
                    state: applied
                    actor: null
                    reason: null
                    created_at: '2025-11-03T13:10:00Z'
                    retracted_at: null
                next_cursor: null
          description: One page.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request does not match the contract.
      security:
        - sourceKey: []
        - personToken: []
components:
  schemas:
    Page_AssertionOut_:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/AssertionOut'
          title: Items
          type: array
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      required:
        - items
      title: Page[AssertionOut]
      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
    AssertionOut:
      additionalProperties: false
      properties:
        actor:
          anyOf:
            - type: string
            - type: 'null'
          title: Actor
        assertion_id:
          format: uuid
          title: Assertion Id
          type: string
        confidence:
          title: Confidence
          type: number
        created_at:
          format: date-time
          title: Created At
          type: string
        handle_a:
          format: uuid
          title: Handle A
          type: string
        handle_b:
          format: uuid
          title: Handle B
          type: string
        level_at_capture:
          $ref: '#/components/schemas/Verification'
        method:
          $ref: '#/components/schemas/AssertionMethod'
        origin_event_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Origin Event Id
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        retracted_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Retracted At
        state:
          enum:
            - applied
            - pending
            - rejected
          title: State
          type: string
      required:
        - assertion_id
        - handle_a
        - handle_b
        - method
        - state
        - confidence
        - level_at_capture
        - created_at
      title: AssertionOut
      type: object
    Verification:
      description: Session verification levels. `no_customer` sits outside the V0-V4 scale.
      enum:
        - V0
        - V1
        - V2
        - V3
        - V4
        - no_customer
      title: Verification
      type: string
    AssertionMethod:
      enum:
        - explicit_identify
        - otp
        - login
        - system_import
        - same_event
        - co_occurrence
        - channel_rotation
        - accepted_suggestion
        - external_resolver
        - declared
      title: AssertionMethod
      type: string
      description: How the link between two handles was established.
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````