openapi: 3.0.3
info:
  title: Figshare API (Macquarie University Research Data Repository) altmetric authors API
  description: 'Macquarie University Research Data Repository (RDR) is built on Figshare for Institutions and surfaces its public datasets, theses and research outputs through the public Figshare REST API v2. Macquarie content is discoverable via this API (DOI prefix 10.25949, Figshare group id 39392) and the public figshare.mq.edu.au discovery portal. This is the faithful upstream Figshare API v2 OpenAPI 3.0.3 description (saved unmodified except for this contextual note).


    Figshare API v2 - Full REST API documentation for managing articles, collections, projects and more.'
  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
tags:
- name: authors
paths:
  /account/authors/search:
    post:
      tags:
      - authors
      summary: Search Authors
      description: Search for authors
      operationId: private_authors_search
      requestBody:
        description: Search Parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateAuthorsSearch'
        required: false
      responses:
        '200':
          description: OK. An array of authors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthorComplete'
        '400':
          description: Bad Request
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
      x-codegen-request-body-name: search
  /account/authors/{author_id}:
    get:
      tags:
      - authors
      summary: Author details
      description: View author details
      operationId: private_author_details
      parameters:
      - name: author_id
        in: path
        description: Author unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Article representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorComplete'
        '400':
          description: Bad Request
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
components:
  schemas:
    AuthorComplete:
      required:
      - first_name
      - group_id
      - institution_id
      - is_public
      - job_title
      - last_name
      properties:
        institution_id:
          type: integer
          description: Institution id
        group_id:
          type: integer
          description: Group id
        first_name:
          type: string
          description: First Name
        last_name:
          type: string
          description: Last Name
        is_public:
          type: integer
          description: if 1 then the author has published items
        job_title:
          type: string
          description: Job title
      allOf:
      - $ref: '#/components/schemas/Author'
      x-tag: authors
    PrivateAuthorsSearch:
      type: object
      properties:
        search_for:
          type: string
          description: Search term
          example: figshare
        page:
          maximum: 5000
          minimum: 1
          type: integer
          description: Page number. Used for pagination with page_size
          example: 1
        page_size:
          maximum: 1000
          minimum: 1
          type: integer
          description: The number of results included on a page. Used for pagination with page
          example: 10
          default: 10
        limit:
          maximum: 1000
          minimum: 1
          type: integer
          description: Number of results included on a page. Used for pagination with query
          example: 10
        offset:
          maximum: 5000
          minimum: 0
          type: integer
          description: Where to start the listing (the offset of the first result). Used for pagination with limit
          example: 0
        institution_id:
          minimum: 0
          type: integer
          description: Return only authors associated to this institution
          example: 1
        orcid:
          type: string
          description: Orcid of author
        group_id:
          minimum: 0
          type: integer
          description: Return only authors in this group or subgroups of the group
        is_active:
          type: boolean
          description: Return only active authors if True
        is_public:
          type: boolean
          description: Return only authors that have published items if True
      x-tag: authors
    Author:
      required:
      - first_name
      - full_name
      - id
      - is_active
      - last_name
      - orcid_id
      - url_name
      type: object
      properties:
        id:
          type: integer
          description: Author id
          example: 97657
        full_name:
          type: string
          description: Author full name
          example: John Doe
        first_name:
          type: string
          description: Author first name
          example: John
        last_name:
          type: string
          description: Author last name
          example: Doe
        is_active:
          type: boolean
          description: True if author has published items
          example: false
        url_name:
          type: string
          description: Author url name
          example: John_Doe
        orcid_id:
          type: string
          description: Author Orcid
          example: 1234-5678-9123-1234
      x-tag: authors
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          description: A machine friendly error code, used by the dev team to identify the error.
        message:
          type: string
          description: A human friendly message explaining the error.
      x-tag: common
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://figshare.com/account/applications/authorize
          tokenUrl: https://api.figshare.com/v2/token
          scopes:
            all: Grants all access
x-additional-descriptions:
- title: Upload files
  position: bottom
  subsections:
  - title: Steps to upload file
    content: description_upload_steps
  - title: Uploads API
    content: description_upload_api
  - title: Parts API
    content: description_upload_parts_api
  - title: Example Upload on figshare
    content: description_upload_example
  - title: Output of Script
    content: description_upload_output
  - title: Upload Bash Script
    content: description_upload_bash
  - title: Upload S3 File to Figshare
    content: description_upload_from_s3
- title: Search
  position: bottom
  subsections:
  - title: How to find data on figshare
    content: description_search_intro
  - title: Search operators
    content: description_search_operators
  - title: Searchable attributes
    content: description_search_attributes
  - title: Quick search
    content: description_search_quick
  - title: Advanced search
    content: description_search_advanced
  - title: Combined field search
    content: description_search_combined
  - title: Complex searches
    content: description_search_complex
