Aerones Reports API

openapi: 3.2.0
info:
  title: Aerones Reports API
  version: 0.1.1
  description: 'Operations tagged reports across 2 of this provider''s published API definitions: aerones-openapi.json, aerones-operations-hub-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Reports
paths:
  /api/core/v1/reports/daily:
    post:
      operationId: customer_portal_download_daily_report
      summary: Generate and download a daily report PDF
      parameters: []
      responses:
        '200':
          description: OK
      description: 'Generate and download a daily report for a service order line.


        Access is scoped to the authenticated user''s customer projects.

        If date is omitted, the report covers all activity dates for the SOL.


        ``require_content=False`` — the deliberate opt-out from the empty-day refusal

        the internal surfaces take. ``date`` may be omitted here, so "empty" means

        "this line has no activity at all", not "nothing happened that day"; the

        caller is a portal in another repository whose 4xx handling we cannot see;

        and there is no dialog here to show a message in. A customer asking for a

        quiet line gets the quiet PDF rather than an error.'
      tags:
      - Reports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DailyReportDownloadRequest'
        required: true
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/final:
    post:
      operationId: customer_portal_download_final_report
      summary: Download a final (SOL) report — engine-rendered or uploaded
      parameters: []
      responses:
        '200':
          description: OK
      description: 'Download the final report for a service order line, whatever its type.


        The single final-report entry point for the portal — callers do not need to

        know how a given service''s report is produced. Every family renders on

        demand, LER included: the render owns the final report, and a LER SOL only

        falls back to the document ops uploaded when Ops Hub itself refuses to

        render — the grid is not composed yet, or the service has no push builder

        at all (``LER-TR`` / ``LER-TOP``).

        That refusal is one dedicated exception, and it is the only thing this

        catches. A reporting-engine failure reaches the same call as a plain

        ``ValidationError`` (``reports.client._execute_definition`` turns an

        outage, a rejected token and a missing definition alike into one), and

        answering that with the fallback would hand the customer whatever

        unrelated document the line carries — labelled as their final report, 200

        OK — every time the engine was down. The fallback streams the document

        from storage the way ``core.endpoints.files`` serves stored files (GCS blob

        bytes with the blob''s own content type, falling back to a public-URL

        redirect). Either way the response is the file bytes with a download

        ``Content-Disposition``, so the client handles one shape. A response is not

        necessarily a PDF: an uploaded LER report may be a DOCX/XLSX/ZIP, and its

        ``Content-Type`` says so.


        The customer-facing counterpart of the technician ``final-report/download``

        endpoint (AECP-303): access is scoped to the caller''s customer purely by

        PostgreSQL RLS on ``ServiceOrderLine`` (via ``ServiceOrderHeader.customer_id``)

        — a SOL the caller cannot see is not found, and that gate stays ahead of

        every branch. The LER family is resolved ahead of the LPS branch here for

        the same reason ``reports.api.render_final_report`` resolves it ahead of

        its own cascade — one line must not resolve to two different families on

        two routes, and this is the route where that costs most, because a client

        reads what it returns. The exposure is smaller than on the technician

        routes (this LPS check reads ``Service.group``, an FK, not the free-typed

        ``service_code``, so a stale code cannot reach it), but the order is the

        invariant, not the size of today''s hole. A refusal is a document fallback

        only for LER: applied to any other family it would hand back whatever

        unrelated document happens to be attached

        (``_get_sol_uploaded_final_link`` matches *any* uploaded document once no

        categorised one exists). Every other family''s refusal reaches the customer

        as a plain 404 — an LPS SOL with no project template among them, because

        the technician-facing "Template not selected" message names an internal

        setting ("Project Info") the portal''s caller cannot act on.'
      tags:
      - Reports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalReportDownloadRequest'
        required: true
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/final/{service_order_line_id}/file:
    get:
      operationId: customer_portal_download_final_report_file
      summary: Download an uploaded final report file (e.g. LER)
      parameters:
      - in: path
        name: service_order_line_id
        schema:
          title: Service Order Line Id
          type: integer
        required: true
      responses:
        '200':
          description: OK
      description: 'Download the uploaded final report attached to a service order line.


        Deprecated in favour of ``POST /final``, which now serves uploaded finals

        itself, so no client needs to classify the report type. Kept — and marked

        deprecated in the schema rather than described as such in prose — for clients

        pinned to the two-endpoint contract; it delegates to the same resolution

        helpers, so the two cannot drift.


        The customer-safe uploaded-file path (TD-1 / AECP-267). Ownership is

        **verified, not assumed**: the SOL is resolved through the RLS-scoped

        queryset first, so a SOL outside the caller''s customer is invisible → 404,

        and only then is its linked file served. This deliberately does **not** proxy

        the generic ``/api/core/v1/files/service_order_line/{id}/`` endpoint, which

        carries no customer RLS and no report permission.'
      tags:
      - Reports
      deprecated: true
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/custom:
    post:
      operationId: customer_portal_start_custom_report
      summary: Request a custom report for a selection of turbines, locations or projects
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinalReportStartResponse'
      description: 'Start rendering one document for the selection; returns a generation id to poll.


        The selection is resolved and refused here, before the engine is called: an id

        outside the caller''s customer, an unknown ``report_type``, band value, anomaly

        type or stage, an empty result and an oversized selection are each a 422 naming

        the cause.

        Requesting needs the Reports feature''s Full level (``CUSTOMER_MANAGE_REPORTS``);

        following the request needs View.'
      tags:
      - Reports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomReportRequest'
        required: true
      security:
      - APIKeyAuth: []
      - CookieAuth: []
    get:
      operationId: customer_portal_list_custom_reports
      summary: List the customer's custom report requests, one page at a time
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          description: Page number
          minimum: 1
          title: Page
          type: integer
        required: false
        description: Page number
      - in: query
        name: page_size
        schema:
          default: 20
          description: Number of items per page
          maximum: 1000
          minimum: 1
          title: Page Size
          type: integer
        required: false
        description: Number of items per page
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CustomReportSummary'
                title: Response
                type: array
      description: One page of the caller's requests, newest first, the total in the ``Total-Count`` header; each row carries its family, status and selection so a finished document can be offered without a new render.
      tags:
      - Reports
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/custom/types:
    get:
      operationId: customer_portal_custom_report_types
      summary: List the report types a custom report can be requested for
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CustomReportType'
                title: Response
                type: array
      description: The registered families with the request fields each reads, so the portal form is driven by the server.
      tags:
      - Reports
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/custom/{generation_id}/status:
    get:
      operationId: customer_portal_custom_report_status
      summary: Poll a custom report request
      parameters:
      - in: path
        name: generation_id
        schema:
          title: Generation Id
          type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinalReportStatusResponse'
      description: Poll a pending request once; it turns complete only after the PDF is stored in Ops Hub's own file store.
      tags:
      - Reports
      security:
      - APIKeyAuth: []
      - CookieAuth: []
  /api/core/v1/reports/custom/{generation_id}/download:
    get:
      operationId: customer_portal_download_custom_report
      summary: Download a finished custom report
      parameters:
      - in: path
        name: generation_id
        schema:
          title: Generation Id
          type: integer
        required: true
      responses:
        '200':
          description: OK
      description: Serve the stored PDF of a completed request under the name it was stored with; the engine is never called.
      tags:
      - Reports
      security:
      - APIKeyAuth: []
      - CookieAuth: []
