openapi: 3.0.3
info:
  title: Biodock Public Analysis Jobs API
  description: Biodock's public REST API lets users invoke actions on the Biodock platform through simple web requests, so an AI microscopy image analysis built on Biodock can be integrated into scripts and programs. Actions invoked through the API are also reflected in the Biodock dashboard (uploaded files appear in the Filesystem, submitted analysis jobs appear on the results page). The API is in beta; resources may change. Note that creating an AI model and creating or publishing pipelines are visual, dashboard-only workflows and cannot be done through the API.
  version: 1.0.0-beta
  contact:
    name: Biodock Support
    url: https://docs.biodock.ai/company/contact-us
    email: security@biodock.ai
  termsOfService: https://www.biodock.ai/termsprivacy
servers:
- url: https://app.biodock.ai/api/external
  description: Biodock public API (production)
security:
- ApiKeyAuth: []
tags:
- name: Analysis Jobs
  description: Submitting, tracking, and downloading analysis jobs
paths:
  /analysis-jobs:
    get:
      operationId: listAnalysisJobs
      summary: List analysis jobs
      description: List the progress of all your analysis jobs.
      tags:
      - Analysis Jobs
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of analysis jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisJobList'
    post:
      operationId: submitAnalysisJob
      summary: Submit analysis job
      description: Submit an analysis job. The files must already be uploaded to the Biodock Filesystem and you must have a published, user-created analysis pipeline. Biodock-authored pipelines are not supported via the API.
      tags:
      - Analysis Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - pipelineId
              - filesystemIds
              properties:
                pipelineId:
                  type: string
                  description: Pipeline to use for analysis.
                filesystemIds:
                  type: array
                  items:
                    type: string
                  description: Filesystem items to analyze.
                name:
                  type: string
                  description: Name of the job.
      responses:
        '200':
          description: Analysis job submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisJob'
  /analysis-jobs/{id}:
    get:
      operationId: fetchAnalysisJob
      summary: Fetch analysis job
      description: View the progress and results of a specific analysis job.
      tags:
      - Analysis Jobs
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The analysis job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisJob'
  /analysis-jobs/{id}/download-masks:
    post:
      operationId: submitDownloadMasksJob
      summary: Submit download masks job
      description: Generate the masks data for an analysis job. Masks data is not generated by default during an analysis job.
      tags:
      - Analysis Jobs
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: Masks generation submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MasksJob'
    get:
      operationId: fetchDownloadMasksJob
      summary: Fetch download masks job
      description: View the progress of masks generation and, once complete, obtain the masks download link.
      tags:
      - Analysis Jobs
      parameters:
      - $ref: '#/components/parameters/PathId'
      responses:
        '200':
          description: The masks download job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MasksJob'
components:
  schemas:
    AnalysisJob:
      type: object
      properties:
        id:
          type: string
        percentageCompleted:
          type: integer
        status:
          type: string
          enum:
          - PENDING
          - SUBMITTED
          - RUNNING
          - SUCCEEDED
          - FAILED
        objectsDataCSVUrl:
          type: string
          format: uri
        aggregateDataCSVUrl:
          type: string
          format: uri
    AnalysisJobList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisJob'
        count:
          type: integer
    MasksJob:
      type: object
      properties:
        percentageCompleted:
          type: integer
        status:
          type: string
          enum:
          - SUBMITTED
          - RUNNING
          - SUCCEEDED
          - FAILED
        masksZipUrl:
          type: string
          format: uri
  parameters:
    StartingAfter:
      name: startingAfter
      in: query
      schema:
        type: string
      description: Pagination cursor id (id of the last item on the previous page).
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: limit
      in: query
      schema:
        type: integer
      description: Maximum number of results to show.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key generated at https://app.biodock.ai/settings/api