FOSSology Upload API

openapi: 3.1.0
info:
  title: FOSSology Admin Upload 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: Upload
  description: Endpoints related to uploads
paths:
  /uploads/{id}:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: groupName
      description: The group name to chose while accessing the package
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getUploadById
      tags:
      - Upload
      summary: Get single upload by id
      description: Returns a single upload
      responses:
        '200':
          description: Get upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upload'
        '503':
          description: 'The ununpack agent has not started yet. Please check the ''Look-at'' header for more information

            '
          headers:
            Look-at:
              description: Contains the URL to get jobs for the given upload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    delete:
      operationId: deleteUploadById
      tags:
      - Upload
      summary: Delete upload by id
      description: 'Delete a single upload by id

        '
      responses:
        '202':
          description: Upload will be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    patch:
      operationId: updateUploadById
      tags:
      - Upload
      description: Update an upload information
      parameters:
      - name: status
        description: New status of the upload
        in: query
        required: false
        schema:
          type: string
          enum:
          - Open
          - InProgress
          - Closed
          - Rejected
        example: Closed
      - name: assignee
        description: New assignee for the project
        in: query
        required: false
        schema:
          type: integer
      requestBody:
        description: 'Comment on the status, required for Closed and Rejected states. Ignored for others.

          '
        content:
          text/plain:
            schema:
              description: The comment for new status
              type: string
              example: The upload cleared for use.
      responses:
        '202':
          description: Upload will be updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
    put:
      operationId: moveUploadById
      tags:
      - Upload
      description: Copy or move an upload by id
      parameters:
      - name: folderId
        description: Folder Id, where upload should be copied to
        in: header
        required: true
        schema:
          type: integer
      - name: action
        in: header
        required: true
        description: Action to be performed
        schema:
          type: string
          enum:
          - copy
          - move
      summary: Copy/Move an upload
      responses:
        '202':
          description: Upload will be copied/moved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads:
    parameters:
    - name: groupName
      description: The group name to chose while accessing the package
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getUploads
      tags:
      - Upload
      summary: Uploads
      parameters:
      - name: folderId
        description: Folder ID to limit the uploads to
        in: query
        required: false
        schema:
          type: integer
      - name: recursive
        description: Load uploads from child folders as well
        in: query
        required: false
        schema:
          type: boolean
          default: true
      - name: name
        description: Filter pattern for name and description
        in: query
        required: false
        schema:
          type: string
      - name: status
        description: Status of uploads
        in: query
        required: false
        schema:
          type: string
          enum:
          - Open
          - InProgress
          - Closed
          - Rejected
      - name: assignee
        description: 'User name to which uploads are assigned to or -me- or -unassigned-

          '
        in: query
        required: false
        schema:
          type: string
      - name: since
        description: Uploads since given date in YYYY-MM-DD format
        in: query
        required: false
        schema:
          type: string
          pattern: \d{4}\-\d{2}\-\d{2}
      - 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
      description: 'The uploads endpoint returns all uploads

        '
      responses:
        '200':
          description: An array of uploads
          headers:
            X-Total-Pages:
              description: Total number of pages which can be fetched
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Upload'
        default:
          $ref: '#/components/responses/defaultResponse'
    post:
      operationId: createUpload
      tags:
      - Upload
      summary: Post new upload to FOSSology
      description: 'Endpoint to create a new upload in FOSSology

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                location:
                  oneOf:
                  - $ref: '#/components/schemas/VcsUpload'
                  - $ref: '#/components/schemas/UrlUpload'
                  - $ref: '#/components/schemas/ServerUpload'
                scanOptions:
                  $ref: '#/components/schemas/ScanOptions'
                mainLicense:
                  type: string
                  description: Main license shortname for the upload.
                  example: MIT
          multipart/form-data:
            schema:
              type: object
              properties:
                fileInput:
                  type: string
                  format: binary
                scanOptions:
                  $ref: '#/components/schemas/ScanOptions'
                mainLicense:
                  type: string
                  description: Main license shortname for the upload.
                  example: MIT
              required:
              - fileInput
      parameters:
      - name: folderId
        description: Folder Id, where upload should be created
        in: header
        required: true
        schema:
          type: integer
      - name: uploadDescription
        description: Visible description of the file
        in: header
        required: false
        schema:
          type: string
      - name: public
        description: The access level to the upload
        in: header
        required: false
        schema:
          type: string
          enum:
          - private
          - protected
          - public
          default: protected
      - name: applyGlobal
        description: 'Apply global decisions for current upload

          '
        in: header
        required: false
        schema:
          type: boolean
          default: false
      - name: ignoreScm
        description: 'Ignore SCM files (Git, SVN, TFS) and files with particular Mimetype

          '
        in: header
        required: false
        schema:
          type: boolean
          default: false
      - name: uploadType
        description: Type of upload done. Choose `file` if uploading a file.
        in: header
        required: true
        schema:
          type: string
          enum:
          - file
          - vcs
          - url
          - server
          default: vcs
      responses:
        '201':
          description: Upload is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/download:
    parameters:
    - name: id
      in: path
      required: true
      description: Download file using Upload ID
      schema:
        type: integer
    get:
      operationId: getUploadFileById
      tags:
      - Upload
      summary: Download the file
      description: 'Get a file by upload id

        '
      responses:
        '200':
          description: Required report
          content:
            text/plain:
              schema:
                type: string
                format: binary
        '403':
          description: Upload is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/summary:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: groupName
      description: The group name to chose while accessing the package
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    - name: agentId
      required: false
      description: Id of the agent
      in: query
      schema:
        type: integer
    get:
      operationId: getSummaryByUploadId
      tags:
      - Upload
      summary: Get single upload summary
      description: Returns summary for single upload
      responses:
        '200':
          description: Get summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSummary'
        '503':
          description: 'The ununpack agent has not started yet. Please check the ''Look-at'' header for more information

            '
          headers:
            Look-at:
              description: Contains the URL to get jobs for the given upload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/item/{itemId}/info:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      description: Upload tree Id of the file
      in: path
      required: true
      schema:
        type: integer
    get:
      operationId: getItemInfo
      tags:
      - Upload
      summary: Get single file info
      description: Returns info for single file
      responses:
        '200':
          description: Get info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fileinfo'
        '404':
          description: 'Item does not exist

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/licenses:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: agent
      required: true
      description: Name of the agent
      in: query
      schema:
        type: array
        items:
          type: string
          enum:
          - nomos
          - monk
          - ninka
          - ojo
          - reportImport
          - reso
          - scancode
        uniqueItems: true
      style: form
      explode: false
    - name: containers
      required: false
      description: Show directories and containers
      in: query
      schema:
        type: boolean
        default: true
    - name: license
      required: false
      description: Show license in response
      in: query
      schema:
        type: boolean
        default: true
    - name: copyright
      required: false
      description: Show copyrights in response
      in: query
      schema:
        type: boolean
        default: false
    - name: page
      description: Page number (starts from 1)
      required: false
      in: header
      schema:
        type: integer
        default: 1
        minimum: 1
    - name: limit
      description: Limits of responses per request
      required: false
      in: header
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 1000
    - name: groupName
      description: The group name to chose while accessing the package
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getLicensesByUploadId
      tags:
      - Upload
      summary: Get licenses found by agent
      description: Returns the list of licenses found by requested agent
      responses:
        '200':
          description: Get licenses
          headers:
            X-Total-Pages:
              description: Total number of pages which can be generated based on limit
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadLicenses'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '503':
          description: 'The ununpack agent or queried agents have not started yet. Please check the ''Look-at'' header for more information.

            '
          headers:
            Look-at:
              description: Contains the URL to get jobs for the given upload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '412':
          description: 'The agent has not been scheduled for the upload. Please check the response message.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/copyrights:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    get:
      operationId: getCopyrightsByUploadId
      tags:
      - Upload
      summary: Get copyrights found on the upload
      description: Returns the list of copyrights found on the requested upload.
      responses:
        '200':
          description: Get copyrights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadCopyrights'
        '503':
          description: 'The ununpack agent or copyright agents have not started yet. Please check the ''Look-at'' header for more information.

            '
          headers:
            Look-at:
              description: Contains the URL to get jobs for the given upload
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '412':
          description: 'The agent has not been scheduled for the upload. Please check the response message.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/permissions:
    parameters:
    - name: id
      required: true
      description: Enter any upload id
      in: path
      schema:
        type: integer
    put:
      operationId: setUploadPermissions
      tags:
      - Upload
      summary: Set permissions for a upload in a folder for different groups
      description: 'Set permissions for a upload in a folder for different groups

        '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                folderId:
                  type: integer
                  description: Enter a folder id
                allUploadsPermission:
                  type: boolean
                  enum:
                  - true
                  - false
                  description: Apply same permissions to all uploads in this folder
                groupId:
                  type: integer
                  description: Enter the id of the group you want to add or edit permission for this upload
                newPermission:
                  type: string
                  enum:
                  - none
                  - read_only
                  - read_write
                  - clearing_admin
                  - admin
                  description: Select the permission for selected group
                publicPermission:
                  type: string
                  enum:
                  - none
                  - read_only
                  - read_write
                  - clearing_admin
                  - admin
                  description: Select the public permission for this upload
              required:
              - allUploadsPermission
      responses:
        '202':
          description: Permissions updated successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '404':
          description: Upload does not exist
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        '503':
          description: Scheduler is not running
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/perm-groups:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    get:
      operationId: getGroupsWithPermissions
      tags:
      - Upload
      summary: Get all the groups with their respective permissions for a upload
      description: Returns the list of all the groups with their respective permissions for a upload
      responses:
        '200':
          description: Get Groups with permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadPermGroups'
        '404':
          description: Upload does not exist
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/item/{itemId}/highlight:
    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
    - name: clearingId
      required: false
      description: Id of the clearing event
      in: query
      schema:
        type: integer
    - name: licenseId
      required: false
      description: Id of the license
      in: query
      schema:
        type: integer
    - name: highlightId
      required: false
      description: Id of the highlight
      in: query
      schema:
        type: integer
    - name: agentId
      required: false
      description: Id of the agent
      in: query
      schema:
        type: integer
    get:
      operationId: getHighlightEntries
      tags:
      - Upload
      summary: Get highlight entries of the content.
      description: 'Get highlight entries of the content for the given upload and item id.

        '
      responses:
        '200':
          description: List of the data about highlight entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HighlightInfo'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Resource Not Found
          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'
  /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:
      - Upload
      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'
  /uploads/{id}/item/{itemId}/clearing-decision:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      required: true
      description: Id of the itemId
      in: path
      schema:
        type: integer
    put:
      operationId: setClearingDecision
      tags:
      - Upload
      summary: Set the clearing decision for a particular upload tree item.
      description: 'Set the clearing decision for a particular upload tree item.

        '
      requestBody:
        description: ClearingDecision payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearingDecision'
      responses:
        '200':
          description: Clearing decision set successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Invalid clearingDecision type or invalid set globalDecision value
          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'
  /uploads/{id}/item/{itemId}/bulk-scan:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      required: true
      description: Id of the itemId
      in: path
      schema:
        type: integer
    post:
      operationId: scheduleBulkScan
      tags:
      - Upload
      summary: Schedule the bulk scan for the item
      description: 'Schedule the bulk scan for the item

        '
      requestBody:
        description: ClearingInfo payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleBulkScan'
      responses:
        '200':
          description: Bulk scan scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /uploads/{id}/item/{itemId}/bulk-history:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      required: true
      description: Id of the itemId
      in: path
      schema:
        type: integer
    get:
      operationId: getBulkHistory
      tags:
      - Upload
      summary: Get the bulk history
      description: 'Get the bulk history for a specific upload item

        '
      responses:
        '200':
          description: List of the data about the bulk history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetBulkHistory'
        '404':
          description: Resource Not Found
          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'
  /uploads/{id}/item/{itemId}/licenses:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    - name: itemId
      required: true
      description: Id of the itemId
      in: path
      schema:
        type: integer
    get:
      operationId: getLicenseDecisions
      tags:
      - Upload
      summary: Get the license decisions list
      description: 'Get the license decisions list for the given upload and item id

        '
      responses:
        '200':
          description: List of the license decisions for the upload-tree id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LicenseDecision'
        '404':
          description: Resource Not Found
          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'
    put:
      operationId: addEditDeleteLicenseDecision
      tags:
      - Upload
      summary: Add, update or delete a license decision.
      description: 'Add, update or delete a license decision for a particular upload tree item.

        '
      requestBody:
        description: Add, update or delete
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AddEditDeleteLicenseDecision'
      responses:
        '200':
          description: Request processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: array
                    description: List of the items' responses whose requests processed successfully.
                    items:
                      $ref: '#/components/schemas/Info'
                  errors:
                    type: array
                    description: List of the errors found.
                    items:
                      $ref: '#/components/schemas/Info'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Resource Not Found
          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'
  /uploads/{id}/licenses/main:
    parameters:
    - name: id
      required: true
      description: Id of the upload
      in: path
      schema:
        type: integer
    get:
      operationId: getMainLicenses
      tags:
      - Upload
      summary: Get main licenses on the upload
      description: 'Get main licenses assigned on a particular upload

        '
      responses:
        '200':
          description: All main licenses from an upload
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'
        '404':
          description: Upload not found.
          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'
    post:
      operationId: setMainLicense
      tags:
      - Upload
      summary: Set the main license for the upload
      description: 'Set the main license for a particular upload.

        '
      requestBody:
        description: MainLicense payload
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMainLicens

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