{
  "openapi": "3.0.0",
  "paths": {
    "/api/v1/tools": {
      "get": {
        "description": "Lists the tools the orchestrator can run inside a turn, each annotated with whether this caller can use it. Tools the caller cannot use are returned with a reason rather than hidden.",
        "operationId": "ToolsController_list",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListToolsResponseDto"
                }
              }
            }
          }
        },
        "summary": "List host-side tools",
        "tags": [
          "tools"
        ]
      }
    },
    "/api/v1/datasets/upload/initiate": {
      "post": {
        "operationId": "DatasetController_initiateUpload",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateDto"
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateResponseDto"
                }
              }
            }
          }
        },
        "summary": "Initiate a dataset upload",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/upload/complete": {
      "post": {
        "operationId": "DatasetController_completeUpload",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteUploadDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompleteUploadResponseDto"
                }
              }
            }
          }
        },
        "summary": "Complete a dataset upload and trigger processing",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/upload/initiate-batch": {
      "post": {
        "description": "Initiate a batch upload. A batch must be homogeneous: either all document formats (pdf, docx, pptx, xlsx, html, zip) or all tabular formats (csv, json, jsonl, parquet). Mixed batches are rejected. TXT files are permissive and may be included in either kind of batch (or alone, in which case the dataset is tabular); their contents are converted during complete-batch.",
        "operationId": "DatasetController_initiateBatchUpload",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateBatchDto"
              }
            }
          }
        },
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateBatchResponseDto"
                }
              }
            }
          }
        },
        "summary": "Initiate a batch upload",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/upload/complete-batch": {
      "post": {
        "description": "Any TXT files in the batch are converted to csv/jsonl. Batches that still contain documents (pdf/docx/pptx/xlsx/html, or unpacked zip contents) move to awaiting_preprocessing and wait for an explicit launch-preprocessing call. Batches with only tabular formats (csv/json/jsonl/parquet, plus any converted-from-TXT files) move directly to column extraction.",
        "operationId": "DatasetController_completeBatchUpload",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteBatchDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompleteBatchResponseDto"
                }
              }
            }
          }
        },
        "summary": "Complete a batch upload and trigger processing",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets": {
      "post": {
        "description": "Unified ingest endpoint. Pass source.url to start an async import — the provider is inferred from the URL host (HuggingFace, Kaggle, Google Sheets, or one public S3 or Cloud Storage object ending in .csv, .json, .jsonl, or .parquet). Omit it to get upload instructions for a presigned S3 PUT. Adapt the result with [POST /datasets/{dataset_id}/adapt](/api/python/resources/datasets/methods/adapt), or send it straight to training with [POST /autoscientist](/api/python/resources/autoscientist/methods/create) when it already holds prompt and completion columns.",
        "operationId": "DatasetController_createDatasetPublic",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDatasetDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateDatasetResponseDto"
                }
              }
            }
          }
        },
        "summary": "Create a dataset from file upload, HuggingFace, Kaggle, Google Sheets, or a public S3 or Cloud Storage object",
        "tags": [
          "Dataset"
        ]
      },
      "get": {
        "operationId": "DatasetController_getDatasets",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "Number of results (max 100, default 20). Used with cursor pagination.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "required": false,
            "in": "query",
            "description": "Cursor from the previous response next_cursor field.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by status. Omit or leave empty for no status filter. Cursor list: pending | running | awaiting_input | succeeded | failed. Offset list (page/perPage): failed | in_progress (or inprogress) | complete, or a legacy exact dataset status. complete is status ready.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "required": false,
            "in": "query",
            "description": "Case-insensitive search. A dataset matches when the text is in its name or its description.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_after",
            "required": false,
            "in": "query",
            "description": "ISO 8601 datetime — datasets created after this time.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_before",
            "required": false,
            "in": "query",
            "description": "ISO 8601 datetime — datasets created before this time.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "required": false,
            "in": "query",
            "description": "Sort field: created_at | updated_at | name (default: created_at).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort_direction",
            "required": false,
            "in": "query",
            "description": "Sort direction: asc | desc (default: desc).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "created_by_user_id",
            "required": false,
            "in": "query",
            "description": "Filter datasets by creator. The user must belong to the same team as the caller.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "required": false,
            "in": "query",
            "description": "Filter by how the dataset was created: original | combined | augmented | invented. Omit or leave empty for no type filter.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CursorListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List datasets",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/upload/complete": {
      "post": {
        "description": "File uploads only. Call after uploading bytes to the presigned URL from POST /datasets. Verifies the file exists in S3, then triggers the preprocessing pipeline. TXT files are converted to rows here. Documents (pdf, docx, pptx, xlsx, html, or a zip holding them) are not: the dataset then reports `awaiting_input` until POST /datasets/{dataset_id}/launch-preprocessing extracts them.",
        "operationId": "DatasetController_completeUploadById",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteUploadByIdDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompleteUploadByIdResponseDto"
                }
              }
            }
          }
        },
        "summary": "Complete a file upload and trigger processing",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/status": {
      "get": {
        "operationId": "DatasetController_getDatasetStatus",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDatasetStatusResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get the processing status of a dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/evaluation": {
      "get": {
        "operationId": "DatasetController_getDatasetEvaluation",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetEvaluationResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get evaluation results for a dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}": {
      "get": {
        "operationId": "DatasetController_getDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDatasetDto"
                }
              }
            }
          }
        },
        "summary": "Get a dataset by ID",
        "tags": [
          "Dataset"
        ]
      },
      "delete": {
        "description": "Soft-deletes a dataset and its associated resources. Cannot delete a dataset while the pipeline is running.",
        "operationId": "DatasetController_deleteDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "404": {
            "description": "Dataset not found"
          },
          "409": {
            "description": "Dataset is currently launching — wait until it finishes"
          }
        },
        "summary": "Delete a dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/finetune/best-launch-config": {
      "get": {
        "description": "Returns the persisted launch snapshot for the winning AutoScientist job (terminal experiment with `best_finetune_job_id`) or the newest succeeded most recent succeeded standalone job when no experiment exists. Matches the launch payload plus `original_model_name` and persisted `trained_model_name` (output label / suffix). Use it to prefill a re-launch instead of reading config from GET /datasets/{dataset_id} or the list.",
        "operationId": "DatasetController_getDatasetBestFinetuneLaunchConfig",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BestFinetuneLaunchConfigResponseDto"
                }
              }
            }
          }
        },
        "summary": "Best fine-tune launch config for re-launch parity",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/export-links": {
      "get": {
        "operationId": "DatasetController_getDatasetExportLinks",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetExportLinksResponseDto"
                }
              }
            }
          }
        },
        "summary": "Poll saved URLs for successful dataset exports (Hugging Face, Kaggle, Google Sheets)",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/preprocessing-credits": {
      "get": {
        "description": "Quotes the credits that extracting a document dataset (pdf, docx, pptx, xlsx, html, or a zip of them) will reserve, from the page count of each document. Pass the same `pages_to_process` or `documents_to_process` you intend to launch with. Page counting runs in the background after upload, so `isFinal: false` means the quote is still partial — poll until it is true. Start extraction with POST /datasets/{dataset_id}/launch-preprocessing.",
        "operationId": "DatasetController_getPreprocessingCredits",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pages_to_process",
            "required": false,
            "in": "query",
            "description": "Maximum number of pages to process. Documents are included until this budget is reached. If omitted, all pages are processed.",
            "schema": {
              "minimum": 1,
              "type": "number"
            }
          },
          {
            "name": "documents_to_process",
            "required": false,
            "in": "query",
            "description": "Maximum number of documents to process. If omitted, all documents are processed.",
            "schema": {
              "minimum": 1,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreprocessingCreditsResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Not a document dataset, or both pages_to_process and documents_to_process were set."
          }
        },
        "summary": "Estimate credit cost for document preprocessing",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/launch-preprocessing": {
      "post": {
        "description": "Extracts the text, tables and figures of an uploaded document dataset (pdf, docx, pptx, xlsx, html, or a zip of them) into rows. After the upload completes, such a dataset reports `awaiting_input` until this is called. Reserves credits from the page count of the selected documents — quote them first with GET /datasets/{dataset_id}/preprocessing-credits — then starts extraction. Poll GET /datasets/{dataset_id}/status: it reports `pending` while extracting and `awaiting_input` once the rows are ready, at which point call POST /datasets/{dataset_id}/adapt.",
        "operationId": "DatasetController_launchPreprocessing",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LaunchPreprocessingBodyDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LaunchPreprocessingResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Not a document dataset, or both pages_to_process and documents_to_process were set."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Preprocessing was already launched for this dataset, or its upload has not completed."
          },
          "503": {
            "description": "The page count of a document could not be read yet. Retry shortly."
          }
        },
        "summary": "Launch document preprocessing",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/augment": {
      "post": {
        "description": "Retrieves additional rows matching this dataset and returns them as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the retrieved ones, so it can be trained on or downloaded directly. Omit both row counts to receive the recommended fill and its cost as a quote; a run needs explicit row counts, or fill_to_recommended=true to fill any count you leave out with its recommended value. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches `succeeded`. Set estimate=true to price the request without starting a run.",
        "operationId": "DatasetController_augmentDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicAugmentDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAugmentResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: the recommended fill has nothing to add, the dataset contains images (the pool is text-only), or its topic mix cannot be determined (domain_rows / general_rows only). A request that named no row counts also gets 400, with the recommended fill and its cost as a quote in the body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAugmentQuoteErrorDto"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — the dataset is not ready. Poll GET /datasets/{dataset_id}/status until it is."
          }
        },
        "summary": "Add rows to a dataset from the curated pool",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/translate": {
      "post": {
        "description": "Translates a sample of this dataset’s rows into each target language and returns the result as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the translated ones, so it can be trained on or downloaded directly. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches `succeeded`. To adapt rows to a country as well as a language, use POST /datasets/{dataset_id}/localize. Set estimate=true to price the request without starting a run.",
        "operationId": "DatasetController_translateDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicTranslateDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicExpandResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: an unsupported language, a dataset containing images, a dataset with no prompt or completion column, or a request that would add no rows."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — the dataset is not ready (poll GET /datasets/{dataset_id}/status until it is), or another request holds this idempotency_key and left no run behind, in which case retry with the same key."
          }
        },
        "summary": "Add translated rows to a dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/localize": {
      "post": {
        "description": "Adapts a sample of this dataset’s rows to each country/language pair — translating the text and matching that country’s conventions — and returns the result as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the localized ones. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches `succeeded`. To translate into a language without targeting a country, use POST /datasets/{dataset_id}/translate. Set estimate=true to price the request without starting a run.",
        "operationId": "DatasetController_localizeDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLocalizeDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicExpandResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: an unsupported country/language pair, a dataset containing images, a dataset with no prompt or completion column, or a request that would add no rows."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — the dataset is not ready (poll GET /datasets/{dataset_id}/status until it is), or another request holds this idempotency_key and left no run behind, in which case retry with the same key."
          }
        },
        "summary": "Add localized rows to a dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/adapt": {
      "post": {
        "description": "Validates column mapping and recipe configuration, reserves credits, and starts the adaptation pipeline, which improves the rows already in the dataset without changing how many there are. To add rows instead, use POST /datasets/{dataset_id}/augment. Set estimate=true to validate and get a cost quote without starting a run. When the mapped image column is also in context_columns, output rows are billed at 10 credits per 100 rows (1–100 rows cost 10 credits; see multimodalPricingApplied and creditMultiplier on the response). Once the run succeeds, train on the result with [POST /autoscientist](/api/python/resources/autoscientist/methods/create).",
        "operationId": "DatasetController_adaptPipeline",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLaunchDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicLaunchResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: column_mapping shape error; a translate, localize or language_expansion failure (unknown ISO 639-1 code, unsupported country/language pair, or a malformed spec); an expand that adds no rows or that this dataset cannot run; or language_expansion combined with translate, localize or expand."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — dataset is already launching, still importing, or row_count not yet available. Poll GET /datasets/{dataset_id}/status until row_count is populated."
          }
        },
        "summary": "Adapt a dataset (or estimate cost)",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/run": {
      "post": {
        "deprecated": true,
        "description": "Deprecated alias of `POST /datasets/{dataset_id}/adapt`, kept for existing clients. Use `POST /datasets/{dataset_id}/adapt` in new code.",
        "operationId": "DatasetController_runPipeline",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLaunchDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicLaunchResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: column_mapping shape error; a translate, localize or language_expansion failure (unknown ISO 639-1 code, unsupported country/language pair, or a malformed spec); an expand that adds no rows or that this dataset cannot run; or language_expansion combined with translate, localize or expand."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — dataset is already launching, still importing, or row_count not yet available. Poll GET /datasets/{dataset_id}/status until row_count is populated."
          }
        },
        "summary": "Adapt a dataset (deprecated)",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/extend-trajectories": {
      "post": {
        "description": "For each row's conversation, generates the user's next message: a single question or request that can only be answered correctly by remembering details from earlier in the conversation, written in the conversation's language. No completion is generated for it. Each request creates a new dataset for the result, returned as `dataset_id`; the dataset in the path is left unchanged. Poll GET /datasets/{dataset_id}/status and download from GET /datasets/{dataset_id}/download with the new id. If the dataset has been adapted (POST /datasets/{dataset_id}/adapt finished), the extension builds on its adapted download: `column_mapping` names columns of that download, so `column_mapping.completion` can be `enhanced_completion`, and the result keeps the adapted columns next to `extended_prompt`. Only `prompt` + `completion` applies there, since adapt splits a chat column into `original_prompt` and `original_completion`. Otherwise the extension reads the uploaded file, with one of two mappings. `column_mapping.chat`: a column of `{\"role\", \"content\"}` turns (or a JSON string of that list), ending on the assistant's reply. Or `column_mapping.prompt` with `column_mapping.completion`: the conversation up to the user's last turn (a turn list, or a plain string), plus the final reply as plain text. Each row of the result carries the conversation (split as for /adapt) plus an `extended_prompt` column. `context`, `universal_prompt` and `image` mappings are not currently supported. Credits and status polling behave as for /adapt; an `idempotency_key` replays the extension it first created, returning its `dataset_id` and `run_id` with zero estimates, since the replay starts and charges nothing (as for /translate). Set estimate=true to validate and get a cost quote without starting a run.",
        "operationId": "DatasetController_extendTrajectories",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicExtendTrajectoriesDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicExtendTrajectoriesResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: `column_mapping` must be `chat` alone, or `prompt` with `completion`, naming columns the input has (an adapted dataset takes `prompt` + `completion` only). Any other `column_mapping` field (such as `context`, `universal_prompt` or `image`) is not currently supported. Also returned for datasets this endpoint cannot read: another extension, a combined, invented, augmented, translated or localized dataset, or one adapted into preference pairs, from a universal prompt, or with images."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "Conflict — dataset is launching or still importing, row_count is not yet available, or another request holds this idempotency_key. Poll GET /datasets/{dataset_id}/status until row_count is populated."
          },
          "422": {
            "description": "Estimate without `column_mapping` on a dataset that has not been adapted and whose saved mapping is neither a chat column nor a prompt + completion pair."
          }
        },
        "summary": "Extend trajectories with a next user turn (or estimate cost)",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/download": {
      "get": {
        "description": "Streams the processed rows in the requested file format. Works on datasets with status `ready` (full output) and also on datasets with status `failed` — in the failed case the stream contains only the rows that were successfully processed before the run aborted, which is useful for recovering partial output from interrupted jobs. Returns 422 only when no run has ever started on this dataset.\n\n**Image columns (JSON / JSONL):** Rows may include `original_image` only when the mapped image column is also in `configured_column_mapping.context`. Read `image_column_formats` from `GET /datasets/{dataset_id}` and look up the active image column to determine encoding: `embedded_bytes` → `{ bytes, path: null }` with base64 bytes; `url` or `file_reference` → presigned HTTPS URL string. When images are not surfaced, `original_image` is omitted and internal `s3://` URIs are never returned. See schema `ProcessedDatasetExportOriginalImageFieldDto`. In CSV and Parquet, embedded bytes appear as a JSON string in the cell.\n\n**Response body:** binary in every format. `fileFormat=parquet` returns a gzipped tar archive of one or more Parquet shards (`.tar.gz`), not a single `.parquet` file — extract it before reading. CSV, JSON and JSONL bodies are UTF-8 text and can be decoded directly.",
        "operationId": "DatasetController_export",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fileFormat",
            "required": false,
            "in": "query",
            "description": "Output file format. Defaults to `csv` if omitted.",
            "schema": {
              "enum": [
                "csv",
                "json",
                "jsonl",
                "parquet"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File download stream. For failed runs, contains partial results (rows processed before failure). For `fileFormat=json` or `jsonl`, each record may include `original_image` per `ProcessedDatasetExportOriginalImageFieldDto` when an image column is mapped and in context.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "examples": {
                  "row_with_url_image": {
                    "summary": "JSONL line (url / file_reference format)",
                    "description": "Illustrative single line when the active image column format is `url` or `file_reference`.",
                    "value": "{\"enhanced_prompt\":\"...\",\"original_image\":\"https://example-bucket.s3.amazonaws.com/image.jpg?X-Amz-Signature=...\"}\n"
                  },
                  "row_with_embedded_image": {
                    "summary": "JSONL line (embedded_bytes format)",
                    "description": "Illustrative single line when the active image column format is `embedded_bytes`.",
                    "value": "{\"enhanced_prompt\":\"...\",\"original_image\":{\"bytes\":\"<base64>\",\"path\":null}}\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unsupported `fileFormat`."
          },
          "422": {
            "description": "No run has started on this dataset yet. Adapt it via POST /datasets/{dataset_id}/adapt first."
          }
        },
        "summary": "Download the processed dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/publish": {
      "post": {
        "description": "Publishes the processed dataset to Hugging Face or Kaggle. Currently returns 501 — not yet implemented.",
        "operationId": "DatasetController_publishDataset",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublishRequestDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublishAcceptedResponseDto"
                }
              }
            }
          },
          "501": {
            "description": "Publishing is not yet available"
          }
        },
        "summary": "Publish a dataset to an external platform",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/combine/validate": {
      "post": {
        "description": "Synchronous compatibility check. Returns a single `issues` array containing both blockers (`level: \"error\"`) and reconcilable concerns (`level: \"warning\"`). `compatible: false` means at least one error-level issue is present (cardinality, ownership, status, run_id). Warning-level entries — column-type mismatches, DPO sources missing ranked generations — are non-blocking; the merge resolves them automatically (mixed types downgrade to instruction_dataset, type mismatches CAST to a common type, etc.). Nothing is written.",
        "operationId": "DatasetController_validateCombine",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateCombineRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns `{compatible, issues, training_type?, total_estimated_rows?}`. Each entry in `issues` carries a `level` (`\"error\"` or `\"warning\"`), a stable `code`, a preformed user-facing `message`, and code-specific structured context. Error codes block the merge; warning codes describe reconciliation the merge performs automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateCombineResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Request shape rejected by class-validator (e.g. non-UUID id, fewer than 2 ids, or array longer than the DTO cap)."
          }
        },
        "summary": "Validate that a set of Datasets can be combined",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/combine": {
      "post": {
        "description": "Accepts an optional Idempotency-Key header to dedupe double-submits; when omitted, the server generates a unique key for this request. Returns the newly merged Dataset.",
        "operationId": "DatasetController_combine",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional retry key. Reuse the effective key returned in the response header to safely replay a request.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CombineRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Merged Dataset result.",
            "headers": {
              "Idempotency-Key": {
                "description": "Effective idempotency key used for this request, whether supplied by the caller or generated by the server.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CombineResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "One of: (a) request shape rejected by class-validator (e.g. non-UUID id, fewer than 2 ids, name missing, or array longer than the DTO cap); (b) caller has no team; (c) compatibility validation failed. See `/combine/validate` for the structural issue codes. Warning-level issues are non-blocking and do not fail this endpoint."
          },
          "401": {
            "description": "Missing or invalid credentials."
          },
          "500": {
            "description": "Server-side failure while creating the merged Dataset."
          }
        },
        "summary": "Combine multiple Datasets into a single new merged Dataset",
        "tags": [
          "Dataset"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/custom-evals": {
      "post": {
        "operationId": "CustomEvalController_create",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCustomEvalDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomEvalResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "The judge prompt failed rubric validation (`code: invalid_judge_prompt`, with per-issue feedback), or the request body is invalid or the dataset is not ready (generic error).",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/InvalidJudgePromptErrorDto"
                    },
                    {
                      "$ref": "#/components/schemas/PublicApiErrorDto"
                    }
                  ]
                }
              }
            }
          }
        },
        "summary": "Start a custom-rubric evaluation for an adapted dataset",
        "tags": [
          "datasets"
        ]
      },
      "get": {
        "operationId": "CustomEvalController_list",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomEvalListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List custom-rubric evaluations for a dataset, newest first",
        "tags": [
          "datasets"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/custom-evals/{custom_eval_id}": {
      "get": {
        "operationId": "CustomEvalController_get",
        "parameters": [
          {
            "name": "dataset_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "custom_eval_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomEvalResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get a single custom-rubric evaluation",
        "tags": [
          "datasets"
        ]
      }
    },
    "/api/v1/autoscientist": {
      "post": {
        "description": "Starts an iterative AutoScientist loop on a dataset you own. The loop runs up to max_iterations training cycles, stopping early when target_win_rate is achieved. Omitted parameters are resolved to platform defaults for the selected model and returned in the response. Poll GET /autoscientist/{experiment_id} for status, then GET /autoscientist/{experiment_id}/download once it succeeds. The dataset must have finished processing: adapt it first with [POST /datasets/{dataset_id}/adapt](/api/python/resources/datasets/methods/adapt), or ingest it raw with [POST /datasets](/api/python/resources/datasets/methods/create) when it already holds prompt and completion columns.",
        "operationId": "AutoScientistPublicController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateAutoScientistRunDto"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAutoScientistRunDto"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — dataset has too few training rows, or an unsupported configuration was supplied."
          },
          "402": {
            "description": "Insufficient credits to start this run."
          },
          "403": {
            "description": "Fine-tuning is not available on your current plan. Upgrade to unlock this feature."
          },
          "404": {
            "description": "Dataset not found or not owned by caller."
          },
          "422": {
            "description": "The dataset is not ready for training yet — its preparation is still running, failed, or was never started."
          },
          "429": {
            "description": "Too many training jobs in flight. Wait for an existing run to complete before starting another."
          },
          "503": {
            "description": "AutoScientist is currently unavailable."
          }
        },
        "summary": "Create an AutoScientist run",
        "tags": [
          "autoscientist"
        ]
      },
      "get": {
        "operationId": "AutoScientistPublicController_list",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "Page size (max 100, default 20).",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cursor",
            "required": false,
            "in": "query",
            "description": "next_cursor from a previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dataset_id",
            "required": false,
            "in": "query",
            "description": "Only runs for this dataset.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAutoScientistRunListDto"
                }
              }
            }
          }
        },
        "summary": "List AutoScientist runs",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/autoscientist/recommend-hyperparams": {
      "post": {
        "description": "Returns the hyperparameters AutoScientist derives for a model and the dataset's effective training size (rows plus planned augmentation). Nothing is launched. Omit `model` to size against the model POST /autoscientist would select for this dataset; the resolved id is returned with the values. POST /autoscientist applies the same values when `hyperparams` is omitted.",
        "operationId": "AutoScientistPublicController_recommendHyperparams",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicRecommendHyperparamsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicRecommendHyperparamsResponseDto"
                }
              }
            }
          },
          "404": {
            "description": "Dataset not found or not owned by caller."
          },
          "422": {
            "description": "Dataset is not ready, or the model id is unsupported."
          },
          "503": {
            "description": "AutoScientist is currently unavailable."
          }
        },
        "summary": "Recommend hyperparameters",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/autoscientist/models": {
      "get": {
        "description": "Returns the set of base models that can be used as the `model` field when creating an AutoScientist run.",
        "operationId": "AutoScientistPublicController_listModels",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTrainingModelListDto"
                }
              }
            }
          }
        },
        "summary": "List available base models for training",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/autoscientist/{experiment_id}": {
      "get": {
        "operationId": "AutoScientistPublicController_retrieve",
        "parameters": [
          {
            "name": "experiment_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAutoScientistRunDto"
                }
              }
            }
          },
          "404": {
            "description": "Run not found or not owned by caller."
          }
        },
        "summary": "Retrieve an AutoScientist run",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/autoscientist/{experiment_id}/cancel": {
      "post": {
        "operationId": "AutoScientistPublicController_cancel",
        "parameters": [
          {
            "name": "experiment_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAutoScientistRunDto"
                }
              }
            }
          },
          "404": {
            "description": "Run not found or not owned by caller."
          },
          "409": {
            "description": "The run is starting its preference-training stage and cannot be cancelled yet. Retry once it reports an iteration in progress."
          }
        },
        "summary": "Cancel an AutoScientist run",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/autoscientist/{experiment_id}/download": {
      "get": {
        "operationId": "AutoScientistPublicController_download",
        "parameters": [
          {
            "name": "experiment_id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Streams the best iteration checkpoint as application/gzip.",
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Run not found or not owned by caller."
          },
          "422": {
            "description": "Run has not completed successfully or the best model is not ready for download."
          }
        },
        "summary": "Download the best trained model artifact",
        "tags": [
          "autoscientist"
        ]
      }
    },
    "/api/v1/training-models": {
      "get": {
        "deprecated": true,
        "description": "Deprecated alias of `GET /autoscientist/models`, kept for existing clients. Returns the set of base models that can be used as the `model` field when creating a training job. Use `GET /autoscientist/models` in new code.",
        "operationId": "FinetuneModelsPublicController_list",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTrainingModelListDto"
                }
              }
            }
          }
        },
        "summary": "List available base models for training (deprecated)",
        "tags": [
          "training-models"
        ]
      }
    },
    "/api/v1/datasets/invent/domains": {
      "get": {
        "description": "Returns every domain code accepted by `POST /datasets/invent`, each with its subdomain codes. Static — safe to cache.",
        "operationId": "InventPublicController_domains",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicInventDomainsResponseDto"
                }
              }
            }
          }
        },
        "summary": "List the domains and subdomains available for generation",
        "tags": [
          "invent"
        ]
      }
    },
    "/api/v1/datasets/invent": {
      "post": {
        "description": "Creates a dataset and starts generating it. Describe the data either by taxonomy — `domains` and/or `subdomains` — or in your own words with `dataset_prompt`: when neither taxonomy field is given, the domains and subdomains are inferred from the prompt. Explicit taxonomy is authoritative and disables that inference. If the prompt cannot be mapped onto the catalog (or inference is unavailable), the request is rejected with `400` asking for explicit `domains`/`subdomains` — it is never widened to every domain. Returns immediately — poll `GET /datasets/{id}` for the status and `GET /datasets/{id}/download` once it reports `succeeded`. Set `estimate: true` to price a request without generating anything.",
        "operationId": "InventEntryController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/CreateInventedDatasetDto"
                  }
                ],
                "anyOf": [
                  {
                    "required": [
                      "domains"
                    ]
                  },
                  {
                    "required": [
                      "subdomains"
                    ]
                  },
                  {
                    "required": [
                      "dataset_prompt"
                    ]
                  },
                  {
                    "required": [
                      "prompt"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation has started, or — with `estimate: true` — the price of running it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicInventedDatasetDto"
                }
              }
            }
          }
        },
        "summary": "Generate a dataset from scratch",
        "tags": [
          "invent"
        ]
      }
    },
    "/api/v1/leaderboard/overview": {
      "get": {
        "description": "Public endpoint; no authentication required. Returns the hero counters and the full domain selector.",
        "operationId": "LeaderboardController_getOverview",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardOverviewResponseDto"
                }
              }
            }
          }
        },
        "summary": "Community leaderboard counters and selectable domains",
        "tags": [
          "leaderboard"
        ]
      }
    },
    "/api/v1/leaderboard": {
      "get": {
        "description": "Public endpoint; no authentication required. Returns one row per user — that user's best-scoring run in the domain — ordered by domain win rate descending, one page at a time. Page with `limit`/`offset`: a \"show more\" click is the same request with `offset` advanced by the rows already on screen, and `pagination.has_more` says whether to show the control at all. Ranks are absolute over the whole ranking, so page two starts at rank 11 and ranks 1–3 identify the top three without a separate response section. `pagination.total` is the eligible population, not the rows in this page. Pass `q` to search every domain by member, run or dataset name — the same page shape, cut from the matches instead of from a single ranking, with `domain` ignored and each row naming the domain it is ranked in.",
        "operationId": "LeaderboardController_getLeaderboard",
        "parameters": [
          {
            "name": "domain",
            "required": false,
            "in": "query",
            "description": "Domain to rank. Accepts the classifier slug (`medical`) or the code form (`domain_medical`), plus `general` for runs scored against the general prompt set. Omit it and the domain with the most ranked entries is used, echoed back in the response. An unrecognised value is rejected with 400.",
            "schema": {
              "example": "medical",
              "type": "string"
            }
          },
          {
            "name": "q",
            "required": false,
            "in": "query",
            "description": "Free-text search over the whole leaderboard — every domain, not the one `domain` selects, which is ignored while `q` is set: a member is looked up by name and the domains they placed in are the answer. Each hit is the entry as its own domain ranks it, so read `data[].domain` rather than the top-level `domain`, which is null for a search. Matches the member name, the run name and the dataset name, case-insensitively, on any part of the value. Split on spaces: every term has to match, in any order and in any of those fields, so `hooker sara` finds the same rows as `sara hooker`. Hits are ordered best score first (a rank only orders its own domain), and each carries the rank it holds there. Pages exactly like an unfiltered ranking: `pagination.total` is the number of matches.",
            "schema": {
              "example": "sara hooker",
              "type": "string"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "Rows to return. Defaults to one \"show more\" click's worth; anything above 50 is rejected with 400.",
            "schema": {
              "minimum": 1,
              "maximum": 50,
              "default": 10,
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "description": "Rows to skip. For \"show more\", pass the number of rows already on screen. Ranks are absolute, so the first row of a page carries rank `offset + 1` — a client can also read the ranks instead of tracking the offset itself.",
            "schema": {
              "minimum": 0,
              "default": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeaderboardResponseDto"
                }
              }
            }
          }
        },
        "summary": "Top users for one domain, by best AutoScientist run",
        "tags": [
          "leaderboard"
        ]
      }
    },
    "/api/v1/models": {
      "get": {
        "description": "Lists the models currently available to the caller through the responses endpoint: hosted models, harnesses and inference stacks. Pass `type=hosted` for the hosted models alone: what the caller's key grants, minus the `-direct` ids, which are omitted rather than listed under the public name they serve. The catalogue only supplies the `display_name` when it carries the model. An approved inference provider key receives the provider catalog representation instead.",
        "operationId": "ModelsController_list",
        "parameters": [
          {
            "name": "X-Organization-Id",
            "in": "header",
            "description": "Required for JWT authentication. API keys are already bound to an organization.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "required": false,
            "in": "query",
            "description": "Narrows the list to the hosted models the caller's key grants, leaving out harnesses and stacks. A `-direct` id is omitted rather than listed under the public name it serves, and a granted model the catalogue does not carry is still listed, without a `display_name`.",
            "schema": {
              "type": "string",
              "enum": [
                "hosted"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The available models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListModelsResponseDto"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint is not available."
          },
          "502": {
            "description": "The model provider could not complete the request."
          },
          "503": {
            "description": "Model inference is not configured for this environment."
          }
        },
        "summary": "List supported models",
        "tags": [
          "models"
        ]
      }
    },
    "/api/v1/responses": {
      "post": {
        "description": "Creates a Responses API response through the inference gateway.",
        "operationId": "ResponsesController_create",
        "parameters": [
          {
            "name": "X-Organization-Id",
            "in": "header",
            "description": "Required for JWT authentication. API keys are already bound to an organization.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "traceparent",
            "in": "header",
            "description": "W3C trace context used to parent this Responses API trace to a caller span.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateResponseDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The response, or with `stream: true` a stream of server-sent events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseObjectDto"
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseStreamEventDto"
                }
              }
            }
          },
          "404": {
            "description": "The endpoint is not available."
          },
          "502": {
            "description": "The model provider could not complete the request."
          },
          "503": {
            "description": "Model inference is not configured for this environment."
          }
        },
        "summary": "Generate a model response",
        "tags": [
          "responses"
        ]
      }
    },
    "/api/v1/responses/{response_id}/input_items": {
      "get": {
        "description": "Lists the materialized input items used to generate a stored response.",
        "operationId": "ResponsesController_listInputItems",
        "parameters": [
          {
            "name": "X-Organization-Id",
            "in": "header",
            "description": "Required for JWT authentication. API keys are already bound to an organization.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "response_id",
            "required": true,
            "in": "path",
            "description": "Identifier of the stored response.",
            "schema": {
              "example": "resp_123",
              "type": "string"
            }
          },
          {
            "name": "order",
            "required": false,
            "in": "query",
            "description": "Sort input items in conversation or reverse order.",
            "schema": {
              "default": "desc",
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "Maximum number of input items to return.",
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "after",
            "required": false,
            "in": "query",
            "description": "Return items after this input-item ID in the requested order.",
            "schema": {
              "example": "msg_123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A cursor-paginated list of response input items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "object",
                    "data",
                    "first_id",
                    "last_id",
                    "has_more"
                  ],
                  "properties": {
                    "object": {
                      "type": "string",
                      "enum": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "first_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "last_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The stored response was not found."
          }
        },
        "summary": "List response input items",
        "tags": [
          "responses"
        ]
      }
    },
    "/api/v1/responses/{response_id}": {
      "get": {
        "description": "Retrieves a tenant-scoped stored Responses API response.",
        "operationId": "ResponsesController_retrieve",
        "parameters": [
          {
            "name": "X-Organization-Id",
            "in": "header",
            "description": "Required for JWT authentication. API keys are already bound to an organization.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "response_id",
            "required": true,
            "in": "path",
            "description": "Identifier of the stored response.",
            "schema": {
              "example": "resp_123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored Responses API response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseObjectDto"
                }
              }
            }
          },
          "404": {
            "description": "The stored response was not found."
          }
        },
        "summary": "Retrieve a model response",
        "tags": [
          "responses"
        ]
      },
      "delete": {
        "description": "Deletes a stored response and its input and output items. Responses that chain from it stay retrievable. A create request whose `previous_response_id` chain passes through the deleted response still works, but the replayed history starts after the deleted response. A response that is still in progress is not stored yet and returns 404.",
        "operationId": "ResponsesController_delete",
        "parameters": [
          {
            "name": "X-Organization-Id",
            "in": "header",
            "description": "Required for JWT authentication. API keys are already bound to an organization.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "response_id",
            "required": true,
            "in": "path",
            "description": "Identifier of the stored response.",
            "schema": {
              "example": "resp_123",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The response was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "response.deleted"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The stored response was not found."
          }
        },
        "summary": "Delete a model response",
        "tags": [
          "responses"
        ]
      }
    }
  },
  "info": {
    "title": "Adaption API",
    "description": "Public API for the Adaption dataset augmentation platform",
    "version": "0.1.22",
    "contact": {}
  },
  "tags": [],
  "servers": [],
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "Bearer",
        "description": "API key or JWT — pass as: Bearer <token>",
        "type": "http"
      }
    },
    "schemas": {
      "MessageResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      },
      "HostedToolDto": {
        "type": "object",
        "properties": {
          "server_label": {
            "type": "string",
            "description": "The `server_label` to reference this connector by in a request, e.g. `{ \"type\": \"mcp\", \"server_label\": \"slack\" }`.",
            "example": "slack"
          },
          "type": {
            "type": "string",
            "description": "Responses API tool type to send in the `tools` array.",
            "enum": [
              "mcp"
            ],
            "example": "mcp"
          },
          "name": {
            "type": "string",
            "example": "Slack"
          },
          "description": {
            "type": "string"
          },
          "auth": {
            "type": "string",
            "description": "Where the outbound credential comes from. `connection` tools use a connection you authorise once, or an `authorization` passed on the request; `caller` tools always take it from the request.",
            "enum": [
              "none",
              "platform",
              "caller",
              "connection"
            ],
            "example": "connection"
          },
          "connect": {
            "type": "string",
            "description": "How a `connection` tool is connected: `oauth` through the browser flow at `connect_path`, `secret` by storing one with POST /connections. Null for tools that use no stored connection.",
            "enum": [
              "oauth",
              "secret"
            ],
            "nullable": true,
            "example": "oauth"
          },
          "connect_path": {
            "type": "string",
            "description": "For an `oauth` tool, the GET path (under the API prefix) that starts its browser connect flow — usually /oauth/{server_label}/connect; Google Drive uses /oauth/google/connect, the shared \"Connect Google\". Null for tools not connected through OAuth.",
            "nullable": true,
            "example": "/oauth/slack/connect"
          },
          "logo_url": {
            "type": "string",
            "description": "URL of the connector's logo, for showing it in a UI. Null for tools without one.",
            "nullable": true,
            "example": "https://proteus-prod-public.s3.us-east-1.amazonaws.com/connectors/slack.svg"
          },
          "mode": {
            "type": "string",
            "description": "How the tool connects. `hosted_proxy`: we run the MCP server against the provider API. `remote_mcp`: we connect as a client to the vendor-hosted MCP server.",
            "enum": [
              "hosted_proxy",
              "remote_mcp"
            ],
            "example": "remote_mcp"
          },
          "default_require_approval": {
            "type": "string",
            "description": "Approval posture applied when the request's tool entry does not set `require_approval`. Defaults to `never`; callers may require approval for all tools or specific write tools.",
            "enum": [
              "always",
              "never"
            ],
            "example": "never"
          },
          "required_scope": {
            "type": "string",
            "description": "Scope a scoped API key must hold to use this tool.",
            "example": "mcp:slack"
          },
          "available": {
            "type": "boolean",
            "description": "Whether this caller can use the tool right now.",
            "example": false
          },
          "unavailable_reason": {
            "type": "string",
            "description": "Why the tool is unavailable. Returned rather than omitting the tool, so a caller can tell \"not on your plan\" from \"does not exist\".",
            "enum": [
              "not_implemented",
              "disabled",
              "requires_plan",
              "requires_scope"
            ],
            "nullable": true,
            "example": "not_implemented"
          }
        },
        "required": [
          "server_label",
          "type",
          "name",
          "description",
          "auth",
          "connect",
          "connect_path",
          "logo_url",
          "mode",
          "default_require_approval",
          "required_scope",
          "available"
        ]
      },
      "ListToolsResponseDto": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "example": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HostedToolDto"
            }
          }
        },
        "required": [
          "object",
          "data"
        ]
      },
      "InitiateDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable name for the dataset",
            "example": "my-training-data"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "json",
              "jsonl",
              "parquet",
              "pdf",
              "docx",
              "pptx",
              "xlsx",
              "html",
              "zip",
              "txt"
            ],
            "description": "Format of the file being uploaded",
            "example": "csv"
          }
        },
        "required": [
          "name",
          "file_format"
        ]
      },
      "InitiateResponseDto": {
        "type": "object",
        "properties": {
          "upload_url": {
            "type": "string",
            "description": "Pre-signed S3 URL — upload the file directly to this URL via HTTP PUT",
            "example": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."
          }
        },
        "required": [
          "upload_url"
        ]
      },
      "CompleteUploadDto": {
        "type": "object",
        "properties": {
          "s3_key": {
            "type": "string",
            "description": "S3 object key returned in the pre-signed URL response from /upload/initiate",
            "example": "uploads/550e8400-e29b-41d4-a716-446655440000/my-training-data.csv"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the dataset",
            "example": "my-training-data"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "json",
              "jsonl",
              "parquet",
              "pdf",
              "docx",
              "pptx",
              "xlsx",
              "html",
              "zip",
              "txt"
            ],
            "description": "Format of the uploaded file",
            "example": "csv"
          },
          "file_size_bytes": {
            "type": "number",
            "description": "Size of the uploaded file in bytes",
            "example": 1048576,
            "minimum": 0,
            "maximum": 2147483648
          }
        },
        "required": [
          "s3_key",
          "name",
          "file_format",
          "file_size_bytes"
        ]
      },
      "CompleteUploadResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "ID of the newly created dataset",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "description": "Dataset status after `POST /upload/complete`. `preprocessing_failed` when the uploaded files do not share one column schema. Omitted by provider initiate endpoints, which finish in the background.",
            "example": "awaiting_preprocessing"
          }
        },
        "required": [
          "dataset_id"
        ]
      },
      "InitiateBatchFileDto": {
        "type": "object",
        "properties": {
          "file_name": {
            "type": "string",
            "description": "Original file name",
            "example": "report.pdf"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "json",
              "jsonl",
              "parquet",
              "pdf",
              "docx",
              "pptx",
              "xlsx",
              "html",
              "zip",
              "txt"
            ],
            "description": "Format of the file",
            "example": "pdf"
          },
          "file_size_bytes": {
            "type": "number",
            "description": "File size in bytes",
            "example": 1048576
          }
        },
        "required": [
          "file_name",
          "file_format",
          "file_size_bytes"
        ]
      },
      "InitiateBatchDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable name for the dataset",
            "example": "my-document-dataset"
          },
          "files": {
            "description": "List of files to upload. A single batch must be homogeneous: either all document formats (pdf, docx, pptx, xlsx, html, zip) or all tabular formats (csv, json, jsonl, parquet). Mixing the two is rejected because the two pipelines use different credit models and preprocessing stages. TXT files are permissive: they may be included in either kind of batch (or alone, producing a tabular dataset). complete-batch converts TXT contents to csv/jsonl and merges them into the resulting dataset.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InitiateBatchFileDto"
            }
          }
        },
        "required": [
          "name",
          "files"
        ]
      },
      "InitiateBatchUploadDto": {
        "type": "object",
        "properties": {
          "file_name": {
            "type": "string",
            "description": "Original file name"
          },
          "upload_url": {
            "type": "string",
            "description": "Presigned S3 upload URL"
          },
          "s3_key": {
            "type": "string",
            "description": "S3 key for the uploaded file"
          }
        },
        "required": [
          "file_name",
          "upload_url",
          "s3_key"
        ]
      },
      "InitiateBatchResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID"
          },
          "uploads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InitiateBatchUploadDto"
            }
          }
        },
        "required": [
          "dataset_id",
          "uploads"
        ]
      },
      "CompleteBatchFileDto": {
        "type": "object",
        "properties": {
          "s3_key": {
            "type": "string",
            "description": "S3 key returned from initiate-batch"
          },
          "file_name": {
            "type": "string",
            "description": "Original file name"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "json",
              "jsonl",
              "parquet",
              "pdf",
              "docx",
              "pptx",
              "xlsx",
              "html",
              "zip",
              "txt"
            ],
            "description": "File format"
          },
          "file_size_bytes": {
            "type": "number",
            "description": "File size in bytes"
          }
        },
        "required": [
          "s3_key",
          "file_name",
          "file_format",
          "file_size_bytes"
        ]
      },
      "CompleteBatchDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID from initiate-batch"
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompleteBatchFileDto"
            }
          }
        },
        "required": [
          "dataset_id",
          "files"
        ]
      },
      "CompleteBatchResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID"
          },
          "status": {
            "type": "string",
            "description": "Current dataset status"
          }
        },
        "required": [
          "dataset_id",
          "status"
        ]
      },
      "PassthroughColumnMappingDto": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Name of the raw column holding the prompt / input text",
            "example": "question"
          },
          "completion": {
            "type": "string",
            "description": "Name of the raw column holding the completion / target text. Required unless chosen and rejected are given.",
            "example": "answer"
          },
          "chosen": {
            "type": "string",
            "description": "Name of the raw column holding the preferred response. Give it together with rejected to ingest a preference dataset.",
            "example": "chosen"
          },
          "rejected": {
            "type": "string",
            "description": "Name of the raw column holding the dispreferred response. Give it together with chosen.",
            "example": "rejected"
          },
          "context": {
            "description": "Names of raw columns to fold in as context alongside the prompt. Each is validated against the uploaded file at ingestion; an unknown name fails the request listing the available columns. The columns themselves are kept in the dataset as well as folded.",
            "example": [
              "article_body"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "prompt"
        ]
      },
      "DatasetSourceDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "HuggingFace, Kaggle, Google Sheets, or public S3 or Cloud Storage object URL. Provide it to import from that source; omit it to upload a local file instead. An object URL is one https file ending in .csv, .json, .jsonl, or .parquet.",
            "example": "https://huggingface.co/datasets/owner/name"
          },
          "files": {
            "description": "File paths to download from the source. Required with HuggingFace/Kaggle `url`. Not used for Google Sheets — use `sheet_names` (or `sheet_name`) instead — or for a public S3 or Cloud Storage object URL.",
            "example": [
              "train.csv"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sheet_names": {
            "description": "Google Sheets tab titles to import. Only for Google Sheets `url`. Omit or pass `[]` to import every tab; pass one or more titles to import only those tabs.",
            "example": [
              "Sheet1",
              "Sales"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sheet_name": {
            "type": "string",
            "description": "Legacy single Google Sheets tab title. Ignored when `sheet_names` is present (including `[]`).",
            "example": "Sheet1"
          },
          "access": {
            "type": "string",
            "enum": [
              "oauth",
              "public"
            ],
            "description": "Google Sheets only. `public` imports a link-shared spreadsheet without a connected Google account. `oauth` (default) uses the connected account and may be unavailable on some accounts.",
            "default": "oauth"
          },
          "name": {
            "type": "string",
            "description": "Name for the dataset. Required for file uploads, where it may double as a filename (\"sales-data.csv\") to supply the format; derived from the URL for provider imports.",
            "example": "sales-data.csv"
          },
          "file_format": {
            "type": "string",
            "enum": [
              "csv",
              "json",
              "jsonl",
              "parquet",
              "pdf",
              "docx",
              "pptx",
              "xlsx",
              "html",
              "zip",
              "txt"
            ],
            "description": "Format of the file being uploaded. Optional when `name` ends in a supported extension — it is inferred from there, and an explicit value overrides it.",
            "example": "csv"
          },
          "processing_mode": {
            "type": "string",
            "enum": [
              "adapt",
              "raw"
            ],
            "description": "How the data is ingested, for both uploads and provider imports. `adapt` (default) runs it through the adaptation pipeline. `raw` materializes the data straight to a trainable dataset with no augmentation, and needs a column_mapping plus tabular input — `file_format` for an upload, or `files` for an import. Imported files are read as one dataset, so they must share a single format and schema. Either can then be fine-tuned or run through AutoScientist.",
            "example": "raw"
          },
          "column_mapping": {
            "description": "Required when processing_mode is `raw`: which columns to canonicalize as the prompt and the answer — either a completion, or a chosen / rejected pair. Ignored when the dataset is adapted.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PassthroughColumnMappingDto"
              }
            ]
          }
        }
      },
      "CreateDatasetDto": {
        "type": "object",
        "properties": {
          "source": {
            "description": "Dataset source. Pass `url` to import from HuggingFace, Kaggle, Google Sheets, or a public S3 or Cloud Storage object (.csv, .json, .jsonl, or .parquet), or `name` + `file_format` to upload a file. For Sheets, optional `sheet_names` selects tabs (omit or `[]` for all).",
            "allOf": [
              {
                "$ref": "#/components/schemas/DatasetSourceDto"
              }
            ]
          }
        },
        "required": [
          "source"
        ]
      },
      "UploadInstructionsDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Pre-signed URL for uploading the file",
            "example": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=..."
          },
          "method": {
            "type": "string",
            "description": "HTTP method to use",
            "example": "PUT"
          },
          "s3_key": {
            "type": "string",
            "description": "S3 object key — pass this back in the complete request if needed for verification"
          }
        },
        "required": [
          "url",
          "method",
          "s3_key"
        ]
      },
      "CreateDatasetResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "ID of the newly created dataset"
          },
          "status": {
            "type": "string",
            "description": "Current dataset status"
          },
          "upload_instructions": {
            "description": "Upload instructions for file sources. PUT your file to the provided URL.",
            "allOf": [
              {
                "$ref": "#/components/schemas/UploadInstructionsDto"
              }
            ]
          }
        },
        "required": [
          "dataset_id",
          "status"
        ]
      },
      "CompleteUploadByIdDto": {
        "type": "object",
        "properties": {
          "file_size_bytes": {
            "type": "number",
            "description": "Size of the uploaded file in bytes (for verification)",
            "example": 1048576,
            "minimum": 0,
            "maximum": 2147483648
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 hex digest of the uploaded file (for integrity verification)",
            "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
          }
        },
        "required": [
          "file_size_bytes"
        ]
      },
      "CompleteUploadByIdResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "ID of the dataset",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "description": "Current status of the dataset after completing upload",
            "example": "processing"
          }
        },
        "required": [
          "dataset_id",
          "status"
        ]
      },
      "PublicDatasetProgressDto": {
        "type": "object",
        "properties": {
          "percent": {
            "type": "integer",
            "nullable": true,
            "description": "Progress percentage (0-100)"
          },
          "processed_rows": {
            "type": "integer",
            "nullable": true,
            "description": "Number of rows processed so far"
          },
          "total_rows": {
            "type": "integer",
            "nullable": true,
            "description": "Total rows to process (samples_to_process or row_count)"
          }
        },
        "required": [
          "percent",
          "processed_rows",
          "total_rows"
        ]
      },
      "PublicDatasetErrorDataDto": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "nullable": true,
            "description": "Error message"
          },
          "code": {
            "type": "string",
            "nullable": true,
            "description": "Stable error code when the failure was structured (e.g. E0100)"
          },
          "level": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ],
            "nullable": true,
            "description": "Severity when known"
          }
        },
        "required": [
          "message",
          "code",
          "level"
        ]
      },
      "PublicDatasetStatusResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "awaiting_input",
              "succeeded",
              "failed"
            ],
            "description": "Current processing status. `awaiting_input` means the dataset is uploaded but waiting for you to start adaptation via datasets.adapt(column_mapping=...) — it will not progress on its own. An uploaded document dataset with no `row_count` yet is instead waiting for POST /datasets/{dataset_id}/launch-preprocessing."
          },
          "row_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of rows in the dataset"
          },
          "progress": {
            "nullable": true,
            "description": "Processing progress. Null when no run is active.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetProgressDto"
              }
            ]
          },
          "error_data": {
            "nullable": true,
            "description": "Error details if the dataset failed. Null otherwise.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetErrorDataDto"
              }
            ]
          }
        },
        "required": [
          "dataset_id",
          "status",
          "row_count",
          "progress",
          "error_data"
        ]
      },
      "EvaluationQualityDto": {
        "type": "object",
        "properties": {
          "grade_before": {
            "type": "string",
            "nullable": true,
            "description": "Letter grade (A-E) before adaptation",
            "example": "C"
          },
          "grade_after": {
            "type": "string",
            "nullable": true,
            "description": "Letter grade (A-E) after adaptation",
            "example": "A"
          },
          "score_before": {
            "type": "number",
            "nullable": true,
            "description": "Quality score (0-10) before adaptation",
            "example": 6.2
          },
          "score_after": {
            "type": "number",
            "nullable": true,
            "description": "Quality score (0-10) after adaptation",
            "example": 8.5
          },
          "percentile_after": {
            "type": "number",
            "nullable": true,
            "description": "Percentile rank (0-100) after adaptation",
            "example": 92.3
          },
          "improvement_percent": {
            "type": "number",
            "nullable": true,
            "description": "Relative quality improvement as a percentage",
            "example": 37.1
          }
        },
        "required": [
          "grade_before",
          "grade_after",
          "score_before",
          "score_after",
          "percentile_after",
          "improvement_percent"
        ]
      },
      "DatasetEvaluationResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Evaluation pipeline status: pending | running | succeeded | failed | skipped",
            "example": "succeeded"
          },
          "quality": {
            "nullable": true,
            "description": "Structured quality metrics. Null until evaluation completes.",
            "allOf": [
              {
                "$ref": "#/components/schemas/EvaluationQualityDto"
              }
            ]
          },
          "raw_results": {
            "type": "object",
            "additionalProperties": true,
            "nullable": true,
            "description": "Raw evaluation results payload for advanced use. Null until evaluation completes."
          }
        },
        "required": [
          "dataset_id",
          "status",
          "quality",
          "raw_results"
        ]
      },
      "PublicDatasetColumnMappingDto": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "nullable": true
          },
          "completion": {
            "type": "string",
            "nullable": true
          },
          "chat": {
            "type": "string",
            "nullable": true
          },
          "context": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "prompt",
          "completion",
          "chat",
          "context",
          "image"
        ]
      },
      "PublicDatasetEvaluationSummaryDto": {
        "type": "object",
        "properties": {
          "grade_before": {
            "type": "string",
            "nullable": true,
            "description": "Letter grade (A-E) before adaptation"
          },
          "grade_after": {
            "type": "string",
            "nullable": true,
            "description": "Letter grade (A-E) after adaptation"
          },
          "score_before": {
            "type": "number",
            "nullable": true,
            "description": "Quality score before adaptation"
          },
          "score_after": {
            "type": "number",
            "nullable": true,
            "description": "Quality score after adaptation"
          },
          "improvement_percent": {
            "type": "number",
            "nullable": true,
            "description": "Relative improvement percentage"
          }
        },
        "required": [
          "grade_before",
          "grade_after",
          "score_before",
          "score_after",
          "improvement_percent"
        ]
      },
      "PublicDatasetDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Unique dataset identifier"
          },
          "kind": {
            "type": "string",
            "nullable": true,
            "enum": [
              "uploaded",
              "combined",
              "invented",
              "augmented",
              "translated",
              "localized",
              "extended"
            ],
            "description": "How this dataset came about. `uploaded` was supplied by you, `combined` merges several datasets, `invented` was generated from a prompt, `augmented` adds rows retrieved from the curated pool to another dataset, `translated` / `localized` add translated copies of another dataset’s rows, and `extended` adds a next user turn to each of another dataset’s conversations.",
            "example": "augmented"
          },
          "source_dataset_id": {
            "type": "string",
            "nullable": true,
            "description": "The dataset this one was derived from. Set when `kind` is `augmented`, `translated`, `localized` or `extended`. Null for `uploaded` and `invented`, and for `combined`, which has several sources rather than one.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable name for the dataset"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed"
            ],
            "description": "Lifecycle status: pending, running, succeeded, or failed"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the dataset was created"
          },
          "created_by_user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "User who created the dataset"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last update"
          },
          "row_count": {
            "type": "integer",
            "nullable": true,
            "description": "Total number of rows in the dataset"
          },
          "configured_column_mapping": {
            "nullable": true,
            "description": "User-configured column mapping. Null if not yet configured.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetColumnMappingDto"
              }
            ]
          },
          "evaluation_summary": {
            "nullable": true,
            "description": "Compact evaluation summary. Null if evaluation has not completed.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetEvaluationSummaryDto"
              }
            ]
          },
          "run_id": {
            "type": "string",
            "nullable": true,
            "description": "ID of the currently active run"
          },
          "progress": {
            "nullable": true,
            "description": "Processing progress. Null when no run is active.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetProgressDto"
              }
            ]
          },
          "error_data": {
            "nullable": true,
            "description": "Error details if the dataset failed. Null otherwise.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicDatasetErrorDataDto"
              }
            ]
          },
          "image_column_formats": {
            "type": "object",
            "additionalProperties": {
              "enum": [
                "embedded_bytes",
                "url",
                "file_reference"
              ]
            },
            "nullable": true,
            "description": "Per-column export encoding for detected image columns (column name → format). Use with `GET /datasets/{dataset_id}/download`: look up the active image column (mapped image column that is also in `configured_column_mapping.context`) to determine how each row's `original_image` is encoded. Null or empty when no image columns were detected."
          }
        },
        "required": [
          "dataset_id",
          "kind",
          "source_dataset_id",
          "name",
          "status",
          "created_at",
          "created_by_user_id",
          "updated_at",
          "row_count",
          "configured_column_mapping",
          "evaluation_summary",
          "run_id",
          "progress",
          "error_data",
          "image_column_formats"
        ]
      },
      "DatasetBestJobConfigDto": {
        "type": "object",
        "properties": {
          "finetune_job_id": {
            "type": "string",
            "format": "uuid",
            "description": "Fine-tune job whose config is shown (experiment best or standalone)."
          },
          "training_experiment_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Training experiment when this snapshot is the AutoScientist best job; null for a standalone job."
          },
          "original_model_name": {
            "type": "string",
            "nullable": true,
            "description": "Base model id the job was launched with."
          },
          "trained_model_name": {
            "type": "string",
            "nullable": true,
            "description": "Output label / suffix for the trained model. Taken from the value recorded at launch when present; otherwise derived from the current dataset name, in which case it can differ from the label the job was submitted with if the dataset was renamed. Null only when no label was recorded and the dataset is unavailable."
          },
          "training_method": {
            "type": "string",
            "nullable": true,
            "enum": [
              "sft",
              "dpo"
            ]
          },
          "training_type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "lora",
              "full"
            ]
          },
          "data_format": {
            "type": "string",
            "nullable": true,
            "enum": [
              "chat",
              "instruction",
              "preference"
            ]
          },
          "hyperparams": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Hyperparameters the job was launched with."
          }
        },
        "required": [
          "finetune_job_id",
          "training_experiment_id",
          "original_model_name",
          "trained_model_name",
          "training_method",
          "training_type",
          "data_format",
          "hyperparams"
        ]
      },
      "BestFinetuneLaunchConfigResponseDto": {
        "type": "object",
        "properties": {
          "best_job_config": {
            "nullable": true,
            "description": "Launch-parity snapshot for the experiment best job (terminal experiment with `best_finetune_job_id`) or, when no experiment exists, the newest succeeded standalone job (`training_experiment_id` null). Null while an experiment is non-terminal, when no best job was chosen yet, or when no qualifying job exists.",
            "allOf": [
              {
                "$ref": "#/components/schemas/DatasetBestJobConfigDto"
              }
            ]
          }
        },
        "required": [
          "best_job_config"
        ]
      },
      "DatasetSummaryDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Dataset ID",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Dataset name",
            "example": "My training data"
          },
          "status": {
            "type": "string",
            "description": "Dataset status",
            "enum": [
              "pending",
              "running",
              "awaiting_input",
              "succeeded",
              "failed"
            ],
            "example": "pending"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string",
            "description": "Last updated timestamp"
          },
          "created_at": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when the dataset was created"
          },
          "row_count": {
            "type": "integer",
            "nullable": true,
            "description": "Total number of rows",
            "example": 1000
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Auto-generated description of the dataset contents"
          }
        },
        "required": [
          "dataset_id",
          "status",
          "updated_at",
          "created_at"
        ]
      },
      "CursorListResponseDto": {
        "type": "object",
        "properties": {
          "datasets": {
            "description": "Page of datasets",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DatasetSummaryDto"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Cursor for the next page. Null when no more results.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        },
        "required": [
          "datasets"
        ]
      },
      "DatasetExportLinksResponseDto": {
        "type": "object",
        "properties": {
          "huggingface": {
            "type": "string",
            "nullable": true,
            "description": "URL of the dataset on Hugging Face, if a successful export exists"
          },
          "kaggle": {
            "type": "string",
            "nullable": true,
            "description": "URL of the dataset on Kaggle, if a successful export exists"
          },
          "google_sheets": {
            "type": "string",
            "nullable": true,
            "description": "URL of the Google Spreadsheet, if a successful export exists"
          }
        }
      },
      "PreprocessingInsufficientCreditsDto": {
        "type": "object",
        "properties": {
          "creditsRequired": {
            "type": "number",
            "description": "Credits the extraction would reserve"
          },
          "creditsAvailable": {
            "type": "number",
            "description": "Credits available to the team"
          }
        },
        "required": [
          "creditsRequired",
          "creditsAvailable"
        ]
      },
      "PreprocessingCreditsResponseDto": {
        "type": "object",
        "properties": {
          "availableCredits": {
            "type": "number",
            "description": "User's total available credits (team balance)"
          },
          "extractionCost": {
            "type": "number",
            "description": "Estimated or actual credit cost for document extraction"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages across all documents (sum of page counts)"
          },
          "totalDocuments": {
            "type": "number",
            "description": "Total documents in the dataset"
          },
          "completedDocuments": {
            "type": "number",
            "description": "Number of documents with completed extraction (page counts known)"
          },
          "isFinal": {
            "type": "boolean",
            "description": "Whether the cost is final (all extractions complete) or an estimate"
          },
          "insufficientCredits": {
            "description": "Present when available credits are insufficient for the extraction cost",
            "allOf": [
              {
                "$ref": "#/components/schemas/PreprocessingInsufficientCreditsDto"
              }
            ]
          }
        },
        "required": [
          "availableCredits",
          "extractionCost",
          "totalPages",
          "totalDocuments",
          "completedDocuments",
          "isFinal"
        ]
      },
      "LaunchPreprocessingBodyDto": {
        "type": "object",
        "properties": {
          "pages_to_process": {
            "type": "number",
            "description": "Maximum number of pages to process. Documents are included until this budget is reached. If omitted, all pages are processed.",
            "minimum": 1
          },
          "documents_to_process": {
            "type": "number",
            "description": "Maximum number of documents to process. If omitted, all documents are processed.",
            "minimum": 1
          },
          "preprocessing_mode": {
            "type": "string",
            "enum": [
              "per_document",
              "per_page"
            ],
            "description": "How extracted content becomes rows: `per_document` (default) makes one row per document, `per_page` one row per page. Omit to keep the mode already set on the dataset.",
            "example": "per_document"
          }
        }
      },
      "LaunchPreprocessingResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "ID of the dataset"
          },
          "status": {
            "type": "string",
            "description": "Dataset status after the launch. Poll GET /datasets/{dataset_id}/status until it reports `awaiting_input`, then call POST /datasets/{dataset_id}/adapt.",
            "example": "pending"
          },
          "credits_escrowed": {
            "type": "number",
            "description": "Credits reserved for extracting the selected documents"
          },
          "pages_to_process": {
            "type": "number",
            "description": "Total pages across the documents selected for extraction"
          },
          "documents_selected": {
            "type": "number",
            "description": "Number of documents selected for extraction"
          },
          "documents_total": {
            "type": "number",
            "description": "Number of documents in the dataset"
          }
        },
        "required": [
          "dataset_id",
          "status"
        ]
      },
      "PublicAugmentDto": {
        "type": "object",
        "properties": {
          "domain_rows": {
            "type": "number",
            "description": "How many additional rows to retrieve from topics matching this dataset. Omit domain_rows and general_rows to receive the recommended fill and its cost as a quote; a run needs a count, or fill_to_recommended=true.",
            "minimum": 0,
            "maximum": 100000,
            "example": 3000
          },
          "general_rows": {
            "type": "number",
            "description": "How many additional rows to retrieve from other topics, to broaden the dataset. Omit domain_rows and general_rows to receive the recommended fill and its cost as a quote; a run needs a count, or fill_to_recommended=true.",
            "minimum": 0,
            "maximum": 100000,
            "example": 1000
          },
          "similar_rows": {
            "type": "number",
            "description": "How many new rows to generate in the style of this dataset. A sample of its rows is analysed for topic, language and prompt/completion conventions, and new rows are generated to match. Combines with domain_rows and general_rows in one run, and is never filled from the recommendation. Naming it makes the request explicit rather than a quote. Defaults to 0.",
            "minimum": 0,
            "maximum": 100000,
            "example": 500
          },
          "fill_to_recommended": {
            "type": "boolean",
            "description": "When true, fills every count you leave out (domain_rows, general_rows) with its recommended value; a count you name is used as given. Omit every count (including similar_rows) and leave this false to receive the recommended fill as a quote instead.",
            "default": false
          },
          "training_type": {
            "type": "string",
            "description": "Shape of the rows to retrieve. `instruction_dataset` (default) retrieves prompt/completion pairs for SFT; `preference_pairs` retrieves chosen/rejected pairs for DPO.",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "example": "instruction_dataset"
          },
          "estimate": {
            "type": "boolean",
            "description": "When true, validates the request and returns the estimated credit cost without starting a run or creating a dataset.",
            "default": false
          },
          "idempotency_key": {
            "type": "string",
            "description": "Opaque key that makes a retried request safe. A second request carrying the same key returns the dataset the first one created instead of starting and charging for a second run.",
            "maxLength": 255
          }
        }
      },
      "PublicAugmentResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "nullable": true,
            "description": "The augmented dataset. It carries this dataset’s rows plus the retrieved ones, and is ready to download once its status reaches `succeeded`. Null for an estimate, which creates nothing.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Status of the augmented dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches `succeeded` or `failed`. An idempotent replay of a finished run returns its terminal status here.",
            "enum": [
              "pending",
              "running",
              "awaiting_input",
              "succeeded",
              "failed"
            ],
            "example": "running"
          },
          "domain_rows": {
            "type": "number",
            "description": "Rows this run retrieves from topics matching the dataset, or the recommended fill an estimate priced.",
            "example": 17000
          },
          "general_rows": {
            "type": "number",
            "description": "Rows this run retrieves from other topics, to broaden the dataset, or the recommended fill an estimate priced.",
            "example": 0
          },
          "estimated_credits_consumed": {
            "type": "number",
            "description": "Credits this run consumes, charged against the requested rows.",
            "example": 40
          },
          "estimate": {
            "type": "boolean",
            "description": "Whether this was an estimate-only request (no run started)."
          }
        },
        "required": [
          "dataset_id",
          "status",
          "domain_rows",
          "general_rows",
          "estimated_credits_consumed",
          "estimate"
        ]
      },
      "PublicAugmentQuoteDetailsDto": {
        "type": "object",
        "properties": {
          "domain_rows": {
            "type": "number",
            "example": 17000
          },
          "general_rows": {
            "type": "number",
            "example": 8000
          },
          "estimated_credits_consumed": {
            "type": "number",
            "example": 250
          },
          "estimate": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "domain_rows",
          "general_rows",
          "estimated_credits_consumed",
          "estimate"
        ]
      },
      "PublicAugmentQuoteErrorDto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "error": {
            "type": "string",
            "example": "Bad Request"
          },
          "message": {
            "type": "string",
            "description": "Explains how to accept the recommended fill or request an estimate."
          },
          "details": {
            "$ref": "#/components/schemas/PublicAugmentQuoteDetailsDto"
          }
        },
        "required": [
          "statusCode",
          "error",
          "message",
          "details"
        ]
      },
      "PublicTranslateDto": {
        "type": "object",
        "properties": {
          "sample_rate": {
            "type": "number",
            "description": "Fraction of this dataset’s rows to expand, per target. At 0.25 with two targets, a 1,000-row dataset gains 500 rows and the new dataset holds 1,500.",
            "minimum": 0.01,
            "maximum": 1,
            "example": 0.25
          },
          "estimate": {
            "type": "boolean",
            "description": "When true, validates the request and returns the estimated credit cost without starting a run or creating a dataset.",
            "default": false
          },
          "idempotency_key": {
            "type": "string",
            "description": "Opaque key that makes a retried request safe. A second request carrying the same key returns the dataset the first one created instead of starting and charging for a second run.",
            "maxLength": 255
          },
          "languages": {
            "description": "Target languages, as ISO 639-1 codes. Each sampled row gains one translated row per language. Unsupported codes are rejected with a sample of the supported ones.",
            "minItems": 1,
            "example": [
              "es",
              "fr"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "sample_rate",
          "languages"
        ]
      },
      "PublicExpandResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "nullable": true,
            "description": "The expanded dataset. It carries this dataset’s rows plus the new ones, and is ready to download once its status reaches `succeeded`. Null for an estimate, which creates nothing.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Status of the expanded dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches `succeeded` or `failed`. An idempotent replay of a finished run returns its terminal status here.",
            "enum": [
              "pending",
              "running",
              "awaiting_input",
              "succeeded",
              "failed"
            ],
            "example": "running"
          },
          "estimated_credits_consumed": {
            "type": "number",
            "description": "Credits this run consumes, charged against the rows it adds. Zero on an idempotent replay: the earlier run reserved the credits, and this call charges nothing.",
            "example": 5
          },
          "estimate": {
            "type": "boolean",
            "description": "Whether this was an estimate-only request (no run started)."
          },
          "estimated_new_rows": {
            "type": "number",
            "description": "Rows this run adds, which is what the credit cost is charged against. Zero on an idempotent replay, which adds none.",
            "example": 500
          }
        },
        "required": [
          "dataset_id",
          "status",
          "estimated_credits_consumed",
          "estimate",
          "estimated_new_rows"
        ]
      },
      "PublicCountryLanguagePairDto": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code.",
            "example": "ES"
          },
          "language": {
            "type": "string",
            "description": "Language code, as ISO 639-1 — optionally with a script subtag. Supported pairs include codes that are not two letters (`zh-Hant` for Taiwan, `yue` for Hong Kong), so the length is not pinned at two here. Membership is decided against the supported-pair list, which names an unsupported entry in its own 400.",
            "example": "ca"
          }
        },
        "required": [
          "country",
          "language"
        ]
      },
      "PublicLocalizeDto": {
        "type": "object",
        "properties": {
          "sample_rate": {
            "type": "number",
            "description": "Fraction of this dataset’s rows to expand, per target. At 0.25 with two targets, a 1,000-row dataset gains 500 rows and the new dataset holds 1,500.",
            "minimum": 0.01,
            "maximum": 1,
            "example": 0.25
          },
          "estimate": {
            "type": "boolean",
            "description": "When true, validates the request and returns the estimated credit cost without starting a run or creating a dataset.",
            "default": false
          },
          "idempotency_key": {
            "type": "string",
            "description": "Opaque key that makes a retried request safe. A second request carrying the same key returns the dataset the first one created instead of starting and charging for a second run.",
            "maxLength": 255
          },
          "pairs": {
            "description": "Target country/language pairs. Each sampled row gains one row localized to each pair — translated into the language and adapted to that country’s conventions. Unsupported combinations are rejected.",
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCountryLanguagePairDto"
            }
          }
        },
        "required": [
          "sample_rate",
          "pairs"
        ]
      },
      "PublicColumnMappingDto": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Column to use as the prompt/instruction field. Trigger for prompt mode (with optional `completion` and `context`); cannot be combined with `chat` or `universal_prompt`.",
            "example": "instruction"
          },
          "completion": {
            "type": "string",
            "description": "Column to use as the completion/response field. Optional in prompt mode and universal-prompt mode; not allowed in chat mode.",
            "example": "response"
          },
          "chat": {
            "type": "string",
            "description": "Column containing chat/conversation data. Chat mode is exclusive: `prompt`, `completion`, `context` and `universal_prompt` must be omitted. An `image` column may accompany it — chat supplies the text framing an image column needs.",
            "example": "messages"
          },
          "context": {
            "description": "Columns to include as context. Optional in prompt mode; required (at least one entry) in universal-prompt mode; not allowed in chat mode.",
            "example": [
              "context"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "universal_prompt": {
            "type": "string",
            "description": "Dataset-wide instruction folded into every row alongside the context columns. Use when there is no per-row prompt column but rows share a common task framing. Requires a per-row differentiator, so that the folded prompt is not identical on every row: at least one entry in `context`, or an `image` column.",
            "example": "Reframe the following passage as a clear, factual question."
          },
          "image": {
            "type": "string",
            "description": "Column containing per-row images (URLs, file paths, or encoded bytes) to fold into the adaptation as multimodal context. Allowed in any mode (prompt, universal-prompt, or chat) as long as text framing is also present — it cannot be the only mapping. The column is automatically added to `context` if omitted. Note: opting a dataset into multimodal context disqualifies it from finetuning.",
            "example": "image_column"
          }
        }
      },
      "RecipeOptionsDto": {
        "type": "object",
        "properties": {
          "prompt_rephrase": {
            "type": "boolean",
            "description": "Rephrase prompts for variety and clarity",
            "example": true
          },
          "deduplication": {
            "type": "boolean",
            "description": "Remove near-duplicate rows",
            "example": true
          },
          "reasoning_traces": {
            "type": "boolean",
            "description": "Add reasoning traces (chain-of-thought) to completions",
            "example": false
          }
        }
      },
      "PublicRecipeSpecDto": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "description": "Reserved. Accepted and stored for forward compatibility, but not yet read — recipe options are currently versioned by release rather than by this field. Omit it.",
            "example": "2026-04",
            "default": "2026-04"
          },
          "recipes": {
            "description": "Adaptation recipe toggles. Omitted recipes use backend defaults.",
            "allOf": [
              {
                "$ref": "#/components/schemas/RecipeOptionsDto"
              }
            ]
          }
        }
      },
      "PublicJobSpecDto": {
        "type": "object",
        "properties": {
          "max_rows": {
            "type": "number",
            "description": "Maximum number of rows to process in this run",
            "minimum": 1
          },
          "idempotency_key": {
            "type": "string",
            "description": "Client-generated idempotency key for safe retries. If a launch with the same key already exists, the original response is returned."
          }
        }
      },
      "PublicBrandControlsDto": {
        "type": "object",
        "properties": {
          "length": {
            "type": "string",
            "description": "Target response length. Controls verbosity of generated completions.",
            "enum": [
              "minimal",
              "concise",
              "detailed",
              "extensive"
            ],
            "example": "concise"
          },
          "safety_categories": {
            "description": "Turns on content-safety analysis for the generated completions. Supply one or more of `violence`, `self_harm`, `harassment`, `hate`, `sexual`. Any non-empty list enables the analysis, and every row is then scored against all five categories — the list does not narrow what is checked. Results arrive as the `prompt_safety_issues` and `response_safety_issues` columns on the adapted dataset. Rows are annotated, never removed.",
            "example": [
              "harassment",
              "hate"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hallucination_mitigation": {
            "type": "boolean",
            "description": "Enable web-search grounding to reduce hallucinations in generated completions.",
            "example": true
          },
          "blueprint": {
            "type": "string",
            "description": "Freeform brand/style instructions injected as a system prompt for every generated completion. Use this to enforce tone, language, persona, or any guideline that does not fit the structured length/safety/grounding controls.",
            "example": "All generated text must be written exclusively in Brazilian Portuguese (pt-BR)."
          }
        }
      },
      "PublicTranslateTargetsDto": {
        "type": "object",
        "properties": {
          "languages": {
            "description": "Target languages, as ISO 639-1 codes. Each sampled row gains one translated row per language. Unsupported codes are rejected with a sample of the supported ones.",
            "minItems": 1,
            "example": [
              "es",
              "fr"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sample_rate": {
            "type": "number",
            "description": "Fraction of rows translated into each language. At 0.25 with two languages, 1,000 rows become 1,500.",
            "minimum": 0.01,
            "maximum": 1,
            "example": 0.25
          }
        },
        "required": [
          "languages",
          "sample_rate"
        ]
      },
      "PublicLocalizeTargetsDto": {
        "type": "object",
        "properties": {
          "pairs": {
            "description": "Target country/language pairs. Each sampled row gains one row localized to each pair — translated into the language and adapted to that country’s conventions. Unsupported combinations are rejected.",
            "minItems": 1,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCountryLanguagePairDto"
            }
          },
          "sample_rate": {
            "type": "number",
            "description": "Fraction of rows localized to each pair. At 0.25 with one pair, 1,000 rows become 1,250.",
            "minimum": 0.01,
            "maximum": 1,
            "example": 0.25
          }
        },
        "required": [
          "pairs",
          "sample_rate"
        ]
      },
      "PublicAdaptExpandDto": {
        "type": "object",
        "properties": {
          "similar_rows": {
            "type": "integer",
            "description": "New rows to generate in the style of this dataset. A sample of its rows is analysed for topic, language and prompt/completion conventions, and new rows are generated to match. Defaults to 0.",
            "minimum": 0,
            "maximum": 100000,
            "example": 500
          },
          "domain_rows": {
            "type": "integer",
            "description": "Rows to retrieve from topics matching this dataset. Defaults to 0.",
            "minimum": 0,
            "maximum": 100000,
            "example": 3000
          },
          "general_rows": {
            "type": "integer",
            "description": "Rows to retrieve from other topics, to broaden the dataset. Defaults to 0.",
            "minimum": 0,
            "maximum": 100000,
            "example": 1000
          }
        }
      },
      "PublicLanguageExpansionSpecDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Expansion mode. `translate` produces one new row variant per target language; `localize` produces one new row variant per country/language pair.",
            "enum": [
              "translate",
              "localize"
            ],
            "example": "translate"
          },
          "languages": {
            "description": "Target language codes (required when type=translate, forbidden when type=localize). Mostly ISO 639-1 two-letter codes such as `es`, with three-letter codes where no two-letter code exists (`fil`, `yue`) and script-tagged codes for Chinese (`zh-Hans`, `zh-Hant`). Matching is case-insensitive, and bare `zh` resolves to `zh-Hans`. Validated against the supported language list at request time; unknown values return 400 with a sample of supported codes.",
            "example": [
              "es",
              "fr"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pairs": {
            "description": "Country/language pairs (required when type=localize, forbidden when type=translate). Each pair is validated against the supported country/language pair list at request time.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCountryLanguagePairDto"
            }
          },
          "sample_rate": {
            "type": "number",
            "description": "Fraction (0.01–1) of input rows that are expanded per target. Output rows ≈ input × (1 + sample_rate × target_count). Required. Credits are billed on the expanded output row count.",
            "minimum": 0.01,
            "maximum": 1,
            "example": 0.25
          }
        },
        "required": [
          "type",
          "sample_rate"
        ]
      },
      "PublicLaunchDto": {
        "type": "object",
        "properties": {
          "column_mapping": {
            "description": "Column role assignments for adaptation. Required for real runs, optional for estimate-only requests.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicColumnMappingDto"
              }
            ]
          },
          "recipe_specification": {
            "description": "Adaptation recipe configuration. Omitted recipes use backend defaults.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicRecipeSpecDto"
              }
            ]
          },
          "job_specification": {
            "description": "Job execution parameters",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicJobSpecDto"
              }
            ]
          },
          "brand_controls": {
            "description": "Brand and quality controls for generated completions. Covers response length, content safety categories, web-search grounding, and a freeform blueprint system prompt.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicBrandControlsDto"
              }
            ]
          },
          "training_type": {
            "type": "string",
            "description": "How to adapt the dataset. `instruction_dataset` (default) produces enhanced prompt/completion pairs for SFT; `preference_pairs` generates chosen/rejected pairs for DPO. Source columns are the same in both cases — `column_mapping.prompt` (and optionally `completion`) — the chosen/rejected fields are produced by the adaptation pipeline.",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "example": "instruction_dataset"
          },
          "estimate": {
            "type": "boolean",
            "description": "When true, validates the request and returns the estimated credit cost without starting a run. The request’s `column_mapping` and expansion fields are still saved to the dataset, as they are what the estimate prices.",
            "default": false
          },
          "translate": {
            "description": "Translate a sample of the rows into further languages, adding one row per sampled row and language. Combines with `localize`; output row count ≈ input × (1 + translate.sample_rate × languages + localize.sample_rate × pairs), and credits are billed on output rows.\n\nPassing `translate`, `localize` or `expand` sets the whole selection for this run: a mode the request leaves out is turned off, including one saved in the dashboard. With none of them (and no `language_expansion`), the selection saved on the dataset is used. Cannot be combined with `language_expansion`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicTranslateTargetsDto"
              }
            ]
          },
          "localize": {
            "description": "Localize a sample of the rows to country/language pairs, adding one row per sampled row and pair. Combines with `translate` and `expand`, with the same rules: passing any of them sets the whole selection for this run. Cannot be combined with `language_expansion`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicLocalizeTargetsDto"
              }
            ]
          },
          "expand": {
            "description": "Add rows before adaptation: generated in the style of this dataset, or retrieved from matching and other topics. They are adapted along with the dataset’s own rows into this dataset, so its row count grows by their total. Translation and localization apply to the dataset’s own rows only.\n\nEach block costs 1 credit per 100 rows, rounded up, on top of the adaptation; the estimate includes it. Set at least one count above 0. Returns 400, leaving the saved selection unchanged, when Expand is not enabled for the organization or the dataset has image context; a column mapping with no chat, prompt or completion column or universal prompt to seed from is a 400 too. Combines with `translate` and `localize`, with the same rules: passing any of them sets the whole selection for this run. Cannot be combined with `language_expansion`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicAdaptExpandDto"
              }
            ]
          },
          "language_expansion": {
            "deprecated": true,
            "description": "Deprecated: use `translate` and `localize`, which can be combined. Holds one mode, translate or localize.\n\nThree-state field:\n- **omitted** — leaves any prior expansion config on the dataset unchanged (no-op). A wizard-saved expansion is preserved across SDK-driven /adapt calls that pass neither `language_expansion` nor `translate` / `localize`.\n- **`language_expansion: null`** — explicitly clears any prior expansion config on this dataset (overrides wizard state), including a dashboard-selected Expand.\n- **object** — overwrites the prior expansion config with the given spec. Every other mode saved on the dataset, Expand included, is turned off.",
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicLanguageExpansionSpecDto"
              }
            ]
          }
        }
      },
      "PublicLaunchResponseDto": {
        "type": "object",
        "properties": {
          "run_id": {
            "type": "string",
            "description": "Unique identifier for this pipeline run. Null for estimate-only requests.",
            "example": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890",
            "nullable": true
          },
          "estimatedMinutes": {
            "type": "number",
            "description": "Estimated processing time in minutes"
          },
          "estimatedCreditsConsumed": {
            "type": "number",
            "description": "Estimated number of credits that will be consumed by this run"
          },
          "estimate": {
            "type": "boolean",
            "description": "Whether this was an estimate-only request (no run started)"
          },
          "multimodalPricingApplied": {
            "type": "boolean",
            "description": "True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate."
          },
          "creditMultiplier": {
            "type": "number",
            "description": "10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing."
          }
        },
        "required": [
          "estimatedMinutes",
          "estimatedCreditsConsumed",
          "estimate",
          "multimodalPricingApplied"
        ]
      },
      "PublicExtendTrajectoriesColumnMappingDto": {
        "type": "object",
        "properties": {
          "chat": {
            "type": "string",
            "description": "Column holding each row's conversation as a list of `{\"role\", \"content\"}` turns (or a JSON string encoding that list), ending on the assistant's reply. The full conversation is the trajectory the next user message is generated from. Send `chat` alone, or `prompt` with `completion` instead. Not available on an adapted dataset: adapt splits the chat column into `original_prompt` and `original_completion`, so map those with `prompt` and `completion`.",
            "example": "messages"
          },
          "prompt": {
            "type": "string",
            "description": "Column holding the conversation up to and including the user's last turn: a list of `{\"role\", \"content\"}` turns (or a JSON string encoding that list), or a plain string read as a single user turn. Requires `completion`; not allowed with `chat`. On an adapted dataset, a column of its download: `original_prompt` if it was adapted from a chat column, otherwise the dataset's own prompt column.",
            "example": "prompt"
          },
          "completion": {
            "type": "string",
            "description": "Column holding the assistant's final reply to `prompt`, as plain text. It becomes the last turn of the trajectory. Requires `prompt`; not allowed with `chat`. On an adapted dataset, a column of its download: `enhanced_completion` extends the adapted reply, the original completion column extends the reply as uploaded.",
            "example": "response"
          }
        }
      },
      "PublicExtendTrajectoriesDto": {
        "type": "object",
        "properties": {
          "column_mapping": {
            "description": "Column role assignments. Required for real runs, optional for estimate-only requests.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicExtendTrajectoriesColumnMappingDto"
              }
            ]
          },
          "job_specification": {
            "description": "Job execution parameters",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicJobSpecDto"
              }
            ]
          },
          "estimate": {
            "type": "boolean",
            "description": "When true, validates the request and returns the estimated credit cost without starting a run.",
            "default": false
          }
        }
      },
      "PublicExtendTrajectoriesResponseDto": {
        "type": "object",
        "properties": {
          "run_id": {
            "type": "string",
            "description": "Unique identifier for this pipeline run. Null for estimate-only requests.",
            "example": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890",
            "nullable": true
          },
          "estimatedMinutes": {
            "type": "number",
            "description": "Estimated processing time in minutes"
          },
          "estimatedCreditsConsumed": {
            "type": "number",
            "description": "Estimated number of credits that will be consumed by this run"
          },
          "estimate": {
            "type": "boolean",
            "description": "Whether this was an estimate-only request (no run started)"
          },
          "multimodalPricingApplied": {
            "type": "boolean",
            "description": "True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate."
          },
          "creditMultiplier": {
            "type": "number",
            "description": "10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing."
          },
          "dataset_id": {
            "type": "string",
            "format": "uuid",
            "description": "The new dataset holding the extended trajectories. Poll GET /datasets/{dataset_id}/status and download from GET /datasets/{dataset_id}/download with this id, not the source dataset's. Null for estimate-only requests.",
            "example": "7d1f3c2a-9b4e-4f60-8a1d-2e5c6b7a8f90",
            "nullable": true
          }
        },
        "required": [
          "estimatedMinutes",
          "estimatedCreditsConsumed",
          "estimate",
          "multimodalPricingApplied",
          "dataset_id"
        ]
      },
      "OriginalImageEmbeddedDto": {
        "type": "object",
        "properties": {
          "bytes": {
            "type": "string",
            "description": "Base64-encoded image bytes (JPEG or PNG)."
          },
          "path": {
            "type": "null",
            "nullable": true,
            "description": "Always null (Hugging Face `datasets` convention).",
            "example": null
          }
        },
        "required": [
          "bytes",
          "path"
        ]
      },
      "ProcessedDatasetExportOriginalImageFieldDto": {
        "type": "object",
        "properties": {
          "original_image": {
            "description": "Mapped source image for this row. Encoding depends on the active image column entry in `image_column_formats` on the dataset: `embedded_bytes` uses the object shape; `url` and `file_reference` use a presigned HTTPS URL string. Null when the row has no image. Omitted when no image column is mapped or the image column is not included in `context`.",
            "oneOf": [
              {
                "type": "string",
                "format": "uri",
                "description": "Presigned HTTPS URL (expires; typically one hour) when format is `url` or `file_reference`."
              },
              {
                "$ref": "#/components/schemas/OriginalImageEmbeddedDto"
              },
              {
                "type": "null"
              }
            ],
            "nullable": true
          }
        }
      },
      "PublishRequestDto": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "enum": [
              "huggingface",
              "kaggle"
            ],
            "description": "Destination platform for publishing the dataset",
            "example": "huggingface"
          },
          "target_spec": {
            "type": "object",
            "description": "Target-specific configuration (e.g. repo name for HuggingFace, slug for Kaggle)",
            "example": {
              "repo_name": "my-augmented-dataset",
              "private": true
            },
            "additionalProperties": true
          }
        },
        "required": [
          "target"
        ]
      },
      "PublishAcceptedResponseDto": {
        "type": "object",
        "properties": {
          "publish_id": {
            "type": "string",
            "description": "Unique identifier for the publish job",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "status": {
            "type": "string",
            "description": "Status of the publish job",
            "example": "queued"
          },
          "message": {
            "type": "string",
            "description": "Additional information about the publish request"
          }
        },
        "required": [
          "publish_id",
          "status"
        ]
      },
      "ValidateCombineRequestDto": {
        "type": "object",
        "properties": {
          "dataset_ids": {
            "description": "Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.",
            "minItems": 2,
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "dataset_ids"
        ]
      },
      "CombineValidationDatasetTypeDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Source Dataset ID."
          },
          "type": {
            "type": "string",
            "description": "DuckDB type observed for this Dataset."
          }
        },
        "required": [
          "dataset_id",
          "type"
        ]
      },
      "CombineValidationColumnDto": {
        "type": "object",
        "properties": {
          "column": {
            "type": "string",
            "description": "Column whose source types do not agree."
          },
          "types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombineValidationDatasetTypeDto"
            }
          },
          "cast_to": {
            "type": "string",
            "description": "Common DuckDB type used by the merge."
          }
        },
        "required": [
          "column",
          "types",
          "cast_to"
        ]
      },
      "CombineValidationTrainingTypeDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "Source Dataset ID."
          },
          "training_type": {
            "type": "string",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "description": "Training type resolved for this source Dataset."
          }
        },
        "required": [
          "dataset_id",
          "training_type"
        ]
      },
      "CombineValidationIssueDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "too_few_sources",
              "too_many_sources",
              "duplicate_source_ids",
              "dataset_not_found",
              "wrong_organization",
              "dataset_not_ready",
              "missing_run_id",
              "mixed_multimodal_sources",
              "all_preference_sources_missing_dpo_columns",
              "incompatible_column_types",
              "preference_source_missing_ranked_generations",
              "mixed_training_types_resolved_to_sft"
            ],
            "description": "Stable machine-readable validation issue code."
          },
          "level": {
            "type": "string",
            "enum": [
              "error",
              "warning"
            ],
            "description": "`error` blocks the merge; `warning` describes automatic reconciliation."
          },
          "message": {
            "type": "string",
            "description": "Preformed user-facing message."
          },
          "count": {
            "type": "number"
          },
          "limit": {
            "type": "number"
          },
          "dataset_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "dataset_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "multimodal_dataset_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "text_dataset_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombineValidationColumnDto"
            }
          },
          "types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombineValidationTrainingTypeDto"
            }
          }
        },
        "required": [
          "code",
          "level",
          "message"
        ]
      },
      "ValidateCombineResponseDto": {
        "type": "object",
        "properties": {
          "compatible": {
            "type": "boolean",
            "description": "Whether the proposed merge can proceed."
          },
          "training_type": {
            "type": "string",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "description": "Resolved training type for a compatible merge. Homogeneous source sets inherit their shared type; mixed instruction + preference sets resolve to `instruction_dataset`."
          },
          "total_estimated_rows": {
            "type": "number",
            "description": "Sum of processed_rows across all sources for a compatible merge."
          },
          "issues": {
            "description": "Validation diagnostics. Errors block the merge; warnings describe reconciliation the merge performs automatically.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CombineValidationIssueDto"
            }
          }
        },
        "required": [
          "compatible",
          "issues"
        ]
      },
      "CombineRequestDto": {
        "type": "object",
        "properties": {
          "dataset_ids": {
            "description": "Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.",
            "minItems": 2,
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "description": "User-supplied name for the merged Dataset. Surfaced in the dataset list."
          }
        },
        "required": [
          "dataset_ids",
          "name"
        ]
      },
      "CombineResponseDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "The newly created merged Dataset’s ID. Returns existing ID on idempotent replay."
          }
        },
        "required": [
          "dataset_id"
        ]
      },
      "InvalidJudgePromptIssueDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "not_a_judge_prompt",
              "scale_not_zero_to_ten",
              "scores_not_integer",
              "missing_rubric"
            ],
            "description": "Which of the rubric rules the prompt broke."
          },
          "detail": {
            "type": "string",
            "description": "User-facing sentence describing the problem and the fix."
          }
        },
        "required": [
          "code",
          "detail"
        ]
      },
      "InvalidJudgePromptDetailsDto": {
        "type": "object",
        "properties": {
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvalidJudgePromptIssueDto"
            }
          },
          "suggested_prompt": {
            "type": "string",
            "nullable": true,
            "description": "A corrected rewrite the user can accept, or null when none could be produced."
          }
        },
        "required": [
          "issues",
          "suggested_prompt"
        ]
      },
      "InvalidJudgePromptErrorDto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "All issue details joined into one line."
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_judge_prompt"
            ],
            "description": "Discriminates this from the other 400s on the route."
          },
          "issues": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvalidJudgePromptIssueDto"
            }
          },
          "suggested_prompt": {
            "type": "string",
            "nullable": true,
            "description": "A corrected rewrite the user can accept, or null when none could be produced."
          },
          "details": {
            "$ref": "#/components/schemas/InvalidJudgePromptDetailsDto"
          }
        },
        "required": [
          "statusCode",
          "error",
          "message",
          "code",
          "issues",
          "details"
        ]
      },
      "PublicApiErrorDto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 400
          },
          "error": {
            "type": "string",
            "example": "Bad Request"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "statusCode",
          "error",
          "message"
        ]
      },
      "CreateCustomEvalDto": {
        "type": "object",
        "properties": {
          "judge_prompt": {
            "type": "string",
            "minLength": 20,
            "maxLength": 20000,
            "description": "The judge rubric. Scored per sample against the original and adapted pairs.",
            "example": "Rate how factually accurate the response is, from 0 (fabricated) to 10 (fully supported)."
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional label so a history of rubrics stays legible."
          }
        },
        "required": [
          "judge_prompt"
        ]
      },
      "CustomEvalResponseDto": {
        "type": "object",
        "properties": {
          "custom_eval_id": {
            "type": "string"
          },
          "dataset_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "pending | running | succeeded | failed",
            "example": "running"
          },
          "judge_prompt": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "score_before": {
            "type": "number",
            "nullable": true,
            "description": "Mean rubric score on the original pairs. Null until the eval succeeds."
          },
          "score_after": {
            "type": "number",
            "nullable": true,
            "description": "Mean rubric score on the adapted pairs. Null until the eval succeeds."
          },
          "improvement_percent": {
            "type": "number",
            "nullable": true,
            "description": "Percentage change from score_before to score_after. Null until the eval succeeds."
          },
          "scored_rows": {
            "type": "integer",
            "nullable": true,
            "description": "Rows the judge scored. A rubric score is an average over this sample, not the whole dataset."
          },
          "error_message": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "custom_eval_id",
          "dataset_id",
          "status",
          "judge_prompt",
          "name",
          "score_before",
          "score_after",
          "improvement_percent",
          "scored_rows",
          "error_message",
          "created_at",
          "completed_at"
        ]
      },
      "CustomEvalListResponseDto": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomEvalResponseDto"
            }
          }
        },
        "required": [
          "items"
        ]
      },
      "PublicTrainingColumnMappingDto": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Source column holding the prompt/instruction text."
          },
          "completion": {
            "type": "string",
            "description": "Source column holding the target completion/response. Used for supervised (sft) training."
          },
          "reasoning_trace": {
            "type": "string",
            "description": "Optional source column holding a reasoning trace to train on. Supported on instruction runs with a model whose GET /autoscientist/models entry reports `train_with_reasoning: true`; naming it with any other model on such a run is rejected."
          },
          "chosen": {
            "type": "string",
            "description": "Source column holding the preferred response. Used for preference (dpo) training, where a row carries two completions rather than one. Pair it with `rejected`."
          },
          "rejected": {
            "type": "string",
            "description": "Source column holding the rejected response. Pair it with `chosen`."
          }
        }
      },
      "PublicAutoScientistHyperparamsDto": {
        "type": "object",
        "properties": {
          "training_type": {
            "type": "string",
            "enum": [
              "lora",
              "full"
            ],
            "description": "Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary."
          },
          "n_epochs": {
            "type": "number",
            "minimum": 1,
            "maximum": 20,
            "example": 1
          },
          "learning_rate": {
            "type": "number",
            "minimum": 1e-8,
            "maximum": 0.01,
            "example": 0.00005
          },
          "batch_size": {
            "description": "Either the literal 'max' or an integer of 1 or more. The allowed range depends on the base model, the training type (LoRA or full) and the training method (DPO is often lower than SFT); a launch with a value outside it is rejected with a 400 that names the range. 'max' always fits. Defaults to 'max'.",
            "example": "max",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "max"
                ]
              },
              {
                "type": "integer",
                "minimum": 1
              }
            ]
          },
          "lora_r": {
            "type": "number",
            "minimum": 1,
            "maximum": 64,
            "example": 8
          },
          "lora_alpha": {
            "type": "number",
            "description": "Must be 1× or 2× lora_r. Only checked when you supply lora_r in the same request; otherwise it is validated against the platform default."
          },
          "lora_dropout": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0,
            "default": 0,
            "description": "Dropout applied to the LoRA layers. Defaults to 0."
          },
          "lora_trainable_modules": {
            "type": "string",
            "description": "'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').",
            "example": "q_proj,v_proj"
          },
          "lr_scheduler_type": {
            "type": "string",
            "enum": [
              "linear",
              "cosine"
            ]
          },
          "min_lr_ratio": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0.1
          },
          "scheduler_num_cycles": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 4,
            "example": 0.5,
            "default": 0.5,
            "description": "Number of cosine decay cycles across training. Must be greater than 0. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor."
          },
          "warmup_ratio": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "example": 0.03
          },
          "max_grad_norm": {
            "type": "number",
            "minimum": 0,
            "example": 2
          },
          "weight_decay": {
            "type": "number",
            "minimum": 0,
            "example": 0,
            "default": 0,
            "description": "L2 penalty applied to the weights. Defaults to 0."
          },
          "train_on_inputs": {
            "type": "boolean",
            "description": "Whether training loss is computed over the prompt tokens as well as the completion. `true` trains on the full sequence, `false` trains only on the completion. Omit to let the platform decide per example, which is the default.",
            "example": false
          },
          "dpo_beta": {
            "type": "number",
            "minimum": 0.05,
            "maximum": 0.9,
            "example": 0.1,
            "description": "Controls how much the model can deviate from the reference model. Lower = more aggressive updates toward preferred responses; higher = stays closer to reference behavior."
          },
          "dpo_normalize_logratios_by_length": {
            "type": "boolean",
            "description": "Normalizes log ratios by sample length during DPO loss calculation. Automatically set to true when simpo_gamma > 0."
          },
          "rpo_alpha": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "default": 0,
            "example": 0,
            "description": "RPO loss modifier: incorporates the NLL loss on selected samples with this weight. Defaults to 0.0 (standard DPO loss). Mutually exclusive with simpo_gamma — both above 0 is rejected."
          },
          "simpo_gamma": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "default": 0,
            "example": 0,
            "description": "SimPO loss modifier: adds a margin to the loss, force-enables length normalization, and excludes reference logits. Defaults to 0.0 (off). Raise dpo_beta alongside it. Mutually exclusive with rpo_alpha — both above 0 is rejected."
          }
        }
      },
      "PublicCreateAutoScientistRunDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "The dataset to train on. Must be a dataset you own that has finished processing."
          },
          "model": {
            "type": "string",
            "description": "Base model id from GET /autoscientist/models. By default, AutoScientist selects a suitable model. The resolved model is returned in the response `model` field."
          },
          "training_method": {
            "type": "string",
            "enum": [
              "instruction",
              "alignment"
            ],
            "description": "Training objective. Pass `alignment` to train on preference pairs; the dataset must have been prepared with `training_type: preference_pairs`. An alignment run trains in two stages — supervised first, then preference — and this run reports the first until the second begins. Supplying `alignment` for any other dataset has no effect: there are no rejected responses to train against, so the run stays `instruction`. Omitted, it defaults to `instruction` unless an alignment run was already configured for this dataset in the dashboard."
          },
          "data_format": {
            "type": "string",
            "enum": [
              "chat",
              "instruction"
            ],
            "default": "chat",
            "description": "Encoding used for the training rows handed to the training provider. Applies to raw datasets only — for an adapted dataset the platform resolves the encoding and this value is ignored. Defaults to `chat`."
          },
          "column_mapping": {
            "description": "Which dataset columns feed training. When omitted, AutoScientist infers the mapping from the dataset. Required columns depend on the data format.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicTrainingColumnMappingDto"
              }
            ]
          },
          "hyperparams": {
            "description": "Hyperparameter overrides. Not advised. AutoScientist derives these values from the resolved model and the effective dataset size; any field supplied here replaces the derived value for that field. Most fields therefore have no fixed default — where one is listed below it is a constant, and everything else is computed per run. Call POST /autoscientist/recommend-hyperparams to inspect the derived values for a dataset without launching a run.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicAutoScientistHyperparamsDto"
              }
            ]
          },
          "augmentation_domain_rows": {
            "type": "number",
            "description": "Number of synthetic domain-targeted rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).",
            "default": 0,
            "minimum": 0,
            "maximum": 40000
          },
          "augmentation_general_rows": {
            "type": "number",
            "description": "Number of synthetic general-diversity rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).",
            "default": 0,
            "minimum": 0,
            "maximum": 50000
          },
          "idempotency_key": {
            "type": "string",
            "description": "Client-generated key for safe retries. Scoped to `dataset_id`: while a run started with this key is still in progress, repeating the request returns that run instead of starting a second one. Once the run reaches a terminal state (succeeded, failed or cancelled) the key no longer matches and the same request starts a new run."
          },
          "voucher": {
            "type": "string",
            "description": "Optional discount voucher code."
          },
          "max_iterations": {
            "type": "number",
            "description": "Maximum number of iterations to run. Defaults to the resolved model configuration (currently 3). The resolved value is returned in the response `max_iterations` field.",
            "minimum": 1,
            "maximum": 5
          },
          "target_win_rate": {
            "type": "number",
            "description": "Target win rate for the AutoScientist loop (between 0.5 and 1 inclusive). Defaults to 0.7 for small models and 0.8 for larger models. The resolved value is returned in the response `target_win_rate` field.",
            "minimum": 0.5,
            "maximum": 1,
            "exclusiveMinimum": false,
            "exclusiveMaximum": false
          }
        },
        "required": [
          "dataset_id"
        ]
      },
      "PublicAutoScientistRunDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "AutoScientist run id."
          },
          "dataset_id": {
            "type": "string",
            "nullable": true,
            "description": "Public id of the dataset the run trained on."
          },
          "model": {
            "type": "string",
            "nullable": true,
            "description": "Resolved base model id used, including an automatically selected model."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string",
            "nullable": true,
            "description": "When the run reached a terminal state. Null while it is still running."
          },
          "iterations_completed": {
            "type": "number",
            "description": "Number of completed iterations."
          },
          "max_iterations": {
            "type": "number",
            "description": "Resolved maximum number of iterations, including the model-specific default."
          },
          "target_win_rate": {
            "type": "number",
            "description": "Resolved target win rate for the AutoScientist loop, including the model-specific default."
          },
          "best_win_rate": {
            "type": "number",
            "nullable": true,
            "description": "Best win rate achieved so far."
          },
          "training_method": {
            "type": "string",
            "enum": [
              "instruction",
              "alignment"
            ],
            "description": "The objective this run is training. Resolved at creation — a requested `alignment` is downgraded to `instruction` when the dataset is not preference pairs, so read this back to confirm what actually runs."
          },
          "best_hyperparams": {
            "nullable": true,
            "description": "Hyperparameters that produced the best iteration so far, and the ones the downloadable artifact was trained with. Null until an iteration completes.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicAutoScientistHyperparamsDto"
              }
            ]
          },
          "column_mapping": {
            "nullable": true,
            "description": "Column mapping the run trained with, echoing what was sent on create. Null when the mapping was left to the platform to infer.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicTrainingColumnMappingDto"
              }
            ]
          },
          "download_available": {
            "type": "boolean",
            "description": "True when the best trained artifact can be downloaded."
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Why the run failed. Null unless `status` is `failed`."
          }
        },
        "required": [
          "id",
          "dataset_id",
          "model",
          "status",
          "created_at",
          "completed_at",
          "iterations_completed",
          "max_iterations",
          "target_win_rate",
          "training_method",
          "best_hyperparams",
          "column_mapping",
          "download_available"
        ]
      },
      "PublicRecommendHyperparamsDto": {
        "type": "object",
        "properties": {
          "dataset_id": {
            "type": "string",
            "description": "The dataset the hyperparameters are sized for. Must be a dataset you own that has finished processing."
          },
          "model": {
            "type": "string",
            "description": "Base model id from GET /autoscientist/models to tune for. Omit to size the recommendation against the model POST /autoscientist selects for this dataset; the resolved id is returned in the response `model` field. That pick assumes no `column_mapping`, so a create request supplying `column_mapping.reasoning_trace` can resolve a different model. Pass the returned `model` back on create to pin it."
          },
          "augmentation_domain_rows": {
            "type": "number",
            "description": "Number of synthetic domain-targeted rows you plan to generate. These are additional to your own rows and count toward the effective training size, so the recommendation matches what you will launch. Defaults to 0 (no augmentation).",
            "default": 0,
            "minimum": 0,
            "maximum": 40000
          },
          "augmentation_general_rows": {
            "type": "number",
            "description": "Number of synthetic general-diversity rows you plan to generate. These are additional to your own rows and count toward the effective training size. Defaults to 0 (no augmentation).",
            "default": 0,
            "minimum": 0,
            "maximum": 50000
          }
        },
        "required": [
          "dataset_id"
        ]
      },
      "PublicRecommendHyperparamsResponseDto": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "Resolved base model id the recommendation is sized for: the value you sent, or the automatically selected model when `model` was omitted. Pass it back as `model` on POST /autoscientist to launch against the same model."
          },
          "hyperparams": {
            "description": "Hyperparameters derived for the resolved model and effective dataset size. POST /autoscientist applies the same values when `hyperparams` is omitted. Overriding is not advised.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicAutoScientistHyperparamsDto"
              }
            ]
          }
        },
        "required": [
          "model",
          "hyperparams"
        ]
      },
      "PublicTrainingModelDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier to pass as `model` when creating a job."
          },
          "display_name": {
            "type": "string",
            "description": "Human-readable model name."
          },
          "model_size": {
            "type": "string",
            "nullable": true,
            "description": "Parameter count label (e.g. \"8B\", \"70B\")."
          },
          "context_length": {
            "type": "number",
            "nullable": true,
            "description": "Maximum context window in tokens."
          },
          "methods": {
            "description": "Training methods supported (e.g. [\"sft\", \"dpo\"]).",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "training_types": {
            "description": "Training types supported (e.g. [\"lora\", \"full\"]).",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "train_with_reasoning": {
            "type": "boolean",
            "description": "Whether this model trains on reasoning traces. When false, mapping a `column_mapping.reasoning_trace` on this model is rejected rather than trained without the trace."
          }
        },
        "required": [
          "id",
          "display_name",
          "methods",
          "training_types",
          "train_with_reasoning"
        ]
      },
      "PublicTrainingModelListDto": {
        "type": "object",
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicTrainingModelDto"
            }
          }
        },
        "required": [
          "models"
        ]
      },
      "PublicAutoScientistRunListDto": {
        "type": "object",
        "properties": {
          "runs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicAutoScientistRunDto"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Cursor for the next page; null when no more results."
          }
        },
        "required": [
          "runs"
        ]
      },
      "PublicInventSubdomainDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Qualified code to send in `subdomains` — copy it as-is rather than assembling it.",
            "example": "medical.symptoms_diagnosis"
          },
          "title": {
            "type": "string",
            "description": "Human-readable name.",
            "example": "Symptoms diagnosis"
          }
        },
        "required": [
          "code",
          "title"
        ]
      },
      "PublicInventDomainDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Code to send in `domains`.",
            "example": "medical"
          },
          "title": {
            "type": "string",
            "description": "Human-readable name.",
            "example": "Medical"
          },
          "subdomains": {
            "description": "Subdomains available within this domain. Empty when the domain has no subdivision — send the domain code alone.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicInventSubdomainDto"
            }
          }
        },
        "required": [
          "code",
          "title",
          "subdomains"
        ]
      },
      "PublicInventDomainsResponseDto": {
        "type": "object",
        "properties": {
          "domains": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicInventDomainDto"
            }
          }
        },
        "required": [
          "domains"
        ]
      },
      "CreateInventedDatasetDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name for the invented dataset.",
            "example": "Medical Q&A dataset"
          },
          "training_type": {
            "type": "string",
            "description": "Shape of the generated data — the same field and values as `datasets.adapt`. `instruction_dataset` produces prompt/completion rows; `preference_pairs` produces ranked completion pairs. Note this is the shape of the DATA, not the training method (elsewhere `training_type` means LoRA vs full fine-tuning). Defaults to `instruction_dataset`. The download carries the generated text in `enhanced_prompt` / `enhanced_completion`; `original_*` are null, since invented data has no source rows it was derived from.",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "default": "instruction_dataset"
          },
          "domains": {
            "description": "Domain codes to generate from, e.g. `medical`. Optional: omit it and the domains come from the parents of your `subdomains`, or — when `subdomains` is omitted too — are inferred from `dataset_prompt`. When you do supply it, it is authoritative: inference is skipped, and a subdomain naming a domain that is not listed here is rejected rather than silently added. Retrieve the valid codes from `GET /datasets/invent/domains`.",
            "example": [
              "medical",
              "personal_finance"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subdomains": {
            "description": "Narrow generation to specific subdomains, as `domain.subdomain` codes e.g. `medical.symptoms_diagnosis`. Qualified by their domain because a bare code can belong to more than one (`wildlife` sits under both agriculture and animal nature). Requested domains with no subdomain listed here are generated across all of theirs. Optional: with neither this nor `domains`, the taxonomy is inferred from `dataset_prompt`. Supplying it disables that inference. Retrieve the valid codes from `GET /datasets/invent/domains`.",
            "example": [
              "medical.symptoms_diagnosis",
              "medical.preventive_care"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rows": {
            "type": "integer",
            "description": "Number of rows to generate, subject to your plan’s per-launch row cap. Treat it as a target: the delivered count can land slightly either side of it, so read `row_count` on the finished dataset for what was actually produced.",
            "minimum": 1,
            "example": 1000
          },
          "translate": {
            "description": "Translate a sample of the generated rows into further languages, adding one row per sampled row and language. Combines with `localize`. Credits are billed on the POST-expansion row count, so setting this quotes and charges above `rows`. Cannot be combined with `language_expansion`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicTranslateTargetsDto"
              }
            ]
          },
          "localize": {
            "description": "Localize a sample of the generated rows to country/language pairs, adding one row per sampled row and pair. Combines with `translate`. Credits are billed on the POST-expansion row count. Cannot be combined with `language_expansion`.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicLocalizeTargetsDto"
              }
            ]
          },
          "language_expansion": {
            "deprecated": true,
            "description": "Deprecated: use `translate` and `localize`, which can be combined. Optionally translate or localize the generated rows into further languages. Credits are billed on the POST-expansion row count, so setting this quotes and charges above `rows`. `sample_rate` (0-1) is the share of rows expanded.",
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/PublicLanguageExpansionSpecDto"
              }
            ]
          },
          "dataset_prompt": {
            "type": "string",
            "description": "Free-text description of the data you want, in your own words — the wizard shows this as \"Dataset Details\". Drives the semantic search that selects rows, so a specific prompt yields more relevant data, and it is woven into the generation instructions. Written for you from your domain selections when omitted. When `domains` and `subdomains` are both omitted this is required, and the domains and subdomains are inferred from it; if none can be inferred the request is rejected with `400` asking for explicit `domains`/`subdomains` rather than generating across every domain.",
            "maxLength": 10000,
            "example": "Patient-facing answers to cardiology questions, plain language, no jargon"
          },
          "prompt": {
            "type": "string",
            "deprecated": true,
            "description": "Deprecated alias for `dataset_prompt`, kept for existing clients. Use `dataset_prompt` in new code. `prompt` will be removed in a future release.",
            "maxLength": 10000
          },
          "estimate": {
            "type": "boolean",
            "description": "Price the request without creating or charging anything. Mirrors `datasets.adapt` — the response carries the same fields either way, with the dataset fields null when this is set.",
            "default": false
          },
          "idempotency_key": {
            "type": "string",
            "description": "Client-supplied key making retries safe. Repeating a request with the same key returns the original dataset instead of generating again.",
            "maxLength": 255
          }
        },
        "required": [
          "rows"
        ]
      },
      "PublicInventedDatasetDto": {
        "type": "object",
        "properties": {
          "estimate": {
            "type": "boolean",
            "description": "True when this response priced the request without running it.",
            "example": false
          },
          "id": {
            "type": "string",
            "description": "Dataset id, or null on an estimate. Pass it straight to `finetune_jobs.create` or `autoscientist.create` once the status is `succeeded`.",
            "nullable": true,
            "example": "3f1b9c62-6f3e-4a1e-9a5c-0b7d2f8e4a10"
          },
          "name": {
            "type": "string",
            "description": "Display name, echoed from the request or the default applied for you.",
            "example": "Clinical Q&A"
          },
          "training_type": {
            "type": "string",
            "description": "Shape of the generated data, echoed from the request.",
            "enum": [
              "instruction_dataset",
              "preference_pairs"
            ],
            "example": "instruction_dataset"
          },
          "domains": {
            "description": "Domain codes the generation covers, echoed from the request — including any inferred from `subdomains`.",
            "example": [
              "medical"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subdomains": {
            "description": "Subdomain codes the generation is narrowed to, if any.",
            "example": [
              "medical.symptoms_diagnosis"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rows": {
            "type": "integer",
            "description": "Number of rows requested.",
            "nullable": true,
            "example": 1000
          },
          "status": {
            "type": "string",
            "description": "Lifecycle status, or null on an estimate. A fresh generation is always `running`; poll `GET /datasets/{dataset_id}` until it reports `succeeded` or `failed`.",
            "enum": [
              "pending",
              "running",
              "awaiting_input",
              "succeeded",
              "failed"
            ],
            "nullable": true,
            "example": "running"
          },
          "created_at": {
            "type": "string",
            "description": "When the dataset was created, or null on an estimate.",
            "format": "date-time",
            "nullable": true,
            "example": "2026-08-03T16:12:04.000Z"
          },
          "estimated_credits": {
            "type": "number",
            "description": "Credits this generation consumes. Billed on the post-expansion row count, so a translated request quotes above its `rows`. Invent pricing is still provisional, so treat the figure as indicative.",
            "example": 800
          },
          "available_credits": {
            "type": "number",
            "description": "Credits currently available to your team.",
            "example": 5000
          }
        },
        "required": [
          "estimate",
          "id",
          "name",
          "training_type",
          "domains",
          "subdomains",
          "rows",
          "status",
          "created_at",
          "estimated_credits",
          "available_credits"
        ]
      },
      "LeaderboardStatsDto": {
        "type": "object",
        "properties": {
          "submitted_runs": {
            "type": "integer",
            "description": "AutoScientist runs submitted, all-time. A PLATFORM total: it counts every experiment on every account, including the ones the ranking leaves out, so it is larger than `contributors` implies.\n\nReported as a fixed multiple of the number of submitted experiments — one submitted experiment is more than one run — so this figure will not match a count of experiments taken any other way. The multiple is the same for every caller and applies to this counter alone."
          },
          "domains_covered": {
            "type": "integer",
            "description": "Domains holding at least one ranked entry. A RANKED-population figure: a domain whose only entries belong to unlisted members reports as uncovered. NOT the length of `domains`, which lists the whole catalogue whether populated or not."
          },
          "contributors": {
            "type": "integer",
            "description": "Distinct listed users holding at least one ranked entry — the RANKED population only. Always less than or equal to `autoscientist_users`, and usually far smaller: ranking requires a completed domain evaluation, which is available on paid plans only, and counts only members who are listed. Use `autoscientist_users`, not this, to answer \"how many people use AutoScientist\"."
          },
          "autoscientist_users": {
            "type": "integer",
            "description": "Distinct users who have run AutoScientist at all: everyone holding at least one experiment, whether or not any of it is eligible for ranking, and whether or not they are listed on the leaderboard. A PLATFORM total, so always greater than or equal to `contributors`, which is the ranked subset of it."
          },
          "data_artifacts_processed": {
            "type": "string",
            "description": "Rows processed by the platform, from the maintained `processed_rows_total` counter — a PLATFORM total across every account. A string because the underlying value is a BigInt.",
            "example": "1284930215"
          }
        },
        "required": [
          "submitted_runs",
          "domains_covered",
          "contributors",
          "autoscientist_users",
          "data_artifacts_processed"
        ]
      },
      "LeaderboardDomainOptionDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true,
            "description": "`Domains.code`. Null for the synthetic `general` bucket.",
            "example": "domain_medical"
          },
          "slug": {
            "type": "string",
            "description": "Classifier slug.",
            "example": "medical"
          },
          "name": {
            "type": "string",
            "description": "Display name.",
            "example": "Medical"
          },
          "entry_count": {
            "type": "integer",
            "description": "Ranked users in this domain — the same figure the ranking reports as `pagination.total`, so the selector and the table can never disagree. Follows the ranked population, so entries belonging to unlisted members are not counted. Zero for a domain nobody has ranked in yet, which is most of them."
          }
        },
        "required": [
          "code",
          "slug",
          "name",
          "entry_count"
        ]
      },
      "LeaderboardOverviewResponseDto": {
        "type": "object",
        "properties": {
          "stats": {
            "$ref": "#/components/schemas/LeaderboardStatsDto"
          },
          "domains": {
            "description": "Every selectable domain — the whole catalogue plus the synthetic `general` bucket — whether or not it currently has ranked entries. The catch-all `Other` domain is never included and is rejected as a `domain` query value.\n\nOrdered populated-first: domains holding entries lead, most populated first, then every empty domain alphabetically by name. Read `entry_count` to decide emphasis — most domains report 0, and a selector that treats every entry as worth featuring will feature 40-odd empty tables.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardDomainOptionDto"
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When this data was computed. The leaderboard is refreshed once a day, so two reads between refreshes return the same counters and the same timestamp — an unchanged page is not a stale one. A domain appearing in the ranking for the first time also triggers a refresh, so the selector gains it within minutes.\n\nNull means the response was computed for this request rather than served from a refresh (no snapshot published yet). It is never the current time, so \"computed live\" stays distinguishable from \"refreshed just now\"."
          }
        },
        "required": [
          "stats",
          "domains",
          "generated_at"
        ]
      },
      "LeaderboardDomainDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true,
            "description": "`Domains.code`. Null for the synthetic `general` and `all` buckets."
          },
          "slug": {
            "type": "string",
            "example": "medical"
          },
          "name": {
            "type": "string",
            "example": "Medical"
          }
        },
        "required": [
          "code",
          "slug",
          "name"
        ]
      },
      "LeaderboardPaginationDto": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "description": "Rows asked for — the page size actually applied."
          },
          "offset": {
            "type": "integer",
            "description": "Rows skipped."
          },
          "total": {
            "type": "integer",
            "description": "Ranked users in this domain, all of them — not the rows in this page. Drives \"showing 10 of 137\". Under `q` it is the number of matches across every domain instead."
          },
          "has_more": {
            "type": "boolean",
            "description": "Whether another page exists. Show the \"show more\" control on true, and call again with `offset + limit`."
          }
        },
        "required": [
          "limit",
          "offset",
          "total",
          "has_more"
        ]
      },
      "LeaderboardCountryDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO country code, as stored.",
            "example": "GB"
          },
          "name": {
            "type": "string",
            "example": "United Kingdom"
          }
        },
        "required": [
          "code",
          "name"
        ]
      },
      "LeaderboardUserLinksDto": {
        "type": "object",
        "properties": {
          "homepage": {
            "type": "string",
            "nullable": true,
            "description": "Profile homepage. Only http(s) links are served — a stored value with any other scheme reads as null, so this is safe to use as an href."
          },
          "github": {
            "type": "string",
            "nullable": true
          },
          "x": {
            "type": "string",
            "nullable": true
          },
          "linkedin": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "homepage",
          "github",
          "x",
          "linkedin"
        ]
      },
      "LeaderboardUserStatsDto": {
        "type": "object",
        "properties": {
          "submissions": {
            "type": "integer",
            "description": "AutoScientist experiments this user has submitted, all-time and across every domain — not only the ranked ones, so it is at least 1 for anyone on the table, and 0 only when the totals read failed."
          },
          "best_win_rate_pct": {
            "type": "number",
            "nullable": true,
            "description": "The user's best domain win rate across every domain, as a percentage with one decimal. Usually higher than this row's `score` when the user ranks better in another domain. Null when they have no completed domain evaluation of their own, and when the totals read failed.",
            "example": 74.2
          },
          "data_points": {
            "type": "integer",
            "description": "Training rows across every distinct dataset the user has run an experiment on, post-augmentation where augmentation ran. A raw count — the popup's \"K\" is formatting.",
            "example": 128400
          }
        },
        "required": [
          "submissions",
          "best_win_rate_pct",
          "data_points"
        ]
      },
      "LeaderboardUserDto": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "Stable public identifier."
          },
          "display_name": {
            "type": "string",
            "nullable": true,
            "description": "Profile name. Null when the profile has none; no contact detail is substituted."
          },
          "avatar_url": {
            "type": "string",
            "nullable": true,
            "description": "Avatar image reference. Null when the profile has none."
          },
          "bio": {
            "type": "string",
            "nullable": true,
            "description": "Profile biography, verbatim. Null — never an empty string — when the profile has none."
          },
          "country": {
            "nullable": true,
            "description": "Profile country. A profile can hold several; the one first alphabetically is served, the same one on every request. Null when the profile names none.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeaderboardCountryDto"
              }
            ]
          },
          "links": {
            "$ref": "#/components/schemas/LeaderboardUserLinksDto"
          },
          "stats": {
            "description": "Whole-account totals for the profile popup. Deliberately not scoped to the domain being ranked — they describe the member, not this row.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeaderboardUserStatsDto"
              }
            ]
          }
        },
        "required": [
          "user_id",
          "display_name",
          "avatar_url",
          "bio",
          "country",
          "links",
          "stats"
        ]
      },
      "LeaderboardBaseModelDto": {
        "type": "object",
        "properties": {
          "display_name": {
            "type": "string",
            "example": "Llama 3.3 70B Instruct"
          },
          "family": {
            "type": "string",
            "nullable": true,
            "description": "Model family — the signal for which base-model logo to show.",
            "example": "llama"
          },
          "size": {
            "type": "string",
            "nullable": true,
            "example": "70B"
          }
        },
        "required": [
          "display_name",
          "family",
          "size"
        ]
      },
      "LeaderboardModelDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "This run's own model name — the same label the product shows for it in the dataset page's trained-model selection, so a member recognises their own row. Composed as `adaption_<base model>_<dataset>_<run id>`; the trailing run id is what distinguishes two runs on the same dataset. Always present: a component that cannot be resolved contributes a placeholder rather than making the whole name absent.\n\nThis was previously the constant \"AutoScientist\" for every row. That branding is the page's, not the API's — render it alongside this name rather than expecting it here.",
            "example": "adaption_llama_3_3_70b_instruct_reference_clinical_qa_a4f81c2e"
          },
          "base_model": {
            "nullable": true,
            "description": "The base model the run fine-tuned, from the canonical model registry. Null when the registry row is unavailable; individual attributes are nullable in their own right.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeaderboardBaseModelDto"
              }
            ]
          }
        },
        "required": [
          "name",
          "base_model"
        ]
      },
      "LeaderboardScoreDto": {
        "type": "object",
        "properties": {
          "domain_win_rate_pct": {
            "type": "number",
            "description": "Win rate from the run's domain evaluation against the fixed per-domain prompt set, as a percentage with one decimal. Shown for context; it is NOT the ranking metric — see `normalized_score`. Comparing it across rows favours runs on stronger base models, which is the bias the ranking score exists to remove.",
            "example": 68.4
          },
          "normalized_score": {
            "type": "number",
            "nullable": true,
            "description": "The base-adjusted score the ranking is ordered by (higher is better). It measures how far above its own base model's typical result in this domain the run lands, on a standardised (z-score-like) scale — so a Llama fine-tune and a Qwen fine-tune are judged by how much each beat its own base, not by raw win rate, which a weak base depresses no matter how good the fine-tune. 0 is a typical run for that base; +1 is about one standard deviation better. Small/thin base groups are shrunk toward the whole-domain average so a lucky one-off cannot top the board. Null only when the run has no comparable runs to be scored against.",
            "example": 1.08
          },
          "percentile": {
            "type": "integer",
            "nullable": true,
            "description": "This run's standing as a percentile of the base-adjusted score — the share of ranked runs it beats, 0–100 (94 = better than 94%). This is the `normalized_score` re-expressed for display; the ranking is ordered by the score itself. The comparison pool is the currently-viewed ranking: every ranked run in the domain (across all base models, not only the same base) for a single domain, or every ranked run of every domain for the \"All Domains\" aggregate. Null when the score is.",
            "example": 94
          },
          "task_win_rate_pct": {
            "type": "number",
            "nullable": true,
            "description": "Win rate from the experiment's own evaluation against the user's data — how well the model does at the task it was trained for. Each run is scored on a different held-out set, so this is NOT comparable between rows and nothing is ordered by it. Null for a run whose iteration evals never produced a score.\n\nFor a run with `alignment: true` this is the best DPO (preference) stage's score, never the SFT stage's — so every row reports the task score of the last training stage its run completed. An alignment run whose DPO stage produced no score reads null rather than falling back to its SFT score, which would be a number measured on the wrong stage.",
            "example": 81
          }
        },
        "required": [
          "domain_win_rate_pct",
          "normalized_score",
          "percentile",
          "task_win_rate_pct"
        ]
      },
      "LeaderboardDatasetDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "rows_before": {
            "type": "integer",
            "nullable": true,
            "description": "Rows in the source dataset, before augmentation. Null when the source dataset is gone or was never row-counted.",
            "example": 12000
          },
          "rows_after": {
            "type": "integer",
            "nullable": true,
            "description": "Rows actually trained on: source plus whatever augmentation minted. Equal to `rows_before` when no augmentation ran, so a UI can show \"12k → 44k\" or a single figure by comparing the two.",
            "example": 44000
          },
          "huggingface_url": {
            "type": "string",
            "nullable": true,
            "description": "Published dataset location on Hugging Face, when one exists."
          },
          "kaggle_url": {
            "type": "string",
            "nullable": true,
            "description": "Published dataset location on Kaggle, when one exists."
          }
        },
        "required": [
          "name",
          "rows_before",
          "rows_after",
          "huggingface_url",
          "kaggle_url"
        ]
      },
      "LeaderboardRowDto": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer",
            "description": "Absolute position in the ranking, from 1 — not the index within the page. Contiguous with no gaps, so ranks 1–3 identify the top three without a separate response section."
          },
          "user": {
            "$ref": "#/components/schemas/LeaderboardUserDto"
          },
          "model": {
            "$ref": "#/components/schemas/LeaderboardModelDto"
          },
          "alignment": {
            "type": "boolean",
            "description": "Whether this run went through alignment training — an SFT stage followed by a DPO (preference) stage. True when the ranked run is the DPO stage of such a pipeline, or the SFT stage with a DPO stage linked to it. False for a standalone SFT run and for a one-shot DPO run with no SFT stage. Never null: a row is either aligned or it is not.\n\nDescriptive only — it does not affect eligibility, rank, or `domain_win_rate_pct`. It does determine which stage `task_win_rate_pct` comes from.",
            "example": true
          },
          "score": {
            "$ref": "#/components/schemas/LeaderboardScoreDto"
          },
          "dataset": {
            "$ref": "#/components/schemas/LeaderboardDatasetDto"
          },
          "model_huggingface_url": {
            "type": "string",
            "nullable": true,
            "description": "Published location of the run's fine-tuned MODEL on Hugging Face — not the dataset it was trained on, which carries its own links under `dataset`. Null unless an export completed successfully — a pending or failed export reads as null."
          },
          "model_kaggle_url": {
            "type": "string",
            "nullable": true,
            "description": "Published location of the run's fine-tuned MODEL on Kaggle — not the dataset it was trained on, which carries its own links under `dataset`. Null unless an export completed successfully — a pending or failed export reads as null."
          },
          "completed_at": {
            "format": "date-time",
            "type": "string",
            "nullable": true
          },
          "domain": {
            "description": "The domain this run is ranked in. Redundant with the top-level `domain` on a single-domain view, but essential for the \"All Domains\" aggregate and for a `q` search, where a user can appear once per domain — this is what tells those rows apart.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeaderboardDomainDto"
              }
            ]
          }
        },
        "required": [
          "rank",
          "user",
          "model",
          "alignment",
          "score",
          "dataset",
          "model_huggingface_url",
          "model_kaggle_url",
          "completed_at",
          "domain"
        ]
      },
      "LeaderboardResponseDto": {
        "type": "object",
        "properties": {
          "domain": {
            "nullable": true,
            "description": "The domain actually ranked — echoed so a caller that omitted `domain` knows which one was chosen. Null when nothing anywhere is ranked, and null for a `q` search, which spans every domain: there each row carries its own `domain` instead.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeaderboardDomainDto"
              }
            ]
          },
          "pagination": {
            "$ref": "#/components/schemas/LeaderboardPaginationDto"
          },
          "data": {
            "description": "One page of the ranking, in rank order. Empty past the end of the ranking and for a recognised domain with no ranked entries.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LeaderboardRowDto"
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When this ranking was computed. Matches the value the overview reports within one generation, so the selector and the table always describe the same data. The leaderboard is refreshed once a day: a run that becomes eligible after a refresh appears at the next one. The exception is a run that gives its domain its first ranked entry — a new domain is picked up within minutes rather than waiting for the next day.\n\nNull means the response was computed for this request rather than served from a refresh. Member identity — name, avatar, biography, links, country — is always current regardless of this timestamp."
          }
        },
        "required": [
          "domain",
          "pagination",
          "data",
          "generated_at"
        ]
      },
      "HostedModelDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Model identifier accepted by the responses endpoint.",
            "example": "qwen3.5-397b"
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the model was created.",
            "example": 1750000000
          },
          "object": {
            "type": "string",
            "enum": [
              "model"
            ],
            "example": "model"
          },
          "owned_by": {
            "type": "string",
            "description": "Organization that owns the model.",
            "example": "platform"
          },
          "display_name": {
            "type": "string",
            "description": "Human-readable name, when the model is one the platform catalogues.",
            "nullable": true,
            "example": "Qwen 3.5 397B"
          },
          "shutdown_date": {
            "type": "string",
            "description": "Date when the model will be shut down, if announced.",
            "nullable": true,
            "example": null
          }
        },
        "required": [
          "id",
          "created",
          "object",
          "owned_by"
        ]
      },
      "ListModelsResponseDto": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ],
            "example": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HostedModelDto"
            }
          }
        },
        "required": [
          "object",
          "data"
        ]
      },
      "ResponseOutputContentDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Content part type: `output_text` for reply text, `refusal` for a refusal.",
            "example": "output_text"
          },
          "text": {
            "type": "string",
            "description": "The reply text, on an `output_text` part.",
            "example": "Once upon a time, a unicorn drifted to sleep on a cloud."
          },
          "refusal": {
            "type": "string",
            "description": "The refusal message, on a `refusal` part."
          },
          "annotations": {
            "type": "array",
            "description": "Citations into `text`, such as file citations from file search.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "type"
        ]
      },
      "ResponseOutputItemDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Item type, such as `message`, `reasoning`, `function_call`, `mcp_call` or `file_search_call`. Fields beyond the ones listed depend on the type.",
            "example": "message"
          },
          "id": {
            "type": "string",
            "description": "Identifier of the output item."
          },
          "status": {
            "type": "string",
            "description": "Status of the item, such as `completed` or `in_progress`.",
            "example": "completed"
          },
          "role": {
            "type": "string",
            "description": "Author of a `message` item.",
            "enum": [
              "assistant"
            ]
          },
          "content": {
            "description": "Content parts of a `message` item.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseOutputContentDto"
            }
          },
          "name": {
            "type": "string",
            "description": "Name of the tool called, on `function_call`, `mcp_call` and `mcp_approval_request` items.",
            "example": "get_weather"
          },
          "arguments": {
            "type": "string",
            "description": "JSON-encoded arguments for the tool, on `function_call`, `mcp_call` and `mcp_approval_request` items.",
            "example": "{\"city\":\"Paris\"}"
          },
          "call_id": {
            "type": "string",
            "description": "Identifier to answer a `function_call` with: send it back as the `call_id` of a `function_call_output` input item.",
            "example": "call_123"
          },
          "server_label": {
            "type": "string",
            "description": "Label of the MCP server, on `mcp_call`, `mcp_approval_request` and `mcp_list_tools` items.",
            "example": "docs"
          },
          "approval_request_id": {
            "type": "string",
            "description": "The approval request this `mcp_call` answers, if it needed approval.",
            "nullable": true
          },
          "output": {
            "type": "string",
            "description": "What the tool returned, on an `mcp_call` item.",
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "Why the tool call failed, on `mcp_call` and `mcp_list_tools` items.",
            "nullable": true
          },
          "tools": {
            "type": "array",
            "description": "Tools the server offers, on an `mcp_list_tools` item.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "summary": {
            "type": "array",
            "description": "Summary parts of a `reasoning` item, each with `type` and `text`.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "encrypted_content": {
            "type": "string",
            "description": "Opaque reasoning state to replay in a later request, on a `reasoning` item.",
            "nullable": true
          },
          "queries": {
            "description": "Search queries, on a `file_search_call` item.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "results": {
            "type": "array",
            "description": "Matched chunks, on a `file_search_call` item.",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "nullable": true
          }
        },
        "required": [
          "type"
        ]
      },
      "ResponseErrorDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "server_error"
          },
          "message": {
            "type": "string",
            "example": "The model provider could not complete the request."
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "ResponseIncompleteDetailsDto": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Why the response is incomplete.",
            "example": "max_output_tokens"
          }
        }
      },
      "ResponseUsageDto": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "example": 36
          },
          "output_tokens": {
            "type": "integer",
            "example": 87
          },
          "total_tokens": {
            "type": "integer",
            "example": 123
          },
          "input_tokens_details": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "cached_tokens": 0
            }
          },
          "output_tokens_details": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "reasoning_tokens": 0
            }
          }
        },
        "required": [
          "input_tokens",
          "output_tokens",
          "total_tokens"
        ]
      },
      "ResponseObjectDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "resp_123"
          },
          "object": {
            "type": "string",
            "enum": [
              "response"
            ],
            "example": "response"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix timestamp (in seconds) when the response was created.",
            "example": 1750000000
          },
          "status": {
            "type": "string",
            "enum": [
              "completed",
              "failed",
              "in_progress",
              "cancelled",
              "queued",
              "incomplete"
            ],
            "example": "completed"
          },
          "model": {
            "type": "string",
            "description": "Public name of the model that generated the response.",
            "example": "qwen3.5-397b"
          },
          "output": {
            "description": "Items the model generated, in order.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseOutputItemDto"
            }
          },
          "output_text": {
            "type": "string",
            "description": "The text of every `output_text` part in `output`, joined. Reasoning and tool calls are excluded.",
            "example": "Once upon a time, a unicorn drifted to sleep on a cloud."
          },
          "error": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseErrorDto"
              }
            ]
          },
          "incomplete_details": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseIncompleteDetailsDto"
              }
            ]
          },
          "usage": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseUsageDto"
              }
            ]
          },
          "previous_response_id": {
            "type": "string",
            "description": "The response this one continues, if any.",
            "nullable": true
          },
          "store": {
            "type": "boolean",
            "description": "Whether the response is stored for later retrieval."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "required": [
          "id",
          "object",
          "status",
          "model",
          "output",
          "output_text"
        ]
      },
      "ResponseStreamEventDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Event type, such as `response.created`, `response.output_text.delta` or `response.completed`. Fields beyond the ones listed depend on the type.",
            "example": "response.output_text.delta"
          },
          "sequence_number": {
            "type": "integer",
            "example": 4
          },
          "response": {
            "description": "The response so far, on `response.*` lifecycle events.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseObjectDto"
              }
            ]
          },
          "delta": {
            "type": "string",
            "description": "The text added, on `*.delta` events.",
            "example": "Once"
          },
          "item": {
            "description": "The output item, on `response.output_item.*` events.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseOutputItemDto"
              }
            ]
          },
          "output_index": {
            "type": "integer",
            "example": 0
          },
          "item_id": {
            "type": "string",
            "description": "Identifier of the output item the event belongs to."
          },
          "content_index": {
            "type": "integer",
            "example": 0
          },
          "text": {
            "type": "string",
            "description": "The complete text, on `*.done` text events."
          }
        },
        "required": [
          "type"
        ]
      },
      "ResponseInputMessageDto": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "user",
              "assistant",
              "system",
              "developer"
            ],
            "example": "user"
          },
          "content": {
            "description": "Text, or an array of content parts: input_text, input_image (image_url as an https or base64 data URL), or input_file (file_url, or filename with base64 file_data). Which parts a model accepts depends on the model; one that cannot read a part returns 400. input_file.file_id is not supported.",
            "oneOf": [
              {
                "type": "string",
                "example": "What was my previous question?"
              },
              {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": [
                  {
                    "type": "input_text",
                    "text": "What is in this image?"
                  },
                  {
                    "type": "input_image",
                    "image_url": "https://example.com/photo.jpg"
                  }
                ]
              }
            ]
          }
        },
        "required": [
          "role",
          "content"
        ]
      },
      "McpRequestToolDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp"
            ],
            "example": "mcp"
          },
          "server_label": {
            "type": "string",
            "description": "Label used to identify this MCP server in tool calls. For hosted tools, use a catalog id from GET /tools.",
            "example": "slack"
          },
          "authorization": {
            "type": "string",
            "description": "Authorization for this request. For server_url tools, this exact value is forwarded as the Authorization header. For hosted tools, it is the connector credential used instead of the stored connection. Never stored, logged or echoed back.",
            "writeOnly": true
          },
          "server_url": {
            "type": "string",
            "description": "Caller-provided public HTTPS MCP endpoint. Adaption calls it directly.",
            "example": "https://mcp.example.com/mcp"
          },
          "server_description": {
            "type": "string",
            "description": "Description of a caller-provided remote MCP server.",
            "maxLength": 4096
          },
          "allowed_tools": {
            "description": "Narrow the connector's tools: an array of tool names, or { tool_names?, read_only? }. Every name must be a tool the connector exposes.",
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "object",
                "properties": {
                  "tool_names": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "read_only": {
                    "type": "boolean"
                  }
                }
              }
            ]
          },
          "require_approval": {
            "description": "Which calls wait for your approval: 'always', 'never', or { always?, never? } tool filters. Unset uses the saved tool permission, which defaults to allow without approval. A call that needs approval ends the response with an `mcp_approval_request` item; replay the output with an `mcp_approval_response` input item to continue.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "always",
                  "never"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "always": {
                    "type": "object",
                    "properties": {
                      "tool_names": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "read_only": {
                        "type": "boolean"
                      }
                    }
                  },
                  "never": {
                    "type": "object",
                    "properties": {
                      "tool_names": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "read_only": {
                        "type": "boolean"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        "required": [
          "type",
          "server_label"
        ]
      },
      "FileSearchToolDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "file_search"
            ],
            "example": "file_search"
          },
          "dataset_ids": {
            "description": "Adapted dataset identifiers to search. Omit with `model: stack:<id>` to use the datasets configured on that stack.",
            "minItems": 1,
            "maxItems": 32,
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "type"
        ]
      },
      "CreateResponseDto": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "Hosted model identifier, or `stack:<slug>` to call one of your inference stacks. A stack supplies its model and default tools; explicitly requested MCP tools must be enabled on the stack, while file_search can name any of the caller's authorized adapted datasets.",
            "example": "qwen3.5-397b"
          },
          "input": {
            "description": "Text input, or an ordered array of messages and items replayed from earlier responses. May be omitted when previous_response_id supplies stored conversation history.",
            "oneOf": [
              {
                "type": "string",
                "example": "Explain why the sky appears blue."
              },
              {
                "type": "array",
                "minItems": 1,
                "items": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ResponseInputMessageDto"
                    },
                    {
                      "type": "object",
                      "description": "An item replayed from an earlier response: message, reasoning, mcp_list_tools, mcp_call, mcp_approval_request, or mcp_approval_response.",
                      "additionalProperties": true
                    }
                  ]
                }
              }
            ]
          },
          "instructions": {
            "type": "string",
            "description": "System-level instructions for the model.",
            "example": "Answer clearly and concisely."
          },
          "agentic_memory": {
            "type": "boolean",
            "description": "Use agentic memory for this request: relevant memories from earlier turns with this stack are added to the model instructions, and the turn may be used to build new memories. Omitted or null uses the stack's agentic memory setting; requests that do not name a stack default to false.",
            "example": true
          },
          "max_output_tokens": {
            "type": "integer",
            "description": "Maximum number of tokens the model may generate.",
            "minimum": 1,
            "example": 1024
          },
          "temperature": {
            "type": "number",
            "description": "Sampling temperature.",
            "minimum": 0,
            "maximum": 2,
            "example": 0.7
          },
          "stream": {
            "type": "boolean",
            "description": "Whether to stream semantic response events using server-sent events.",
            "default": false,
            "example": true
          },
          "tools": {
            "type": "array",
            "description": "Responses API tools. Catalog MCP entries are hosted by Adaption; MCP entries with server_url are called by Adaption with caller-owned authorization; file_search runs over authorized adapted datasets. With `model: stack:<id>`, omitted tools means the stack's configured tools (none when tool_choice is \"none\"), and an empty array means no tools; requested hosted MCP labels must be enabled on the stack, and file_search uses the stack dataset scope when dataset_ids is omitted. connector_id MCP tools are not supported.",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/McpRequestToolDto"
                },
                {
                  "$ref": "#/components/schemas/FileSearchToolDto"
                },
                {
                  "type": "object",
                  "description": "Another OpenAI-compatible Responses tool forwarded to the model provider.",
                  "required": [
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "not": {
                        "enum": [
                          "mcp",
                          "file_search"
                        ]
                      }
                    }
                  },
                  "additionalProperties": true
                }
              ]
            }
          },
          "max_tool_calls": {
            "type": "integer",
            "description": "Maximum number of first-party and MCP tool calls to run for this response. Once reached, the model is asked to answer without calling more tools.",
            "minimum": 1,
            "maximum": 64,
            "example": 8
          },
          "store": {
            "type": "boolean",
            "description": "Whether Adaption should retain this response for later use with previous_response_id. Adaption defaults to false, unlike OpenAI, so retention requires explicitly setting store to true. A stored response is kept for 30 days from its creation, then deleted. When an ancestor was deleted, previous_response_id still works, but the replayed history starts at the oldest response still stored. To keep the full context, resend it with previous_response_id set to null.",
            "example": false,
            "default": false
          },
          "previous_response_id": {
            "type": "string",
            "description": "A previously stored response whose input and output should precede this turn."
          },
          "background": {
            "type": "boolean",
            "description": "Background execution is incompatible with the hosted-tool loop. Only false is accepted.",
            "example": false,
            "default": false
          },
          "tool_choice": {
            "description": "How the model may use the attached tools. Omitted or `auto`, the model decides whether to search and how to word the query. `none` forbids tools entirely. Naming a function demands that call: use `{ \"type\": \"function\", \"name\": \"file_search\" }` when an answer must be grounded in the attached datasets, and the response fails rather than answering unsearched.",
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "auto",
                  "none"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "function"
                    ]
                  },
                  "name": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "name"
                ]
              }
            ],
            "example": "auto"
          }
        },
        "required": [
          "model"
        ]
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ]
}