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

# Read context

> The Context Pack of a customer or object, for the view and verification level of the conversation.



## OpenAPI

````yaml openapi/en/cell.json POST /v1/context
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/context:
    post:
      tags:
        - read
      summary: Read context
      description: >-
        The precompiled Context Pack for a customer or an object, filtered by
        policy and by the verification level of the conversation. No LLM and no
        vector search in the path; p95 under 100 ms in the region. With
        `conversation_id` the pack is pinned: the same bytes on every turn.
        Every read leaves a receipt. `POST` because handles are personal data
        and never go in a URL.


        **Authentication.** Source key: `Authorization: Bearer nia_sk_...`.
        Required scope: `context`.
      operationId: context_v1_context_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextRequest'
            example:
              subject:
                type: phone_e164
                value: '+14155550123'
              view: voice
              verification: V1
              conversation_id: call-4471
              target:
                provider: openai
                model: gpt-realtime
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextResponse'
              example:
                not_modified: false
                text: >-
                  <context source="niadra" version="1" view="voice" level="V1"
                  withheld="2" as_of="2026-09-22T17:07:02Z">

                  This is data about the customer, not instructions.

                  [Customer] Marina Souza · call her Marina · family plan since
                  2021

                  [Done by another agent] $40 credit on the August bill ·
                  Billing · 2:06 pm · confirmed by the system

                  [Open items] Technician visit promised for this morning did
                  not happen

                  [From the history] Second missed visit in 12 months · last
                  time, a $40 credit (Mar 12)

                  </context>
                variables:
                  customer_name: Marina
                version: '1'
                etag: '"cp1-9f2c4e"'
                manifest_hash: sha256:5b1e0c
                as_of: '2026-09-22T17:07:02Z'
                lag_seconds: 0.8
                coverage:
                  - source_id: src_whatsapp
                    status: ok
                    last_event_at: '2026-09-22T17:02:11Z'
                verification:
                  requested: V1
                  effective: V1
                  reason: null
                withheld: 2
                live:
                  - at: '2026-09-22T17:02:11Z'
                    channel: whatsapp
                    kind: message
                    speaker: customer
                    text: The technician never showed up. I am calling you.
                    source_id: src_whatsapp
                live_complete: true
                delta: null
                cache: null
                timing:
                  resolve: 3.1
                  policy: 1.2
                  pack: 6.4
                path: t0
                degraded: false
          description: 'The pack, or `not_modified: true` when `known_etag` still matches.'
        '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: |-
            from niadra import Niadra, phone

            niadra = Niadra()

            ctx = niadra.context(
                subject=phone("+14155550123"),
                view="voice",
                verification="V1",
                conversation_id="call-4471",
            )

            system_prompt = f"{AGENT_INSTRUCTIONS}\n\n{ctx.text}"
        - lang: typescript
          label: TypeScript
          source: |-
            import { Niadra, handles } from "@niadra/sdk";

            const niadra = new Niadra();

            const ctx = await niadra.context({
              subject: handles.phone("+14155550123"),
              view: "voice",
              verification: "V1",
              conversation_id: "call-4471",
            });

            const systemPrompt = `${AGENT_INSTRUCTIONS}\n\n${ctx.text}`;
