swagger: "2.0"
info:
  version: 0.3.0
  title: "stash"
  description: "PDF Storage Microservice"
  termsOfService: "https://keenanvision.net/terms/"
  contact:
    email: "info@keenanvision.net"
  license:
    name: "Proprietary - Copyright (c) 2018-2024 by Vernon Keenan"
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    in: "header"
    name: "X-API-Key"
  kvSessionCookie:
    type: "apiKey"
    in: "header"
    name: "Cookie"
    description: "Members session cookie. Credential values are never accepted in request bodies, responses, or logs."
security:
  - ApiKeyAuth: []
schemes:
  - "https"
basePath: "/vk/stash/v1"
host: "gw.tnxs.net"
consumes:
  - "application/json"
produces:
  - "application/json"
parameters:
  limitQuery:
    description: Maximum metadata records to return
    in: query
    name: limit
    required: false
    type: integer
    format: int64
    minimum: 1
    maximum: 100
    default: 25
  offsetQuery:
    description: Metadata records to skip
    in: query
    name: offset
    required: false
    type: integer
    format: int64
    minimum: 0
    maximum: 10000
    default: 0
responses:
  AccessForbidden:
    description: "Access forbidden, account lacks access"
    schema:
      $ref: "#/definitions/Error"
  NotFound:
    description: Resource was not found
    schema:
      $ref: "#/definitions/Error"
  ServerError:
    description: Server Internal Error
    schema:
      $ref: "#/definitions/Error"
  Unauthorized:
    description: "Access Unauthorized, invalid API-KEY was used"
    schema:
      $ref: "#/definitions/Error"
  UnprocessableEntity:
    description: "Unprocessable Entity, likely a bad parameter"
    schema:
      $ref: "#/definitions/Error"
  DocumentResponse:
    description: Rendered documents response
    schema:
      $ref: "#/definitions/DocumentResponse"
paths:
  /pdfs:
    get:
      description: "Return bounded metadata for verified PDFs in the configured Keenan Vision tenant. Requires a native service principal with exact stash:pdf:read and an active Keenan Vision or Contributor session."
      operationId: listPdfs
      parameters:
        - $ref: "#/parameters/limitQuery"
        - $ref: "#/parameters/offsetQuery"
      responses:
        "200":
          $ref: "#/responses/DocumentResponse"
        "401":
          $ref: "#/responses/Unauthorized"
        "403":
          $ref: "#/responses/AccessForbidden"
        "422":
          $ref: "#/responses/UnprocessableEntity"
        "500":
          $ref: "#/responses/ServerError"
      security:
        - ApiKeyAuth: []
          kvSessionCookie: []
      summary: List verified tenant PDF metadata
      tags:
        - StashPdf
    post:
      deprecated: true
      description: "Disabled. Stash is metadata-read-only; create and rendering fail closed before body validation or provider access."
      operationId: postPdfs
      responses:
        "403":
          $ref: "#/responses/AccessForbidden"
      summary: PDF creation is disabled
      tags:
        - StashPdf
  /pdfs/{pdfId}:
    get:
      description: "Return metadata for one verified PDF in the configured Keenan Vision tenant. Requires a native service principal with exact stash:pdf:read and an active Keenan Vision or Contributor session."
      operationId: getPdfs
      parameters:
        - name: pdfId
          in: path
          description: PDF record ID
          required: true
          type: string
      responses:
        "200":
          $ref: "#/responses/DocumentResponse"
        "401":
          $ref: "#/responses/Unauthorized"
        "403":
          $ref: "#/responses/AccessForbidden"
        "404":
          $ref: "#/responses/NotFound"
        "422":
          $ref: "#/responses/UnprocessableEntity"
        "500":
          $ref: "#/responses/ServerError"
      security:
        - ApiKeyAuth: []
          kvSessionCookie: []
      summary: Get a single PDF record by ID
      tags:
        - StashPdf
definitions:
  Document:
    properties:
      Filename:
        type: string
      ID:
        type: string
      SagaType:
        type: string
      ParentID:
        type: string
      Title:
        type: string
      URI:
        type: string
    type: object
  DocumentResponse:
    description: An array of rendered documents
    properties:
      Data:
        items:
          $ref: "#/definitions/Document"
        type: array
      Meta:
        $ref: "#/definitions/ResponseMeta"
    type: object
  Error:
    properties:
      Code:
        format: int64
        type: number
      Fields:
        type: string
      Message:
        type: string
    type: object
  NewPDF:
    properties:
      Description:
        description: Description
        type: string
      Filename:
        description: Filename only
        type: string
      HTML:
        description: The HTML data in text format
        type: string
      LastAccessedByID:
        description: Last Accessed By
        type: string
      ObjectType:
        description: This document's financial object origination
        type: string
      OwnerID:
        description: User who created the PDF
        type: string
      ParentID:
        description: ID of the record that owns this PDF
        type: string
      Ref:
        description: External reference if any
        type: string
      Title:
        description: Document descriptive title
        type: string
    type: object
  PDFRequest:
    properties:
      Data:
        items:
          $ref: "#/definitions/NewPDF"
        type: array
      Meta:
        $ref: "#/definitions/RequestMeta"
    type: object
  RequestMeta:
    properties:
      ExternalAccount:
        description: Account Number of the Reseller or OEM
        type: string
    required:
      - ExternalAccount
    type: object
  ResponseMeta:
    properties:
      Contact:
        description: Microservice Contact Info
        type: string
      Copyright:
        description: Copyright Info
        type: string
      License:
        description: License Information and Restrictions
        type: string
      OperationID:
        description: Operation ID
        type: string
      RequestIP:
        description: Request IP Address
        type: string
      RequestType:
        description: Request Type
        type: string
      RequestURL:
        description: Request URL
        type: string
      ServerInfo:
        description: Data Server Info
        type: string
      ServerResponseTime:
        description: Data Server Response Time (ms)
        type: string
      ServerTimestamp:
        description: Backend Server Timestamp
        type: string
      ExternalAccount:
        description: Account Number used for recording transactions
        type: string
    type: object