swagger: "2.0"
info:
  version: 0.3.0
  title: "stash"
  description: "Read-only client projection of the Stash PDF metadata contract"
  termsOfService: "https://keenanvision.net/terms/"
  contact:
    email: "info@keenanvision.net"
  license:
    name: "Proprietary - Copyright (c) 2018-2024 by Vernon Keenan"
x-provider-pr: "vernonkeenan/stash#16"
x-provider-head: "b2f5b4a6ae5ff507dfdc86bb7b9ee5a9bb924131"
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."
schemes:
  - "http"
basePath: "/v1"
host: "stash.vernonkeenan.com:8080"
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: Sanitized PDF metadata 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
  /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:
    description: Sanitized PDF metadata; document bytes and legacy ownership fields are excluded.
    properties:
      Filename:
        type: string
      ID:
        type: string
      Title:
        type: string
      URI:
        type: string
    type: object
  DocumentResponse:
    description: An array of sanitized PDF metadata
    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
  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