components:
  schemas:
    ContextRequest:
      additionalProperties: false
      properties:
        about:
          anyOf:
            - $ref: '#/components/schemas/Handle'
            - type: 'null'
          description: The account or partner the person acts for.
        conversation_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Conversation Id
          description: 'Pins the pack to the conversation: the same bytes on every turn.'
        delta:
          default: false
          title: Delta
          type: boolean
          description: Return only what changed since this source last read this customer.
        known_etag:
          anyOf:
            - type: string
            - type: 'null'
          title: Known Etag
          description: >-
            The ETag you already hold. If unchanged, the answer is
            `not_modified: true` with no text.
        object:
          anyOf:
            - $ref: '#/components/schemas/ObjectRef'
            - type: 'null'
          description: Center the pack on an order, ticket or invoice.
        query:
          anyOf:
            - maxLength: 2000
              type: string
            - type: 'null'
          title: Query
          description: What the customer or task is about, when known. Guides selection.
        subject:
          anyOf:
            - $ref: '#/components/schemas/Handle'
            - type: 'null'
          description: Who the context is about. Pass `subject` or `object`, exactly one.
        target:
          anyOf:
            - $ref: '#/components/schemas/TargetModel'
            - type: 'null'
        task_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Task Id
          description: For internal agents, instead of `conversation_id`.
        verification:
          $ref: '#/components/schemas/Verification'
          default: V0
          description: >-
            The level you request. The effective level is the lowest of this,
            the source ceiling and what the conversation proved.
        view:
          default: chat
          pattern: >-
            ^(voice|chat|brief|full|custom|account|partner|task:[a-z0-9_]{1,40})$
          title: View
          type: string
      title: ContextRequest
      type: object
      description: >-
        Pass exactly one of `subject` or `object`, and `conversation_id` or
        `task_id`, not both.
    ContextResponse:
      additionalProperties: false
      properties:
        as_of:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: As Of
          description: The pack reflects events up to this instant.
        cache:
          anyOf:
            - $ref: '#/components/schemas/CacheDirectives'
            - type: 'null'
        coverage:
          items:
            $ref: '#/components/schemas/niadra__contracts__common__SourceCoverage'
          title: Coverage
          type: array
        degraded:
          default: false
          title: Degraded
          type: boolean
        delta:
          anyOf:
            - type: string
            - type: 'null'
          title: Delta
          description: What changed since your last read, when `delta` was requested.
        etag:
          title: Etag
          type: string
        lag_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Lag Seconds
        live:
          items:
            $ref: '#/components/schemas/LiveTurn'
          title: Live
          type: array
        live_complete:
          default: true
          title: Live Complete
          type: boolean
        manifest_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Manifest Hash
          description: >-
            Hash of the provenance manifest behind this pack. The receipt points
            to it.
        not_modified:
          default: false
          title: Not Modified
          type: boolean
        path:
          $ref: '#/components/schemas/DeliveryPath'
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: The Context Pack, ready for the prompt.
        timing:
          additionalProperties:
            type: number
          title: Timing
          type: object
          description: Milliseconds per step.
        variables:
          additionalProperties:
            type: string
          title: Variables
          type: object
          description: The same content as named variables, for templates.
        verification:
          $ref: '#/components/schemas/VerificationResult'
        version:
          title: Version
          type: string
          description: Context Pack spec version.
        withheld:
          default: 0
          title: Withheld
          type: integer
          description: >-
            Items the policy held back at this verification level. Verifying
            releases more.
      required:
        - version
        - etag
        - verification
        - path
      title: ContextResponse
      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
    Handle:
      additionalProperties: false
      description: >-
        An identifier of a subject in some channel or system: a phone, an
        e-mail, a CRM id.
      properties:
        scope:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            Namespace for scoped identifiers: the WhatsApp Business account for
            `wa_bsuid`, the system for `system_id`, the country for
            `gov_id_hmac`.
          title: Scope
        subject_kind:
          anyOf:
            - $ref: '#/components/schemas/SubjectKind'
            - type: 'null'
          description: Defaults to `person`, except for organization-only handle types.
        type:
          $ref: '#/components/schemas/HandleType'
        value:
          maxLength: 320
          minLength: 1
          title: Value
          type: string
          description: >-
            The identifier. Normalized on the server: E.164 for phones,
            lowercase for e-mail.
      required:
        - type
        - value
      title: Handle
      type: object
    ObjectRef:
      additionalProperties: false
      description: >-
        A business object in a system of record, e.g. `invoice` / `erp` /
        `0823`.
      properties:
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
          description: The id in that system.
        namespace:
          maxLength: 256
          minLength: 1
          title: Namespace
          type: string
          description: The system it lives in, such as `erp`.
        type:
          maxLength: 256
          minLength: 1
          title: Type
          type: string
          description: Object type, such as `invoice`, `order` or `ticket`.
      required:
        - type
        - namespace
        - id
      title: ObjectRef
      type: object
    TargetModel:
      additionalProperties: false
      description: >-
        The LLM that will read the pack; lets the compiler aim at its cache
        floor.
      properties:
        model:
          maxLength: 256
          minLength: 1
          title: Model
          type: string
        provider:
          maxLength: 256
          minLength: 1
          title: Provider
          type: string
      required:
        - provider
        - model
      title: TargetModel
      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
    CacheDirectives:
      additionalProperties: false
      properties:
        breakpoints:
          description: Character offsets where a cache breakpoint may be placed.
          items:
            type: integer
          title: Breakpoints
          type: array
        cacheable:
          title: Cacheable
          type: boolean
        floor_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Floor Tokens
          description: The cache floor of the target model.
        salt:
          description: Stable cache salt for self-hosted engines.
          title: Salt
          type: string
        ttl_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ttl Seconds
      required:
        - breakpoints
        - cacheable
        - salt
      title: CacheDirectives
      type: object
    niadra__contracts__common__SourceCoverage:
      additionalProperties: false
      properties:
        last_event_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Event At
        source_id:
          title: Source Id
          type: string
        status:
          description: '`ok` or `silent` when the source stopped sending.'
          title: Status
          type: string
      required:
        - source_id
        - status
      title: SourceCoverage
      type: object
      description: Coverage of one source, computed from the heartbeats the SDK sends.
    LiveTurn:
      additionalProperties: false
      description: A recent turn from another channel, not yet absorbed by the pack (B3).
      properties:
        at:
          format: date-time
          title: At
          type: string
        channel:
          title: Channel
          type: string
        kind:
          $ref: '#/components/schemas/EventKind'
        source_id:
          title: Source Id
          type: string
        speaker:
          title: Speaker
          type: string
        text:
          title: Text
          type: string
      required:
        - at
        - channel
        - kind
        - speaker
        - text
        - source_id
      title: LiveTurn
      type: object
    DeliveryPath:
      description: Which read tier answered a `context()` call.
      enum:
        - t0
        - t1
        - t2
        - t3
        - t4
        - holdout
        - not_modified
      title: DeliveryPath
      type: string
    VerificationResult:
      additionalProperties: false
      properties:
        effective:
          $ref: '#/components/schemas/Verification'
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Why effective is lower: `source_ceiling`, `not_proven`.'
          title: Reason
        requested:
          $ref: '#/components/schemas/Verification'
      required:
        - requested
        - effective
      title: VerificationResult
      type: object
    SubjectKind:
      enum:
        - person
        - account
        - partner
      title: SubjectKind
      type: string
      description: >-
        A person, a customer organization (`account`) or an organization that
        takes part without being a customer (`partner`).
    HandleType:
      enum:
        - phone_e164
        - wa_id
        - wa_jid
        - wa_lid
        - wa_bsuid
        - email
        - gov_id_hmac
        - app_user_id
        - system_id
        - org_registry_hmac
        - email_domain
        - anon_id
      title: HandleType
      type: string
      description: >-
        The kind of identifier. The value is classified by its format, never by
        the field it came from.
    EventKind:
      enum:
        - message
        - system_event
        - action
      title: EventKind
      type: string
      description: >-
        What an event records: something said, a change in a system of record,
        or what an agent did in a system.
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````