Tinvio SQL Query API

openapi: 3.2.0
info:
  title: Tinvio Com SQL Query API
  version: '1.0'
  contact:
    email: build.with@jaz.ai
    name: API Support
    url: https://jaz.ai
  description: 'Operations tagged SQL Query across 2 of this provider''s published API definitions: tinvio-com-openapi-original.yaml, tinvio-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getjaz.com
tags:
- description: Run read-only pseudo-SQL queries against a curated reporting schema.
  name: SQL Query
paths:
  /api/v1/reports/sql-query/export:
    post:
      description: Submits a read-only pseudo-SQL SELECT query for asynchronous CSV export. The query is validated immediately; a background job then runs it. Poll the returned jobId via the export status endpoint for the download URL. Send an Idempotency-Key header to make a retry return the same job.
      operationId: create-report-sql-query-export
      parameters:
      - description: Optional idempotency key; a repeat with the same key returns the existing job instead of starting a second export.
        in: header
        name: Idempotency-Key
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Export a Pseudo-SQL Query
      tags:
      - SQL Query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PseudoSqlQueryRequest'
        description: Pseudo-SQL query.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/reports/sql-query/export/{id}:
    get:
      description: Returns the status of a pseudo-SQL CSV export job. When the status is COMPLETED the response carries a short-lived download URL. Stop polling once the status is a terminal state (COMPLETED, FAILED, or EXPIRED).
      operationId: get-report-sql-query-export
      parameters:
      - description: Identifier of the export job.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get Pseudo-SQL Export Status
      tags:
      - SQL Query
    servers:
    - url: https://api.getjaz.com
  /api/v1/reports/sql-query/preview:
    post:
      description: Runs a read-only pseudo-SQL SELECT query against the curated reporting schema and returns a capped row preview (up to 100 rows). Use this to check a query before exporting.
      operationId: create-report-sql-query-preview
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Preview a Pseudo-SQL Query
      tags:
      - SQL Query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PseudoSqlQueryRequest'
        description: Pseudo-SQL query.
        required: true
    servers:
    - url: https://api.getjaz.com
  /api/v1/reports/sql-query/schema:
    get:
      description: 'Returns the curated pseudo-SQL catalog (tables, columns, joins, functions) plus the canonical agent skills doc envelope. Use this as the source of truth for query builders, dropdown population, and agent skill auto-pull. The content is the same for every organization; `version` is a stable cache key per deployment. Send `If-None-Match: ""` (exact-match only; `*` and multi-value lists are treated as a cache miss) to skip the body on a cache hit.'
      operationId: list-report-sql-query-schema
      parameters:
      - description: Previously cached version (quoted). Returns 304 if it matches.
        in: header
        name: If-None-Match
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BaseResponse'
                - properties:
                    data:
                      $ref: '#/components/schemas/PseudoSqlSchemaResponse'
                  type: object
        '304':
          description: Not modified. Matches If-None-Match.
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The report service rejected the request (for example, a missing REPORTS:ADMIN role)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream returned a null or malformed schema payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Fetch the Curated Pseudo-SQL Schema
      tags:
      - SQL Query
    servers:
    - url: https://api.getjaz.com
  /api/v1/reports/sql-query/skills-doc:
    get:
      description: 'Returns the canonical jaz-pseudo-sql.md skills doc body with `Content-Disposition: attachment` so a browser or `curl -O` saves it directly. Drop the file into a Claude / Codex / Cursor agent context as the source of truth for writing pseudo-SQL queries. Send `If-None-Match: ""` (exact-match only) to skip the body on a cache hit. Same `` value as the /schema endpoint.'
      operationId: list-report-sql-query-skills-doc
      parameters:
      - description: Previously cached version (quoted). Returns 304 if it matches.
        in: header
        name: If-None-Match
        schema:
          type: string
      responses:
        '200':
          description: Raw markdown body (Agent Skills format)
          content:
            text/markdown:
              schema:
                type: string
        '304':
          description: Not modified. Matches If-None-Match.
        '401':
          description: Missing or invalid API key
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment Required
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The report service rejected the request (for example, a missing REPORTS:ADMIN role)
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream returned an empty or malformed skills doc
          content:
            text/markdown:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Download the Agent Skills Doc
      tags:
      - SQL Query
    servers:
    - url: https://api.getjaz.com
