openapi: 3.1.1
info:
  title: Fastfold API
  version: 1.0.0
  contact:
    name: FastFold API Support
    email: hello@fastfold.ai
  license:
    name: Proprietary
    url: https://fastfold.ai
servers:
  - url: https://api.fastfold.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Jobs
    description: Create and manage jobs
  - name: Library
    description: Manage folders, files, and search in your library
  - name: Workflows
    description: Create, configure, execute, and inspect workflow runs
paths:
  /v1/jobs:
    post:
      tags:
        - Jobs
      summary: Create Job
      description: >
        Create a new job to fold protein sequences using AI models. The job will
        be processed

        asynchronously and you can track its status using the returned job ID.
      operationId: createJob
      parameters:
        - name: from
          in: query
          description: Optional library item ID to associate with this job
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Job creation request with sequences and parameters
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobInput"
            examples:
              boltz2Affinity:
                summary: Boltz-2 affinity with ligand CCD
                value:
                  name: My Boltz-2 Affinity Job
                  isPublic: false
                  sequences:
                    - proteinChain:
                        sequence: MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQGVDDAFYTLVREIRKHKE
                    - ligandSequence:
                        sequence: U4U
                        is_ccd: true
                        property_type: affinity
                  params:
                    modelName: boltz-2
              complexWithConstraints:
                summary: Protein complex with constraints
                value:
                  name: Protein Complex with Pocket
                  sequences:
                    - proteinChain:
                        sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSQELLSRYPDLDAKGRERAIAKDLGAVFLVGIGGKLSDGHRHDVRAPDYDDWSTPSELGHAGLNGDILVWNPVLEDAFELSSMGIRVDADTLKHQLALTGDEDRLELEWHQALLRGEMPQTIGGGIGQSRLTMLLLQLPHIGQVQAGVWPAAVRESVPSLL
                        chain_id: A
                        count: 1
                    - proteinChain:
                        sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSQELLSRYPDLDAKGRERAIAKDLGAVFLVGIGGKLSDGHRHDVRAPDYDDWSTPSELGHAGLNGDILVWNPVLEDAFELSSMGIRVDADTLKHQLALTGDEDRLELEWHQALLRGEMPQTIGGGIGQSRLTMLLLQLPHIGQVQAGVWPAAVRESVPSLL
                        chain_id: B
                        count: 1
                  params:
                    modelName: multimer
                    relaxPrediction: true
                  constraints:
                    pocket:
                      - binder:
                          chain_id: A
                        contacts:
                          - chain_id: B
                            res_idx: 10
                          - chain_id: B
                            res_idx: 11
              boltz2WithModifications:
                summary: Boltz-2 model with modifications
                value:
                  name: Modified Protein
                  sequences:
                    - proteinChain:
                        sequence: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSQELLSRYPDLDAKGRERAIAKDLGAVFLVGIGGKLSDGHRHDVRAPDYDDWSTPSELGHAGLNGDILVWNPVLEDAFELSSMGIRVDADTLKHQLALTGDEDRLELEWHQALLRGEMPQTIGGGIGQSRLTMLLLQLPHIGQVQAGVWPAAVRESVPSLL
                        chain_id: A
                        modifications:
                          - res_idx: 5
                            ccd: PTM
                        cyclic: true
                  params:
                    modelName: boltz-2
                    recyclingSteps: 3
                    samplingSteps: 10
                    diffusionSample: 1
                    stepScale: 0.1
                    affinityMwCorrection: true
                    samplingStepsAffinity: 5
                    diffusionSamplesAffinity: 1
              streptococcalProteinGPocket:
                summary: Streptococcal protein G with ATP pocket constraint
                value:
                  name: Streptococcal protein G with Pocket
                  sequences:
                    - proteinChain:
                        sequence: MTYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE
                        chain_id: A
                    - ligandSequence:
                        sequence: ATP
                        is_ccd: true
                        chain_id: B
                  params:
                    modelName: boltz-2
                  constraints:
                    pocket:
                      - binder:
                          chain_id: B
                        contacts:
                          - chain_id: A
                            res_idx: 12
                          - chain_id: A
                            res_idx: 15
                          - chain_id: A
                            res_idx: 18
              humanKRASG12CWithCovalentLigand:
                summary: Human KRAS G12C protein with covalent ligand bond
                value:
                  name: Human KRAS G12C protein with covalent ligand
                  sequences:
                    - proteinChain:
                        sequence: MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQGVDDAFYTLVREIRKHKE
                        chain_id: A
                    - ligandSequence:
                        sequence: U4U
                        is_ccd: true
                        chain_id: B
                  params:
                    modelName: boltz-2
                  constraints:
                    bond:
                      - atom1:
                          chain_id: A
                          res_idx: 12
                          atom_name: SG
                        atom2:
                          chain_id: B
                          res_idx: 1
                          atom_name: C22
              esm1bOpenFold:
                summary: ESM1b OpenFold style folding
                value:
                  name: ESM1b OpenFold
                  sequences:
                    - proteinChain:
                        sequence: MGLSDGEWQLVLNVWGKVEADIPGHGQEVLIRLFKGHPETLERFDKFKHLKSEDEMKASEDLKKHGATVLTALGGILKKKGHHEAEIKPLAQSHATKHKIPVKYLEFISECIIQVLQSKHPGDFGADAQRAMNKALELFRKDMASNYKELGFQG
                        chain_id: A
                  params:
                    modelName: esm1b
              monomerAlphaFold2:
                summary: Monomer AlphaFold2
                value:
                  name: Monomer AlphaFold2
                  sequences:
                    - proteinChain:
                        sequence: MGLSDGEWQLVLNVWGKVEADIPGHGQEVLIRLFKGHPETLERFDKFKHLKSEDEMKASEDLKKHGATVLTALGGILKKKGHHEAEIKPLAQSHATKHKIPVKYLEFISECIIQVLQSKHPGDFGADAQRAMNKALELFRKDMASNYKELGFQG
                        chain_id: A
                  params:
                    modelName: monomer
              multimerAlphaFold2:
                summary: Multimer AlphaFold2
                value:
                  name: Multimer AlphaFold2
                  sequences:
                    - proteinChain:
                        sequence: MCNTNMSVSTEGAASTSQIPASEQETLVRPKPLLLKLLKSVGAQNDTYTMKEIIFYIGQYIMTKRLYDEKQQHIVYCSNDLLGDVFGVPSFSVKEHRKIYAMIYRNLVAV
                        chain_id: A
                    - proteinChain:
                        sequence: SQETFSGLWKLLPPE
                        chain_id: B
                  params:
                    modelName: multimer
              complexDnaBoltz:
                summary: Protein-DNA complex using Boltz
                value:
                  name: Complex DNA Boltz
                  sequences:
                    - proteinChain:
                        sequence: MASSRRESINPWILTGFADAEGSFGLSILNRNRGTARYHTRLSFTIMLHNKDKSILENIQSTWKVGSILNNGDHYVSLVVYRFEDLKVIIDHFEKYPLITQKLGDYKLFKQAFSVMENKEHLKENGIKELVRIKAKMNWGLNDELKKAFPENISKERPLINKNIPNFKWLAGFTSGDGSFFVRLRKSNVNARVRVQLVFEISQHIRDKNLMNSLITYLGCGHIYEGNKSERSWLQFRVEKFSDINDKIIPVFQENTLIGVKLEDFEDWCKVAKLIEEKKHLTESGLDEIKKIKLNMNKGR
                        chain_id: A
                    - dnaSequence:
                        sequence: GGGGGCATGCAGATCCCACAGGCGCG
                        chain_id: B
                    - dnaSequence:
                        sequence: CCGCGCCTGTGGGATCTGCATGCCCC
                        chain_id: C
                  params:
                    modelName: boltz
              boltz2AffinityLigandSmiles:
                summary: Boltz-2 affinity with ligand SMILES
                value:
                  name: Boltz-2 Affinity Ligand Smiles
                  sequences:
                    - proteinChain:
                        sequence: PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMSLPGRWKPKMIGGIGGFIKVRQYDQILIEICGHKAIGTVLVGPTPVNIIGRNLLTQIGCTLNF
                        chain_id: A
                    - ligandSequence:
                        sequence: CC1CN(CC(C1)NC(=O)C2=CC=CC=C2N)C(=O)NC(C)(C)C
                        chain_id: B
                  params:
                    modelName: boltz-2
              simpleFold100M:
                summary: SimpleFold 100M
                value:
                  name: SimpleFold 100M
                  sequences:
                    - proteinChain:
                        sequence: GASKLRAVLEKLKLSRDDISTAAGMVKGVVDHLLLRLKCDSAFRGVGLLNTGSYYEHVKISAPNEFDVMFKLEVPRIQLEEYSNTRAYYFVKFKRNPKENPLSQFLEGEILSASKMLSKFRKIIKEEINDDTDVIMKRKRGGSPAVTLLISEKISVDITLALESKSSWPASTQEGLRIQNWLSAKVRKQLRLKPFYLVPKHAEETWRLSFSHIEKEILNNHGKSKTCCENKEEKCCRKDCLKLMKYLLEQLKERFKDKKHLDKFSSYHVKTAFFHVCTQNPQDSQWDRKDLGLCFDNCVTYFLQCLRTEKLENYFIPEFNLFSSNLIDKRSKEFLTKQIEYERNNEFPVFD
                        chain_id: A
                  params:
                    modelName: simplefold_100M
      responses:
        "200":
          description: Job created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
              example:
                jobId: 550e8400-e29b-41d4-a716-446655440000
                jobRunId: 660e8400-e29b-41d4-a716-446655440001
                jobName: My Protein Fold
                jobStatus: INITIALIZED
                sequencesIds:
                  - 770e8400-e29b-41d4-a716-446655440002
        "400":
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Invalid sequence format
        "401":
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Unauthorized
        "429":
          description: Too Many Requests - Daily quota exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: "Daily quota exceeded. Limit: 30 calls per day. Current: 30 calls."
  /v1/jobs/{jobId}/results:
    get:
      tags:
        - Jobs
      summary: Get Job Results
      description: >
        Fetch job + latest job run + sequences for a job ID.


        - If the job is **public** (`isPublic: true`), authentication is **not
        required**.

        - If the job is **not public** (`isPublic: false` or `null`),
        authentication is required and the caller must own the job.
      operationId: getJobResults
      security:
        - bearerAuth: []
        - {}
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Job ID
      responses:
        "200":
          description: Job results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResultsOutput"
              examples:
                complexJob:
                  summary: Complex job (top-level predictionPayload)
                  value:
                    job:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      status: COMPLETED
                      name: Job_2026-01-06_18:46
                      date: 2026-01-06T23:46:14.413714
                      updatedAt: 2026-01-06T23:48:17.564509
                      isComplex: true
                      isPublic: true
                    parameters:
                      count: 2
                      createdAt: 2026-01-06T23:46:14.423605
                      modelName: boltz-2
                      weightSet: Boltz-2
                      method: Boltz-2
                      relaxPrediction: true
                    sequences:
                      - id: f989c0c1-37ac-4f6e-aacf-579ebe79c22e
                        createdAt: 2026-01-06T23:46:14.417233
                        updatedAt: 2026-01-06T23:48:20.503840
                        name: null
                        sequence: MTYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE
                        type: protein
                      - id: 42aea8ca-4cec-450a-890f-fd13d6625809
                        createdAt: 2026-01-06T23:46:14.417247
                        updatedAt: 2026-01-06T23:48:20.503840
                        name: null
                        sequence: ATP
                        type: ligand
                    predictionPayload:
                      predictionStatus: COMPLETED
                      jobRunStatus: COMPLETED
                      msaStatus: PENDING
                      prediction: true
                      error: null
                      meanPLLDT: 76.26388669013977
                      executionTimeInMinutes: 1.99
                      pdb_url: ""
                      cif_url: https://artifacts.fastfold.ai/.../output_model_0.cif
                      msa_coverage_plot_url: null
                      pae_plot_url: https://artifacts.fastfold.ai/.../PAE_heatmap.svg
                      plddt_plot_url: https://artifacts.fastfold.ai/.../pLDDT_plot.svg
                      metrics_json_url: https://artifacts.fastfold.ai/.../plddt_pae_metrics.json
                      config_json_url: null
                      citations_bibtex_url: null
                      plots_url: ""
                      ptm_score: 0.8331819772720337
                      iptm_score: 0.6137562990188599
                      max_pae_score: null
                      seed: "1496388795"
                      execution_time_in_minutes: 1.99
                      affinity_result_raw_json:
                        affinity_pred_value: 0.9314461946487427
                        affinity_probability_binary: 0.38347506523132324
                nonComplexJob:
                  summary: Non-complex job (per-sequence predictionPayload)
                  value:
                    job:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      status: COMPLETED
                      name: Job_2026-01-07_12:58
                      date: 2026-01-07T17:58:40.989292
                      updatedAt: 2026-01-07T18:00:07.805305
                      isComplex: false
                      isPublic: false
                    parameters:
                      count: 2
                      createdAt: 2026-01-07T17:58:41.531574
                      modelName: monomer
                      weightSet: AlphaFold
                      method: ColabFold
                      relaxPrediction: true
                    sequences:
                      - id: a1fb8db4-001c-4a74-90e3-4f7bb075f40f
                        createdAt: 2026-01-07T17:58:41.256587
                        updatedAt: 2026-01-07T17:59:53.647548
                        name: null
                        sequence: MCNTNMSVSTEGAASTSQIPASEQETLVRPKPLLLKLLKSVGAQNDTYTMKEIIFYIGQYIMTKRLYDEKQQHIVYCSNDLLGDVFGVPSFSVKEHRKIYAMIYRNLVAV
                        type: protein
                        predictionPayload:
                          predictionStatus: COMPLETED
                          jobRunStatus: COMPLETED
                          msaStatus: PENDING
                          prediction: true
                          error: "File not found: output_a1fb8db4-001c-4a74-90e3-4f7bb075f40f.cif"
                          meanPLLDT: 85.86245454545454
                          executionTimeInMinutes: 1.2
                          pdb_url: https://artifacts.fastfold.ai/.../rank_001.pdb
                          cif_url: https://artifacts.fastfold.ai/.../output.cif
                      - id: 75cdd52a-eddc-46cb-81f2-0d7af3fe7f9d
                        createdAt: 2026-01-07T17:58:41.256616
                        updatedAt: 2026-01-07T18:00:06.175863
                        name: null
                        sequence: SQETFSGLWKLLPPE
                        type: protein
                        predictionPayload:
                          predictionStatus: COMPLETED
                          jobRunStatus: COMPLETED
                          msaStatus: PENDING
                          prediction: true
                          error: "File not found: output_75cdd52a-eddc-46cb-81f2-0d7af3fe7f9d.cif"
                          meanPLLDT: 76.30466666666668
                          executionTimeInMinutes: 1.4
                          pdb_url: https://artifacts.fastfold.ai/.../rank_001.pdb
                          cif_url: https://artifacts.fastfold.ai/.../output.cif
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Job not found
  /v1/jobs/{jobId}/public:
    patch:
      tags:
        - Jobs
      summary: Update Job Public Visibility
      description: >
        Update a job's `isPublic` flag.

        Authentication is required and **only the job owner** can change this
        field.
      operationId: updateJobPublic
      security:
        - bearerAuth: []
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Job ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobPublicUpdate"
            examples:
              makePublic:
                summary: Make job public
                value:
                  isPublic: true
              makePrivate:
                summary: Make job private
                value:
                  isPublic: false
      responses:
        "200":
          description: Updated job visibility
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobPublicUpdateResponse"
              example:
                jobId: 550e8400-e29b-41d4-a716-446655440000
                isPublic: true
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Unauthorized
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Job not found
  /v1/library/create:
    post:
      tags:
        - Library
      summary: Create library item
      description: Create a new folder or file in the library.
      operationId: createLibraryItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLibraryItemRequest"
            examples:
              createFolder:
                summary: Create folder
                value:
                  name: Workflow Inputs
                  type: folder
              createFile:
                summary: Create file item
                value:
                  name: design-spec-input-1.yml
                  type: file
                  fileType: input
                  origin: USER_UPLOAD
                  metadata:
                    usedBy:
                      - type: PROJECT
                        id: 30a39083-2ab8-4f48-a1bf-49dba0a2f470
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibraryItem"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Parent folder not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/library/{item_id}/upload-files:
    post:
      tags:
        - Library
      summary: Upload files to library item
      description: Upload one or more files to an existing library item folder.
      operationId: uploadFilesToLibraryItem
      parameters:
        - $ref: "#/components/parameters/ItemId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                label:
                  type: string
                pae_json:
                  type: string
      responses:
        "200":
          description: Updated item with uploaded files metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibraryItem"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Library item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/library/{item_id}/files/{file_name}:
    put:
      tags:
        - Library
      summary: Replace library file
      description: Replace an existing file and return replacement details.
      operationId: replaceLibraryItemFile
      parameters:
        - $ref: "#/components/parameters/ItemId"
        - $ref: "#/components/parameters/FileName"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Replaced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReplaceFileResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Item or file not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/library/search:
    get:
      tags:
        - Library
      summary: Search library
      description: Search library items by name.
      operationId: searchLibrary
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: recent
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibrarySearchResponse"
              example:
                q: workflow
                count: 1
                results:
                  - id: 75f9dca4-7d64-4bc2-8b18-a08ad6d2f4b3
                    name: workflow.yml
                    type: file
                    fileType: input
                    createdAt: 2026-02-22T20:31:33.007374
                    updatedAt: 2026-02-22T20:31:34.316422
                    parentId: 13b7cf85-2e55-4fd2-8750-b3b4517e6f62
                    parentName: Workflow Inputs
                    metadata: {}
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/library/{item_id}:
    get:
      tags:
        - Library
      summary: Get library item by ID
      description: Return a single file/folder item. For folders, returns nested children.
      operationId: getLibraryItem
      parameters:
        - $ref: "#/components/parameters/ItemId"
        - name: fetch_PAE
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Library item
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibraryItem"
        "404":
          description: Item not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/library/list:
    get:
      tags:
        - Library
      summary: List root library items
      description: List root-level items with filters and cursor pagination.
      operationId: listLibrary
      parameters:
        - name: file_type
          in: query
          required: false
          schema:
            type: string
        - name: project_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
        - name: updated_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: updated_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: skip
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Root library listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibraryListResponse"
              example:
                root:
                  - id: 13b7cf85-2e55-4fd2-8750-b3b4517e6f62
                    name: Workflow Inputs
                    type: folder
                    createdAt: 2026-02-22T20:31:33.007374
                    updatedAt: 2026-02-22T20:31:34.316422
                    colorHex: "#1f2937"
                count: 1
                next_cursor: null
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/workflows/graph/add:
    post:
      tags:
        - Workflows
      summary: Create a boltzgen v1 workflow
      description: |
        Create a new workflow graph shell.
        The backend creates a workflow workspace by default.
      operationId: addWorkflowGraph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkflowInput"
            examples:
              createBoltzgenV1:
                summary: Create a boltzgen v1 workflow
                value:
                  name: My workflow via API
                  workflow_name: boltzgen_v1
      responses:
        "200":
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRunResponse"
              example:
                status: PENDING
                workflow_id: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
                tasks_total_count: 0
                workflow_type: boltzgen_v1
                input_sequence: null
                tasks_completed_count: 0
                tasks_failed_count: 0
                tasks: []
                created_at: 2026-02-22T20:31:33.007374
                updated_at: 2026-02-22T20:31:34.316422
                name: My workflow via API
                reasoning_markdown_results: null
                user_id: 9a361e2b-0d22-4f08-8f26-c3c7a1266e48
                log_file_url: null
                library_item_workspace_id: 5cb0c786-5217-4d98-8ac6-6d9f6585f0db
                input_payload: null
                project_id: null
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Unsupported workflow type
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Unauthorized
  /v1/workflows/{workflow_id}/workflow.yml:
    get:
      tags:
        - Workflows
      summary: Get workflow YAML spec
      description: |
        Returns the current workflow graph serialized as YAML.
      operationId: getWorkflowYml
      parameters:
        - $ref: "#/components/parameters/WorkflowId"
      responses:
        "200":
          description: Workflow YAML
          content:
            application/yaml:
              schema:
                type: string
              example: >
                version: 1

                jobs:
                  start:
                    type: start
                    description: Workflow start point
                    label: Start
                  design_spec:
                    type: input
                    subType: design_specification_yml
                    description: Define entities (proteins, ligands, files) and constraints for the design specification. Library item files must be managed via the Library API.
                    workflowTaskTypeId: input_design_spec_boltzgen_v1
                    inputPayload:
                      inputYML: c92a75eeda074fd1a3975220da72595e_design-spec-input-1.yml
                      inputYMLLibraryItemId: 932243a2-f830-4a98-9009-117f46e2bf4d
                      files:
                      - libraryItemId: b7d3fe21-a56b-43fb-a613-71914868bafe
                        fileName: 75bd9bfef02d4e29a718fe28442dfc4f_5cqg.cif
                    label: Design Spec
                  boltzgen:
                    type: pipeline
                    subType: boltzgen
                    description: Boltzgen pipeline with multiple processing steps
                    workflowTaskTypeId: pipeline_run_boltzgen_v1
                    inputPayload:
                      protocolName: protein-anything
                      numDesigns: 5
                      budget: 2
                    label: Boltzgen
                  end:
                    type: end
                    description: End of your workflow
                    label: End
                workflows:
                  main:
                    jobs:
                      - start
                      - design_spec:
                          requires:
                          - start
                      - boltzgen:
                          requires:
                          - design_spec
                      - end:
                          requires:
                          - boltzgen
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Workflow not found
    post:
      tags:
        - Workflows
      summary: Set/replace workflow graph from YAML spec
      description: >
        Replace the workflow graph with a YAML spec, then sync a canonical
        `workflow.yml`

        artifact in the workflow workspace.


        For `inputPayload.files` and other library item references, files must
        be managed

        through the [Library API](/library/createLibraryItem).
      operationId: setWorkflowYml
      parameters:
        - $ref: "#/components/parameters/WorkflowId"
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: string
            examples:
              boltzgenSpec:
                summary: Boltzgen workflow YAML with nodes and dependencies
                value: >
                  version: 1

                  jobs:
                    start:
                      type: start
                      description: Workflow start point
                      label: Start
                    design_spec:
                      type: input
                      subType: design_specification_yml
                      description: Define entities (proteins, ligands, files) and constraints for the design specification. Library item files must be managed via the Library API.
                      workflowTaskTypeId: input_design_spec_boltzgen_v1
                      inputPayload:
                        inputYML: c92a75eeda074fd1a3975220da72595e_design-spec-input-1.yml
                        inputYMLLibraryItemId: 932243a2-f830-4a98-9009-117f46e2bf4d
                        files:
                        - libraryItemId: b7d3fe21-a56b-43fb-a613-71914868bafe
                          fileName: 75bd9bfef02d4e29a718fe28442dfc4f_5cqg.cif
                      label: Design Spec
                    boltzgen:
                      type: pipeline
                      subType: boltzgen
                      description: Boltzgen pipeline with multiple processing steps
                      workflowTaskTypeId: pipeline_run_boltzgen_v1
                      inputPayload:
                        protocolName: protein-anything
                        numDesigns: 5
                        budget: 2
                      label: Boltzgen
                    end:
                      type: end
                      description: End of your workflow
                      label: End
                  workflows:
                    main:
                      jobs:
                      - start
                      - design_spec:
                          requires:
                          - start
                      - boltzgen:
                          requires:
                          - design_spec
                      - end:
                          requires:
                          - boltzgen
      responses:
        "200":
          description: Workflow graph replaced and workflow.yml synced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowYmlSetResponse"
              example:
                workflowId: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
                graph:
                  workflowId: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
                  nodes: []
                  edges: []
                workflowYml:
                  createdLibraryItem: false
                  libraryItemId: 7df594c6-cf7a-4da6-838e-feecf0165602
                  fileName: workflow.yml
                  versionId: c0fdad95-b2f8-4f54-8740-dcbf7b4820ba
        "400":
          description: Invalid YAML or graph data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Empty YAML spec
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/workflows/execute:
    post:
      tags:
        - Workflows
      summary: Execute workflow
      description: |
        Trigger execution for a workflow.
        Currently supports `boltzgen_v1`.
      operationId: executeWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkflowExecuteRequest"
            example:
              workflowId: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
      responses:
        "200":
          description: Execution accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowRunResponse"
              example:
                status: INITIALIZED
                workflow_id: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
                tasks_total_count: 0
                workflow_type: boltzgen_v1
                input_sequence: null
                tasks_completed_count: 0
                tasks_failed_count: 0
                tasks: []
                created_at: 2026-02-22T20:31:33.007374
                updated_at: 2026-02-22T20:31:34.316422
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Invalid workflowId
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /v1/workflows/status/{workflow_id}:
    get:
      tags:
        - Workflows
      summary: Get workflow status
      operationId: getWorkflowStatus
      parameters:
        - $ref: "#/components/parameters/WorkflowId"
      responses:
        "200":
          description: Workflow status with task states
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowStatusResponse"
              example:
                workflow_id: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
                status: RUNNING
                created_at: 2026-02-22T20:31:33.007374
                updated_at: 2026-02-22T20:35:01.104221
                tasks:
                  - task_id: 9e96cfe4-df9b-46cd-9ad4-93ed413f2fbe
                    task_type: input_design_spec_boltzgen_v1
                    status: COMPLETED
                    node_id: 065aa1da-274d-44a9-b090-cd89f9dc130f
                    order_index: 1
                  - task_id: 3b13e529-5f60-42c1-b5fc-cf2354e72e9e
                    task_type: pipeline_run_boltzgen_v1
                    status: RUNNING
                    node_id: 4fdbfd17-ef2a-4d11-aacb-6f82a11668fa
                    order_index: 2
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Workflow not found
  /v1/workflows/logs/{workflow_id}:
    get:
      tags:
        - Workflows
      summary: Get workflow logs
      description: >
        Returns workflow logs.

        For terminal workflows, the backend serves stored log file content
        (`text/plain`).

        While running, it may proxy upstream log output.
      operationId: getWorkflowLogs
      parameters:
        - $ref: "#/components/parameters/WorkflowId"
      responses:
        "200":
          description: Logs content
          content:
            application/json:
              schema:
                type: string
              example: |
                [2026-02-22 20:35:01] Starting pipeline_run_boltzgen_v1
                [2026-02-22 20:35:10] Loading design spec...
                [2026-02-22 20:35:22] Running boltzgen step...
                [2026-02-22 20:36:58] Completed
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow/log not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Workflow log file not available
  /v1/workflows/task-results/{workflow_id}:
    get:
      tags:
        - Workflows
      summary: Get workflow task results
      operationId: getWorkflowTaskResults
      parameters:
        - $ref: "#/components/parameters/WorkflowId"
      responses:
        "200":
          description: Task results with parsed outputs when available
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkflowTaskResultsResponse"
              example:
                tasksResults:
                  - task_id: 9e96cfe4-df9b-46cd-9ad4-93ed413f2fbe
                    task_type: input_design_spec_boltzgen_v1
                    node_id: 065aa1da-274d-44a9-b090-cd89f9dc130f
                    order_index: 1
                    output_library_items: []
                    parsed_results: null
                  - task_id: 3b13e529-5f60-42c1-b5fc-cf2354e72e9e
                    task_type: pipeline_run_boltzgen_v1
                    node_id: 4fdbfd17-ef2a-4d11-aacb-6f82a11668fa
                    order_index: 2
                    output_library_items:
                      - libraryItemId: d451f2d3-0ee5-4a69-9494-df427fd6a56b
                        fileName: 6e388b8f9bca4c4ca0c22ffbf6a327ec_rank1_model.cif
                    parsed_results:
                      - id: 1
                        final_rank: 1
                        designed_sequence: ACDEFGHIKLMNPQRSTVWY
                        num_design: 1
                        quality_score: 0.91
                        file:
                          libraryItemId: d451f2d3-0ee5-4a69-9494-df427fd6a56b
                          fileName: 6e388b8f9bca4c4ca0c22ffbf6a327ec_rank1_model.cif
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: Workflow not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Bearer token authentication. Use your API key with:
        `Authorization: Bearer <YOUR_API_KEY>`
  schemas:
    JobInput:
      type: object
      required:
        - name
        - sequences
        - params
      properties:
        name:
          type: string
          description: Name of the job
          example: My Protein Fold
        isPublic:
          type: boolean
          description: Whether the job results should be publicly accessible
          default: false
        sequences:
          type: array
          description: List of sequences to fold
          minItems: 1
          items:
            $ref: "#/components/schemas/SequenceInput"
        params:
          $ref: "#/components/schemas/ParamsInput"
        constraints:
          $ref: "#/components/schemas/ConstraintsInput"
        chatId:
          type: string
          format: uuid
          nullable: true
          description: Optional chat ID to associate with this job
          example: 880e8400-e29b-41d4-a716-446655440000
    SequenceInput:
      type: object
      description: >
        Sequence input. Exactly one of proteinChain, rnaSequence, dnaSequence,
        or ligandSequence must be provided.
      properties:
        sourceSequenceId:
          type: string
          format: uuid
          nullable: true
          description: ID of source sequence if cloning from library
        proteinChain:
          $ref: "#/components/schemas/ProteinChainInput"
        rnaSequence:
          $ref: "#/components/schemas/RnaSequenceInput"
        dnaSequence:
          $ref: "#/components/schemas/DnaSequenceInput"
        ligandSequence:
          $ref: "#/components/schemas/LigandSequenceInput"
    ProteinChainInput:
      type: object
      required:
        - sequence
      properties:
        sequence:
          type: string
          description: Amino acid sequence (single letter code)
          example: MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSQELLSRYPDLDAKGRERAIAKDLGAVFLVGIGGKLSDGHRHDVRAPDYDDWSTPSELGHAGLNGDILVWNPVLEDAFELSSMGIRVDADTLKHQLALTGDEDRLELEWHQALLRGEMPQTIGGGIGQSRLTMLLLQLPHIGQVQAGVWPAAVRESVPSLL
        chain_id:
          type: string
          nullable: true
          description: Chain identifier
          example: A
        label:
          type: string
          nullable: true
          description: Human-readable label for the chain
          example: Chain A
        count:
          type: integer
          default: 1
          description: Number of copies of this chain
          minimum: 1
          example: 1
        property_type:
          type: string
          nullable: true
          description: Property type classification
        cyclic:
          type: boolean
          nullable: true
          description: Whether the protein is cyclic
          default: false
        modifications:
          type: array
          nullable: true
          description: List of modifications to apply
          items:
            $ref: "#/components/schemas/ModificationInput"
    RnaSequenceInput:
      type: object
      required:
        - sequence
      properties:
        sequence:
          type: string
          description: RNA sequence (A, U, G, C)
          example: AUGCAUGCAUGCAUGC
        chain_id:
          type: string
          nullable: true
          example: A
        label:
          type: string
          nullable: true
          example: RNA Chain A
        count:
          type: integer
          default: 1
          minimum: 1
        property_type:
          type: string
          nullable: true
        cyclic:
          type: boolean
          nullable: true
          default: false
        modifications:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ModificationInput"
    DnaSequenceInput:
      type: object
      required:
        - sequence
      properties:
        sequence:
          type: string
          description: DNA sequence (A, T, G, C)
          example: ATGCATGCATGCATGC
        chain_id:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        count:
          type: integer
          default: 1
          minimum: 1
        property_type:
          type: string
          nullable: true
        cyclic:
          type: boolean
          nullable: true
          default: false
        modifications:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ModificationInput"
    LigandSequenceInput:
      type: object
      required:
        - sequence
      properties:
        sequence:
          type: string
          description: Ligand sequence or CCD code
          example: HEM
        chain_id:
          type: string
          nullable: true
        label:
          type: string
          nullable: true
        count:
          type: integer
          default: 1
          minimum: 1
        property_type:
          type: string
          nullable: true
        is_ccd:
          type: boolean
          nullable: true
          description: Whether the sequence is a CCD code
          default: false
    ModificationInput:
      type: object
      required:
        - res_idx
        - ccd
      properties:
        res_idx:
          type: integer
          description: Residue index (1-based)
          minimum: 1
          example: 5
        ccd:
          type: string
          description: Chemical Component Dictionary code for the modification
          example: PTM
    ParamsInput:
      type: object
      required:
        - modelName
      properties:
        modelName:
          $ref: "#/components/schemas/ModelName"
        msaAlgorithm:
          type: string
          nullable: true
          description: MSA algorithm to use
          default: jackhmmer
          example: jackhmmer
        relaxPrediction:
          type: boolean
          default: false
          description: Whether to relax the prediction structure
        seed:
          type: string
          nullable: true
          description: Random seed for reproducibility
          example: "12345"
        recyclingSteps:
          type: integer
          nullable: true
          description: Number of recycling steps (for Boltz models)
          minimum: 1
          example: 3
        samplingSteps:
          type: integer
          nullable: true
          description: Number of sampling steps (for Boltz models)
          minimum: 1
          example: 10
        diffusionSample:
          type: integer
          nullable: true
          description: Number of diffusion samples (for Boltz models)
          minimum: 1
          example: 1
        stepScale:
          type: number
          format: float
          nullable: true
          description: Step scale factor (for Boltz models)
          minimum: 0
          example: 0.1
        affinityMwCorrection:
          type: boolean
          nullable: true
          description: Apply molecular weight correction for affinity (for Boltz models)
          default: false
        samplingStepsAffinity:
          type: integer
          nullable: true
          description: Number of sampling steps for affinity (for Boltz models)
          minimum: 1
          example: 5
        diffusionSamplesAffinity:
          type: integer
          nullable: true
          description: Number of diffusion samples for affinity (for Boltz models)
          minimum: 1
          example: 1
    ModelName:
      type: string
      enum:
        - monomer
        - multimer
        - esm1b
        - boltz
        - boltz-2
        - simplefold_100M
        - simplefold_360M
        - simplefold_700M
        - simplefold_1.1B
        - simplefold_1.6B
        - simplefold_3B
      description: >
        Folding model to use:

        - `monomer`: AlphaFold2 for single chain proteins

        - `multimer`: AlphaFold2 for protein complexes

        - `esm1b`: ESM-1b language model

        - `boltz`: Boltz model for protein folding

        - `boltz-2`: Enhanced Boltz-2 model

        - `simplefold_*`: SimpleFold models of varying sizes (100M to 3B
        parameters)
      example: monomer
    ConstraintsInput:
      type: object
      description: Optional constraints to apply during folding
      properties:
        pocket:
          type: array
          nullable: true
          description: Pocket constraints defining binding sites
          items:
            $ref: "#/components/schemas/PocketItemInput"
        bond:
          type: array
          nullable: true
          description: Bond constraints between atoms
          items:
            $ref: "#/components/schemas/BondItemInput"
    PocketItemInput:
      type: object
      required:
        - binder
        - contacts
      properties:
        binder:
          $ref: "#/components/schemas/BinderInput"
        contacts:
          type: array
          description: List of contact residues
          items:
            $ref: "#/components/schemas/ContactInput"
    BinderInput:
      type: object
      required:
        - chain_id
      properties:
        chain_id:
          type: string
          description: Chain ID of the binder
          example: A
    ContactInput:
      type: object
      required:
        - chain_id
        - res_idx
      properties:
        chain_id:
          type: string
          description: Chain ID of the contact residue
          example: B
        res_idx:
          type: integer
          description: Residue index (1-based)
          minimum: 1
          example: 10
    BondItemInput:
      type: object
      required:
        - atom1
        - atom2
      properties:
        atom1:
          $ref: "#/components/schemas/AtomReferenceInput"
        atom2:
          $ref: "#/components/schemas/AtomReferenceInput"
    AtomReferenceInput:
      type: object
      required:
        - chain_id
        - res_idx
        - atom_name
      properties:
        chain_id:
          type: string
          description: Chain ID
          example: A
        res_idx:
          type: integer
          description: Residue index (1-based)
          minimum: 1
          example: 5
        atom_name:
          type: string
          description: Atom name (e.g., CA, N, C, O)
          example: CA
    JobResponse:
      type: object
      description: Response after successfully creating a job
      properties:
        jobId:
          type: string
          format: uuid
          description: Unique identifier for the job
          example: 550e8400-e29b-41d4-a716-446655440000
        jobRunId:
          type: string
          format: uuid
          description: Unique identifier for the job run
          example: 660e8400-e29b-41d4-a716-446655440001
        jobName:
          type: string
          description: Name of the job
          example: My Protein Fold
        jobStatus:
          $ref: "#/components/schemas/JobStatus"
        sequencesIds:
          type: array
          nullable: true
          description: List of sequence IDs created for this job
          items:
            type: string
            format: uuid
          example:
            - 770e8400-e29b-41d4-a716-446655440002
    JobStatus:
      type: string
      enum:
        - PENDING
        - INITIALIZED
        - RUNNING
        - COMPLETED
        - FAILED
        - STOPPED
      description: |
        Current status of the job:
        - `PENDING`: Job is queued but not yet initialized
        - `INITIALIZED`: Job has been created and is ready to run
        - `RUNNING`: Job is currently being processed
        - `COMPLETED`: Job finished successfully
        - `FAILED`: Job encountered an error
        - `STOPPED`: Job was stopped before completion
      example: INITIALIZED
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Workflow not found
    JobRunResultsSummary:
      type: object
      required:
        - count
      properties:
        count:
          type: integer
          description: Number of sequences for the latest job run
          example: 2
        createdAt:
          type: string
          nullable: true
          description: Job run creation timestamp (ISO 8601)
        modelName:
          type: string
          nullable: true
          description: Model name for the job run
        weightSet:
          type: string
          nullable: true
        method:
          type: string
          nullable: true
        relaxPrediction:
          type: boolean
          nullable: true
    PredictionPayload:
      type: object
      required:
        - predictionStatus
        - jobRunStatus
        - msaStatus
      properties:
        predictionStatus:
          $ref: "#/components/schemas/JobStatus"
        jobRunStatus:
          $ref: "#/components/schemas/JobStatus"
        msaStatus:
          $ref: "#/components/schemas/JobStatus"
        prediction:
          type: boolean
          nullable: true
        error:
          type: string
          nullable: true
        meanPLLDT:
          type: number
          nullable: true
        executionTimeInMinutes:
          type: number
          nullable: true
        pdb_url:
          type: string
          nullable: true
        cif_url:
          type: string
          nullable: true
        msa_coverage_plot_url:
          type: string
          nullable: true
        pae_plot_url:
          type: string
          nullable: true
        plddt_plot_url:
          type: string
          nullable: true
        metrics_json_url:
          type: string
          nullable: true
        config_json_url:
          type: string
          nullable: true
        citations_bibtex_url:
          type: string
          nullable: true
        plots_url:
          type: string
          nullable: true
        ptm_score:
          type: number
          nullable: true
        iptm_score:
          type: number
          nullable: true
        max_pae_score:
          type: number
          nullable: true
        seed:
          type: string
          nullable: true
        execution_time_in_minutes:
          type: number
          nullable: true
        affinity_result_raw_json:
          type: object
          nullable: true
          additionalProperties: true
    JobSequenceOutput:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - sequence
        - type
      properties:
        id:
          type: string
          description: Sequence ID
        createdAt:
          type: string
          description: Sequence creation timestamp (ISO 8601)
        updatedAt:
          type: string
          description: Sequence update timestamp (ISO 8601)
        name:
          type: string
          nullable: true
          description: Sequence label (if provided)
        sequence:
          type: string
        type:
          type: string
        predictionPayload:
          $ref: "#/components/schemas/PredictionPayload"
          nullable: true
    JobResultsOutput:
      type: object
      required:
        - job
        - parameters
        - sequences
      properties:
        job:
          $ref: "#/components/schemas/JobInfoOutput"
        parameters:
          $ref: "#/components/schemas/JobRunResultsSummary"
        sequences:
          type: array
          items:
            $ref: "#/components/schemas/JobSequenceOutput"
        predictionPayload:
          $ref: "#/components/schemas/PredictionPayload"
          nullable: true
    JobInfoOutput:
      type: object
      required:
        - id
        - status
        - name
        - date
        - updatedAt
        - isComplex
      properties:
        id:
          type: string
          format: uuid
          description: Job ID
        status:
          $ref: "#/components/schemas/JobStatus"
        name:
          type: string
        date:
          type: string
        updatedAt:
          type: string
        isComplex:
          type: boolean
          description: Whether the latest job run is treated as a complex run
        isPublic:
          type: boolean
          nullable: true
    JobPublicUpdate:
      type: object
      required:
        - isPublic
      properties:
        isPublic:
          type: boolean
    JobPublicUpdateResponse:
      type: object
      required:
        - jobId
        - isPublic
      properties:
        jobId:
          type: string
          format: uuid
        isPublic:
          type: boolean
          nullable: true
    LibraryItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
            - file
            - folder
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        fileType:
          type: string
          nullable: true
        origin:
          type: string
          nullable: true
        size:
          type: integer
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        children:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
        colorHex:
          type: string
          nullable: true
    CreateLibraryItemRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - folder
            - file
        parent_id:
          type: string
          format: uuid
          nullable: true
        fileType:
          type: string
          nullable: true
        origin:
          type: string
          nullable: true
        size:
          type: integer
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        colorHex:
          type: string
          nullable: true
    LibrarySearchResponse:
      type: object
      properties:
        q:
          type: string
        count:
          type: integer
        results:
          type: array
          items:
            type: object
            additionalProperties: true
    LibraryListResponse:
      type: object
      properties:
        root:
          type: array
          items:
            $ref: "#/components/schemas/LibraryItem"
        count:
          type: integer
        next_cursor:
          type: string
          nullable: true
    ReplaceFileResponse:
      type: object
      properties:
        item:
          $ref: "#/components/schemas/LibraryItem"
        replaced:
          type: object
          properties:
            oldFileName:
              type: string
            newFileName:
              type: string
            newS3Key:
              type: string
            bytes:
              type: integer
            sha256:
              type: string
            etag:
              type: string
              nullable: true
            versionId:
              type: string
              nullable: true
    WorkflowInput:
      type: object
      required:
        - workflow_name
      properties:
        workflow_name:
          type: string
          description: Workflow template/type name
          example: boltzgen_v1
        name:
          type: string
          default: ""
          example: My workflow via API
        workflow_input:
          type: object
          nullable: true
          additionalProperties: true
    WorkflowTask:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
        workflow_id:
          type: string
          format: uuid
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        task_type:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        completion_time_in_seconds:
          type: number
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
        result_raw_json:
          nullable: true
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
        output_library_items:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
    WorkflowRunResponse:
      type: object
      required:
        - workflow_id
        - tasks_total_count
        - tasks
      properties:
        status:
          type: string
          nullable: true
        workflow_id:
          type: string
          format: uuid
        tasks_total_count:
          type: integer
        workflow_type:
          type: string
          nullable: true
        input_sequence:
          type: string
          nullable: true
        tasks_completed_count:
          type: integer
          nullable: true
        tasks_failed_count:
          type: integer
          nullable: true
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowTask"
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          nullable: true
        reasoning_markdown_results:
          type: string
          nullable: true
        user_id:
          type: string
          format: uuid
          nullable: true
        log_file_url:
          type: string
          nullable: true
        library_item_workspace_id:
          type: string
          format: uuid
          nullable: true
        input_payload:
          type: object
          nullable: true
          additionalProperties: true
        project_id:
          type: string
          format: uuid
          nullable: true
    WorkflowExecuteRequest:
      type: object
      required:
        - workflowId
      properties:
        workflowId:
          type: string
          format: uuid
          example: ecdf7c28-d773-41cb-bfa6-05e7ff27af42
    WorkflowStatusTask:
      type: object
      required:
        - task_id
        - task_type
        - status
      properties:
        task_id:
          type: string
          format: uuid
        task_type:
          type: string
        status:
          type: string
        node_id:
          type: string
          format: uuid
          nullable: true
        order_index:
          type: integer
          nullable: true
        completion_time_in_seconds:
          type: number
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    WorkflowStatusResponse:
      type: object
      required:
        - workflow_id
        - status
        - tasks
      properties:
        workflow_id:
          type: string
          format: uuid
        status:
          type: string
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowStatusTask"
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
    WorkflowTaskResult:
      type: object
      required:
        - task_id
        - task_type
      properties:
        task_id:
          type: string
          format: uuid
        task_type:
          type: string
        node_id:
          type: string
          format: uuid
          nullable: true
        order_index:
          type: integer
          nullable: true
        output_library_items:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
        parsed_results:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
    WorkflowTaskResultsResponse:
      type: object
      required:
        - tasksResults
      properties:
        tasksResults:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowTaskResult"
    WorkflowNodeResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
        workflowTaskTypeId:
          type: string
        position:
          type: object
          additionalProperties: true
        data:
          type: object
          additionalProperties: true
        inputPayload:
          type: object
          nullable: true
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    WorkflowEdgeResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
        source:
          type: string
          format: uuid
        target:
          type: string
          format: uuid
        sourceHandle:
          type: string
          nullable: true
        targetHandle:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    WorkflowGraphResponse:
      type: object
      properties:
        workflowId:
          type: string
          format: uuid
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowNodeResponse"
        edges:
          type: array
          items:
            $ref: "#/components/schemas/WorkflowEdgeResponse"
    WorkflowYmlSetResponse:
      type: object
      properties:
        workflowId:
          type: string
          format: uuid
        graph:
          $ref: "#/components/schemas/WorkflowGraphResponse"
        workflowYml:
          type: object
          additionalProperties: true
  parameters:
    ItemId:
      name: item_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    FileName:
      name: file_name
      in: path
      required: true
      schema:
        type: string
    WorkflowId:
      name: workflow_id
      in: path
      required: true
      description: Workflow ID
      example: ""
      schema:
        type: string
        format: uuid
