Optilogic Workspace API

openapi: 3.2.0
info:
  description: "All Optilogic users can view the endpoint documentation below, <a href='https://optilogic.app/#/user-account?tab=pricing'>upgrade to a paid account</a> to gain access.<br /><br />Once you have api access, use the `refreshApiKey` endpoint with your account login information or use the `Quick Start` form below to get started.\n### Installing Additional Python Packages <a id=\"installing-additional-python-packages\"></a>\nWhen a job is run - such as when using the **Job POST** endpoint - the system will check the directoryPath specified in the POST call for a file named `requirements.txt`. If the file exists, then the system will attempt to install all packages specified by running `pip install -r requirements.txt` before running the file specified in the filePath parameter.\n### Accessing your Files <a id=\"accessing-your-files\"></a>\nYour files are stored in the */projects* directory of the workspace. Files saved in this directory are available to your *Atlas* workspace and to REST API endpoints.\nAll directory paths passed as a *directoryPath*, *sourceDirectoryPath*, or *targetDirectoryPath* parameter are relative to the */projects* directory.\nThis means you must **not** include */projects* as part of the path string.\n\nExample:\n  - directoryPath = \"pyomo-examples/models/diet-problem\"\n  - filePath = \"diet-problem.py\"\n\nExample:\n  - directoryPath = \".\"\n  - filePath = \"my-model.py\"\n\n<br>\n\n## Example Application <a id=\"example-app\"></a>\n\n<a target=\"_blank\" href=\"https://optilogic.github.io/optiapp-web-demo/\">OptiJS Demo</a>\n\nThis demo application uses the OptiJS client library to run and monitor jobs from Python modules on a users' account. Custom applications can be quickly created on top of the Optilogic API using the <a target=\"_blank\" href=\"https://cdn.optilogic.app/web/optijs/api.js\">OptiJS</a> and <a target=\"_blank\" href=\"https://pypi.org/project/optilogic\">OptiPy</a> client libraries.\n\n\n<br>\n"
  version: 1.0.0
  title: Optilogic REST Workspace API
  contact:
    name: Optilogic Support
    email: support@optilogic.com
servers:
- url: https://api.optilogic.app/v0
tags:
- name: workspace
  description: Get information about a workspace, including job and file information
