FOSSology License API

openapi: 3.1.0
info:
  title: FOSSology Admin License 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: License
  description: License and obligation management
paths:
  /obligations/import-csv:
    post:
      operationId: importObligationCsv
      tags:
      - License
      summary: Import an obligation csv file
      description: 'Import an obligation csv file

        '
      requestBody:
        description: Information about delimiters, inclosure and csv file.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                enclosure:
                  type: string
                  description: Enclosure for string in CSV
                  default: '"'
                delimiter:
                  type: string
                  description: Delimiters for fields in CSV
                  default: ','
                file_input:
                  type: string
                  format: binary
                  description: CSV to be imported
              required:
              - file_input
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '200':
          description: Successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /obligations/export-csv:
    get:
      operationId: exportLicenseObligations
      parameters:
      - name: id
        description: Obligation id to export, 0 for all
        in: query
        required: false
        schema:
          type: integer
      tags:
      - License
      summary: Export a csv obligation list
      description: 'Export a csv license obligation list

        '
      responses:
        '200':
          description: Successfully exported
          content:
            text/plain:
              schema:
                type: string
                format: binary
        '403':
          description: Route is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /obligations/import-json:
    post:
      operationId: importObligationsFromJSON
      tags:
      - License
      summary: Import an obligation json file
      description: 'Import an obligation json file

        '
      requestBody:
        description: Include the JSON file
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileInput:
                  type: string
                  format: binary
                  description: JSON to be imported
              required:
              - fileInput
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '200':
          description: Successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /obligations/export-json:
    get:
      operationId: exportObligationsToJSON
      parameters:
      - name: id
        description: Obligation id to export, 0 for all
        in: query
        required: false
        schema:
          type: integer
      tags:
      - License
      summary: Export a json obligation list
      description: 'Export a json license obligation list

        '
      responses:
        '200':
          description: Successfully exported
          content:
            text/json:
              schema:
                type: string
                format: binary
        '403':
          description: Route is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/item/{itemId}/view:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      required: true
      description: Id of the item
      in: path
      schema:
        type: integer
    get:
      operationId: viewTheContentOfTheFile
      tags:
      - License
      summary: Get the contents of the file
      description: Returns the contents of a specific file
      responses:
        '200':
          description: Get contents
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Upload or Item does not exist
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license:
    parameters:
    - name: groupName
      description: The group name to chose
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getLicenses
      tags:
      - License
      parameters:
      - name: page
        description: Page number to fetch
        in: header
        required: false
        schema:
          type: integer
          default: 1
      - name: limit
        description: Limits of responses per request
        in: header
        required: false
        schema:
          type: integer
          minimum: 1
          default: 100
      - name: active
        description: Get only active licenses
        in: header
        required: false
        schema:
          type: boolean
          default: false
      - name: kind
        description: Which kind of licenses to get.
        in: query
        required: false
        schema:
          type: string
          enum:
          - candidate
          - main
          - all
          default: all
      summary: Get all license from the database
      description: 'Get a list of available licenses (filtered by kind or status)

        '
      responses:
        '200':
          description: All licenses from database
          headers:
            X-Total-Pages:
              description: Total number of pages which can be fetched
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - type: object
                    properties:
                      id:
                        type: integer
                        description: Id key
                        example: 125
                  - $ref: '#/components/schemas/License'
        default:
          $ref: '#/components/responses/defaultResponse'
    post:
      operationId: createLicense
      tags:
      - License
      summary: Create a new license
      description: 'Add a new license to the database

        '
      requestBody:
        description: Information about new license
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/License'
              - type: object
                properties:
                  mergeRequest:
                    description: Open a merge request for candidate license?
                    type: boolean
                    default: false
              required:
              - shortName
      responses:
        '201':
          description: License added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '409':
          description: License with same name or text already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/import-csv:
    post:
      operationId: importLicense
      tags:
      - License
      summary: Import a csv license
      description: 'Import a csv license to the database

        '
      requestBody:
        description: Information about delimiters, inclosure and csv file.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                enclosure:
                  type: string
                  description: Enclosure for string in CSV
                  default: '"'
                delimiter:
                  type: string
                  description: Delimiters for fields in CSV
                  default: ','
                file_input:
                  type: string
                  format: binary
                  description: CSV to be imported
              required:
              - file_input
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '200':
          description: Successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/export-csv:
    get:
      operationId: exportLicense
      parameters:
      - name: id
        description: License id to export, 0 for all
        in: query
        required: false
        schema:
          type: integer
      tags:
      - License
      summary: Export a csv license
      description: 'Export a csv license

        '
      responses:
        '200':
          description: Successfully exported
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '403':
          description: Route is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/import-json:
    post:
      operationId: handleImportLicense
      tags:
      - License
      summary: Import a json license
      description: 'Import a json license to the database

        '
      requestBody:
        description: Include the JSON file
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileInput:
                  type: string
                  format: binary
                  description: JSON to be imported
              required:
              - fileInput
      responses:
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '200':
          description: Successfully imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/export-json:
    get:
      operationId: exportAdminLicenseToJSON
      parameters:
      - name: id
        description: License id to export, 0 for all
        in: query
        required: false
        schema:
          type: integer
      tags:
      - License
      summary: Export a json license
      description: 'Export a json license

        '
      responses:
        '200':
          description: Successfully exported
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '403':
          description: Route is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/{shortname}:
    parameters:
    - name: shortname
      in: path
      required: true
      description: Shortname of the license
      schema:
        type: string
    - name: groupName
      description: The group name to chose
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getLicenseByShortname
      tags:
      - License
      summary: Get a specific license
      description: 'Get information about a specific license

        '
      responses:
        '200':
          description: License
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    id:
                      type: integer
                      description: Id key
                      example: 125
                - $ref: '#/components/schemas/License'
                - type: object
                  properties:
                    obligations:
                      description: Obligations associated with the license
                      type: array
                      items:
                        $ref: '#/components/schemas/Obligation'
        '404':
          description: License not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    patch:
      operationId: updateLicenseByShortname
      tags:
      - License
      summary: Update a license
      description: 'Update information about a given license

        '
      requestBody:
        description: Information to be updated
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Set the properties to be updated
              properties:
                fullName:
                  description: New fullname
                  type: string
                  nullable: true
                  example: Updated license name
                text:
                  description: New license text
                  type: string
                  nullable: true
                  example: Updated and corrected license text
                url:
                  description: New URL for license
                  type: string
                  nullable: true
                  example: https://opensource.org/licenses/MIT
                risk:
                  description: New risk value
                  type: integer
                  nullable: true
                  example: 2
      responses:
        '200':
          description: License added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/admincandidates:
    get:
      operationId: getAdminLicenseCandidates
      tags:
      - License
      summary: Get license Candidates for admin view
      description: 'Get a list of license candidates from the database.

        '
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LicenseCandidate'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/admincandidates/{id}:
    parameters:
    - name: id
      required: true
      description: Id of the license-candidate
      in: path
      schema:
        type: integer
    delete:
      operationId: deleteByLicenseCandidateId
      tags:
      - License
      summary: Delete license candidate by id.
      description: 'Delete a single admin-license-candidate by the given id.

        '
      responses:
        '202':
          description: License candidate will be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/adminacknowledgements:
    get:
      operationId: getAdminLicenseAcknowledgements
      tags:
      - License
      summary: Get all admin license acknowledgements
      description: 'Get a list of the admin license acknowledgements

        '
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdminLicenseAcknowledgement'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    put:
      operationId: mutateAdminLicenseAcknowledgement
      tags:
      - License
      summary: Add, Edit, Enable & Disable
      description: 'Add, edit and toggle admin-license acknowledgement

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MutateAdminAcknowledgement'
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/stdcomments:
    get:
      operationId: getAllStandardLicenseComments
      tags:
      - License
      summary: Get all standard license comments
      description: 'Get a list of all standard license comments.

        '
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StandardComment'
        default:
          $ref: '#/components/responses/defaultResponse'
    put:
      operationId: mutateStdComments
      tags:
      - License
      summary: Add, Edit, Enable & Disable
      description: 'Add, edit and toggle standard comments

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MutateStdComment'
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error with details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/verify/{shortname}:
    parameters:
    - name: shortname
      in: path
      required: true
      description: Shortname of the license to be verified
      schema:
        type: string
    put:
      operationId: verifyLicense
      tags:
      - License
      summary: Verify a license as new or variant
      description: 'Verify a license as new or variant of another license

        '
      requestBody:
        description: The shortname of the parent license | Same name if it's to be verified as a new license
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentShortname:
                  description: Shortname of the parent license
                  type: string
                  example: MIT
      responses:
        '200':
          description: License verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Given License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/merge/{shortname}:
    parameters:
    - name: shortname
      in: path
      required: true
      description: Shortname of the license to be merged
      schema:
        type: string
    put:
      operationId: mergeLicense
      tags:
      - License
      summary: Merge a license with another
      description: 'Merge a license to another existing license

        '
      requestBody:
        description: The shortname of the parent license to be merged into
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parentShortname:
                  description: Shortname of the parent license
                  type: string
                  example: MIT
      responses:
        '200':
          description: License merged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Given License not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /license/suggest:
    post:
      operationId: getSuggestedLicense
      tags:
      - License
      summary: Get suggested license by reference text.
      description: 'Get a single suggested license by the given reference text.

        '
      requestBody:
        description: Reference text to get suggested license
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                referenceText:
                  description: Reference text to get suggested license
                  type: string
                  example: According to MIT license, add some modifications
      responses:
        '200':
          description: Request is successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSuggestedLicense'
        '403':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
