---
swagger: "2.0"
info:
  description: "API to support pVacSeq user interface for generating reports on pipeline\
    \ results"
  version: "1.0.0"
  title: "pVacSeq Server Schema"
host: "localhost"
schemes:
- "https"
produces:
- "application/json"
paths:
  /api/v1/processes/{id}/results:
    get:
      tags:
      - "results"
      summary: "Get available output files from the requested pVAC-Seq run"
      description: "The results endpoint returns a list of available pipeline data\
        \ files for generating reports.  If the requested process is still running \
        this endpoint returns an empty list. If the id is invalid it will return an error\n"
      operationId: "pvacseq.server.controllers.default_controller.results_get"
      parameters:
      - name: "id"
        in: "path"
        description: "Process ID from which to fetch results"
        required: true
        type: "integer"
      responses:
        200:
          description: "An array of results"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Result"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
      x-tags:
      - tag: "results"
  /api/v1/processes/{id}/results/{fileID}:
    get:
      tags:
      - "file"
      summary: "Get pipeline output data"
      description: "This endpoint returns raw data from the requested output file \
        from the requested pVAC-Seq run.  If the process is still running this will \
        return an empty list.  If the id or fileID is invalid, it will return an error\n"
      operationId: "pvacseq.server.controllers.default_controller.results_getfile"
      parameters:
      - name: "id"
        in: "path"
        description: "Process ID from which to read results"
        required: true
        type: "integer"
      - name: "count"
        in: "query"
        description: "Number of results to return"
        required: false
        type: "integer"
        default: 10
      - name: "page"
        in: "query"
        description: "Page number of results to return"
        required: false
        type: "integer"
        default: 1
      - name: "fileID"
        in: "path"
        description: "File id from which to read data"
        required: true
        type: "integer"
      responses:
        200:
          description: "An array of entries"
          schema:
            type: "array"
            items: {
              type: "object"
            }
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
      x-tags:
      - tag: "file"
  /api/v1/processes/{id}/results/{fileID}/cols:
    get:
      tags:
      - "columns"
      summary: "Get column mappings"
      description: "This endpoint returns mappings from standardized column names\
        to their names as they appear in the source data of the specified file. \
        If the process is still running, this will return an empty object. \
        If the process id or fileID are invalid, it will return an error \n"
      operationId: "pvacseq.server.controllers.default_controller.results_getcols"
      parameters:
      - name: "id"
        in: "path"
        description: "Process ID from which to read results"
        required: true
        type: "integer"
      - name: "fileID"
        in: "path"
        description: "File id from which to read data"
        required: true
        type: "integer"
      responses:
        200:
          description: "An object mapping the columns"
          schema:
            type: "object"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
      x-tags:
      - tag: "cols"
  /api/v1/start:
    post:
      tags:
      - "start"
      summary: "Start a new pVAC-Seq run"
      description: "This endpoint initiates a new pVAC-Seq run and returns the \
        api process id (not an OS pid) for the new run.\n"
      operationId: "pvacseq.server.controllers.default_controller.start"
      parameters:
      - name: "input"
        in: "formData"
        description: "Input VCF File: Filepath to the input VCF file"
        required: true
        type: "string"
      - name: "samplename"
        in: "formData"
        description: "Sample Name: Name for your sample"
        required: true
        type: "string"
      - name: "alleles"
        in: "formData"
        description: "Alleles: A comma-separated list of alleles to run the sequences against"
        required: true
        type: "string"
      - name: "epitope_lengths"
        in: "formData"
        description: "Epitope Lengths: A comma-separated list of epitope lengths to produce"
        required: false
        type: "string"
        default: "10"
      - name: "prediction_algorithms"
        in: "formData"
        description: "Prediction Algorithms: A comma-separated list of prediction algorithms to use"
        required: true
        type: "string"
      - name: "output"
        in: "formData"
        description: "Output Directory: The directory to which output will be written"
        required: true
        type: "string"
      - name: "peptide_sequence_length"
        in: "formData"
        description: "Peptide Sequence Length: Length of the peptide sequences to produce in the FASTA"
        required: false
        type: "integer"
        default: 21
      - name: "additional_input_file_list"
        in: "formData"
        description: "Additional Input File List: yaml file of additional files to be used as inputs, e.g. cufflinks output files"
        required: false
        type: "string"
        default: ""
      - name: "net_chop_method"
        in: "formData"
        description: "Net Chop Method: Run NetChop using the specified method"
        type: "string"
        enum: ["cterm", "20s"]
        required: false
        default: ''
      - name: "netmhc_stab"
        in: "formData"
        description: "NetMHC STAB: Run NetMHCStabPan at the end of the pipeline"
        type: "boolean"
        default: false
      - name: "top_result_per_mutation"
        in: "formData"
        description: "Top Result Per Mutation: Output top scoring candidate per allele-length per mutation"
        type: "boolean"
        default: false
      - name: "top_score_metric"
        in: "formData"
        description: "Top Score Metric: ic50 metric for choosing best epitopes during binding filtering"
        type: "string"
        enum: ["lowest", "median"]
        default: "median"
      - name: "binding_threshold"
        in: "formData"
        description: "Binding Threshold: Report only epitopes with a predicted binding score below this value"
        type: "integer"
        default: 500
      - name: "minimum_fold_change"
        in: "formData"
        description: "Minimum Fold Change: Report only epitopes with a fold change between the mutant and wildtype sequences above this value"
        type: "integer"
        default: 0
      - name: "normal_cov"
        in: "formData"
        description: "Normal Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "5"
      - name: "tdna_cov"
        in: "formData"
        description: "Tumor DNA Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "10"
      - name: "trna_cov"
        in: "formData"
        description: "Tumor RNA Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "10"
      - name: "normal_vaf"
        in: "formData"
        description: "Normal VAF Cutoff: Sites below this cutoff will be considered"
        type: "integer"
        default: "2"
      - name: "tdna_vaf"
        in: "formData"
        description: "Tumor DNA VAF Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "40"
      - name: "trna_vaf"
        in: "formData"
        description: "Tumor RNA VAF Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "40"
      - name: "expn_val"
        in: "formData"
        description: "Gene and Transcript Expression cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: 1
      - name: "net_chop_threshold"
        in: "formData"
        description: "NetChop Threshold: NetChop prediction threshold"
        type: "number"
        default: 0.5
      - name: "fasta_size"
        in: "formData"
        description: "FASTA Size: Number of entries submitted to IEDB in each request.  Must be an even number"
        type: "integer"
        default: 200
      - name: "iedb_retries"
        in: "formData"
        description: "IEDB Retries: Number of retries when making requests to the IEDB RESTful web interface. Must be less than or equal to 100"
        type: "integer"
        default: 5
      - name: "downstream_sequence_length"
        in : "formData"
        description: "Downstream Sequence Length: Cap to limit the downstream sequence length for frameshifts when creating the fasta file. Use 'full' to include the full downstream sequence"
        type: "string"
        default: "1000"
      - name: "keep_tmp_files"
        in: "formData"
        description: "Keep Temp Files? Keep temporary files in the output directory after completion"
        type: "boolean"
        default: false
      responses:
        200:
          description: "Returns the process ID of the newly started pVAC-Seq run"
          schema:
            type: "integer"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
      x-tags:
      - tag: "test"
  /api/v1/staging:
    post:
      tags:
      - "staging"
      summary: "Start a new pVAC-Seq run from a web form"
      description: "This endpoint serves as an intermediary between a web form \
        and the start endpoint.  Uploaded files are saved to temporary locations \
        and their paths are forwarded to the start endpoint.  Additionally, an output \
        directory is automatically generated\n"
      operationId: "pvacseq.server.controllers.default_controller.staging"
      parameters:
      - name: "input"
        in: "formData"
        description: "Input VCF File: Local VCF file"
        required: true
        type: "file"
      - name: "samplename"
        in: "formData"
        description: "Sample Name: Your name for the sample"
        required: true
        type: "string"
      - name: "alleles"
        in: "formData"
        description: "Alleles: A comma-separated list of alleles to run the sequences against"
        required: true
        type: "string"
      - name: "epitope_lengths"
        in: "formData"
        description: "Epitope Lengths: A comma-separated list of epitope lengths to produce"
        required: false
        type: "string"
        default: "10"
      - name: "prediction_algorithms"
        in: "formData"
        description: "Prediction Algorithm: A comma-separated list of prediction algorithms to use"
        required: true
        type: "string"
      - name: "peptide_sequence_length"
        in: "formData"
        description: "Peptide Sequence Length: Length of the peptide sequences to produce in the FASTA"
        required: false
        type: "integer"
        default: 21
      - name: "gene_expn_file"
        in: "formData"
        description: "Gene Expression File: Filepath to the genes.fpkm_tracking file from Cufflinks"
        required: false
        type: "string"
        default: ""
      - name: "transcript_expn_file"
        in: "formData"
        description: "Transcript Expression File: Filepath to the isoforms.fpkm_tracking file from Cufflinks"
        required: false
        type: "string"
        default: ""
      - name: "normal_snvs_coverage_file"
        in: "formData"
        description: "Normal SNVs Coverage File: Filepath to bam-readcount output file for normal BAM and snvs"
        required: false
        type: "string"
        default: ""
      - name: "normal_indels_coverage_file"
        in: "formData"
        description: "Normal Indels Coverage File: Filepath to bam-readcount output file for normal BAM and indels"
        required: false
        type: "string"
        default: ""
      - name: "tdna_snvs_coverage_file"
        in: "formData"
        description: "Tumor DNA Coverage File: Filepath to bam-readcount output file for tumor DNA BAM and snvs"
        required: false
        type: "string"
        default: ""
      - name: "tdna_indels_coverage_file"
        in: "formData"
        description: "Tumor DNA Coverage File: Filepath to bam-readcount output file for tumor DNA BAM and indels"
        required: false
        type: "string"
        default: ""
      - name: "trna_snvs_coverage_file"
        in: "formData"
        description: "Tumor RNA Coverage File: Filepath to bam-readcount output file for tumor RNA BAM and snvs"
        required: false
        type: "string"
        default: ""
      - name: "trna_indels_coverage_file"
        in: "formData"
        description: "Tumor RNA Coverage File: Filepath to bam-readcount output file for tumor RNA BAM and indels"
        required: false
        type: "string"
        default: ""
      - name: "net_chop_method"
        in: "formData"
        description: "Net Chop Method: Run NetChop using the specified method"
        type: "string"
        enum: ["cterm", "20s", ""]
        required: false
        default: ''
      - name: "netmhc_stab"
        in: "formData"
        description: "NetMHC STAB: Run NetMHCStabPan at the end of the pipeline"
        required: false
        type: "string"
        default: ""
      - name: "top_result_per_mutation"
        in: "formData"
        description: "Top Results per Mutation: Output top scoring candidate per allele-length per mutation"
        required: false
        type: "string"
        default: ""
      - name: "top_score_metric"
        in: "formData"
        description: "Top Score Metric: ic50 metric for choosing best epitopes during binding filtering"
        required: false
        type: "string"
        enum: ["lowest", "median"]
        default: "median"
      - name: "binding_threshold"
        in: "formData"
        description: "Binding Threshold: Report only epitopes with a predicted binding score below this value"
        required: false
        type: "integer"
        default: 500
      - name: "minimum_fold_change"
        in: "formData"
        description: "Medium Fold Change: Report only epitopes with a fold change between the mutant and wildtype sequences above this value"
        required: false
        type: "integer"
        default: 0
      - name: "normal_cov"
        in: "formData"
        description: "Normal Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "5"
      - name: "tdna_cov"
        in: "formData"
        description: "Tumor DNA Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "10"
      - name: "trna_cov"
        in: "formData"
        description: "Tumor RNA Coverage Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "10"
      - name: "normal_vaf"
        in: "formData"
        description: "Normal VAF Cutoff: Sites below this cutoff will be considered"
        type: "integer"
        default: "2"
      - name: "tdna_vaf"
        in: "formData"
        description: "Tumor DNA VAF Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "40"
      - name: "trna_vaf"
        in: "formData"
        description: "Tumor RNA VAF Cutoff: Sites above this cutoff will be considered"
        type: "integer"
        default: "40"
      - name: "expn_val"
        in: "formData"
        description: "Gene and Transcript Expression cutoff: Sites above this cutoff will be considered"
        required: false
        type: "integer"
        default: 1
      - name: "net_chop_threshold"
        in: "formData"
        description: "NetChop Threshold: NetChop prediction threshold"
        required: false
        type: "number"
        default: 0.5
      - name: "fasta_size"
        in: "formData"
        description: "FASTA Size: Number of entries submitted to IEDB in each request.  Must be an even number"
        required: false
        type: "integer"
        default: 200
      - name: "iedb_retries"
        in: "formData"
        description: "IEDB Retries: Number of retries when making requests to the IEDB RESTful web interface. Must be less than or equal to 100"
        type: "integer"
        default: 5
      - name: "downstream_sequence_length"
        in : "formData"
        description: "Downstream Sequence Length: Cap to limit the downstream sequence length for frameshifts when creating the fasta file. Use 'full' to include the full downstream sequence"
        type: "string"
        default: "1000"
      - name: "keep_tmp_files"
        in: "formData"
        description: "Keep Temp Files? Keep temporary files in the output directory after completion"
        required: false
        type: "string"
        default: ""
      responses:
        200:
          description: "Returns the process ID of the newly started pVAC-Seq run"
          schema:
            type: "integer"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
      x-tags:
      - tag: "staging"
  /api/v1/processes:
    get:
      tags:
        - "processes"
      summary: "Get list of running processes"
      description: "This endpoint returns a list of active pvacseq runs\n"
      operationId: "pvacseq.server.controllers.default_controller.processes"
      responses:
        200:
          description: "A list of active processes"
          schema:
            type: "array"
            items: {
              $ref: "#/definitions/ProcessSummary"
            }
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /api/v1/processes/{id}:
    get:
      tags:
        - "processes"
      summary: "Get info about a specific process"
      description: "This endpoint returns data about a currently running process. \
        If the process id is invalid, it returns an error.\n"
      operationId: "pvacseq.server.controllers.default_controller.process_info"
      parameters:
      - name: "id"
        in: "path"
        description: "Process id of an active pVAC-Seq run"
        required: true
        type: "integer"
      responses:
        200:
          description: "Returns all data collected about the requested process"
          schema:
            $ref: "#/definitions/Process"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /api/v1/shutdown:
    get:
      tags:
        - "shutdown"
      summary: "Terminate any running processes"
      description: "This endpoint handles the cleanup for closing any active \
        pvacseq runs\n"
      operationId: "pvacseq.server.controllers.default_controller.shutdown"
      responses:
        200:
          description: "Returns a list of the process ID's for the terminated processes"
          schema:
            type: "array"
            items: {
              type: "integer"
            }
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /api/v1/stop/{id}:
    get:
      tags:
        - "stop"
      summary: "Terminate the specified process"
      description: "This endpoint closes the requested process if it is still running. /
        id must refer to a valid process id started by the current user"
      operationId: "pvacseq.server.controllers.default_controller.stop"
      parameters:
      - name: "id"
        in: "path"
        description: "Process id of an active pVAC-Seq run"
        required: true
        type: "integer"
      responses:
        200:
          description: "Returns the status of the process just before termination"
          schema:
            $ref: "#/definitions/Process"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /api/v1/checkallele:
    get:
      tags:
        - "allele"
      summary: "Verifies that the specified allele is supported"
      description: "Checks the supplied allele against the list of supported alleles \
        and returns a boolean indicating if the allele is supported or not"
      operationId: "pvacseq.server.controllers.default_controller.check_allele"
      parameters:
        - name: "allele"
          in: "query"
          description: "Allele name to check"
          required: true
          type: "string"
      responses:
        200:
          description: "Returns a boolean indicating if the allele is supported or not"
          schema:
            type: "boolean"
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /api/v1/reset:
    get:
      tags:
        - "reset"
      summary: "Resets the log of old processes"
      description: "Clears out processes which were started by previous instances \
        of the ui server.  Processes started by this instance will be kept unless \
        the clearall paramter is set to 1"
      operationId: "pvacseq.server.controllers.default_controller.reset"
      parameters:
        - name: "clearall"
          in: "query"
          description: "Informs the controller to drop all processes, not just old ones"
          type: "integer"
          default: 0
      responses:
        200:
          description: "Returns a list of cleared process id's (which are now \
            invalid until reassigned by starting new runs)"
          schema:
            type: "array"
            items: {
              type: "integer"
            }
        default:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/Error"
  /static/testpage:
    get:
      tags:
        - "test"
      summary: "A test submission form"
      description: "Returns a web page containing a form for submitting a new pVAC-Seq run. \
        Submission is sent to the /api/v1/staging endpoint, where it is processed \
        then forwarded to the /api/v1/start endpoint\n"
      produces:
        - "text/html"
      operationId: "pvacseq.server.controllers.default_controller.test"
      responses:
        200:
          description: "Returns a static page"
          schema:
            type: "string"
