openapi: 3.0.3
info:
  title: DataFirst Microdata Catalog API (NADA) articles API
  description: DataFirst is a University of Cape Town research unit and data service providing online access to survey and administrative microdata from South Africa and other African countries. Its open data portal is built on the NADA (National Data Archive) cataloging tool, which exposes a public, unauthenticated REST/JSON API for browsing the catalog of studies. This OpenAPI description was reverse-engineered from confirmed live responses of the public catalog endpoint (verified returning survey metadata in JSON). Only paths and response fields actually observed in live responses are documented here.
  version: '1.0'
  contact:
    name: DataFirst
    url: https://www.datafirst.uct.ac.za/
servers:
- url: https://www.datafirst.uct.ac.za/dataportal/index.php/api
  description: DataFirst NADA public catalog API
tags:
- name: articles
  description: Public articles (research outputs / datasets)
paths:
  /articles:
    get:
      tags:
      - articles
      summary: List public articles
      description: Returns a list of public articles, optionally filtered and paginated.
      operationId: listArticles
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - name: institution
        in: query
        description: Only return articles belonging to this institution id.
        schema:
          type: integer
      - name: order
        in: query
        description: Field used to order results.
        schema:
          type: string
          enum:
          - published_date
          - modified_date
          - views
          - cites
          - shares
      - name: order_direction
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: A list of public articles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '400':
          $ref: '#/components/responses/BadRequest'
  /articles/search:
    post:
      tags:
      - articles
      summary: Search public articles
      description: Search public articles using a structured search body. Supports full-text search, DOI/handle lookups, institution and group filters.
      operationId: searchArticles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleSearch'
      responses:
        '200':
          description: A list of matching public articles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '400':
          $ref: '#/components/responses/BadRequest'
  /articles/{article_id}:
    get:
      tags:
      - articles
      summary: Get a public article
      description: Returns the complete public representation of a single article.
      operationId: getArticle
      parameters:
      - name: article_id
        in: path
        required: true
        description: Unique identifier of the article.
        schema:
          type: integer
      responses:
        '200':
          description: The requested article.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleComplete'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ArticleComplete:
      type: object
      description: Complete public representation of an article.
      allOf:
      - $ref: '#/components/schemas/Article'
      - type: object
        properties:
          figshare_url:
            type: string
            format: uri
          description:
            type: string
            description: HTML description of the article.
          download_disabled:
            type: boolean
          files:
            type: array
            description: List of up to 10 article files.
            items:
              $ref: '#/components/schemas/PublicFile'
          folder_structure:
            type: object
            additionalProperties:
              type: string
            description: Mapping of file ids to folder paths, if folders are used.
          authors:
            type: array
            items:
              $ref: '#/components/schemas/Author'
          custom_fields:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                value: {}
          tags:
            type: array
            items:
              type: string
          categories:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                title:
                  type: string
          license:
            type: object
            properties:
              value:
                type: integer
              name:
                type: string
              url:
                type: string
                format: uri
    PublicFile:
      type: object
      properties:
        id:
          type: integer
          example: 65270877
        name:
          type: string
          example: dataset.csv
        size:
          type: integer
          example: 17091
        is_link_only:
          type: boolean
        download_url:
          type: string
          format: uri
          example: https://ndownloader.figshare.com/files/65270877
        supplied_md5:
          type: string
        computed_md5:
          type: string
        mimetype:
          type: string
          example: text/csv
    Article:
      type: object
      required:
      - id
      - title
      - doi
      - url
      - timeline
      - defined_type
      - defined_type_name
      properties:
        id:
          type: integer
          description: Unique identifier for article.
          example: 32573085
        title:
          type: string
          description: Title of article.
        doi:
          type: string
          description: DOI of the article.
          example: 10.6084/m9.figshare.32573085.v1
        handle:
          type: string
          description: Handle of the article.
        url:
          type: string
          format: uri
          description: API endpoint for the article.
          example: https://api.figshare.com/v2/articles/32573085
        published_date:
          type: string
          description: Date the article was published.
          example: '2026-06-04T02:59:32Z'
        thumb:
          type: string
          format: uri
          description: Thumbnail image URL.
        defined_type:
          type: integer
          description: Numeric item type identifier.
          example: 3
        defined_type_name:
          type: string
          description: Human-readable item type.
          example: dataset
        group_id:
          type: integer
        url_public_api:
          type: string
          format: uri
        url_public_html:
          type: string
          format: uri
        timeline:
          $ref: '#/components/schemas/Timeline'
        resource_title:
          type: string
        resource_doi:
          type: string
        created_date:
          type: string
          example: '2026-06-04T02:59:32Z'
        modified_date:
          type: string
          example: '2026-06-04T02:59:32Z'
    Timeline:
      type: object
      description: Publishing timeline for an item.
      properties:
        posted:
          type: string
          description: Date the item was posted.
          example: '2026-06-04T02:59:32'
        firstOnline:
          type: string
          description: Date the item first went online.
        revision:
          type: string
          description: Date of the last revision.
    Author:
      type: object
      properties:
        id:
          type: integer
          example: 24130866
        full_name:
          type: string
          example: Jane Researcher
        first_name:
          type: string
        last_name:
          type: string
        is_active:
          type: boolean
        url_name:
          type: string
        orcid_id:
          type: string
          example: 0000-0002-1825-0097
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
    ArticleSearch:
      type: object
      description: Structured search body for public articles.
      properties:
        search_for:
          type: string
          description: Full-text search string.
          example: malaria south africa
        resource_doi:
          type: string
          description: Only return articles with this resource_doi.
        doi:
          type: string
          description: Only return articles with this doi.
        handle:
          type: string
        project_id:
          type: integer
        item_type:
          type: integer
          description: 'Only return articles of this type. Mapping: 1 Figure, 2 Media, 3 Dataset, 5 Poster, 6 Journal contribution, 7 Presentation, 8 Thesis, 9 Software, 11 Online resource, 12 Preprint, 13 Book, 14 Conference contribution, 15 Chapter, 17 Educational resource, 18 Report, 19 Standard, 23 Data management plan, 24 Workflow.'
        institution:
          type: integer
        group:
          type: integer
        published_since:
          type: string
        modified_since:
          type: string
        order:
          type: string
          enum:
          - published_date
          - modified_date
          - views
          - cites
          - shares
        order_direction:
          type: string
          enum:
          - asc
          - desc
        page:
          type: integer
        page_size:
          type: integer
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  parameters:
    pageSize:
      name: page_size
      in: query
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
    page:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
    offset:
      name: offset
      in: query
      description: Number of results to skip.
      schema:
        type: integer
        minimum: 0
    limit:
      name: limit
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000