FOSSology Job API

openapi: 3.1.0
info:
  title: FOSSology Admin Job 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: Job
  description: FOSSology jobs
paths:
  /jobs:
    parameters:
    - name: groupName
      description: The group name to chose while accessing jobs
      in: header
      required: false
      schema:
        type: string
        description: Group name, from last login if not provided
    get:
      operationId: getJobs
      tags:
      - Job
      summary: Gets all jobs created by the logged in user
      description: Returns all jobs with their status created by the logged in user
      parameters:
      - name: limit
        required: false
        schema:
          type: integer
          minimum: 1
        in: header
      - name: page
        required: false
        schema:
          type: integer
          minimum: 1
        in: header
      - name: sort
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        in: query
      - name: status
        description: Returns only jobs with the selected status.
        required: false
        schema:
          type: string
          enum:
          - Processing
          - Queued
          - Completed
          - Failed
        in: query
      - name: upload
        required: false
        schema:
          type: integer
        in: query
        description: Return jobs for the given upload id only
      responses:
        '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/Job'
        default:
          $ref: '#/components/responses/defaultResponse'
    post:
      operationId: startJobs
      tags:
      - Job
      summary: Schedule an Analysis
      description: Schedule an Analysis of an existing upload
      parameters:
      - name: folderId
        in: header
        required: true
        schema:
          type: integer
      - name: uploadId
        in: header
        required: true
        schema:
          type: integer
      requestBody:
        description: Agents to be scheduled with the job
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanOptions'
      responses:
        '201':
          description: Job Scheduled with job id in message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/all:
    get:
      operationId: getAllJobs
      tags:
      - Job
      summary: Gets all jobs created by all users
      description: Returns all jobs with their status created by every user. This API returns a response only if the requesting user is an Admin.
      parameters:
      - name: limit
        required: false
        schema:
          type: integer
          minimum: 1
        in: header
      - name: page
        required: false
        schema:
          type: integer
          minimum: 1
        in: header
      - name: status
        description: Returns only jobs with the selected status.
        required: false
        schema:
          type: string
          enum:
          - Processing
          - Queued
          - Completed
          - Failed
        in: query
      - name: sort
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        in: query
      responses:
        '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/Job'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/scheduler/operation/{operationName}:
    parameters:
    - name: operationName
      required: true
      description: Name of the operation
      in: path
      schema:
        type: string
        enum:
        - status
        - database
        - reload
        - agents
        - verbose
        - stop
        - restart
        - pause
        - priority
    get:
      operationId: getSchedulerOptionsByOperation
      tags:
      - Job
      summary: get scheduler options by operation
      description: Returns the scheduler options for a specific operation
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSchedulerOption'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/scheduler/operation/run:
    parameters:
    - name: job
      required: false
      description: Name of the selected job
      in: query
      schema:
        type: string
    - name: level
      required: false
      description: Level of the selected verbose
      in: query
      schema:
        type: string
    - name: priority
      required: false
      description: Priority option selected
      in: query
      schema:
        type: string
    post:
      operationId: handleSchedulerRun
      tags:
      - Job
      summary: Run the scheduler
      description: Run the scheduler with the selected options from a specific operation
      requestBody:
        description: Scheduler operation
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operation:
                  type: string
                  description: Operation to be run by the scheduler
                  enum:
                  - status
                  - database
                  - reload
                  - agents
                  - verbose
                  - stop
                  - restart
                  - pause
                  - priority
      responses:
        '200':
          description: Scheduler run successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '400':
          description: Bad Request
          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'
  /jobs/{id}:
    parameters:
    - name: id
      required: true
      description: Id of the job
      in: path
      schema:
        type: integer
    get:
      operationId: getJobById
      tags:
      - Job
      summary: Gets single job by id
      description: Returns job with the status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/history:
    parameters:
    - name: upload
      required: true
      in: query
      description: Return jobs for the given upload id
      schema:
        type: integer
    get:
      operationId: getJobsHistoryPerUpload
      tags:
      - Job
      summary: Get the history of all the jobs queued based on an upload
      description: Returns the history of all the jobs queued based on an upload
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShowJob'
        '400':
          description: Bad Request. 'upload' is a required query param
          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'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/dashboard/statistics:
    get:
      operationId: getJobStatistics
      tags:
      - Job
      summary: Get the statistics of all the jobs
      description: Returns the statistics of all the jobs for the Admin Dashboard
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetJobStatistics'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/dashboard:
    get:
      operationId: getAllServerJobs
      tags:
      - Job
      summary: Gets all jobs server jobs with scheduler status
      description: Returns all jobs with the scheduler status for the Admin Dashboard. This API returns a response only if the requesting user is an Admin.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllServerJobs'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /jobs/{id}/{queue}:
    parameters:
    - name: id
      required: true
      description: Id of the Job
      in: path
      schema:
        type: integer
    - name: queue
      required: true
      description: Id of the job queue to be deleted
      in: path
      schema:
        type: integer
    delete:
      operationId: deleteJob
      tags:
      - Job
      summary: Deletes a job using its Id and Queue
      description: Deletes a job queue and all the other job queues depending on it
      responses:
        '200':
          description: Job deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '403':
          description: You don't have permission to delete this job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '404':
          description: Job/JobQueue not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        '500':
          description: Failed to kill job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Info'
        default:
          $ref: '#/components/responses/defaultResponse'
  /report:
    get:
      operationId: getReportsByUpload
      tags:
      - Job
      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:
      - Job
      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'