definitions:
  Process:
    type: "object"
    properties:
      pid:
        type: "integer"
        description: "Actual pid assigned by the OS for this pVAC-Seq run"
      id:
        type: "integer"
        description: "Unique process ID used for accessing the process data through the api"
      command:
        type: "string"
        description: "The shell command issued to start this pVAC-Seq run"
      status:
        type: "string"
        description: "The most recent message sent by pVAC-Seq"
      log:
        type: "string"
        description: "The full output transcript from pVAC-Seq"
      output:
        type: "string"
        description: "The output folder of the specified process"
      running:
        type: "boolean"
        description: "Indicates whether or not the process is still running"
      attached:
        type: "boolean"
        description: "Indicates whether or not the process is still directly attached \
          to the server, or if the process has become orphaned"
  Result:
    type: "object"
    properties:
      id:
        type: "integer"
        description: "Unique identifier of the result file."
      description:
        type: "string"
        description: "Description of result file"
      display_name:
        type: "string"
        description: "Display name of result file (try to keep under 32 chars or so)"
      url:
        type: "string"
        description: "URL of results file"
      size:
        type: "string"
        description: "Size of data file, in bytes"
  ProcessSummary:
    type: "object"
    properties:
      id:
        type: "integer"
        description: "Unique process ID used for accessing the process data through the api"
      running:
        type: "boolean"
        description: "Indicates whether or not the process is still running"
  Error:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      message:
        type: "string"
      fields:
        type: "string"