openapi: 3.0.0
info:
  title: Verae Zapier Middleware API
  description: |
    Zapier-facing HTTP surface. Zapier CLI app calls these routes only.
    Async job watching and webhook delivery may use NATS behind this API.
  version: 0.1.0
servers:
  - url: http://localhost:3100
    description: Local middleware
paths:
  /health:
    get:
      summary: Liveness probe
      operationId: health
      responses:
        '200':
          description: OK
  /zapier/v1/auth/me:
    get:
      summary: Validate API key connection (Zapier auth test)
      operationId: authMe
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Tenant + plan + usage
        '401':
          description: Unauthorized
  /zapier/v1/timestamp:
    post:
      summary: Create timestamp (async jobId)
      operationId: createTimestamp
      security:
        - BearerAuth: []
      responses:
        '202':
          description: Accepted
  /zapier/v1/timestamp/wait:
    post:
      summary: Create timestamp and wait for completion
      operationId: createTimestampAndWait
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Completed or failed status
  /zapier/v1/verify:
    post:
      summary: Verify certificate
      operationId: verifyTimestamp
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Verification result
  /zapier/v1/webhooks/subscribe:
    post:
      summary: REST Hook subscribe
      operationId: webhookSubscribe
      security:
        - BearerAuth: []
      responses:
        '201':
          description: Subscribed
  /zapier/v1/webhooks/unsubscribe:
    delete:
      summary: REST Hook unsubscribe
      operationId: webhookUnsubscribe
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Unsubscribed
  /zapier/v1/hashes/{sha256}:
    get:
      summary: Lookup timestamp by SHA256 (mock)
      operationId: lookupHash
      security:
        - BearerAuth: []
      parameters:
        - name: sha256
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Found }
        '404': { description: Missing }
  /zapier/v1/receipts/{jobId}:
    get:
      summary: Certified retrieval receipt (json or pdf)
      operationId: getReceipt
      security:
        - BearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema: { type: string }
        - name: format
          in: query
          schema: { type: string, enum: [json, pdf] }
      responses:
        '200': { description: Receipt }
  /zapier/v1/objects:
    post:
      summary: Store encrypted blob and timestamp
      operationId: putObject
      security:
        - BearerAuth: []
      responses:
        '201': { description: Stored }
  /zapier/v1/objects/trees:
    post:
      summary: Store encrypted directory tree
      operationId: putTree
      security:
        - BearerAuth: []
      responses:
        '201': { description: Stored }
  /zapier/v1/shares/{token}:
    get:
      summary: Redeem a share token
      operationId: redeemShare
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Ciphertext + dek (mock) }
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Middleware API key (zmw_…) or session token (zmt_…)