{
  "openapi": "3.0.0",
  "info": {
    "title": "Express API for Dataset Service",
    "version": "1.0.0",
    "description": "This is a simple Express application that uses Sequelize and PostgreSQL to manage data sets.",
    "termsOfService": "https://readcoop.eu/terms-and-conditions/",
    "contact": {
      "email": "info@readcoop.eu"
    }
  },
  "servers": [
    {
      "url": "https://api-dataset.transkribus.org",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "oAuth2AuthCode": {
        "type": "oauth2",
        "description": "READCOOP SSO",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://account.readcoop.eu/authTesting/realms/readcoop/protocol/openid-connect/auth",
            "tokenUrl": "https://account.readcoop.eu/authTesting/realms/readcoop/protocol/openid-connect/token",
            "refreshUrl": "https://account.readcoop.eu/authTesting/realms/readcoop/protocol/openid-connect/token",
            "scopes": {
              "openid": "standard scope"
            },
            "clientId": "subscription-api-client-swagger"
          }
        }
      }
    }
  },
  "security": [
    {
      "oAuth2AuthCode": [
        "openid"
      ]
    }
  ],
  "paths": {
    "/v1/bookmarks": {
      "get": {
        "summary": "Get all bookmarked datasets for the current user",
        "tags": [
          "Dataset Bookmarks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "search",
            "schema": {
              "type": "string"
            },
            "description": "Search term to filter bookmarked datasets"
          },
          {
            "in": "query",
            "name": "index",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pagination start index"
          },
          {
            "in": "query",
            "name": "nValues",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Number of items to return"
          },
          {
            "in": "query",
            "name": "sortColumn",
            "schema": {
              "type": "string",
              "default": "created_at"
            },
            "description": "Column to sort by"
          },
          {
            "in": "query",
            "name": "sortDirection",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            },
            "description": "Sort direction"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookmarked datasets retrieved successfully"
          },
          "401": {
            "description": "Unauthorized - Authentication required"
          },
          "500": {
            "description": "Server error"
          }
        },
        "operationId": "get-v1-bookmarks"
      },
      "post": {
        "summary": "Add a dataset to user's bookmarks",
        "tags": [
          "Dataset Bookmarks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "dataset_id"
                ],
                "properties": {
                  "dataset_id": {
                    "type": "string",
                    "description": "ID of the dataset to bookmark (can be numeric for regular datasets or string like 'model_1234' for model datasets)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dataset bookmarked successfully"
          },
          "400": {
            "description": "Dataset ID is required"
          },
          "401": {
            "description": "Unauthorized - Authentication required"
          },
          "404": {
            "description": "Dataset not found"
          },
          "409": {
            "description": "Dataset already bookmarked"
          },
          "500": {
            "description": "Server error"
          }
        },
        "operationId": "post-v1-bookmarks"
      }
    },
    "/v1/bookmarks/{dataset_id}": {
      "delete": {
        "summary": "Remove a dataset from user's bookmarks",
        "tags": [
          "Dataset Bookmarks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "ID of the dataset to remove from bookmarks"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookmark removed successfully"
          },
          "401": {
            "description": "Unauthorized - Authentication required"
          },
          "404": {
            "description": "Bookmark not found"
          },
          "500": {
            "description": "Server error"
          }
        },
        "operationId": "delete-v1-bookmarks-datasetid"
      }
    },
    "/v1/bookmarks/{dataset_id}/status": {
      "get": {
        "summary": "Check if a dataset is bookmarked by the current user",
        "tags": [
          "Dataset Bookmarks"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "ID of the dataset to check"
          }
        ],
        "responses": {
          "200": {
            "description": "Returns bookmark status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "isBookmarked": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication required"
          },
          "500": {
            "description": "Server error"
          }
        },
        "operationId": "get-v1-bookmarks-datasetid-status"
      }
    },
    "/v1/data-access/datasets": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get all datasets (stored datasets and model training data)",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "userId",
            "schema": {
              "type": "integer"
            },
            "description": "Optional user ID for filtering datasets by access permissions"
          },
          {
            "in": "query",
            "name": "accessType",
            "schema": {
              "type": "string"
            },
            "description": "Filter datasets by access type (e.g., 'public', 'private')"
          },
          {
            "in": "query",
            "name": "tags",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter datasets by tags"
          },
          {
            "in": "query",
            "name": "search",
            "schema": {
              "type": "string"
            },
            "description": "Search term to filter datasets by name, description, or title"
          },
          {
            "in": "query",
            "name": "index",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "0-based starting index for pagination"
          },
          {
            "in": "query",
            "name": "nValues",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Number of items to retrieve per page"
          },
          {
            "in": "query",
            "name": "source",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "admin",
                "stored",
                "shared",
                "public",
                "model",
                "bookmark"
              ],
              "default": "all"
            },
            "description": "Source of the datasets to retrieve. `all` and `admin` both return every dataset and require the `Transkribus Admin` realm role."
          },
          {
            "in": "query",
            "name": "sortBy",
            "schema": {
              "type": "string",
              "default": "created_at"
            },
            "description": "Field to sort by (stored datasets - id, name, description, dataset_type, visibility, created_at, owner_id) (model datasets - modelId, name, userName, featuredWeight, language, created)"
          },
          {
            "in": "query",
            "name": "sortDirection",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC",
                "asc",
                "desc"
              ],
              "default": "DESC"
            },
            "description": "Sort direction (ASC or DESC)"
          },
          {
            "in": "query",
            "name": "prov",
            "schema": {
              "type": "string"
            },
            "description": "Filter datasets by prov"
          },
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string"
            },
            "description": "Filter datasets by type"
          },
          {
            "in": "query",
            "name": "minItems",
            "schema": {
              "type": "integer"
            },
            "description": "Filter datasets with at least this many items"
          },
          {
            "in": "query",
            "name": "maxItems",
            "schema": {
              "type": "integer"
            },
            "description": "Filter datasets with at most this many items"
          },
          {
            "in": "query",
            "name": "isoLanguages",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Filter model datasets by isoLanguages (only applies when source=model)"
          },
          {
            "in": "query",
            "name": "creatorId",
            "schema": {
              "type": "integer"
            },
            "description": "Filter model datasets by creator ID (only applies when source=model)"
          },
          {
            "in": "query",
            "name": "minTrainingItems",
            "schema": {
              "type": "integer"
            },
            "description": "Filter model datasets with at least this many training items (only applies when source=model)"
          },
          {
            "in": "query",
            "name": "maxTrainingItems",
            "schema": {
              "type": "integer"
            },
            "description": "Filter model datasets with at most this many training items (only applies when source=model)"
          }
        ],
        "responses": {
          "200": {
            "description": "All datasets retrieved successfully"
          }
        },
        "operationId": "get-v1-data-access-datasets"
      }
    },
    "/v1/data-access/datasets/counts": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get counts for all dataset categories",
        "description": "Returns counts for all dataset categories in a single request.\nUseful for displaying tab counts without loading actual data.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset counts retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "counts": {
                      "type": "object",
                      "properties": {
                        "stored": {
                          "type": "integer",
                          "description": "Number of stored (active) datasets the user owns"
                        },
                        "shared": {
                          "type": "integer",
                          "description": "Number of datasets shared with the user by somebody else"
                        },
                        "public": {
                          "type": "integer",
                          "description": "Number of published public datasets"
                        },
                        "model": {
                          "type": "integer",
                          "description": "Number of model-connected datasets"
                        },
                        "all": {
                          "type": "integer",
                          "description": "Total number of all datasets (stored + model)"
                        },
                        "bookmark": {
                          "type": "integer",
                          "description": "Number of bookmarked datasets"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "operationId": "get-v1-data-access-datasets-counts"
      }
    },
    "/v1/data-access/model-datasets/{modelId}": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get a model-connected dataset by model ID",
        "description": "Retrieves a model-connected dataset by its model ID.\nThis is a dedicated endpoint for model datasets, separate from stored datasets.\nReturns the model's training data formatted as a dataset.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "modelId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "The numeric model ID (e.g., 501, 6781)"
          },
          {
            "in": "query",
            "name": "index",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "0-based starting index for items pagination"
          },
          {
            "in": "query",
            "name": "nValues",
            "schema": {
              "type": "integer",
              "default": 5
            },
            "description": "Number of items to retrieve per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Model dataset retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "description": "Model dataset information with paginated items"
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "index": {
                          "type": "integer"
                        },
                        "nValues": {
                          "type": "integer"
                        },
                        "totalItems": {
                          "type": "integer"
                        },
                        "totalPages": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Model not found"
          }
        },
        "operationId": "get-v1-data-access-model-datasets-modelid"
      }
    },
    "/v1/data-access/model-datasets/{modelId}/validation": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get validation data for a model-connected dataset",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "modelId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "index",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "nValues",
            "schema": {
              "type": "integer",
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation data retrieved successfully"
          }
        },
        "operationId": "get-v1-data-access-model-datasets-modelid-validation"
      }
    },
    "/v1/data-access/datasets/{datasetId}/access": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get all access grants for a dataset",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset access grants retrieved successfully"
          }
        },
        "operationId": "get-v1-data-access-datasets-datasetid-access"
      },
      "post": {
        "tags": [
          "Data Access"
        ],
        "summary": "Grant access to a dataset for a user or group",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "entity_type": {
                    "type": "string",
                    "enum": [
                      "user",
                      "group"
                    ]
                  },
                  "entity_id": {
                    "type": "integer"
                  },
                  "permissions": {
                    "type": "string",
                    "enum": [
                      "read",
                      "write"
                    ],
                    "default": "read"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Access granted successfully"
          }
        },
        "operationId": "post-v1-data-access-datasets-datasetid-access"
      }
    },
    "/v1/data-access/datasets/{datasetId}/access/{accessId}": {
      "delete": {
        "tags": [
          "Data Access"
        ],
        "summary": "Revoke access to a dataset for a user or group",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "path",
            "name": "accessId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Access revoked successfully"
          }
        },
        "operationId": "delete-v1-data-access-datasets-datasetid-access-accessid"
      }
    },
    "/v1/data-access/datasets/{datasetId}/transfer-ownership": {
      "post": {
        "tags": [
          "Data Access"
        ],
        "summary": "Transfer dataset ownership to another user. The previous owner is demoted to Editor.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "new_owner_id"
                ],
                "properties": {
                  "new_owner_id": {
                    "type": "integer",
                    "description": "ID of the user who will become the new owner"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ownership transferred successfully"
          },
          "400": {
            "description": "Invalid request"
          },
          "403": {
            "description": "Only the current owner can transfer ownership"
          },
          "404": {
            "description": "Dataset not found"
          }
        },
        "operationId": "post-v1-data-access-datasets-datasetid-transfer-ownership"
      }
    },
    "/v1/data-access/datasets/{datasetId}/audit-log": {
      "get": {
        "tags": [
          "Data Access"
        ],
        "summary": "Get audit log entries for a dataset",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "ID of the dataset to retrieve audit log for"
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset audit log retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "dataset_id": {
                          "type": "integer"
                        },
                        "audit_log": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "timestamp": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "user": {
                                "type": "string"
                              },
                              "action": {
                                "type": "string"
                              },
                              "details": {
                                "type": "object"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Access denied - only dataset owner can view audit log"
          },
          "404": {
            "description": "Dataset not found"
          },
          "500": {
            "description": "Server error"
          }
        },
        "operationId": "get-v1-data-access-datasets-datasetid-audit-log"
      }
    },
    "/v1/datasets": {
      "get": {
        "tags": [
          "Datasets"
        ],
        "summary": "List user's datasets",
        "operationId": "get-v1-datasets"
      },
      "post": {
        "tags": [
          "Datasets"
        ],
        "summary": "Create new dataset",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "userId"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Dataset name"
                  },
                  "description": {
                    "type": "string",
                    "description": "Dataset description (supports HTML)"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "document_type": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "language": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "license": {
                    "type": "string"
                  },
                  "centuries": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "doi": {
                    "type": "string",
                    "description": "Digital Object Identifier for academic citation (format 10.xxxx/xxxxx)"
                  },
                  "userId": {
                    "type": "integer",
                    "description": "Owner user ID"
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets"
      }
    },
    "/v1/datasets/{id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Get dataset with latest version",
        "operationId": "get-v1-datasets-id"
      },
      "put": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Update dataset metadata",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Dataset name"
                  },
                  "description": {
                    "type": "string",
                    "description": "Dataset description (supports HTML)"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Custom tags for categorization"
                  },
                  "document_type": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Ground truth types (e.g., text, layout, fields, tables)"
                  },
                  "language": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "ISO language codes"
                  },
                  "license": {
                    "type": "string",
                    "description": "License identifier (e.g., cc0, cc-by, openrail)"
                  },
                  "centuries": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    },
                    "description": "Century numbers covered by this dataset"
                  },
                  "doi": {
                    "type": "string",
                    "description": "Digital Object Identifier for academic citation (format 10.xxxx/xxxxx)"
                  }
                }
              }
            }
          }
        },
        "operationId": "put-v1-datasets-id"
      },
      "delete": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Delete dataset",
        "operationId": "delete-v1-datasets-id"
      }
    },
    "/v1/datasets/{id}/withdraw": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Request withdrawal of a DOI'd dataset (owner/admin)",
        "description": "Step 1 of admin-approved deletion. Hides the DOIs (concept + every\nversion DOI), flips the dataset private, cancels any pending\npublication review, and queues a pending deletion review for an\nadmin to approve. Purges nothing itself — the purge happens only on\nadmin approval. 409 if a deletion request is already pending.\n",
        "operationId": "post-v1-datasets-id-withdraw"
      }
    },
    "/v1/datasets/{id}/withdraw/cancel": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Cancel a pending withdrawal request (owner/admin)",
        "description": "Marks the pending deletion review cancelled before an admin acts on\nit. The dataset deliberately STAYS private — going public again\nrequires a fresh publication request through the normal review gate.\n404 if no deletion request is pending.\n",
        "operationId": "post-v1-datasets-id-withdraw-cancel"
      }
    },
    "/v1/datasets/{id}/make-citable": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Make an already-published dataset citable — mints DOIs (owner/admin)",
        "description": "Self-service opt-in. Sets doi_mint_status to 'pending' and mints the\nconcept DOI + a version DOI per public version asynchronously. One-way:\n422 if the dataset is already citable, private, or withdrawn. 409 while\nDataCite minting is disabled.\n",
        "operationId": "post-v1-datasets-id-make-citable"
      }
    },
    "/v1/datasets/{id}/versions": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Versions"
        ],
        "summary": "List all versions for a dataset",
        "operationId": "get-v1-datasets-id-versions"
      },
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Versions"
        ],
        "summary": "Create new draft version",
        "operationId": "post-v1-datasets-id-versions"
      }
    },
    "/v1/datasets/{id}/versions/{vid}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Versions"
        ],
        "summary": "Get version with split stats",
        "operationId": "get-v1-datasets-id-versions-vid"
      },
      "patch": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Versions"
        ],
        "summary": "Update version metadata (label, note)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "version_label": {
                    "type": "string",
                    "description": "Human-readable label for the version"
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "User note describing this version"
                  }
                }
              }
            }
          }
        },
        "operationId": "patch-v1-datasets-id-versions-vid"
      },
      "delete": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Versions"
        ],
        "summary": "Delete draft version only (🔒 fails on frozen)",
        "operationId": "delete-v1-datasets-id-versions-vid"
      }
    },
    "/v1/datasets/items": {
      "post": {
        "tags": [
          "Dataset Items"
        ],
        "summary": "Create items (not yet linked to any version)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "collId": {
                          "type": "integer"
                        },
                        "docId": {
                          "type": "integer"
                        },
                        "pageId": {
                          "type": "integer"
                        },
                        "pageNr": {
                          "type": "integer"
                        },
                        "imageId": {
                          "type": "string"
                        },
                        "imageKey": {
                          "type": "string"
                        },
                        "image": {
                          "type": "object"
                        },
                        "transcriptId": {
                          "type": "string"
                        },
                        "transcriptKey": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        },
                        "status": {
                          "type": "string"
                        },
                        "isIncomplete": {
                          "type": "boolean"
                        },
                        "nrOfRegions": {
                          "type": "integer"
                        },
                        "nrOfTranscribedRegions": {
                          "type": "integer"
                        },
                        "nrOfWordsInRegions": {
                          "type": "integer"
                        },
                        "nrOfLines": {
                          "type": "integer"
                        },
                        "nrOfTranscribedLines": {
                          "type": "integer"
                        },
                        "nrOfWordsInLines": {
                          "type": "integer"
                        },
                        "nrOfWords": {
                          "type": "integer"
                        },
                        "nrOfTranscribedWords": {
                          "type": "integer"
                        },
                        "nrOfCharsInLines": {
                          "type": "integer"
                        },
                        "nrOfTables": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Items created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "itemIds": {
                          "type": "array",
                          "items": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-items"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/items": {
      "get": {
        "tags": [
          "Dataset Items"
        ],
        "summary": "List items in a version (filterable by split)",
        "description": "Returns the items linked to a version. Requires read access to the\ndataset (owner, admin, an explicit access grant, or a public dataset).\n\n**This response is paginated and `limit` defaults to 100.** Items come\nback ordered by row id, and whether a given split appears in the first\npage depends on the order the items happened to be inserted — a version\nwith thousands of validation items can answer an unpaginated request\nwith train items only. Always compare `data.length` against `total`,\nand page until you have `total` rows. To ask about one split, filter\nwith `split=` rather than scanning an unfiltered page: `total` is then\nthe exact count for that split. `GET .../versions/{vid}/splits` returns\nper-split counts directly and is not subject to pagination at all.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Dataset (definition) ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "vid",
            "in": "path",
            "required": true,
            "description": "Version ID (must belong to the dataset given in `id`)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "split",
            "in": "query",
            "description": "Optional split filter",
            "schema": {
              "type": "string",
              "enum": [
                "train",
                "validation",
                "test"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max number of items to return. Defaults to 100 when omitted — pass\nan explicit value to get more. `0` is treated as omitted (falls back\nto 100) and negative values are rejected by the database, so page\nwith a real page size instead of trying to disable the limit.\n",
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of items to skip (pagination)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Items retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of matching items (ignores limit/offset)"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "version_id": {
                            "type": "integer"
                          },
                          "item_id": {
                            "type": "integer"
                          },
                          "split_type": {
                            "type": "string",
                            "enum": [
                              "train",
                              "validation",
                              "test"
                            ]
                          },
                          "item": {
                            "type": "object",
                            "description": "The linked dataset_items record"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token"
          },
          "403": {
            "description": "Caller does not have read access to the dataset"
          },
          "404": {
            "description": "Version not found, or does not belong to the given dataset"
          },
          "502": {
            "description": "Model-connected datasets (`model_<n>`) only. A split had to be\nfetched from the external Transkribus API and that call failed, so\nthe item list would have been incomplete. No items are returned\nrather than a silently short list. A model that genuinely has no\nvalidation data answers 200 with an empty validation split instead.\n"
          }
        },
        "operationId": "get-v1-datasets-id-versions-vid-items"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/source-breakdown": {
      "get": {
        "tags": [
          "Dataset Items"
        ],
        "summary": "Per-source-collection item counts for a version",
        "description": "Returns how many of the version's items came from each source\ncollection (grouped by `coll_id`), largest first, plus the total over\ncollection-sourced items. Used to show the source make-up of a sampled\nversion. Requires read access to the dataset.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Dataset (definition) ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "vid",
            "in": "path",
            "required": true,
            "description": "Version ID (must belong to the dataset given in `id`)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Breakdown retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total items with a source collection"
                        },
                        "breakdown": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "collId": {
                                "type": "integer"
                              },
                              "count": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid authentication token"
          },
          "403": {
            "description": "Caller does not have read access to the dataset"
          },
          "404": {
            "description": "Version not found, or does not belong to the given dataset"
          }
        },
        "operationId": "get-v1-datasets-id-versions-vid-source-breakdown"
      }
    },
    "/v1/datasets/{id}/items": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Add items to draft (🔒 fails on frozen)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "itemIds"
                ],
                "properties": {
                  "itemIds": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "split": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test"
                    ],
                    "default": "train"
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-items"
      },
      "delete": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Remove multiple items from draft (batch operation, 🔒 fails on frozen)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "itemIds"
                ],
                "properties": {
                  "itemIds": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "delete-v1-datasets-id-items"
      }
    },
    "/v1/datasets/{id}/check-duplicates": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Check for duplicate items before adding (checks all splits)",
        "description": "Checks if the provided items already exist in the dataset across ALL splits.\nReturns duplicate information including which split each duplicate is in.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "imageId": {
                          "type": "string"
                        },
                        "transcriptId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-check-duplicates"
      }
    },
    "/v1/datasets/{id}/items/{itemId}": {
      "delete": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "itemId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Remove single item from draft (🔒 fails on frozen)",
        "operationId": "delete-v1-datasets-id-items-itemid"
      }
    },
    "/v1/datasets/{id}/items/split": {
      "patch": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Move multiple items between splits (batch operation, 🔒 fails on frozen)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "itemIds",
                  "targetSplit"
                ],
                "properties": {
                  "itemIds": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "targetSplit": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test"
                    ]
                  }
                }
              }
            }
          }
        },
        "operationId": "patch-v1-datasets-id-items-split"
      }
    },
    "/v1/datasets/{id}/items/split/move-percentage": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Items"
        ],
        "summary": "Move a percentage of items between splits in one request (🔒 fails on frozen)",
        "description": "Server-side equivalent of (list items by split) + (PATCH split).\nSelects `floor(sourceSplit.count * percentage/100)` items and\nreassigns them to `targetSplit` atomically.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sourceSplit",
                  "targetSplit",
                  "percentage"
                ],
                "properties": {
                  "sourceSplit": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test"
                    ]
                  },
                  "targetSplit": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test"
                    ]
                  },
                  "percentage": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "first",
                      "random"
                    ],
                    "default": "first"
                  },
                  "seed": {
                    "type": "string",
                    "description": "Optional seed for reproducible random selection (only used when method=random)"
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-items-split-move-percentage"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/splits": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Splits"
        ],
        "summary": "Get split statistics",
        "operationId": "get-v1-datasets-id-versions-vid-splits"
      }
    },
    "/v1/datasets/{id}/split": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Splits"
        ],
        "summary": "Apply automatic split (🔒 fails on frozen)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ratios",
                  "seed"
                ],
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "random"
                    ],
                    "default": "random"
                  },
                  "ratios": {
                    "type": "object",
                    "properties": {
                      "train": {
                        "type": "number"
                      },
                      "validation": {
                        "type": "number"
                      },
                      "test": {
                        "type": "number"
                      }
                    }
                  },
                  "seed": {
                    "type": "string",
                    "minLength": 8
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-split"
      }
    },
    "/v1/datasets/{id}/train-validation-split": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Splits"
        ],
        "summary": "Apply train/validation split only (🔒 fails on frozen)",
        "description": "Applies automatic split to train and validation sets only, leaving the test set unchanged.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ratios",
                  "seed"
                ],
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": [
                      "random"
                    ],
                    "default": "random"
                  },
                  "ratios": {
                    "type": "object",
                    "properties": {
                      "train": {
                        "type": "number"
                      },
                      "validation": {
                        "type": "number"
                      }
                    }
                  },
                  "seed": {
                    "type": "string",
                    "minLength": 8
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-train-validation-split"
      }
    },
    "/v1/datasets/{id}/items/{itemId}/split": {
      "put": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "itemId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Splits"
        ],
        "summary": "Manual split assignment (🔒 fails on frozen)",
        "operationId": "put-v1-datasets-id-items-itemid-split"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/freeze": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Lifecycle"
        ],
        "summary": "Freeze draft → frozen (⚠️ IRREVERSIBLE)",
        "description": "Freezes a draft version, making it immutable.\n- Validates all items have split assignments\n- Cannot be undone\n- Frontend should show confirmation dialog\n",
        "operationId": "post-v1-datasets-id-versions-vid-freeze"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/copy": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Copy"
        ],
        "summary": "Copy version to new draft",
        "operationId": "post-v1-datasets-id-versions-vid-copy"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/copy-all": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Copy"
        ],
        "summary": "Copy all items to new or existing dataset",
        "description": "Copy ALL items from a version to a new or existing dataset.\nUse targetSplit to assign all items to a specific split (train/validation/test),\nor set targetSplit to \"preserve\" to carry over the original split assignments.\n- Provide `name` to create a new dataset\n- Provide `targetDatasetId` to copy to an existing dataset's draft version\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 3,
                    "description": "Name for the new dataset (required if not using targetDatasetId)"
                  },
                  "description": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "document_type": {
                    "type": "string"
                  },
                  "license": {
                    "type": "string"
                  },
                  "customFields": {
                    "type": "object"
                  },
                  "sourceInfo": {
                    "type": "object"
                  },
                  "dataQualityMetrics": {
                    "type": "object"
                  },
                  "queryCriteria": {
                    "type": "object"
                  },
                  "targetDatasetId": {
                    "type": "integer",
                    "description": "ID of existing dataset to copy to (alternative to name)"
                  },
                  "targetSplit": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test",
                      "preserve"
                    ],
                    "default": "train",
                    "description": "Split to assign all copied items to. Use \"preserve\" to keep original train/validation/test assignments."
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-versions-vid-copy-all"
      }
    },
    "/v1/datasets/{id}/versions/{vid}/splits/{split}/copy": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "vid",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "split",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Dataset Copy"
        ],
        "summary": "Copy single split to new or existing dataset",
        "description": "Copy items from a split to either a new dataset or an existing one.\n- Provide `name` to create a new dataset with that name (plus optional dataset params)\n- Provide `targetDatasetId` to copy to an existing dataset's draft version\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 3,
                    "description": "Name for the new dataset (required if not using targetDatasetId)"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description for the new dataset"
                  },
                  "title": {
                    "type": "string",
                    "description": "Title for the new dataset"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tags for the new dataset"
                  },
                  "document_type": {
                    "type": "string",
                    "description": "Document type for the new dataset"
                  },
                  "license": {
                    "type": "string",
                    "description": "License for the new dataset"
                  },
                  "customFields": {
                    "type": "object",
                    "description": "Custom fields for the new dataset"
                  },
                  "sourceInfo": {
                    "type": "object",
                    "description": "Source info for the new dataset"
                  },
                  "dataQualityMetrics": {
                    "type": "object",
                    "description": "Data quality metrics for the new dataset"
                  },
                  "queryCriteria": {
                    "type": "object",
                    "description": "Query criteria for the new dataset"
                  },
                  "targetDatasetId": {
                    "type": "integer",
                    "description": "ID of existing dataset to copy to (alternative to name)"
                  },
                  "targetSplit": {
                    "type": "string",
                    "enum": [
                      "train",
                      "validation",
                      "test"
                    ],
                    "default": "train",
                    "description": "Target split in the existing dataset (only used with targetDatasetId)"
                  }
                }
              }
            }
          }
        },
        "operationId": "post-v1-datasets-id-versions-vid-splits-split-copy"
      }
    },
    "/v1/datasets/sample/preview": {
      "post": {
        "tags": [
          "Dataset Sampling"
        ],
        "summary": "Preview a deterministic sample over selected collections",
        "description": "Pure function of the inputs. Used to drive the wizard preview screen.\nNo DB writes.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "collectionIds",
                  "strategy",
                  "sampleSize",
                  "seed",
                  "gtFilter"
                ],
                "properties": {
                  "collectionIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "random",
                      "stratified"
                    ]
                  },
                  "sampleSize": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "seed": {
                    "type": "string",
                    "minLength": 8
                  },
                  "gtFilter": {
                    "type": "string",
                    "enum": [
                      "any",
                      "gt_only"
                    ]
                  },
                  "excludeFromDatasetId": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "When set, exclude pages already in this dataset's draft from the eligible pool."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview computed successfully"
          },
          "400": {
            "description": "Invalid request body"
          },
          "403": {
            "description": "User lacks access to one or more collections"
          },
          "502": {
            "description": "Upstream Transkribus error during pool enumeration"
          }
        },
        "operationId": "post-v1-datasets-sample-preview"
      }
    },
    "/v1/datasets/{datasetId}/sample/commit": {
      "post": {
        "tags": [
          "Dataset Sampling"
        ],
        "summary": "Commit a sample into an existing dataset's draft version",
        "description": "Runs the sampler over the requested collections (same params as\npreview), then persists the picked pages as dataset_items linked to\nthe dataset's draft version with the given split. Persists the\nsampling params + pool fingerprint on the version for auditability.\n",
        "parameters": [
          {
            "in": "path",
            "name": "datasetId",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "collectionIds",
                  "strategy",
                  "sampleSize",
                  "seed",
                  "gtFilter",
                  "splitRatio"
                ],
                "properties": {
                  "collectionIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "random",
                      "stratified"
                    ]
                  },
                  "sampleSize": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "seed": {
                    "type": "string",
                    "minLength": 8
                  },
                  "gtFilter": {
                    "type": "string",
                    "enum": [
                      "any",
                      "gt_only"
                    ]
                  },
                  "splitRatio": {
                    "type": "object",
                    "required": [
                      "train",
                      "val",
                      "test"
                    ],
                    "properties": {
                      "train": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "val": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "test": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      }
                    },
                    "description": "Integer percentages that must sum to 100."
                  },
                  "targetVersionId": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "createDraftFromLatest": {
                    "type": "boolean"
                  },
                  "replaceDuplicates": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sample committed to draft version"
          },
          "400": {
            "description": "Invalid request body"
          },
          "409": {
            "description": "No draft version exists and createDraftFromLatest not set"
          },
          "422": {
            "description": "Sample is empty (pool was filtered to zero items)"
          },
          "501": {
            "description": "createDraftFromLatest requested but not yet supported"
          }
        },
        "operationId": "post-v1-datasets-datasetid-sample-commit"
      }
    },
    "/v1/datasets/sample/commit-new": {
      "post": {
        "tags": [
          "Dataset Sampling"
        ],
        "summary": "Create a new dataset (and initial draft) and commit a sample into it",
        "description": "Transactionally creates a new dataset definition and an initial draft\nversion owned by the caller, then runs the sampler and commits the\npicked pages into the new draft with the requested split.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "collectionIds",
                  "strategy",
                  "sampleSize",
                  "seed",
                  "gtFilter",
                  "splitRatio",
                  "name"
                ],
                "properties": {
                  "collectionIds": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "random",
                      "stratified"
                    ]
                  },
                  "sampleSize": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "seed": {
                    "type": "string",
                    "minLength": 8
                  },
                  "gtFilter": {
                    "type": "string",
                    "enum": [
                      "any",
                      "gt_only"
                    ]
                  },
                  "splitRatio": {
                    "type": "object",
                    "required": [
                      "train",
                      "val",
                      "test"
                    ],
                    "properties": {
                      "train": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "val": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "test": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      }
                    },
                    "description": "Integer percentages that must sum to 100."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 3
                  },
                  "description": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "document_type": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "license": {
                    "type": "string"
                  },
                  "language": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dataset, draft version, and sample committed"
          },
          "400": {
            "description": "Invalid request body"
          },
          "422": {
            "description": "Sample is empty (pool was filtered to zero items)"
          }
        },
        "operationId": "post-v1-datasets-sample-commit-new"
      }
    },
    "/v1/public/datasets": {
      "get": {
        "tags": [
          "Datasets"
        ],
        "summary": "List public datasets (no auth) — DOI landing / catalog feed",
        "operationId": "get-v1-public-datasets"
      }
    },
    "/v1/public/datasets/{id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Public dataset record with citations + provenance (no auth)",
        "operationId": "get-v1-public-datasets-id"
      }
    },
    "/v1/public/datasets/{id}/versions/{versionId}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "versionId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Datasets"
        ],
        "summary": "Public record for a specific dataset version (version-DOI landing, no auth)",
        "operationId": "get-v1-public-datasets-id-versions-versionid"
      }
    }
  },
  "tags": [
    {
      "name": "Datasets",
      "description": "API endpoints for managing datasets and versions (ADR-001 compliant)."
    },
    {
      "name": "Dataset Versions",
      "description": "API endpoints for managing immutable dataset version snapshots."
    },
    {
      "name": "Dataset Items",
      "description": "API endpoints for accessing canonical data items (images/transcripts)."
    },
    {
      "name": "Dataset Splits",
      "description": "API endpoints for managing train/validation/test splits."
    },
    {
      "name": "Dataset Bookmarks",
      "description": "API endpoints for managing user bookmarks/favorites of datasets."
    },
    {
      "name": "Dataset Sampling",
      "description": "API endpoints for deterministic sampling of pages into datasets."
    }
  ]
}
