Victoria University of Wellington Articles API

openapi: 3.0.3
info:
  title: Figshare API (Open Access Repository) Articles API
  description: Public, read-only subset of the Figshare v2 REST API, which powers the Open Access Te Herenga Waka—Victoria University of Wellington research repository. Only the public, unauthenticated endpoints and objects that the real Figshare OpenAPI description supports are included here. The full, authoritative specification is published by Figshare at https://docs.figshare.com/.
  version: '2.0'
  contact:
    name: Figshare Support
    url: https://support.figshare.com/support/home
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.figshare.com/v2
  description: Figshare public API v2
tags:
- name: Articles
paths:
  /articles:
    get:
      operationId: articles_list
      summary: List public articles
      description: Returns a paginated list of public articles. For the Victoria University of Wellington repository, results can be scoped using the institution / group filtering parameters supported by Figshare.
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
      - name: page_size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: order
        in: query
        schema:
          type: string
          enum:
          - published_date
          - modified_date
          - views
          - downloads
          - shares
          - cites
      - 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'
      tags:
      - Articles
  /articles/search:
    post:
      operationId: articles_search
      summary: Search public articles
      description: Returns a list of public articles filtered by the search parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleSearch'
      responses:
        '200':
          description: A list of public articles matching the search
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
      tags:
      - Articles
  /articles/{article_id}:
    get:
      operationId: article_details
      summary: View an article
      parameters:
      - name: article_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Full article details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleComplete'
        '404':
          description: Article not found
      tags:
      - Articles
  /articles/{article_id}/versions:
    get:
      operationId: article_versions
      summary: List article versions
      parameters:
      - name: article_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: List of versions for the article
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleVersion'
      tags:
      - Articles
  /articles/{article_id}/versions/{version_id}:
    get:
      operationId: article_version_details
      summary: View a specific article version
      parameters:
      - name: article_id
        in: path
        required: true
        schema:
          type: integer
      - name: version_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Full article details for the requested version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleComplete'
      tags:
      - Articles
  /articles/{article_id}/files:
    get:
      operationId: article_files
      summary: List files for an article
      parameters:
      - name: article_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: List of files for the article
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleFile'
      tags:
      - Articles
  /articles/{article_id}/files/{file_id}:
    get:
      operationId: article_file_details
      summary: View a single article file
      parameters:
      - name: article_id
        in: path
        required: true
        schema:
          type: integer
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: File details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleFile'
      tags:
      - Articles
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        parent_id:
          type: integer
          nullable: true
    ArticleSearch:
      type: object
      properties:
        search_for:
          type: string
        doi:
          type: string
        handle:
          type: string
        institution:
          type: integer
        group:
          type: integer
        published_since:
          type: string
          format: date
        modified_since:
          type: string
          format: date
        order:
          type: string
          enum:
          - published_date
          - modified_date
          - views
          - downloads
          - shares
          - cites
        order_direction:
          type: string
          enum:
          - asc
          - desc
        page:
          type: integer
        page_size:
          type: integer
    ArticleComplete:
      allOf:
      - $ref: '#/components/schemas/Article'
      - type: object
        description: Full article details including authors, files and categories.
        properties:
          resource_doi:
            type: string
            nullable: true
          resource_title:
            type: string
            nullable: true
          item_type:
            type: integer
          license:
            $ref: '#/components/schemas/License'
          authors:
            type: array
            items:
              $ref: '#/components/schemas/Author'
          files:
            type: array
            items:
              $ref: '#/components/schemas/ArticleFile'
          categories:
            type: array
            items:
              $ref: '#/components/schemas/Category'
          tags:
            type: array
            items:
              type: string
          references:
            type: array
            items:
              type: string
          custom_fields:
            type: object
            additionalProperties: true
    Author:
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
        is_active:
          type: boolean
        url_name:
          type: string
        orcid_id:
          type: string
          nullable: true
    Article:
      type: object
      description: Public article listing entry.
      properties:
        id:
          type: integer
        title:
          type: string
        doi:
          type: string
        handle:
          type: string
        url:
          type: string
          format: uri
        published_date:
          type: string
          format: date-time
          nullable: true
        modified_date:
          type: string
          format: date-time
          nullable: true
        created_date:
          type: string
          format: date-time
          nullable: true
        description:
          type: string
        is_public:
          type: boolean
        views:
          type: integer
        downloads:
          type: integer
        shares:
          type: integer
        cites:
          type: integer
        size:
          type: integer
          format: int64
        version:
          type: integer
    License:
      type: object
      properties:
        value:
          type: integer
        name:
          type: string
        url:
          type: string
          format: uri
    ArticleVersion:
      type: object
      properties:
        version:
          type: integer
        url:
          type: string
          format: uri
    ArticleFile:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        size:
          type: integer
          format: int64
        computed_md5:
          type: string
          nullable: true
        download_url:
          type: string
          format: uri
        is_link_only:
          type: boolean