- title: Stats
  position: bottom
  subsections:
  - title: Stats service
    subsections:
    - title: Intro
      content: description_stats_service_intro
    - title: Authentication
      content: description_stats_service_auth
    - title: Errors
      content: description_stats_service_errors
    - title: Endpoints
      content: description_stats_service_endpoints
  - title: Breakdown
    subsections:
    - title: Endpoints for retrieving a breakdown
      content: description_stats_breakdown_endpoints
    - title: Authorization
      content: description_stats_breakdown_auth
    - title: Endpoint format
      content: description_stats_breakdown_format
    - title: Request parameters
      content: description_stats_breakdown_params
    - title: Examples
      content: description_stats_breakdown_examples
  - title: Timeline
    subsections:
    - title: Endpoints for retrieving a timeline
      content: description_stats_timeline_endpoints
    - title: Authorization
      content: description_stats_timeline_auth
    - title: Endpoint format
      content: description_stats_timeline_format
    - title: Request parameters
      content: description_stats_timeline_params
    - title: Examples
      content: description_stats_timeline_examples
  - title: Tops
    subsections:
    - title: Endpoints for retrieving tops
      content: description_stats_tops_endpoints
    - title: Authorization
      content: description_stats_tops_auth
    - title: Endpoint format
      content: description_stats_tops_format
    - title: Request parameters
      content: description_stats_tops_params
    - title: Examples
      content: description_stats_tops_examples
  - title: Totals
    subsections:
    - title: Endpoints for retrieving totals
      content: description_stats_totals_endpoints
    - title: Authorization
      content: description_stats_totals_auth
    - title: Endpoint format
      content: description_stats_totals_format
    - title: Examples
      content: description_stats_totals_examples
  - title: Count Articles
    subsections:
    - title: Endpoint for retrieving counts
      content: description_stats_count_endpoints
    - title: Authorization
      content: description_stats_count_auth
    - title: Endpoint format
      content: description_stats_count_format
    - title: Example
      content: description_stats_count_examples
- title: OAI PMH
  position: bottom
  subsections:
  - title: OAI-PMH
    content: description_oai_pmh
  - title: Base URL
    content: description_oai_baseurl
  - title: Item equals Article
    content: description_oai_itemarticle
  - title: Metadata formats
    content: description_oai_metadata
  - title: Datestamps
    content: description_oai_datestamp
  - title: Sets
    content: description_oai_sets
  - title: Update schedule
    content: description_oai_update_schedule
  - title: Pagination and Resumption Token Expiration
    content: description_oai_pagination
  - title: Rate limit
    content: description_oai_ratelimit
  - title: Future development
    content: description_oai_futuredev
  - title: Some examples
    content: description_oai_someexamples
- title: HR Feed
  position: bottom
  subsections:
  - title: HR Feed Private Endpoint
    content: description_hrfeed_endpoint
  - title: HR Feed examples
    subsections:
    - title: Python
      content: description_hrfeed_examples_python
    - title: Java
      content: description_hrfeed_examples_java
    - title: C Sharp
      content: description_hrfeed_examples_csharp
    - title: Curl
      content: description_hrfeed_examples_curl
  - title: Response
    content: description_hrfeed_response
  - title: Errors
    content: description_hrfeed_errors
  - title: Notes
    content: description_hrfeed_notes
- title: Custom Fields
  position: bottom
  subsections:
  - title: Custom Fields Private Endpoints
    content: description_custom_fields_endpoint
  - title: Custom Fields examples
    subsections:
    - title: Python
      content: description_custom_fields_examples_python
    - title: Java
      content: description_custom_fields_examples_java
    - title: C Sharp
      content: description_custom_fields_examples_csharp
    - title: Curl
      content: description_custom_fields_examples_curl
  - title: Response
    content: description_custom_fields_response
  - title: Errors
    content: description_custom_fields_errors
  - title: Notes
    content: description_custom_fields_notes
- title: figshare Documentation
  position: top
  subsections:
  - title: figshare Documentation
    content: description_intro
  - title: OAuth
    subsections:
    - title: Intro
      content: description_oauth_intro
    - title: Quick guide
      content: description_oauth_quick
    - title: Scope
      content: description_oauth_scope
    - title: Grant Types
      content: description_oauth_grant
  - title: API description
    subsections:
    - title: Feature list
      content: description_api_features
    - title: Sending parameters
      content: description_api_parameters
    - title: Resource representations
      content: description_api_resourcerepresentation
    - title: Authentication
      content: description_api_auth
    - title: Errors
      content: description_api_errors
    - title: Searching filtering and pagination
      content: description_api_search
    - title: Rate limiting
      content: description_api_ratelimit
    - title: Conditional requests
      content: description_api_requests
    - title: CORS policy
      content: description_api_cors
    - title: Impersonation
      content: description_api_impersonation
x-original-swagger-version: '2.0'