components:
  schemas:
    StandardComment:
      type: object
      properties:
        id:
          type: integer
          example: 2
          description: The primary key of the comment.
        name:
          type: string
          example: firstComment
          description: The name of the comment.
        comment:
          type: string
          example: The comment's text
          description: The text content of the comment.
        is_enabled:
          type: boolean
          example: true
          description: Indicates whether the comment is enabled or not.
    HighlightInfo:
      type: object
      properties:
        start:
          type: integer
          description: Start position of the highlight in file
          example: 68
        end:
          type: integer
          description: End position of the highlight in file
          example: 70
        type:
          type: string
          description: Type of highlight
          enum:
          - M
          - MC
          - MA
          - MD
          - S
          - K
          - B
          - C
          - U
          - E
          - A
          - I
          - X
          - KW
          - any
        shortName:
          type: string
          description: License shortname
          example: MIT
        refStart:
          type: integer
          description: Start of monk diff highlight (relative)
          example: 0
        refEnd:
          type: integer
          description: End of monk diff highlight (relative)
          example: 53
        infoText:
          type: string
          description: Tooltip text
          example: 'MIT: ''MIT License


            Copyright (c) <year> <copyright holders>'''
        htmlElement:
          type: string
    MutateStdComment:
      type: object
      properties:
        id:
          type: integer
          description: 'The ID of the standard comment.

            Required if update is TRUE.

            '
          example: 2
        name:
          type: string
          description: 'The name of the standard comment.

            Required if update is FALSE.

            '
          example: commentName
        comment:
          type: string
          description: 'The standard comment text.

            Required if update is FALSE.

            '
          example: comment text
        toggle:
          type: boolean
          description: A boolean indicating the toggle state.
          example: true
        update:
          type: boolean
          description: 'A boolean indicating if an update is needed.

            If TRUE, update the given standard comment.

            if FALSE, add new standard comment.

            '
          example: true
    MutateAdminAcknowledgement:
      type: object
      properties:
        id:
          type: integer
          description: 'The ID of the acknowledgement.

            Required if update is TRUE.

            '
          example: 2
        name:
          type: string
          description: 'The name of the acknowledgement.

            Not required if update is TRUE and toggle is set.

            '
          example: ackName
        ack:
          type: string
          description: 'The acknowledgement text.

            Not required if update is TRUE and toggle is set.

            '
          example: acknowledgement text
        toggle:
          type: boolean
          description: A boolean indicating the toggle state.
          example: true
        update:
          type: boolean
          description: 'A boolean indicating if an update is needed.

            If true, update the given admin acknowledgement.

            if false, add new admin acknowledgement.

            '
          example: true
    GetSuggestedLicense:
      type: object
      properties:
        id:
          type: integer
          description: The primary key of the suggested license.
          example: 1329
        spdxName:
          type: string
          description: The SPDX identifier of the suggested license.
          example: LicenseRef-fossology-testmerge
        shortname:
          type: string
          description: The short name of the suggested license.
          example: MIT
        fullname:
          type: string
          description: The full name of the suggested license.
          example: MIT license
        text:
          type: string
          description: The text content of the suggested license.
          example: "Copyright (c) 2002 by AUTHOR PROFESSIONAL IDENTIFICATION * URL \"PROMOTIONAL SLOGAN FOR AUTHOR'S PROFESSIONAL PRACTICE\"\r\n"
        url:
          type: string
          description: The URL associated with the suggested license.
          example: https://www.google.com/
        notes:
          type: string
          description: Additional notes or comments about the suggested license.
          example: public notes
        risk:
          type: integer
          description: The risk level associated with the suggested license.
          example: 2
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/HighlightInfo'
    AdminLicenseAcknowledgement:
      type: object
      properties:
        id:
          type: integer
          description: The primary key of the AdminAcknowledgement
          example: 2
        name:
          type: string
          description: The name of the AdminAcknowledgement
          example: ackupdated
        acknowledgement:
          type: string
          description: The acknowledgement text of the AdminAcknowledgement
          example: updated Ack text
        is_enabled:
          type: boolean
          description: Indicates if the AdminAcknowledgement is enabled
          example: true
    License:
      description: License from the database
      type: object
      properties:
        shortName:
          description: Short name
          type: string
          example: MIT
        fullName:
          description: Full name
          type: string
          example: MIT License
        text:
          description: License text
          type: string
          example: MIT License Copyright (c) <year> <copyright holders> ...
        url:
          description: URL of the license text
          type: string
          example: https://opensource.org/licenses/MIT
        risk:
          description: Risk level
          type: integer
          nullable: true
          example: 3
        isCandidate:
          description: Is the license a candidate?
          type: boolean
    Info:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          description: Message in the info
        type:
          type: string
      

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fossology/refs/heads/main/openapi/fossology-license-api-openapi.yml