openapi: 3.2.0
info:
  title: 4TU.ResearchData Datasets API
  version: v2+v3
  summary: Public read API for the 4TU.ResearchData repository operated by TU Delft Library.
  description: 'Public, unauthenticated read interface to the 4TU.ResearchData repository at https://data.4tu.nl, the science/engineering/design research data repository of the 4TU.Federation. The service runs on `djehuty`, open-source repository software written by 4TU.ResearchData and Nikhef — it is NOT a Figshare, Elsevier Pure, Dataverse or DSpace tenancy. The `/v2` surface is deliberately backward compatible with the Figshare v2 API shape (differences: `uuid` supersedes `id`, and usage errors return precise HTTP codes rather than always 400); `/v3` is djehuty''s own surface. Endpoints under `/v2/account/` and parts of `/v3` require a personal API token.

    OPERATOR NOTE: data.4tu.nl resolves to 131.180.169.22, inside the RIPE `DUNET` inetnum registered to Technische Universiteit Delft, and re3data records TU Delft Library as the hosting institution for the 4TU.Federation consortium (with TU Eindhoven, University of Twente and Wageningen University as the other partners). It is therefore institution-operated infrastructure that is co-owned by a four-university consortium, not a vendor platform.'
  contact:
    name: 4TU.ResearchData
    email: researchdata@4tu.nl
    url: https://data.4tu.nl/info/about-4turesearchdata/contact
  license:
    name: EUPL-1.2 (djehuty software)
    url: https://github.com/4TUResearchData/djehuty/blob/main/LICENSE
  termsOfService: https://data.4tu.nl/info/about-4turesearchdata/policies-guidelines
servers:
- url: https://data.4tu.nl
  description: 4TU.ResearchData production (TU Delft Library operated)
tags:
- name: Datasets
  description: Published datasets (called "articles" on the Figshare-compatible v2 surface).
paths:
  /v2/articles:
    get:
      tags:
      - Datasets
      operationId: listArticles
      summary: List published datasets
      description: Returns a page of publicly published datasets, newest first by default.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: order
        in: query
        required: false
        schema:
          type: string
          examples:
          - published_date
      - name: order_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: institution
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A list of dataset summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatasetSummary'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/articles/search:
    post:
      tags:
      - Datasets
      operationId: searchArticles
      summary: Search published datasets
      description: 'Full-text and faceted search over published datasets. A GET against this path returns 405 with the body `Acceptable methods: [''POST'']`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                search_for:
                  type: string
                limit:
                  type: integer
                offset:
                  type: integer
                order:
                  type: string
                order_direction:
                  type: string
                  enum:
                  - asc
                  - desc
      responses:
        '200':
          description: Matching dataset summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatasetSummary'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
  /v2/articles/{uuid}:
    get:
      tags:
      - Datasets
      operationId: getArticle
      summary: Get one published dataset
      parameters:
      - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The full dataset record, including files, authors, funding and license.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/articles/{uuid}/files:
    get:
      tags:
      - Datasets
      operationId: listArticleFiles
      summary: List the files attached to a dataset
      parameters:
      - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: Files, with size and both supplied and computed MD5 checksums.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/articles/{uuid}/versions:
    get:
      tags:
      - Datasets
      operationId: listArticleVersions
      summary: List the published versions of a dataset
      parameters:
      - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: Version numbers with their canonical API URLs.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    version:
                      type: integer
                    url:
                      type: string
                      format: uri
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/datasets:
    get:
      tags:
      - Datasets
      operationId: listDatasets
      summary: List published datasets (djehuty v3)
      description: djehuty's own dataset listing. Same record shape as /v2/articles; note that the `url` field in each record still points back at the /v2 path.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: order
        in: query
        required: false
        schema:
          type: string
      - name: order_direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: A list of dataset summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DatasetSummary'
