openapi: 3.0.3
info:
  title: ReSight Report API
  version: 2.0.7
  description: >-
    The ReSight Report API enables generation of reports in multiple formats (PDF, PNG, JPEG) from either 
    a single JSON payload or a set of input files (transform). The API supports validation, transformation, and rendering operations.

    :::info

    To run ReSight from a Docker image as a REST API, you can launch the container with the CMD `./server`. By default, it will listen on port 80. Example:

    ```
    docker run -p 80:80 demo_satellite ./server
    ```

    :::

    :::warning

    Note that this API is not authenticated. The authentication can be handled by a proxy server or by only allowing the API to be accessed from a trusted network.

    :::

    You can [download this OpenAPI](https://developer.resight.com/specs/docker-rest.yaml) specification and use it to generate client libraries or documentation.
  termsOfService: https://developer.resight.com/terms-of-service
  contact:
    name: ReSight Developer's PoC
    url: https://developer.resight.com
    email: developers@resight.com
  x-logo:
    url: https://www.resight.com/assets/logo-resight.svg
servers:
  - url: http://localhost
    description: The base URL for the API running as a Docker image.
paths:
  /:
    summary: Retrieve Report Template Information
    get:
      tags: [Informational]
      operationId: getReportTemplateInfo
      summary: Retrieve Report Template Information
      description: >-
        Retrieves basic information about the report template.
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: A SemVer version number of the report.
                description: ""
              example:
                version: 1.0.0
          description: ""
          headers: {}
          links: {}
  /schema:
    summary: Get Report Template JSON Schema
    get:
      summary: Get Report Template JSON Schema
      tags: [Informational]
      operationId: getReportTemplateJSONSchema
      description: >-
        Returns the JSON Schema that defines the expected structure and validation rules for the report data. 

        Use this schema to ensure your data payload is valid before rendering. You don't need to run this every time a report is generated since the validation is also performed when the report is rendered. This endpoint is provided for convenience and testing.
      responses:
        "200":
          description: "The JSON Schema used to validate the report data before rendering."
  /transform:
    summary: List Allowed Transforms
    get:
      summary: List Allowed Transforms
      tags: [Informational]
      operationId: getReportTemplateTransformList
      description: >-
        Returns descriptions of all transforms supported by this report template. Each transform defines 
        a set of input files that can be used to generate the report.
      responses:
        "200":
          description: "The description of all the transform supported by this report."
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the transform.
                    description:
                      type: string
                      description: A description of the transform.
                    inputs:
                      $ref: "#/components/schemas/TransformInputs"
  /validate:
    summary: Validate Report Data
    post:
      summary: Validate Report Data
      tags: [Validation]
      operationId: postReportTemplateValidate
      description: >-
        Validates whether the provided JSON data conforms to the report template's schema.
        Returns a success response if valid, or detailed validation errors if invalid.
      requestBody:
        description: The data to validate.
        content:
          application/json:
            schema:
              type: object
              description: A container object for the data to validate.
              properties:
                data:
                  type: object
                  description: The data to validate.
                strict:
                  type: boolean
                  description: Indicates if the validation should be strict.
              required:
                - data
      responses:
        "204":
          description: >-
            A valid response if the passed payload satisfies the validation JSON Schema required to render a report.
        "400":
          description: >-
            The passed payload does not satisfy the validation JSON Schema required to render a report.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
  /render:
    summary: Generate Report
    post:
      summary: Generate Report
      tags: [Rendering]
      operationId: postRenderReportTemplate
      description: >-
        Generates a report in one of the supported formats.
      requestBody:
        description: The data and the options to render.
        content:
          application/json:
            schema:
              type: object
              description: A container object for the data and the options to render.
              properties:
                data:
                  type: object
                  description: The data to render.
                format:
                  type: string
                  enum: [pdf, png, webp, jpg, jpeg]
                  description: The format of the report to render.
                responseFormat:
                  type: string
                  enum: [multipart, zip]
                  description: >-
                    The format of the response when the report pages are rendered
                    individually as images. This is only applicable when the
                    format is not pdf.
                quality:
                  type: number
                  format: int
                  description: The quality of compression when the format is `jpeg` or `webp`.
                  minimum: 0
                  maximum: 100
                  default: 80
                scaleFactor:
                  type: number
                  format: int
                  minimum: 1
                  maximum: 3
                  default: 1
                  description: >-
                    The scale factor to render the report. A higher scale factor
                    will result in a higher resolution image.
                pages:
                  description: >-
                    The pages to render. When a number is passed, it indicates
                    the page number to render. When a range is passed, it
                    indicates the start and end page numbers. When `all` is
                    passed, all the pages are rendered.
                  default: all
                  anyOf:
                    - type: number
                    - type: string
                      pattern: ^\d+-\d+$
                    - type: string
                      pattern: ^all$
                debug:
                  description: >-
                    Indicates if the debug information should be rendered in the
                    report.
                  anyOf:
                    - type: boolean
                      default: false
                      description: >-
                        Turns on or off all the debug information.
                    - type: object
                      properties:
                        layout:
                          type: boolean
                          description: Turns on or off the layout debug information.
                        blocks:
                          type: boolean
                          description: Turns on or off the blocks debug information.
                        origin:
                          type: boolean
                          description: Turns on or off the origin debug information.
                        path:
                          type: boolean
                          description: Turns on or off the path debug information.
              additionalProperties: false
      responses:
        "200":
          description: >-
            The generated report in one for the supported formats.


            Possible formats are: `application/jpeg`, `application/jpg`, `application/pdf`, `application/png`, `application/zip`, `multipart/form-data`.


            When the format is `zip`, it will contain a file for each page of the report in the format `page-{page-number}.{format}`.
        "400":
          $ref: "#/components/responses/400"
  /transform/{transform_name}:
    summary: Get Transform Description
    get:
      summary: Get Transform Description
      tags: [Informational]
      parameters:
        - $ref: "#/components/parameters/transform_name"
      operationId: getReportTemplateTransform
      description: >-
        Returns a description the file(s) required to satisfy the specified
        transform
      responses:
        "200":
          description: "A description the file(s) required to satisfy the specified transform."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransformInputs"
        "404":
          $ref: "#/components/responses/404"
    post:
      summary: Convert Transform Data to JSON
      tags: [Informational]
      parameters:
        - $ref: "#/components/parameters/transform_name"
      operationId: postReportTemplateTransform
      description: >-
        Converts the provided input files into the JSON format required by the report template. This is the data that should be passed to the `POST /render` endpoint. You don't have to convert the data to JSON to render as you can use the `/render/{transform_name}` endpoint directly with the same input files.
      requestBody:
        description: The files to transform and use to render the report.
        content:
          multipart/form-data:
            schema:
              description: >-
                The multipart form data. Each file is mapped to a key as described
                in the `TransformInputs` schema. Keys can be repeated if
                multiple files are expected.
      responses:
        "200":
          description: "The JSON value that can be used to render the report."
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
  /validate/{transform_name}:
    summary: >-
      Validate Transform Data
    post:
      summary: Validate Transform Data
      tags: [Validation]
      parameters:
        - $ref: "#/components/parameters/transform_name"
      operationId: postReportTemplateTransformValidation
      description: >-
        Validates the provided transform input files. Returns a success response if the files are valid and can 
        be used to generate a report, or validation errors if there are issues.
      requestBody:
        description: A key-value pair for each file to validate. The key name is provided by the `GET /transform/{transform_name}` endpoint.
        content:
          multipart/form-data: {}
      responses:
        "200":
          description: "A valid response if the passed files are correct to be rendered."
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
  /render/{transform_name}:
    summary: Generate Report with Transform
    post:
      summary: Generate Report with Transform
      tags: [Rendering]
      parameters:
        - $ref: "#/components/parameters/transform_name"
      operationId: postRenderReportTemplateWithTransform
      description: >-
        Generates a report by processing the provided transform input files.


        The report can be generated in various formats (PDF, PNG, JPEG) with configurable options for quality and pagination.
      requestBody:
        description: A key-value pair for each file to render. Each key name is provided by the `GET /transform/{transform_name}` endpoint. The first file should be a file called `options` in JSON format that describes the options to render the report as described for the `POST /render` endpoint.
        content:
          multipart/form-data: {}
      responses:
        "200":
          description: "The generated report in one for the supported formats."
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
components:
  parameters:
    transform_name:
      name: transform_name
      in: path
      description: >-
        The name of the transform. A transform identifies a set of one or more
        files that can be used to generate a report.
      required: true
      deprecated: false
      schema:
        type: string
  responses:
    "200":
      description: Operation succeeded
    "204":
      description: A successful response that brings no content.
    "400":
      content:
        application/json:
          schema:
            type: string
      description: Illegal input for operation.
    "404":
      description: Resource not found.
  securitySchemes: {}
  schemas:
    TransformInputs:
      type: object
      description: The file inputs required by the transform.
      properties:
        ".+":
          type: object
          description: >-
            The description of the input file or files. The keys of this object are the names representing the input file or files.
          properties:
            format:
              type: string
              description: >-
                The format of the input file or files. This will be the extension of the expected file.
            multiple:
              type: boolean
              description: >-
                Indicates if a single file or multiple files are expected.
  headers: {}
tags:
  - name: Rendering
    description: Operations related to produce an artifact like PDF or PNG.
  - name: Informational
    description: Informational operations.
  - name: Validation
    description: Operations related to validate payloads.
externalDocs:
  description: The ReSight developer's site.
  url: https://developer.resight.com
security: []