components:
  schemas:
    FinalReportStatusResponse:
      additionalProperties: false
      description: Polling response for an in-flight final-report generation.
      properties:
        generation_id:
          title: Generation Id
          type: integer
        status:
          description: pending | complete | failed
          title: Status
          type: string
        generated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Generated At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      required:
      - generation_id
      - status
      title: FinalReportStatusResponse
      type: object
    CustomReportRequest:
      additionalProperties: false
      description: 'Request body for a custom report: the family and the selection (Ops Hub ids).'
      properties:
        report_type:
          description: Report family, e.g. 'findings'
          title: Report Type
          type: string
        turbine_ids:
          items:
            type: integer
          title: Turbine Ids
          type: array
        location_ids:
          items:
            type: integer
          title: Location Ids
          type: array
        project_ids:
          items:
            type: integer
          title: Project Ids
          type: array
        date_from:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Earliest inspection completion date (inclusive)
          title: Date From
        date_to:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Latest inspection completion date (inclusive)
          title: Date To
        severity_levels:
          description: Severity band, LEVEL_0 .. LEVEL_5
          items:
            type: string
          title: Severity Levels
          type: array
        anomaly_type_ids:
          items:
            type: integer
          title: Anomaly Type Ids
          type: array
        stages:
          description: Finding stages, RELEASED .. CLOSED; empty means every stage
          items:
            type: string
          title: Stages
          type: array
        services:
          description: Service codes of the family, e.g. IIN / VIN; empty means all
          items:
            type: string
          title: Services
          type: array
      required:
      - report_type
      title: CustomReportRequest
      type: object
    FinalReportDownloadRequest:
      additionalProperties: false
      description: Request body for generating a final (SOL) report from the client portal.
      properties:
        service_order_line_id:
          description: Service order line ID to generate the final report for
          title: Service Order Line Id
          type: integer
      required:
      - service_order_line_id
      title: FinalReportDownloadRequest
      type: object
    CustomReportSummary:
      description: One custom report request as the portal lists it, resolved straight off a ``dispatch.Report`` row.
      properties:
        generation_id:
          title: Generation Id
          type: integer
        report_type:
          title: Report Type
          type: string
        status:
          description: pending | complete | failed
          title: Status
          type: string
        selection:
          title: Selection
          type: object
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        generated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Generated At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      required:
      - generation_id
      - report_type
      - status
      - selection
      title: CustomReportSummary
      type: object
    DailyReportDownloadRequest:
      additionalProperties: false
      description: Request body for generating a daily report from the client portal.
      properties:
        service_order_line_id:
          anyOf:
          - type: integer
          - type: 'null'
          description: Service order line ID to generate the report for
          title: Service Order Line Id
        service_order_line_ids:
          anyOf:
          - items:
              type: integer
            maxItems: 50
            minItems: 1
            type: array
          - type: 'null'
          description: Service order line IDs to generate one report for
          title: Service Order Line Ids
        date:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Optional report date (YYYY-MM-DD). If omitted, the report covers all activity dates for the SOL.
          title: Date
        robot_set_ids:
          anyOf:
          - items:
              type: integer
            maxItems: 50
            type: array
          - type: 'null'
          description: Optional robot sets to narrow the report to
          title: Robot Set Ids
      title: DailyReportDownloadRequest
      type: object
    CustomReportService:
      additionalProperties: false
      description: 'One "Service" choice of a family: the service code and the label the portal shows.'
      properties:
        code:
          title: Code
          type: string
        label:
          title: Label
          type: string
      required:
      - code
      - label
      title: CustomReportService
      type: object
    CustomReportType:
      additionalProperties: false
      description: One report family the portal may request, with the request fields it reads and its services.
      properties:
        name:
          title: Name
          type: string
        label:
          title: Label
          type: string
        filters:
          description: CustomReportRequest fields the family reads
          items:
            type: string
          title: Filters
          type: array
        services:
          items:
            $ref: '#/components/schemas/CustomReportService'
          title: Services
          type: array
        max_selection_lines:
          default: 0
          description: 'Always 0: no cap. Kept for portals that still read it.'
          title: Max Selection Lines
          type: integer
        max_selection_findings:
          default: 0
          description: 'Always 0: no cap. Kept for portals that still read it.'
          title: Max Selection Findings
          type: integer
      required:
      - name
      - label
      - filters
      - services
      title: CustomReportType
      type: object
    FinalReportStartResponse:
      additionalProperties: false
      description: Response after kicking off async final-report generation.
      properties:
        generation_id:
          description: Report row ID
          title: Generation Id
          type: integer
        status:
          description: pending | complete | failed
          title: Status
          type: string
      required:
      - generation_id
      - status
      title: FinalReportStartResponse
      type: object
    CustomReportRequest_2:
      additionalProperties: false
      description: 'Request body for a custom report: the family and the selection (Ops Hub ids).'
      properties:
        report_type:
          description: Report family, e.g. 'findings'
          title: Report Type
          type: string
        turbine_ids:
          items:
            type: integer
          title: Turbine Ids
          type: array
        location_ids:
          items:
            type: integer
          title: Location Ids
          type: array
        project_ids:
          items:
            type: integer
          title: Project Ids
          type: array
        date_from:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Earliest inspection completion date (inclusive)
          title: Date From
        date_to:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Latest inspection completion date (inclusive)
          title: Date To
        severity_levels:
          description: Severity band, LEVEL_0 .. LEVEL_5
          items:
            type: string
          title: Severity Levels
          type: array
        anomaly_type_ids:
          items:
            type: integer
          title: Anomaly Type Ids
          type: array
        services:
          description: Service codes of the family, e.g. IIN / VIN; empty means all
          items:
            type: string
          title: Services
          type: array
      required:
      - report_type
      title: CustomReportRequest
      type: object
    CustomReportSummary_2:
      additionalProperties: false
      description: One custom report request as the portal lists it.
      properties:
        generation_id:
          title: Generation Id
          type: integer
        report_type:
          title: Report Type
          type: string
        status:
          description: pending | complete | failed
          title: Status
          type: string
        selection:
          title: Selection
          type: object
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        generated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Generated At
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      required:
      - generation_id
      - report_type
      - status
      - selection
      title: CustomReportSummary
      type: object
    DailyReportDownloadRequest_2:
      additionalProperties: false
      description: Request body for generating a daily report from the client portal.
      properties:
        service_order_line_id:
          description: Service order line ID to generate the report for
          title: Service Order Line Id
          type: integer
        date:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          description: Optional report date (YYYY-MM-DD). If omitted, the report covers all activity dates for the SOL.
          title: Date
      required:
      - service_order_line_id
      title: DailyReportDownloadRequest
      type: object
    CustomReportType_2:
      additionalProperties: false
      description: One report family the portal may request, with the request fields it reads, its services and its cap.
      properties:
        name:
          title: Name
          type: string
        label:
          title: Label
          type: string
        filters:
          description: CustomReportRequest fields the family reads
          items:
            type: string
          title: Filters
          type: array
        services:
          items:
            $ref: '#/components/schemas/CustomReportService'
          title: Services
          type: array
        max_selection_lines:
          title: Max Selection Lines
          type: integer
      required:
      - name
      - label
      - filters
      - services
      - max_selection_lines
      title: CustomReportType
      type: object
  securitySchemes:
    APIKeyAuth:
      type: http
      scheme: bearer
    CookieAuth:
      type: apiKey
      in: cookie
      name: opshub_prod_sessionid
    AuthBearer:
      type: http
      scheme: bearer
x-refined-from:
- aerones-openapi.json
- aerones-operations-hub-openapi.json