components:
  schemas:
    GetSchedulerOption:
      type: object
      properties:
        jobList:
          type: array
          description: List of jobs
          items:
            type: string
          example:
          - scheduler
        priorityList:
          type: array
          description: List of priorities
          items:
            type: integer
          example:
          - -20
          - -19
          - -18
        verboseList:
          type: array
          description: List of verbose levels
          items:
            type: integer
          example:
          - 1
          - 3
        agentList:
          type: array
          description: List of agents
          items:
            type: string
          example:
          - clixml
          - pkgagent
          - maintagent
          - deciderjob
    GetJobStatistics:
      type: object
      properties:
        agentName:
          type: string
          description: Name of the agent
          example: monkbulk
        agentDesc:
          type: string
          description: Description of the agent
          example: monkbulk agent
        firedJobs:
          type: integer
          description: Number of fired jobs
          example: 23
    ShowJob:
      description: History of all the jobs and the job queue info
      type: object
      properties:
        jobId:
          type: integer
          description: Job ID
        jobName:
          type: string
          description: Job name (generally upload name)
        jobQueue:
          type: array
          items:
            $ref: '#/components/schemas/JobQueue'
          description: Jobs queued for the current job
        uploadId:
          type: integer
          description: Upload ID to which the job belongs to.
    JobQueue:
      description: Structure of jobs queue
      type: object
      properties:
        jobQueueId:
          description: Job queue id
          type: integer
        jobQueueType:
          description: Job queue type (generally agent name)
          type: string
        startTime:
          description: Job queue start time
          type: string
        endTime:
          description: Job queue end time
          type: string
        status:
          description: Job queue completion status
          type: string
        itemsProcessed:
          description: Number of items processed
          type: integer
        log:
          description: Location of log file if exists
          type: string
          nullable: true
        dependencies:
          description: List of dependent job queue ids
          type: array
          items:
            type: integer
        itemsPerSec:
          description: Number of items processed per second
          type: number
          format: float
        canDoActions:
          description: Job can accept new actions like pause and cancel
          type: boolean
        isInProgress:
          description: Checks if the job queue is still in progress
          type: boolean
        isReady:
          description: Is the job ready
          type: boolean
        download:
          description: Report download information
          type: object
          nullable: true
          properties:
            text:
              description: Text for download link
              type: string
            link:
              description: Link to download the report
              type: string
    Job:
      type: object
      properties:
        id:
          type: integer
          description: ID of the job
        name:
          type: string
          description: Name of the job
        queueDate:
          type: string
          description: When the job was queued
        uploadId:
          type: integer
          description: Upload for which the job was scheduled
        userId:
          type: integer
          description: User who scheduled the job
        groupId:
          type: integer
          description: Group under which the job was scheduled
        eta:
          type: integer
          description: ETA of job to finish in seconds
        status:
          type: string
          enum:
          - Completed
          - Failed
          - Queued
          - Processing
          description: Denotes the current status of the job in the queue
    ScanOptions:
      type: object
      properties:
        analysis:
          $ref: '#/components/schemas/Analysis'
        decider:
          $ref: '#/components/schemas/LicenseDecider'
        reuse:
          $ref: '#/components/schemas/Reuser'
        scancode:
          $ref: '#/components/schemas/Scancode'
    AllServerJobs:
      type: object
      properties:
        data:
          type: array
          description: List of agents
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the agent
                example: decider
              running:
                type: integer
                description: Number of running instances
                example: 0
              pending:
                type: integer
                description: Number of pending instances
                example: 1
              eta:
                type: string
                description: Estimated time of arrival
                example: N/A
        scheduler:
          type: string
          description: Current scheduler status
          enum:
          - Running
          - Stopped
    LicenseDecider:
      type: object
      properties:
        nomos_monk:
          type: boolean
          description: Scanners matches if all Nomos findings are within the Monk findings.
        bulk_reused:
          type: boolean
          description: Bulk phrases from reused packages.
        new_scanner:
          type: boolean
          description: New scanner results, i.e., decisions were marked as work in progress if new scanner finds additional licenses.
        ojo_decider:
          type: boolean
          description: Scanners matches if Ojo or REUSE.Software findings are no contradiction with other findings.
        conclude_license_type:
          type: string
          description: 'Auto conclude license if they are of provided type.

            Omit the field or keep as empty string to not use this option.

            '
          example: Permissive
        copyright_deactivation:
          type: boolean
          description: Deactivate false positive copyrights (experimental).
        copyright_clutter_removal:
          type: boolean
          description: Deactivate false positive copyrights and remove clutter from them (experimental).
    Scancode:
      type: object
      properties:
        license:
          type: boolean
          description: A full comparison between the database of licenses present in ScanCode and the code uploaded by users based approach.
        copyright:
          type: boolean
          description: Copyright along with copyright holder/author information.
        email:
          type: boolean
          description: Email(s) present in the scan code file.
        url:
          type: boolean
          description: URL(s) present in the scan code file.
    Analysis:
      type: object
      properties:
        bucket:
          type: boolean
          description: Should bucket analysis be run on this upload
        copyright_email_author:
          type: boolean
          description: Should Copyright/Email/URL/Author Analysis be run on this upload.
        ecc:
          type: boolean
          description: Should ECC Analysis be run on this upload.
        patent:
          type: boolean
          description: Should IPRA Analysis be run on this upload.
        keyword:
          type: boolean
          description: Should keyword Analysis be run on this upload.
        mime:
          type: boolean
          description: Should MIME Analysis be run on this upload.
        monk:
          type: boolean
          description: Should Monk Analysis be run on this upload.
        nomos:
          type: boolean
          description: Should Nomos Analysis be run on this upload.
        ojo:
          type: boolean
          description: Should OJO Analysis be run on this upload.
        package:
          type: boolean
          description: Should Package Analysis be run on this upload.
        reso:
          type: boolean
          description: Should REUSE.Software Analysis be run on this upload.
        heritage:
          type: boolean
          description: Should Software Heritage Analysis be run on this upload.
        compatibility:
          type: boolean
          description: Should Compatibility Analysis be run on this upload.
    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
    Reuser:
      type: object
      properties:
        reuse_upload:
          type: integer
          description: The UploadID to reuse.
        reuse_group:
          type: string
          description: The group of the reused upload
        reuse_main:
          type: boolean
          description: Copy the main license from reused package?
        reuse_enhanced:
          type: boolean
          description: Run enhanced reuser with diff tool (slow)
        reuse_report:
          type: boolean
          description: Copy all report configuration from conf page.
        reuse_copyright:
          type: boolean
          description: Copy the copyright deactivation and edits.
      required:
      - reuse_upload
      - reuse_group
  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'