openapi: 3.1.1
info:
  title: Verity Prover API
  description: API for generating verifiable proofs of API responses
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local Verity Prover Proxy Server
paths:
  /proxy:
    post:
      summary: Proxy a POST request with proof generation
      description: Forwards any HTTP request to a target URL and generates TLS proofs
      parameters:
        - name: T-PROXY-URL
          in: header
          required: true
          schema:
            type: string
          description: Target URL to proxy the request to
          example: https://jsonplaceholder.typicode.com/posts
        - name: T-REQUEST-ID
          in: header
          required: true
          schema:
            type: string
          description: Unique identifier for the proof request
          example: 678D765E-B6D0-4BFA-AD4C-EBBC92815B25
        - name: T-REDACTED
          in: header
          required: false
          schema:
            type: string
          description: Comma-separated list of fields to redact in format [req|res]:[body|header]:[field_name]
          example: res:body:id,req:body:userId,res:body:userId,req:header:x-api-key
        - name: T-PROVE-FAILED-REQ
          in: header
          required: false
          schema:
            type: string
          description: If present, proof generation will continue even for failed requests (status >= 400)
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              example:
                title: usher
                body: labs
                userId: 10
      responses:
        '200':
          description: Successful response from proxied endpoint with proof generation initiated
          content:
            application/json:
              schema:
                type: object
    get:
      summary: Proxy a GET request with proof generation
      description: Technically, any HTTP method can be used, but the most common use cases are GET and POST. Forwards a GET request to a target URL and generates proofs
      parameters:
        - name: T-PROXY-URL
          in: header
          required: true
          schema:
            type: string
          description: Target URL to proxy the request to
          example: https://jsonplaceholder.typicode.com/posts
        - name: T-REQUEST-ID
          in: header
          required: true
          schema:
            type: string
          description: Unique identifier for the proof request
          example: 678D765E-B6D0-4BFA-AD4C-EBBC92815B25
        - name: T-REDACTED
          in: header
          required: false
          schema:
            type: string
          description: Comma-separated list of fields to redact in format [req|res]:[body|header]:[field_name]
          example: res:body:id,req:body:userId,res:body:userId,req:header:x-api-key,res:query:userId,search:title,req:header:x-api-key,res:path:1
        - name: T-PROVE-FAILED-REQ
          in: header
          required: false
          schema:
            type: string
          description: If present, proof generation will continue even for failed requests (status >= 400)
      responses:
        '200':
          description: Successful response from proxied endpoint with proof generation initiated
          content:
            application/json:
              schema:
                type: object
  /proof/{requestId}:
    get:
      summary: Subscribe to proof events
      description: Opens a Server-Sent Events (SSE) connection to receive proofs for a specific request
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The request ID to receive proofs for
          example: 678D765E-B6D0-4BFA-AD4C-EBBC92815B25
      responses:
        '200':
          description: SSE connection established
          content:
            text/event-stream:
              schema:
                type: string
                description: Stream of proof events
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message