A-Alpha Bio Datasets API

openapi: 3.2.0
info:
  title: A Alpha Bio Datasets API
  version: 0.0.43
  description: 'Operations tagged Datasets across 2 of this provider''s published API definitions: a-alpha-bio-atlas-data-product-openapi-original.json, a-alpha-bio-atlas-datasets-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.atlas.aalphabio.com
  description: 'Atlas Data Product API production host (observed: serves /openapi.json and every /api/v1/* path; named in the atlas.aalphabio.com SPA preconnect hint)'
tags:
- name: Datasets
paths:
  /api/v1/datasets:
    get:
      tags:
      - Datasets
      summary: List accessible datasets
      description: Returns all datasets the user can access, plus publicly visible datasets. By default returns only the latest version of each dataset and excludes locked datasets. Locked datasets are datasets whose metadata is publicly visible but whose data requires a purchase or subscription to access. Set `all_versions=true` to include all versions. Set `include_locked=true` to include locked datasets. Coming-soon teasers are excluded by default; set `include_coming_soon=true` to include them.
      operationId: listDatasets
      security:
      - HTTPBearer: []
      parameters:
      - name: all_versions
        in: query
        required: false
        schema:
          type: boolean
          description: Include all versions, not just latest
          default: false
          title: All Versions
        description: Include all versions, not just latest
      - name: include_locked
        in: query
        required: false
        schema:
          type: boolean
          description: Include locked datasets (purchasable datasets the user hasn't unlocked yet)
          default: false
          title: Include Locked
        description: Include locked datasets (purchasable datasets the user hasn't unlocked yet)
      - name: include_coming_soon
        in: query
        required: false
        schema:
          type: boolean
          description: Include coming-soon teaser datasets (upcoming releases with visible metadata but no data yet)
          default: false
          title: Include Coming Soon
        description: Include coming-soon teaser datasets (upcoming releases with visible metadata but no data yet)
      responses:
        '200':
          description: Successfully retrieved list of accessible datasets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}:
    get:
      tags:
      - Datasets
      summary: Get dataset metadata
      description: Returns the metadata for a specific dataset. Use optional `version` query param to get a specific version (defaults to latest).
      operationId: getDataset
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved dataset metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetGetResponse'
        '400':
          description: Bad request - missing ID
        '404':
          description: Dataset not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/datacard:
    get:
      tags:
      - Datasets
      summary: Get dataset Data Card
      description: Returns the structured Data Card for a specific dataset. Use optional `version` query param to get a specific version (defaults to latest).
      operationId: getDatasetDatacard
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved Data Card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatacardResponse'
        '400':
          description: Bad request - missing ID
        '404':
          description: Dataset not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/data:
    get:
      tags:
      - Datasets
      summary: Get dataset CSV data
      description: 'Returns dataset CSV data. Redirects to a presigned S3 URL for the data file. Query params: `version` (defaults to latest), `max_rows` (limit rows), `mode` (data mode), `redirect` (`false` for JSON URL).'
      operationId: getDatasetData
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: max_rows
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: Limit number of data rows returned
          title: Max Rows
        description: Limit number of data rows returned
      - name: mode
        in: query
        required: false
        schema:
          type: string
          description: Data mode to retrieve
          default: source
          title: Mode
        description: Data mode to retrieve
      - name: redirect
        in: query
        required: false
        schema:
          type: boolean
          description: Set to `false` to return URL in JSON instead of 302 redirect
          default: true
          title: Redirect
        description: Set to `false` to return URL in JSON instead of 302 redirect
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved data
          content:
            application/json:
              schema: {}
        '302':
          description: Redirect to presigned S3 URL
        '400':
          description: Bad request - missing ID or invalid mode
        '401':
          description: Unauthorized - authentication required
        '404':
          description: Data file not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/schema:
    get:
      tags:
      - Datasets
      summary: Get dataset CSV schema
      description: 'Returns the column schema for a dataset''s CSV data. The response can be unpacked directly into `pd.read_csv(url, **schema)`. Query params: `version` (defaults to latest), `mode` (data mode).'
      operationId: getDatasetSchema
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: mode
        in: query
        required: false
        schema:
          type: string
          description: Data mode to retrieve schema for
          default: source
          title: Mode
        description: Data mode to retrieve schema for
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetSchemaResponse'
        '400':
          description: Bad request - missing ID or invalid mode
        '401':
          description: Unauthorized - authentication required
        '404':
          description: Schema not found for this dataset/mode
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/structures:
    get:
      tags:
      - Datasets
      summary: List dataset structure files
      description: Returns a list of structure files in the dataset. Use optional `version` query param (defaults to latest).
      operationId: listDatasetStructures
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved structure file list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetStructureListResponse'
        '400':
          description: Bad request - missing ID
        '401':
          description: Unauthorized - authentication required
        '404':
          description: Dataset not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/structures/download:
    get:
      tags:
      - Datasets
      summary: Download all structure files as a zip archive
      description: Returns a pre-signed S3 URL for a zip archive of all structure files. Use optional `version` query param (defaults to latest).
      operationId: downloadDatasetStructures
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved pre-signed URL for structures zip
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetFileUrlResponse'
        '400':
          description: Bad request - missing ID
        '401':
          description: Unauthorized - authentication required
        '404':
          description: Structures not available or zip not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/structures/{filename}:
    get:
      tags:
      - Datasets
      summary: Get dataset structure file
      description: Returns the content of a structure file (e.g., `.cif`) from the dataset's structures directory. Use optional `version` query param (defaults to latest).
      operationId: getDatasetStructure
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successfully retrieved structure file
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request - missing ID or filename
        '401':
          description: Unauthorized - authentication required
        '404':
          description: Structure file not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/datasets/{id}/figures/{tab}/{filename}:
    get:
      tags:
      - Datasets
      summary: Get dataset figure content
      description: Returns the raw bytes of a figure referenced by `card_content.bio.figures[*].filenames[*]`. Figures are grouped by the dataset-page tab that renders them (e.g. `bio`) so each tab's images live under a predictable S3 prefix. Same access level as GET /datasets/{id}.
      operationId: getDatasetFigure
      security:
      - HTTPBearer: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      - name: tab
        in: path
        required: true
        schema:
          type: string
          title: Tab
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Figure bytes
          content:
            application/json:
              schema: {}
        '400':
          description: Bad request - missing ID, tab, or filename
        '404':
          description: Dataset not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MlCardContentResponse:
      properties:
        noise_signals:
          items:
            $ref: '#/components/schemas/CardContentNoiseSignal'
          type: array
          title: Noise Signals
        recommended_splits:
          anyOf:
          - type: string
          - type: 'null'
          title: Recommended Splits
        data_views:
          items:
            $ref: '#/components/schemas/CardContentDataView'
          type: array
          title: Data Views
        schema_columns:
          items:
            $ref: '#/components/schemas/CardContentSchemaColumn'
          type: array
          title: Schema Columns
      type: object
      title: MlCardContentResponse
      description: '``MlCardContent`` as served by the API, plus the derived column schema.


        ``schema_columns`` is sourced from the version''s ``data.source.schema.json``

        on S3 at request time (see ``datasets_api._read_schema_columns``) so it stays

        in sync with the actual CSV. It lives only here, on the response model — the

        stored ``MlCardContent`` cannot hold it, so a stale copy can never be

        persisted and there is nothing to strip on save.'
    ExecCardContent:
      properties:
        scientific_value:
          anyOf:
          - type: string
          - type: 'null'
          title: Scientific Value
        use_cases:
          items:
            $ref: '#/components/schemas/CardContentUseCase'
          type: array
          title: Use Cases
        differentiations:
          items:
            $ref: '#/components/schemas/CardContentTitleBody'
          type: array
          title: Differentiations
        stat_subs:
          anyOf:
          - $ref: '#/components/schemas/CardContentStatSubs'
          - type: 'null'
      type: object
      title: ExecCardContent
      description: Fields rendered on the dataset's Executive Summary tab.
    DatacardResponse:
      properties:
        exec:
          $ref: '#/components/schemas/ExecCardContent'
        ml:
          $ref: '#/components/schemas/MlCardContentResponse'
        bio:
          $ref: '#/components/schemas/BioCardContent'
      type: object
      title: DatacardResponse
      description: 'Response from GET /datasets/{id}/datacard endpoint.


        Same shape as CardContent — one sub-object per detail-page tab (`exec`,

        `ml`, `bio`) — except `ml` is the served variant, enriched with the

        S3-derived `schema_columns` (see `MlCardContentResponse`).'
    DatasetItem:
      properties:
        id:
          type: string
          title: Id
          description: Dataset identifier
          examples:
          - ab1001
        name:
          type: string
          title: Name
          description: Display name of the dataset
          examples:
          - AlphaBlock 1001
        experiment:
          type: string
          title: Experiment
          description: Brief description of the experiment
          examples:
          - This dataset explores the local affinity landscape...
        details:
          type: string
          title: Details
          description: Detailed description with bullet points
          examples:
          - '* Paratope coverage: >600 mutations...'
        modes:
          items:
            $ref: '#/components/schemas/DataMode'
          type: array
          title: Modes
          description: Available data modes for this dataset
          examples:
          - - file_type: csv.gz
              name: source
            - file_type: csv.gz
              name: ml
        release_date:
          type: string
          title: Release Date
          description: Release date of the dataset
          examples:
          - '2024-01-15'
        version:
          type: string
          title: Version
          description: Current version of the dataset
          examples:
          - '1'
        status:
          type: string
          title: Status
          description: Workflow status of this dataset version (draft, pending_review, published, retracted). Non-published statuses are only ever returned to admins previewing with drafts included.
          default: published
          examples:
          - published
          - draft
        locked:
          type: boolean
          title: Locked
          description: Whether the dataset is locked (user has no access to data)
          default: true
          examples:
          - false
        coming_soon:
          type: boolean
          title: Coming Soon
          description: Whether the dataset is an upcoming release shown as a teaser. When true the metadata is visible but the data is not yet available to anyone; the card is always locked.
          default: false
          examples:
          - false
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: URL to the dataset page in the web portal
          examples:
          - https://data.aalphabio.tools/dataset/ab1001
        structure_count:
          type: integer
          title: Structure Count
          description: Number of structure files (.cif) available in the structures directory
          default: 0
          examples:
          - 74973
        tasks:
          items:
            type: string
          type: array
          title: Tasks
          description: List of task types for this dataset
          examples:
          - - optimization
            - design
        binder:
          anyOf:
          - type: string
          - type: 'null'
          title: Binder
          description: Binder type for this dataset
          examples:
          - VHH
        target:
          items:
            type: string
          type: array
          title: Target
          description: List of target types for this dataset
          examples:
          - - viral
            - COVID
        product:
          type: string
          title: Product
          description: Product slug for this dataset
          examples:
          - atlas-vhh
          - exclusive
          - open-source
        product_display_name:
          type: string
          title: Product Display Name
          description: Human-readable product name
          examples:
          - Atlas VHH Consortia
          - Exclusive
          - Open Source
        product_kind:
          $ref: '#/components/schemas/ProductKind'
          description: Category of the dataset's product
          examples:
          - consortium
          - exclusive
          - open-source
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Product release name (for datasets in a named product release)
          examples:
          - VHH Q1 2025
        a_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: A Size
          description: Number of A (binder) sequences in the dataset
          examples:
          - 500
        alpha_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Alpha Size
          description: Number of Alpha (target) sequences in the dataset
          examples:
          - 200
        total_ppi_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Ppi Count
          description: Total number of protein-protein interactions measured
          examples:
          - 100000
        unique_ppi_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Unique Ppi Count
          description: Number of unique protein-protein interactions
          examples:
          - 50000
        density:
          anyOf:
          - type: number
          - type: 'null'
          title: Density
          description: Fraction of (a_size * alpha_size) grid actually observed
          examples:
          - 0.52
        tags:
          items:
            type: string
          type: array
          title: Tags
          description: List of tags for this dataset
          examples:
          - - dSSM
            - optimization
        has_tutorial:
          type: boolean
          title: Has Tutorial
          description: Whether this dataset has a Jupyter notebook tutorial available
          default: false
          examples:
          - true
      type: object
      required:
      - id
      - name
      - experiment
      - details
      - modes
      - release_date
      - version
      - product
      - product_display_name
      - product_kind
      title: DatasetItem
      description: A single dataset item.
    BioCardContent:
      properties:
        biological_system:
          anyOf:
          - type: string
          - type: 'null'
          title: Biological System
        figures:
          items:
            $ref: '#/components/schemas/CardContentFigure'
          type: array
          title: Figures
        findings:
          items:
            $ref: '#/components/schemas/CardContentTitleBody'
          type: array
          title: Findings
        considerations:
          items:
            type: string
          type: array
          title: Considerations
      type: object
      title: BioCardContent
      description: Fields rendered on the dataset's Biology & Assay tab.
    CardContentNoiseSignal:
      properties:
        label:
          type: string
          title: Label
        value:
          type: string
          title: Value
        sub:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub
      type: object
      required:
      - label
      - value
      title: CardContentNoiseSignal
      description: One stat card in the 'Noise & signal' section.
    CardContentSchemaColumn:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        description:
          type: string
          title: Description
      type: object
      required:
      - name
      - type
      - description
      title: CardContentSchemaColumn
      description: One row of the 'Schema (key columns)' table.
    ProductKind:
      type: string
      enum:
      - consortium
      - exclusive
      - licensable
      - open-source
      title: ProductKind
      description: "Category that a `product_types` row belongs to.\n\nStored on `ProductTypeEnum.kind`. Drives access control:\n\n- `open-source` bypasses license and subscription checks.\n- `consortium` gates access behind a `ProductSubscription` scoped to\n  the product (with `product_release.release_date` as the subscriber\n  gate); per-block `dataset_licenses` rows grant perpetual access.\n- `licensable` has no subscription path; access requires a\n  `dataset_licenses` row. Any number of companies can be licensed.\n- `exclusive` has no subscription path AND restricts licensing to a\n  single company — the dataset's `designer`. Exclusive blocks are\n  also always hidden from non-licensees (the\n  `metadata_visible_to_public` flag is ignored)."
    CardContentUseCase:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
      type: object
      required:
      - title
      - description
      title: CardContentUseCase
      description: One row of the 'Use cases unlocked' section.
    DatasetSchemaResponse:
      properties:
        dtype:
          additionalProperties:
            type: string
          type: object
          title: Dtype
          description: Column name to pandas dtype mapping
          examples:
          - id: Int64
            name: string
            score: float64
        parse_dates:
          items:
            type: string
          type: array
          title: Parse Dates
          description: Column names to parse as datetime
          examples:
          - - created_at
            - updated_at
      type: object
      required:
      - dtype
      title: DatasetSchemaResponse
      description: Response from GET /datasets/{id}/schema endpoint.
    DatasetStructureListResponse:
      properties:
        files:
          items:
            type: string
          type: array
          title: Files
          description: List of structure filenames
      type: object
      required:
      - files
      title: DatasetStructureListResponse
      description: Response from GET /datasets/{id}/structures endpoint.
    CardContentFigure:
      properties:
        title:
          type: string
          title: Title
        filenames:
          items:
            type: string
          type: array
          title: Filenames
          description: Image filenames rendered as equal-width columns (e.g. ['affinity.svg'])
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
      type: object
      required:
      - title
      title: CardContentFigure
      description: 'One figure in the ''Data analysis'' section.


        "One figure" = one title + one caption, but may include multiple

        side-by-side images via `filenames` — one image = full-width, N images

        = N equal columns.'
    CardContentTitleBody:
      properties:
        title:
          type: string
          title: Title
        body:
          type: string
          title: Body
      type: object
      required:
      - title
      - body
      title: CardContentTitleBody
      description: A {title, body} item — used for differentiation and key findings.
    CardContentDataView:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
      type: object
      required:
      - name
      - description
      title: CardContentDataView
      description: 'One item in the ''Data views'' section.


        ``mode`` is the view''s data-pair handle token (e.g. ``source``, ``ml``): the

        admin editor stores each view''s S3 pair as ``data.<mode>.csv.gz`` /

        ``data.<mode>.schema.json`` and the public API serves it under that mode. The

        portal detail page itself ignores it.'
    CardContentStatSubs:
      properties:
        a_size:
          anyOf:
          - type: string
          - type: 'null'
          title: A Size
        alpha_size:
          anyOf:
          - type: string
          - type: 'null'
          title: Alpha Size
        ppi:
          anyOf:
          - type: string
          - type: 'null'
          title: Ppi
      type: object
      title: CardContentStatSubs
      description: Per-stat subtitle text shown beneath the stats row.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DatasetFileUrlResponse:
      properties:
        url:
          type: string
          title: Url
          description: Pre-signed S3 URL for the file
      type: object
      required:
      - url
      title: DatasetFileUrlResponse
      description: Response from GET /datasets/{id}/files/{filename} endpoint.
    DatasetGetResponse:
      properties:
        dataset:
          $ref: '#/components/schemas/DatasetItem'
          description: The requested dataset metadata
      type: object
      required:
      - dataset
      title: DatasetGetResponse
      description: Response from GET /datasets/{id} endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DataMode:
      properties:
        name:
          type: string
          title: Name
          description: Mode name
          examples:
          - source
          - ml
        file_type:
          type: string
          title: File Type
          description: File type (csv or csv.gz)
          examples:
          - csv.gz
      type: object
      required:
      - name
      - file_type
      title: DataMode
      description: A data mode available for a dataset.
    DatasetListResponse:
      properties:
        objects:
          items:
            $ref: '#/components/schemas/DatasetItem'
          type: array
          title: Objects
          description: List of accessible dataset items
      type: object
      required:
      - objects
      title: DatasetListResponse
      description: Response from GET /datasets endpoint.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- a-alpha-bio-atlas-data-product-openapi-original.json
- a-alpha-bio-atlas-datasets-openapi.yml