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

# Simulate policy

> What a source would see of a profile, item by item, before you grant access.



## OpenAPI

````yaml openapi/en/cell.json POST /v1/policy/simulate
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/policy/simulate:
    post:
      tags:
        - governance
      summary: Simulate policy
      description: >-
        Shows what a source or an audience would receive for one profile, item
        by item, before you grant access: the effect of the policy on each item
        (`allow`, `mask` or `deny`), the rule that decided it and the text the
        agent would get. Nothing is delivered and no receipt of a read is
        written; the simulation itself is recorded as an administrative action.


        **Authentication.** Console person token with the `security` role (or
        admin), or a source key with the `admin` scope.
      operationId: simulate_v1_policy_simulate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateRequest'
            example:
              profile_id: 0192f7a0-3b2e-7d41-8c5a-2e9f4b7a1c03
              source_id: 0192f79e-11aa-7b20-9f3e-6c1d2e4f5a60
              verification: V1
              view: voice
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateResponse'
              example:
                audience: customer_agent
                verification: V1
                policy_version: pol-14
                items:
                  - id: act_01J8ZK
                    kind: action
                    category: billing
                    effect: allow
                    delivered: true
                    rule: billing-to-service
                    reason: null
                  - id: fct_doc
                    kind: fact
                    category: document
                    effect: deny
                    delivered: false
                    rule: document-needs-v3
                    reason: verification
                withheld:
                  verification: 1
                text: >-
                  <context source="niadra" version="1" view="voice" level="V1"
                  withheld="1">...</context>
          description: >-
            The simulated items, the withheld counts per reason and the
            resulting text.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The request does not match the contract.
      security:
        - sourceKey: []
        - personToken: []
components:
  schemas:
    SimulateRequest:
      additionalProperties: false
      properties:
        audience:
          anyOf:
            - $ref: '#/components/schemas/Audience'
            - type: 'null'
        profile_id:
          format: uuid
          title: Profile Id
          type: string
        purposes:
          items:
            maxLength: 256
            minLength: 1
            type: string
          title: Purposes
          type: array
        source_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Simulate as this source; or give audience and purposes.
          title: Source Id
        verification:
          $ref: '#/components/schemas/Verification'
          default: V1
        view:
          default: chat
          pattern: >-
            ^(voice|chat|brief|full|custom|account|partner|task:[a-z0-9_]{1,40})$
          title: View
          type: string
      required:
        - profile_id
      title: SimulateRequest
      type: object
    SimulateResponse:
      additionalProperties: false
      properties:
        audience:
          $ref: '#/components/schemas/Audience'
        items:
          items:
            $ref: '#/components/schemas/SimulatedItem'
          title: Items
          type: array
        policy_version:
          title: Policy Version
          type: string
        text:
          description: The pack the reader would receive.
          title: Text
          type: string
        verification:
          $ref: '#/components/schemas/Verification'
        withheld:
          additionalProperties:
            type: integer
          title: Withheld
          type: object
      required:
        - policy_version
        - verification
        - audience
        - items
        - withheld
        - text
      title: SimulateResponse
      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
    Audience:
      enum:
        - customer_agent
        - internal_agent
        - human
        - reviewer
        - analyst
        - trigger_target
        - export
      title: Audience
      type: string
    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
    SimulatedItem:
      additionalProperties: false
      properties:
        category:
          title: Category
          type: string
        delivered:
          description: False when allowed but left out by the budget.
          title: Delivered
          type: boolean
        effect:
          enum:
            - allow
            - mask
            - deny
          title: Effect
          type: string
        id:
          title: Id
          type: string
        kind:
          title: Kind
          type: string
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        rule:
          anyOf:
            - type: string
            - type: 'null'
          title: Rule
      required:
        - id
        - kind
        - category
        - effect
        - delivered
      title: SimulatedItem
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````