paths:
  /workspaces:
    get:
      tags:
      - workspace
      summary: Get a list of available workspaces in an account
      description: ''
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}:
    get:
      tags:
      - workspace
      summary: Get information about a workspace
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Workspace name to get information
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/jobs:
    get:
      tags:
      - workspace
      summary: List the jobs for a specific workspace
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Workspace to list jobs from
        required: true
        schema:
          type: string
      - name: command
        in: query
        description: Filter by command property
        required: false
        schema:
          type: string
      - name: history
        in: query
        description: Filter by submitted property. Number of days or 'All'. Default is 7.
        required: false
        schema:
          type: string
      - name: runSecsMax
        in: query
        description: Filter by runTime property. Maximum seconds (list only where runTime is less than)
        required: false
        schema:
          type: integer
      - name: runSecsMin
        in: query
        description: Filter by runTime property. Minimum seconds (list only where runTime is greater than)
        required: false
        schema:
          type: integer
      - name: status
        in: query
        description: Filter by status property
        required: false
        schema:
          type: string
          enum:
          - submitted
          - starting
          - started
          - running
          - canceling
          - done
          - stopping
          - stopped
          - cancelled
          - error
      - name: tags
        in: query
        description: Filter by tags property
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/jobs/stats:
    get:
      tags:
      - workspace
      summary: Get the stats only for jobs for a specific workspace
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Workspace to list jobs from
        required: true
        schema:
          type: string
      - name: command
        in: query
        description: Filter by command property
        required: false
        schema:
          type: string
      - name: history
        in: query
        description: Filter by submitted property. Number of days or 'All'. Default is 7.
        required: false
        schema:
          type: string
      - name: runSecsMax
        in: query
        description: Filter by runTime property. Maximum seconds (list only where runTime is less than)
        required: false
        schema:
          type: integer
      - name: runSecsMin
        in: query
        description: Filter by runTime property. Minimum seconds (list only where runTime is greater than)
        required: false
        schema:
          type: integer
      - name: status
        in: query
        description: Filter by status property
        required: false
        schema:
          type: enum
          enum:
          - submitted"
          - starting
          - started
          - running
          - canceling
          - done
          - stopping
          - stopped
          - cancelled
          - error
      - name: tags
        in: query
        description: Filter by tags property
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListStats'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/job:
    post:
      tags:
      - workspace
      summary: Queue a job
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace to run a job from
        required: true
        schema:
          type: string
      - name: directoryPath
        in: query
        description: Path to folder/directory (see [Accessing your Files](#accessing-your-files))
        required: true
        schema:
          type: string
      - name: filename
        in: query
        description: Name of the file to run
        required: true
        schema:
          type: string
      - name: command
        in: query
        description: Modify job behavior to use one of Optilogic's Applied Research tools
        required: false
        schema:
          type: string
          enum:
          - run
          - presolve
          - run_model
          default: run
      - name: commandArgs
        in: query
        description: 'Additional arguments for the selected command


          *Note*: This string is included as provided. Directory and file paths (if any) are **not** inherently relative to */projects* as discussed in [Accessing your Files](#accessing-your-files)


          *Example*: "/tmp/some_file.txt --verbose"

          '
        required: false
        schema:
          type: string
      - name: resourceConfig
        in: query
        description: Resource configuration (cpu and ram) used to run a job
        required: false
        schema:
          type: string
          enum:
          - mini
          - 4XS
          - 3XS
          - 2XS
          - XS
          - S
          - M
          - L
          - XL
          - 2XL
          - 3XL
          - 4XL
          default: 3XS
      - name: tags
        in: query
        description: Comma-separated list of tags for the job.
        required: false
        schema:
          type: string
      - name: timeout
        in: query
        description: Maximum job runtime in seconds. The job will be canceled if it runs past this value.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobPost'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
      security:
      - APIKeyHeader: []
  /{workspace}/job/{jobKey}:
    get:
      tags:
      - workspace
      summary: Get job information
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace where the job is running
        required: true
        schema:
          type: string
      - name: jobKey
        in: path
        description: Key of target job
        required: true
        schema:
          type: string
      - name: op
        in: query
        description: Operation - 'status' gets the job status, 'log' downloads a zip file with job info, results, and errors, 'result' downloads the job's result file, 'error' downloads the job's error file
        required: false
        schema:
          type: string
          enum:
          - status
          - log
          - result
          - error
          default: status
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
    delete:
      tags:
      - workspace
      summary: Stop a queued or running job
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace where the job is running
        required: true
        schema:
          type: string
      - name: jobKey
        in: path
        description: Key of target job
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobDelete'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/jobBatch/jobify:
    post:
      tags:
      - workspace
      summary: Queue a list of jobs
      description: Allows you to queue jobs from a list of python modules.
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace that contains your python modules.
        required: true
        schema:
          type: string
      - name: resourceConfig
        in: query
        description: Resource configuration (cpu and ram) used for any jobs that will be queued.
        required: false
        schema:
          type: string
          enum:
          - mini
          - 4XS
          - 3XS
          - 2XS
          - XS
          - S
          - M
          - L
          - XL
          - 2XL
          - 3XL
          - 4XL
          default: 3XS
      - name: tags
        in: query
        description: Comma-separated list of tags for the jobs that will queued.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobifyPost'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                batchItems:
                  type: array
                  example:
                  - pyModulePath: /projects/My Files/Advanced Model Template/Advanced Model Template_gurobi.py
                  - pyModulePath: /projects/Model Library/MIP Optimization/cutting_sheet_metal/cutting_sheet_metal.py
                    commandArgs: arg1 arg2
                    timeout: 300
                  items:
                    type: object
                    properties:
                      pyModulePath:
                        description: The path to the python module that will be run.
                        type: string
                        required: true
                      commandArgs:
                        description: Arguments to send to the python module.
                        type: string
                        required: false
                      timeout:
                        description: Maximum job runtime in seconds. The job will be canceled if it runs past this value.
                        type: integer
                        required: false
        description: Sequential list of python modules to be queued
        required: true
  /{workspace}/jobBatch/jobify/searchNRun:
    post:
      tags:
      - workspace
      summary: Queue a list of jobs from a list of search terms
      description: Allows you to send a list of search terms and queue all matching python modules as jobs.
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace that contains your python modules.
        required: true
        schema:
          type: string
      - name: resourceConfig
        in: query
        description: Resource configuration (cpu and ram) used for any jobs that will be queued.
        required: false
        schema:
          type: string
          enum:
          - mini
          - 4XS
          - 3XS
          - 2XS
          - XS
          - S
          - M
          - L
          - XL
          - 2XL
          - 3XL
          - 4XL
          default: 3XS
      - name: tags
        in: query
        description: Comma-separated list of tags for the jobs that will queued.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobifyPost'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                batchItems:
                  type: array
                  example:
                  - pySearchTerm: Transportation
                    commandArgs: -hours 48
                  - pySearchTerm: MIP Optimization/flow_shop_scheduling
                    timeout: 300
                  items:
                    type: object
                    properties:
                      pySearchTerm:
                        description: Search term that allows us to find the right python modules.
                        type: string
                        required: true
                      commandArgs:
                        description: Arguments to send to the matching python modules.
                        type: string
                        required: false
                      timeout:
                        description: Maximum job runtime in seconds. All matches will be canceled if they run past this value.
                        type: integer
                        required: false
        description: Sequential list of search items. Matches will be queued as new jobs.
        required: true
  /{workspace}/jobBatch/backToBack:
    post:
      tags:
      - workspace
      summary: Run a list of python modules
      description: Run a list of python modules, as a single job, back to back, one after another.
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace that contains your python modules.
        required: true
        schema:
          type: string
      - name: resourceConfig
        in: query
        description: Resource configuration (cpu and ram) used to run this job.
        required: false
        schema:
          type: string
          enum:
          - mini
          - 4XS
          - 3XS
          - 2XS
          - XS
          - S
          - M
          - L
          - XL
          - 2XL
          - 3XL
          - 4XL
          default: 3XS
      - name: tags
        in: query
        description: Comma-separated list of tags for this job.
        required: false
        schema:
          type: string
      - name: timeout
        in: query
        description: Maximum job runtime in seconds. The job will be canceled if it runs past this value.
        required: false
        schema:
          type: integer
      - name: verboseOutput
        in: query
        description: When enabled, adds descriptive information to the output.
        required: false
        schema:
          type: boolean
          enum:
          - false
          - true
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPost'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                batchItems:
                  type: array
                  example:
                  - pyModulePath: /projects/My Files/Advanced Model Template/Advanced Model Template_gurobi.py
                  - pyModulePath: /projects/Model Library/MIP Optimization/cutting_sheet_metal/cutting_sheet_metal.py
                    commandArgs: arg1 arg2
                    timeout: 300
                  items:
                    type: object
                    properties:
                      pyModulePath:
                        description: The python module to run. The full path is required.
                        type: string
                        required: true
                      commandArgs:
                        description: Arguments to send to the python module.
                        type: string
                        required: false
                      timeout:
                        description: Maximum job runtime in seconds for this python module.
                        type: integer
                        required: false
        description: List of python modules. They will be run sequentially, in this order.
        required: true
  /{workspace}/jobBatch/backToBack/searchNRun:
    post:
      tags:
      - workspace
      summary: Run a list of matching python modules.
      description: Allows you to send a list, of search terms, and run all matching python modules, back to back in one job.
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace that contains your python modules.
        required: true
        schema:
          type: string
      - name: resourceConfig
        in: query
        description: Resource configuration (cpu and ram) used for this job.
        required: false
        schema:
          type: string
          enum:
          - mini
          - 4XS
          - 3XS
          - 2XS
          - XS
          - S
          - M
          - L
          - XL
          - 2XL
          - 3XL
          - 4XL
          default: 3XS
      - name: tags
        in: query
        description: Comma-separated list of tags for this job.
        required: false
        schema:
          type: string
      - name: timeout
        in: query
        description: Maximum job runtime in seconds. The job will be canceled if it runs past this value.
        required: false
        schema:
          type: integer
      - name: verboseOutput
        in: query
        description: When enabled, adds descriptive information to the output.
        required: false
        schema:
          type: boolean
          enum:
          - false
          - true
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPost'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
      security:
      - APIKeyHeader: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                batchItems:
                  type: array
                  example:
                  - pySearchTerm: Transportation
                    commandArgs: -hours 48
                  - pySearchTerm: MIP Optimization/flow_shop_scheduling
                    timeout: 300
                  items:
                    type: object
                    properties:
                      pySearchTerm:
                        description: Search term that allows us to find the right python modules.
                        type: string
                        required: true
                      commandArgs:
                        description: Arguments to send to the matching python modules.
                        type: string
                        required: false
                      timeout:
                        description: Maximum runtime in seconds. A match will be canceled if it runs past this value.
                        type: integer
                        required: false
        description: Sequential list of search items. All matching python modules will be run before we look at the next search item.
        required: true
  /{workspace}/files:
    get:
      tags:
      - workspace
      summary: List all user files in the workspace
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Workspace to list files from
        required: true
        schema:
          type: string
      - name: filter
        in: query
        description: Search term to filter results
        required: false
        schema:
          type: string
      - name: maxDepth
        in: query
        description: Limit how many directories deep the search will iterate
        required: false
        schema:
          type: integer
      - name: baseDir
        in: query
        description: Optional starting directory to list files from
        required: false
        schema:
          type: string
      - name: includeDir
        in: query
        description: If true the response will include an array of all directory paths encountered
        required: false
        schema:
          type: boolean
          enum:
          - false
          - true
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/job/{jobKey}/ledger:
    get:
      tags:
      - workspace
      summary: Get records from the specified job's ledger
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace where the job was ran
        required: true
        schema:
          type: string
      - name: jobKey
        in: path
        description: Key of target job
        required: true
        schema:
          type: string
      - name: keys
        in: query
        description: Comma-separated string - Limits records to those whose key appears in the list. No value will return all records
        required: false
        schema:
          type: string
          default: ''
      - name: limit
        in: query
        description: Limit how many records will be returned
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobLedger'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - APIKeyHeader: []
  /{workspace}/job/{jobKey}/metrics:
    get:
      tags:
      - workspace
      summary: Get metrics gathered while the job was running
      description: ''
      parameters:
      - name: workspace
        in: path
        description: Name of the workspace where the job was ran
        required: true
        schema:
          type: string
      - name: jobKey
        in: path
        description: Key of target job
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobMetrics'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
            

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