grafomem-com Decision Trail API

openapi: 3.2.0
info:
  title: GRAFOMEM Cloud Decision Trail API
  description: GMP-conformant governed agent memory platform. Provides vector-backed memory stores, multi-agent orchestration, decision trail audit logging, erasure proof certificates, governance policy evaluation, regulatory reports, webhook alerts, SSO/OIDC, and real-time SSE streaming.
  version: 1.9.0
tags:
- name: Decision Trail
  description: Inference audit logging and replay
paths:
  /v1/decisions/log:
    post:
      tags:
      - Decision Trail
      summary: Log Decision
      description: 'Log an AI inference decision with full provenance.


        Records the query, retrieved facts, model used, output produced,

        and optionally Ed25519-signs the decision record.'
      operationId: log_decision_v1_decisions_log_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogDecisionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/decisions/stats:
    get:
      tags:
      - Decision Trail
      summary: Decision Stats
      description: Summary statistics for the tenant's decision trail.
      operationId: decision_stats_v1_decisions_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/decisions/export:
    get:
      tags:
      - Decision Trail
      summary: Export Decisions
      description: 'Bulk export all decisions as newline-delimited JSON (NDJSON).


        Streams the response for memory efficiency with large datasets.

        Suitable for feeding to auditors, compliance tools, or SIEM systems.'
      operationId: export_decisions_v1_decisions_export_get
      parameters:
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/decisions/{decision_id}:
    get:
      tags:
      - Decision Trail
      summary: Get Decision
      description: Retrieve a single decision record by its ID.
      operationId: get_decision_v1_decisions__decision_id__get
      parameters:
      - name: decision_id
        in: path
        required: true
        schema:
          type: string
          title: Decision Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/decisions/{decision_id}/replay:
    get:
      tags:
      - Decision Trail
      summary: Replay Decision
      description: 'Replay a decision: show the decision, the memory state at that

        time, which facts were used, and which have been deleted since.


        This is the core auditability feature: reconstruct exactly what

        the AI knew when it made a decision.'
      operationId: replay_decision_v1_decisions__decision_id__replay_get
      parameters:
      - name: decision_id
        in: path
        required: true
        schema:
          type: string
          title: Decision Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/decisions/:
    get:
      tags:
      - Decision Trail
      summary: Query Decisions
      description: Query decisions with filters and pagination.
      operationId: query_decisions_v1_decisions__get
      parameters:
      - name: store_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Store Id
      - name: session_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
      - name: model_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Id
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 100
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/decisions/scrub/{fact_ref}:
    delete:
      tags:
      - Decision Trail
      summary: Scrub Fact
      description: 'Scrub a deleted fact from all decision records (GDPR Article 17).


        When a fact is hard-deleted from memory, call this endpoint to

        replace its content in all decision records with ''[REDACTED]''.

        Returns the number of affected decisions.'
      operationId: scrub_fact_v1_decisions_scrub__fact_ref__delete
      parameters:
      - name: fact_ref
        in: path
        required: true
        schema:
          type: integer
          title: Fact Ref
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrubResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ScrubResponse:
      properties:
        fact_ref:
          type: integer
          title: Fact Ref
        decisions_affected:
          type: integer
          title: Decisions Affected
      type: object
      required:
      - fact_ref
      - decisions_affected
      title: ScrubResponse
      description: Response for GDPR fact scrubbing.
    ReplayResponse:
      properties:
        decision:
          $ref: '#/components/schemas/DecisionResponse'
        memory_state_at_decision:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Memory State At Decision
        facts_used:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Facts Used
        facts_since_deleted:
          items:
            type: integer
          type: array
          title: Facts Since Deleted
      type: object
      required:
      - decision
      title: ReplayResponse
      description: Response model for decision replay.
    LogDecisionRequest:
      properties:
        store_id:
          type: string
          title: Store Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        query:
          type: string
          title: Query
        retrieved_fact_refs:
          items:
            type: integer
          type: array
          title: Retrieved Fact Refs
        retrieved_contents:
          items:
            type: string
          type: array
          title: Retrieved Contents
        retrieval_scores:
          items:
            type: number
          type: array
          title: Retrieval Scores
        retrieval_options:
          additionalProperties: true
          type: object
          title: Retrieval Options
        model_id:
          type: string
          title: Model Id
        prompt_template_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Template Hash
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
        raw_output:
          type: string
          title: Raw Output
        parsed_output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parsed Output
        output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Tokens
        latency_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latency Ms
        signing_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Signing Key
        parent_decision_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Decision Id
      type: object
      required:
      - store_id
      - query
      - model_id
      - raw_output
      title: LogDecisionRequest
      description: Request body for POST /v1/decisions/log.
    DecisionResponse:
      properties:
        decision_id:
          type: string
          title: Decision Id
        tenant_id:
          type: string
          title: Tenant Id
        store_id:
          type: string
          title: Store Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        created_at:
          type: string
          title: Created At
        query:
          type: string
          title: Query
        retrieved_fact_refs:
          items:
            type: integer
          type: array
          title: Retrieved Fact Refs
        retrieved_contents:
          items:
            type: string
          type: array
          title: Retrieved Contents
        retrieval_scores:
          items:
            type: number
          type: array
          title: Retrieval Scores
        retrieval_options:
          additionalProperties: true
          type: object
          title: Retrieval Options
        model_id:
          type: string
          title: Model Id
        prompt_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Hash
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
        raw_output:
          type: string
          title: Raw Output
        parsed_output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Parsed Output
        output_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Output Tokens
        latency_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Latency Ms
        signature:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature
        public_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Key
        parent_decision_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Decision Id
      type: object
      required:
      - decision_id
      - tenant_id
      - store_id
      - created_at
      - query
      - model_id
      - raw_output
      title: DecisionResponse
      description: Response model for a single decision record.