verae-edge-billing/openapi.yaml

openapi: 3.0.3
info:
  title: Zappier API (zap.verae.ai)
  version: 0.2.0
  description: |
    Metered data API for Zapier and direct API clients.

    **Timestamping (v1):** digests-only. Edge meters the call, then waits on
    middleware `POST /api/v1/timestamp` (legacy alias `POST /api/timestamp`)
    which calls Verae Time `POST /api/timestamp` — same path MCP uses on
    api.veraetime.net. Responses include `apiVersion: v1`, `receipt_id` (CID),
    `created_at`, and `merkle` when `wait` is true (default).

    **Back-compat:** unversioned middleware `/api/*` aliases remain. Upstream
    Verae Time and MCP keep `/api/timestamp` unchanged.

    **Optional exports:** set `attachPdf: true` or `formats: ["pdf"]` (also
    `csv`, `text`) for registration-document fields like mcp.verae.ai/register.html.
    PDF is off by default.

    **Auth:** prefer long-lived `xVerae-…` tokens from the customer portal
    (`/portal` → Security). Send as `x-api-key` or `Authorization: Bearer`.
    Legacy `key-…` customer keys remain valid. Create/list/revoke via
    `/portal/api/tokens` (portal session required).
security:
  - apiKey: []
  - bearerToken: []
paths:
  /v1/status:
    get:
      operationId: status
      summary: Service status (free)
      responses:
        '200':
          description: OK
  /v1/transform:
    post:
      operationId: transform
      summary: Uppercase a string (fixed price)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
      responses:
        '200':
          description: OK
  /v1/storage:
    post:
      operationId: storage
      summary: Store metadata and file attachments (variable price by size)
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  type: string
                  description: JSON string of metadata
                attachments:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: OK
    get:
      operationId: storage-list
      summary: List your stored items (free)
      responses:
        '200':
          description: OK

  /v1/timestamps:
    post:
      operationId: timestampsBatch
      summary: Batch register digests (wait + receipts; Verae /api/batch/timestamp)
      description: |
        Digests only — hash locally (same as https://mcp.verae.ai/).
        Edge calls middleware `POST /api/v1/batch/timestamp` (legacy `/api/batch/timestamp`),
        which uses Verae Time `POST /api/batch/timestamp` when the plan allows, otherwise
        sequential `POST /api/timestamp` + wait (MCP-style). Max 500.
        Default `wait: true` returns `receipt_id` / `created_at` / `merkle` per result.
        `attachPdf` is opt-in.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      maxItems: 500
                      items:
                        $ref: '#/components/schemas/DigestStampItem'
                    wait:
                      type: boolean
                      default: true
                    attachPdf:
                      type: boolean
                      default: false
                      description: Opt-in registration PDF (pdfBase64) per result
                    formats:
                      $ref: '#/components/schemas/ResultFormats'
                - type: object
                  required: [sha256s]
                  properties:
                    sha256s:
                      type: array
                      maxItems: 500
                      items:
                        type: string
                        description: 64-hex SHA-256 digest
                    wait:
                      type: boolean
                      default: true
                    attachPdf:
                      type: boolean
                      default: false
                    formats:
                      $ref: '#/components/schemas/ResultFormats'
      responses:
        '200':
          description: Completed (wait=true) — results with receipt_id / created_at
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStampResponse'
        '202':
          description: Accepted async (wait=false) — jobIds
  /v1/timestamp:
    post:
      operationId: timestamp
      summary: Register one digest (wait + receipt; Verae /api/timestamp)
      description: |
        Digests only. Proxies middleware `POST /api/v1/timestamp` (legacy `/api/timestamp`)
        → Verae Time `POST /api/timestamp` (identical path MCP uses). Waits by default
        and returns MCP-shaped receipt fields. Set `attachPdf: true` for the registration PDF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
                  description: Raw UTF-8 (hashed server-side) or 64-hex digest
                sha256:
                  type: string
                  description: Preferred 64-hex SHA-256
                digest:
                  type: string
                  description: Alias of sha256
                hashAlg:
                  type: string
                  default: SHA256
                documentName:
                  type: string
                  description: Shown on registration PDF / text export
                wait:
                  type: boolean
                  default: true
                attachPdf:
                  type: boolean
                  default: false
                  description: Opt-in Verae Timestamp Registration Document (pdfBase64)
                formats:
                  $ref: '#/components/schemas/ResultFormats'
                restamp:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Completed — receipt_id (CID), created_at, merkle; pdfBase64 if attachPdf
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StampReceipt'
        '202':
          description: Accepted async (wait=false)
  /v1/hashes/{sha256}:
    get:
      operationId: hash-lookup
      summary: Lookup a SHA256 timestamp (mock)
      parameters:
        - name: sha256
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Missing
  /v1/receipts/{jobId}:
    get:
      operationId: receipt
      summary: Retrieval receipt JSON (mock job ids from /v1/timestamp)
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Missing
  /v1/add:
    post:
      operationId: add
      summary: Add two numbers (activate-now sample)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [number1, number2]
              properties:
                number1:
                  type: number
                  description: First addend
                number2:
                  type: number
                  description: Second addend
      responses:
        '200':
          description: OK
  /v1/usage:
    get:
      operationId: usage
      summary: Your usage summary for the current period
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Legacy `key-…` or long-lived `xVerae-…` token from the portal
    bearerToken:
      type: http
      scheme: bearer
      description: Same `xVerae-…` token as Bearer (LLM-key style)
  schemas:
    ResultFormats:
      description: |
        Export formats (register.html-style). Default is JSON body only.
        Include `pdf` or set attachPdf=true for the registration PDF.
      oneOf:
        - type: string
          enum: [json, csv, text, pdf, all]
        - type: array
          items:
            type: string
            enum: [json, csv, text, pdf]
    DigestStampItem:
      type: object
      properties:
        data:
          type: string
          description: 64-hex SHA-256 digest
        digest:
          type: string
        sha256:
          type: string
        hashAlg:
          type: string
          default: SHA256
        restamp:
          type: boolean
          default: false
        documentName:
          type: string
    StampReceipt:
      type: object
      properties:
        apiVersion:
          type: string
          example: v1
        jobId:
          type: string
          format: uuid
        sha256:
          type: string
        status:
          type: string
          example: completed
        existing:
          type: boolean
        receipt_id:
          type: string
          description: Certificate CID (MCP receipt_id)
        certificate:
          type: string
          description: Alias of receipt_id
        created_at:
          type: string
          format: date-time
        timestamp:
          type: string
          format: date-time
        merkle:
          type: string
          description: Block index / merkle hint from Verae status metadata
        scope:
          type: string
          example: global
        lookup_url:
          type: string
          format: uri
        documentName:
          type: string
        pdfBase64:
          type: string
          description: Present only when attachPdf=true or formats includes pdf
        pdfFilename:
          type: string
        pdfContentType:
          type: string
          example: application/pdf
        text:
          type: string
        csv:
          type: string
        quote:
          type: object
    BatchStampResponse:
      type: object
      properties:
        apiVersion:
          type: string
          example: v1
        mode:
          type: string
          enum: [batch, sequential]
        jobIds:
          type: array
          items:
            type: string
        count:
          type: integer
        created:
          type: integer
        existing:
          type: integer
        totalCredits:
          type: number
        results:
          type: array
          items:
            $ref: '#/components/schemas/StampReceipt'