components:
  schemas:
    DatasetSummary:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          description: Legacy Figshare numeric id; null on djehuty-native records.
        uuid:
          type: string
          format: uuid
        title:
          type: string
        doi:
          type: string
          description: DataCite DOI under the 10.4121 prefix.
        handle:
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
        published_date:
          type:
          - string
          - 'null'
        thumb:
          type:
          - string
          - 'null'
        defined_type:
          type:
          - integer
          - 'null'
        defined_type_name:
          type:
          - string
          - 'null'
        group_id:
          type:
          - integer
          - 'null'
        url_private_api:
          type: string
          format: uri
        url_public_api:
          type: string
          format: uri
        url_private_html:
          type: string
          format: uri
        url_public_html:
          type: string
          format: uri
        timeline:
          type: object
        resource_title:
          type:
          - string
          - 'null'
        resource_doi:
          type:
          - string
          - 'null'
    File:
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
        uuid:
          type: string
          format: uuid
        name:
          type: string
        size:
          type: integer
        is_link_only:
          type: boolean
        is_incomplete:
          type: boolean
        download_url:
          type: string
          format: uri
        supplied_md5:
          type:
          - string
          - 'null'
        computed_md5:
          type:
          - string
          - 'null'
    License:
      type: object
      properties:
        value:
          type: integer
        name:
          type: string
        url:
          type: string
          format: uri
        type:
          type: string
          enum:
          - data
          - software
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    Author:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        full_name:
          type: string
        orcid_id:
          type:
          - string
          - 'null'
          description: ORCID iD, where the depositor supplied one.
        is_active:
          type: boolean
        url_name:
          type:
          - string
          - 'null'
    Category:
      type: object
      properties:
        id:
          type: integer
        uuid:
          type: string
          format: uuid
        title:
          type: string
        parent_id:
          type:
          - integer
          - 'null'
        parent_uuid:
          type:
          - string
          - 'null'
        path:
          type: string
        source_id:
          type:
          - integer
          - 'null'
        taxonomy_id:
          type:
          - integer
          - 'null'
    Dataset:
      allOf:
      - $ref: '#/components/schemas/DatasetSummary'
      - type: object
        properties:
          files:
            type: array
            items:
              $ref: '#/components/schemas/File'
          authors:
            type: array
            items:
              $ref: '#/components/schemas/Author'
          custom_fields:
            type: array
          description:
            type: string
          funding:
            type:
            - string
            - 'null'
          funding_list:
            type: array
          version:
            type: integer
          status:
            type: string
          size:
            type: integer
          created_date:
            type:
            - string
            - 'null'
          modified_date:
            type:
            - string
            - 'null'
          is_public:
            type: boolean
          is_confidential:
            type: boolean
          is_metadata_record:
            type: boolean
          license:
            $ref: '#/components/schemas/License'
          tags:
            type: array
            items:
              type: string
          categories:
            type: array
            items:
              $ref: '#/components/schemas/Category'
          references:
            type: array
            items:
              type: string
          citation:
            type: string
          is_embargoed:
            type: boolean
          embargo_date:
            type:
            - string
            - 'null'
          embargo_type:
            type:
            - string
            - 'null'
          figshare_url:
            type: string
            format: uri
  responses:
    MethodNotAllowed:
      description: The HTTP method is not permitted on this path.
      content:
        text/plain:
          schema:
            type: string
          examples:
            postOnly:
              value: 'Acceptable methods: [''POST'']'
    NotFound:
      description: The resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              value:
                message: This resource does not exist.
  parameters:
    Uuid:
      name: uuid
      in: path
      required: true
      description: The dataset or collection UUID. On this repository `uuid` supersedes the Figshare numeric `id`.
      schema:
        type: string
        format: uuid
  securitySchemes:
    tokenAuth:
      type: http
      scheme: token
      description: '`Authorization: token YOUR_TOKEN_HERE`. Tokens are issued from the depositor dashboard after logging in; there is no OAuth 2.0 flow and no published scope vocabulary.'
x-artifact:
  generated: '2026-08-19'
  method: derived
  source: Derived from live unauthenticated probes of https://data.4tu.nl on 2026-08-19 (every path, parameter, status code and field name in this document was observed in a real response), cross-read against the djehuty API documentation at https://raw.githubusercontent.com/4TUResearchData/djehuty/main/docs/api.md and https://djehuty.4tu.nl/. 4TU.ResearchData publishes no OpenAPI of its own; the djehuty repository tree contains no openapi/swagger file (checked via the GitHub trees API, 575 entries). This is API Evangelist's derivation, not a 4TU artifact.
  x-operator: institution
  x-operator-evidence: data.4tu.nl -> 131.180.169.22, RIPE inetnum 131.180.0.0/16 netname DUNET, org-name "Technische Universiteit Delft". re3data r3d100010216 lists TU Delft Library as a hosting institution alongside the 4TU.Federation.