openapi: 3.1.0
info:
  title: FOSSology Admin Report API
  description: Automate your fossology instance using REST API
  version: 1.6.2
  contact:
    email: fossology@fossology.org
  license:
    name: GPL-2.0-only
    url: https://github.com/fossology/fossology/blob/master/LICENSE
servers:
- url: http://localhost/repo/api/v1
  description: Localhost instance
- url: http://localhost/repo/api/v2
  description: Localhost instance (Version 2)
security:
- bearerAuth: []
- oauth: []
tags:
- name: Report
  description: Upload's report
paths:
  /report:
    get:
      operationId: getReportsByUpload
      tags:
      - Report
      summary: Get the reports for a given upload
      description: 'List all reports available for a given upload

        '
      parameters:
      - name: uploadId
        in: header
        required: true
        description: Id of the upload to generate the report for
        schema:
          type: integer
      - name: reportFormat
        in: header
        required: true
        description: Which report to be genereated
        schema:
          type: string
          enum:
          - dep5
          - spdx2
          - spdx2tv
          - readmeoss
          - unifiedreport
          - clixml
          - cyclonedx
          - spdx3json
          - spdx3rdf
          - spdx3jsonld
      - name: groupName
        description: The group name to chose while generating a report
        in: header
        required: false
        schema:
          type: string
          description: Group name, from last login if not provided
      responses:
        '201':
          description: Report generation is scheduled. Link to download report will be in message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /report/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: Id the report to download
      schema:
        type: integer
    - name: groupName
      description: The group name to chose while downloading specific report
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getReportById
      tags:
      - Report
      summary: Download the report
      description: 'Get a report by id

        '
      responses:
        '200':
          description: Required report
          content:
            text/plain:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
            application/xml:
              schema:
                type: string
                format: binary
        '503':
          description: Report is not ready yet. Check 'Retry-After' header.
          headers:
            Retry-After:
              description: Retry the request after this many seconds
              schema:
                type: integer
                example: 10
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /report/import:
    parameters:
    - name: groupName
      description: The group name to chose while uploading report
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    - name: upload
      in: query
      required: true
      description: Upload ID
      schema:
        type: integer
    - name: reportFormat
      in: query
      required: true
      description: Type of report being uploaded
      schema:
        enum:
        - decisionimporter
        - spdxrdf
    post:
      operationId: uploadReport
      tags:
      - Report
      summary: Import a report to an existing upload
      description: 'Import a report to an existing upload

        '
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                report:
                  description: Report file to be imported
                  type: string
                  format: binary
              oneOf:
              - $ref: '#/components/schemas/DecisionImporter'
              - $ref: '#/components/schemas/SpdxRdfImport'
              required:
              - report
      responses:
        '201':
          description: ReportImport job is scheduled successfully for the given upload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Bad Request, missing parameters in request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: Upload is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Upload does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '503':
          description: Scheduler is not running!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
components:
  schemas:
    DecisionImporter:
      description: Information required by Decision Importer agent
      type: object
      properties:
        importerUser:
          type: integer
          description: User ID on which to tag imported decisions. Use '0' for self.
          default: 0
          example: 3
      required:
      - importerUser
    SpdxRdfImport:
      description: Information required by SPDX RDF report import agent.
      type: object
      properties:
        addNewLicensesAs:
          type: string
          description: Create new licenses as
          enum:
          - candidate
          - license
          default: candidate
        addLicenseInfoFromInfoInFile:
          type: boolean
          description: 'Add the License Info as findings from SPDX tag of type licenseInfoInFile

            '
          default: true
        addLicenseInfoFromConcluded:
          type: boolean
          description: 'Add the License Info as findings from SPDX tag of type licenseConcluded

            '
          default: false
        addConcludedAsDecisions:
          type: boolean
          description: Add concluded licenses as decisions
          default: true
        addConcludedAsDecisionsTBD:
          type: boolean
          description: Add concluded licenses imported as "to be discussed"
          default: true
        addCopyrights:
          type: boolean
          description: Add the copyright information as text findings
          default: false
    Info:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          description: Message in the info
        type:
          type: string
          enum:
          - INFO
          - ERROR
          description: Denotes if info was created on error
  responses:
    defaultResponse:
      description: Some error occurred. Check the "message"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Info'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token from FOSSology
    oauth:
      description: Machine-2-Machine communication from oauth
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/authorize
          scopes: {}
externalDocs:
  description: Basic guide
  url: https://github.com/fossology/fossology/wiki/FOSSology-REST-API
x-reuse:
- - name: id
    required: true
    description: Upload Id
    in: path
    schema:
      type: integer
  - name: itemId
    required: true
    description: UploadTree ID (available via /uploads/{id}/topitem & /uploads/{id}/item/{itemId}/tree/view)
    in: path
    schema:
      type: integer
  - name: status
    required: true
    in: query
    description: Status of the CX
    schema:
      type: string
      enum:
      - active
      - inactive
  - name: limit
    description: Limits of responses per request
    required: false
    in: header
    schema:
      type: integer
      default: 100
      minimum: 1
      maximum: 1000
  - name: page
    description: Page number for responses
    required: false
    in: header
    schema:
      type: integer
      default: 1
      minimum: 1
- - name: id
    required: true
    description: Upload ID
    in: path
    schema:
      type: integer
  - name: itemId
    required: true
    description: Upload tree ID
    in: path
    schema:
      type: integer
  - name: hash
    required: true
    description: CX hash
    in: path
    schema:
      type: string
- '200':
    description: OK
    headers:
      X-Total-Pages:
        description: Total number of pages which can be generated based on limit
        schema:
          type: integer
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/GetFileCopyrights'
  '400':
    description: Bad Request. 'upload' is a required query param
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Info'
  default:
    $ref: '#/components/responses/defaultResponse'
- '200':
    description: OK
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Info'
  '403':
    description: Access denied
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Info'
  default:
    $ref: '#/components/responses/defaultResponse'
- description: Updated text
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/SetCopyrightInfo'