components:
  schemas:
    ErrorResponse:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorResponseData'
          description: Error details.
      type: object
    PseudoSqlSchemaResponse:
      properties:
        agentSkillsDoc:
          allOf:
          - $ref: '#/components/schemas/PseudoSqlAgentSkillsDoc'
          description: Downloadable jaz-pseudo-sql.md skills doc envelope.
        functionCount:
          description: Number of functions.
          example: 47
          type: integer
        functions:
          description: Available scalar and aggregate functions.
          items:
            $ref: '#/components/schemas/PseudoSqlFunction'
          type: array
        joinCount:
          description: Number of join edges.
          example: 91
          type: integer
        joins:
          description: Declared join edges; a query may JOIN two tables only along one of these.
          items:
            $ref: '#/components/schemas/PseudoSqlJoinEdge'
          type: array
        tableCount:
          description: Number of tables.
          example: 70
          type: integer
        tables:
          description: Curated tables a pseudo-SQL query may reference, with the full column list.
          items:
            $ref: '#/components/schemas/PseudoSqlTable'
          type: array
        version:
          description: Stable 16-character hex prefix of sha256(canonical-JSON(dump) || skills-doc-content). Send back as If-None-Match to skip the body on a cache hit.
          example: abc123def4567890
          type: string
      type: object
    BaseResponse:
      properties:
        data:
          description: The response object.
      type: object
    PseudoSqlAgentSkillsDoc:
      properties:
        byteSize:
          description: Byte length of content. Convenience for clients setting Content-Length.
          example: 30421
          type: integer
        content:
          description: 'Full markdown body. Begins with Agent Skills frontmatter (---\nname: jaz-pseudo-sql\n...) followed by the syntax guide followed by the rendered table reference.'
          type: string
        contentType:
          description: MIME type, always text/markdown.
          example: text/markdown
          type: string
        filename:
          description: Suggested file name when downloading.
          example: jaz-pseudo-sql.md
          type: string
      type: object
    PseudoSqlFunction:
      properties:
        aggregate:
          description: True for aggregate functions such as count and sum.
          example: true
          type: boolean
        maxArgs:
          description: Maximum argument count; -1 means variadic.
          example: 1
          type: integer
        minArgs:
          description: Minimum argument count.
          example: 1
          type: integer
        name:
          description: Function name, in lower case.
          example: sum
          type: string
      type: object
    PseudoSqlJoinEdge:
      properties:
        leftColumn:
          description: Column on the left side of the join.
          example: contact_id
          type: string
        leftTable:
          description: Table on the left side of the join.
          example: invoices
          type: string
        rightColumn:
          description: Column on the right side of the join.
          example: id
          type: string
        rightTable:
          description: Table on the right side of the join.
          example: contacts
          type: string
      type: object
    PseudoSqlSchemaColumn:
      properties:
        name:
          description: Column name.
          example: invoice_number
          type: string
        type:
          description: Column data type.
          enum:
          - text
          - int
          - numeric
          - bool
          - date
          - timestamptz
          - uuid
          example: text
          type: string
      type: object
    PseudoSqlTable:
      properties:
        columns:
          description: Columns you may SELECT, in declared order (also the SELECT * order).
          items:
            $ref: '#/components/schemas/PseudoSqlSchemaColumn'
          type: array
        label:
          description: Human-readable label.
          example: Invoices
          type: string
        name:
          description: Table name.
          example: invoices
          type: string
      type: object
    PseudoSqlQueryRequest:
      properties:
        query:
          description: Read-only pseudo-SQL SELECT query to run against the curated reporting schema.
          example: SELECT invoice_number, total, balance FROM invoices WHERE status = 'SENT' LIMIT 10
          maxLength: 16384
          type: string
      required:
      - query
      type: object
    ErrorResponseData:
      properties:
        error_type:
          description: Error category, for example validation_error, invalid_request_body, or internal_server_error.
          example: validation_error
          type: string
        errors:
          description: Error messages describing what went wrong.
          items:
            type: string
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Organization API key. Pass it in the x-jk-api-key header on every request.
      in: header
      name: x-jk-api-key
      type: apiKey
x-refined-from:
- tinvio-com-openapi-original.yaml
- tinvio-com-openapi.yml