openapi: 3.0.3
info:
title: La Trobe University OPAL (Figshare) Public articles API
description: Public, machine-readable retrieval surface for La Trobe University's open-access repository, OPAL (Open @ La Trobe), which is hosted on the Figshare platform and served by the Figshare REST API v2. La Trobe records are institution-scoped (institution id 234). This document is a faithful subset of the upstream Figshare API 2.0 OpenAPI description (https://docs.figshare.com/swagger.json), limited to the public, unauthenticated article and collection retrieval/search/files/versions endpoints used to harvest OPAL content. No private/account or write operations are included.
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 API v2 (serves La Trobe OPAL records, institution=234)
tags:
- name: articles
paths:
/articles:
get:
tags:
- articles
summary: Public Articles
description: Returns a list of public articles
operationId: articles_list
parameters:
- name: X-Cursor
in: header
description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter, please note that the offset parameter will not be available, but the limit parameter will still work as expected.
schema:
type: string
- name: page
in: query
description: Page number. Used for pagination with page_size
schema:
maximum: 5000
minimum: 1
type: integer
- name: page_size
in: query
description: The number of results included on a page. Used for pagination with page
schema:
maximum: 1000
minimum: 1
type: integer
default: 10
- name: limit
in: query
description: Number of results included on a page. Used for pagination with query
schema:
maximum: 1000
minimum: 1
type: integer
- name: offset
in: query
description: Where to start the listing (the offset of the first result). Used for pagination with limit
schema:
maximum: 5000
minimum: 0
type: integer
- name: order
in: query
description: The field by which to order. Default varies by endpoint/resource.
schema:
type: string
default: published_date
enum:
- published_date
- created_date
- modified_date
- views
- shares
- downloads
- cites
- name: order_direction
in: query
schema:
type: string
default: desc
enum:
- asc
- desc
- name: institution
in: query
description: only return articles from this institution
schema:
type: integer
- name: published_since
in: query
description: Filter by article publishing date. Will only return articles published after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
schema:
type: string
- name: modified_since
in: query
description: Filter by article modified date. Will only return articles modified after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
schema:
type: string
- name: group
in: query
description: only return articles from this group
schema:
type: integer
- name: resource_doi
in: query
description: Deprecated by related materials. Only return articles with this resource_doi
schema:
type: string
- name: item_type
in: query
description: 'Only return articles with the respective type. Mapping for item_type is: 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, 16 - Peer review, 17 - Educational resource, 18 - Report, 19 - Standard, 20 - Composition, 21 - Funding, 22 - Physical object, 23 - Data management plan, 24 - Workflow, 25 - Monograph, 26 - Performance, 27 - Event, 28 - Service, 29 - Model'
schema:
type: integer
- name: doi
in: query
description: only return articles with this doi
schema:
type: string
- name: handle
in: query
description: only return articles with this handle
schema:
type: string
responses:
'200':
description: OK. An array of articles
headers:
X-Cursor:
description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
'400':
description: Bad Request
content: {}
'422':
description: Unprocessable Entity. Syntax is correct but one of the parameters isn't correctly processed
content: {}
'500':
description: Internal Server Error
content: {}
security: []
/articles/search:
post:
tags:
- articles
summary: Public Articles Search
description: Returns a list of public articles, filtered by the search parameters
operationId: articles_search
parameters:
- name: X-Cursor
in: header
description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter, please note that the offset parameter will not be available, but the limit parameter will still work as expected.
schema:
type: string
requestBody:
description: Search Parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleSearch'
required: false
responses:
'200':
description: OK. An array of articles
headers:
X-Cursor:
description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
schema:
type: string
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArticleWithProject'
'400':
description: Bad Request
content: {}
'422':
description: Unprocessable Entity. Syntax is correct but one of the parameters isn't correctly processed
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-codegen-request-body-name: search
/articles/{article_id}:
get:
tags:
- articles
summary: View article details
description: View an article
operationId: article_details
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Article representation
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleComplete'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article
/articles/{article_id}/files:
get:
tags:
- articles
summary: List article files
description: Files list for article
operationId: article_files
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
- name: page
in: query
description: Page number. Used for pagination with page_size
schema:
maximum: 5000
minimum: 1
type: integer
- name: page_size
in: query
description: The number of results included on a page. Used for pagination with page
schema:
maximum: 1000
minimum: 1
type: integer
default: 10
- name: limit
in: query
description: Number of results included on a page. Used for pagination with query
schema:
maximum: 1000
minimum: 1
type: integer
- name: offset
in: query
description: Where to start the listing (the offset of the first result). Used for pagination with limit
schema:
maximum: 5000
minimum: 0
type: integer
responses:
'200':
description: OK. List of article files
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicFile'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article files
/articles/{article_id}/files/{file_id}:
get:
tags:
- articles
summary: Article file details
description: File by id
operationId: article_file_details
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
- name: file_id
in: path
description: File Unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. File representation
content:
application/json:
schema:
$ref: '#/components/schemas/PublicFile'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article files
/articles/{article_id}/versions:
get:
tags:
- articles
summary: List article versions
description: List public article versions
operationId: article_versions
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Article version representations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArticleVersions'
'400':
description: Bad Request. Article ID must be an integer and bigger than 0.
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article
/articles/{article_id}/versions/{version_id}:
get:
tags:
- articles
summary: Article details for version
description: Article with specified version
operationId: article_version_details
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
- name: version_id
in: path
description: Article Version Number
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Article representation
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleComplete'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article
components:
schemas:
CommonSearch:
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
order_direction:
type: string
description: Direction of ordering
example: desc
default: desc
enum:
- asc
- desc
institution:
type: integer
description: only return collections from this institution
example: 2000013
published_since:
type: string
description: Filter by article publishing date. Will only return articles published after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
example: '2017-12-22'
modified_since:
type: string
description: Filter by article modified date. Will only return articles modified after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
example: '2017-12-22'
group:
type: integer
description: only return collections from this group
example: 2000013
x-tag: common
FundingInformation:
required:
- funder_name
- grant_code
- id
- is_user_defined
- title
- url
type: object
properties:
id:
type: integer
description: Funding id
example: 1
title:
type: string
description: The funding name
example: Scholarly funding
grant_code:
type: string
description: The grant code
funder_name:
type: string
description: Funder's name
is_user_defined:
type: integer
description: Return 1 whether the grant has been introduced manually, 0 otherwise
url:
type: string
description: The grant url
format: url
example: https://app.dimensions.ai/details/grant/1
x-tag: funding
Timeline:
allOf:
- $ref: '#/components/schemas/TimelineUpdate'
x-tag: timeline
PublicFile:
required:
- computed_md5
- download_url
- id
- is_link_only
- name
- size
- supplied_md5
type: object
properties:
id:
type: integer
description: File id
example: 3000002
name:
type: string
description: File name
example: test.xls
size:
type: integer
description: File size
example: 14848
is_link_only:
type: boolean
description: True if file is hosted somewhere else
example: false
download_url:
type: string
description: Url for file download
format: url
example: https://ndownloader.figshare.com/files/3000002
supplied_md5:
type: string
description: File supplied md5
example: 043a51806d646e88cafbf19e7b82846f
computed_md5:
type: string
description: File computed md5
example: 043a51806d646e88cafbf19e7b82846f
mimetype:
type: string
description: MIME Type of the file, it defaults to an empty string
example: application/pdf
x-tag: common
ArticleSearch:
properties:
resource_doi:
type: string
description: Only return articles with this resource_doi
example: 10.6084/m9.figshare.1407024
item_type:
type: integer
description: 'Only return articles with the respective type. Mapping for item_type is: 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, 16 - Peer review, 17 - Educational resource, 18 - Report, 19 - Standard, 20 - Composition, 21 - Funding, 22 - Physical object, 23 - Data management plan, 24 - Workflow, 25 - Monograph, 26 - Performance, 27 - Event, 28 - Service, 29 - Model'
example: 1
doi:
type: string
description: Only return articles with this doi
example: 10.6084/m9.figshare.1407024
handle:
type: string
description: Only return articles with this handle
example: 111084/m9.figshare.14074
project_id:
type: integer
description: Only return articles in this project
example: 1
order:
type: string
description: The field by which to order
example: published_date
default: created_date
enum:
- created_date
- published_date
- modified_date
- views
- shares
- downloads
- cites
allOf:
- $ref: '#/components/schemas/CommonSearch'
x-tag: articles
CustomArticleField:
required:
- field_type
- is_mandatory
- name
- order
- settings
- value
type: object
properties:
name:
type: string
description: Custom metadata name
example: key
value:
type: object
description: Custom metadata value (can be either a string or an array of strings)
example: value
field_type:
type: string
description: Custom field type
example: textarea
enum:
- text
- textarea
- dropdown
- url
- email
- date
- dropdown_large_list
settings:
type: object
properties: {}
description: Settings for the custom field
example:
validations:
min_length: 1
max_length: 1000
placeholder: Enter your custom field here
order:
type: integer
description: Order of the custom field
example: 1
is_mandatory:
type: boolean
description: Whether the field is mandatory or not
example: false
x-tag: articles
License:
required:
- name
- url
- value
type: object
properties:
value:
type: integer
description: License value
example: 1
name:
type: string
description: License name
example: CC BY
url:
type: string
description: License url
format: url
example: http://creativecommons.org/licenses/by/4.0/
x-tag: institutions
ArticleComplete:
required:
- authors
- custom_fields
- download_disabled
- embargo_options
- figshare_url
- files
- folder_structure
properties:
figshare_url:
type: string
description: Article public url
format: url
example: http://figshare.com/articles/media/article_name/2000005
download_disabled:
type: boolean
description: If true, downloading of files for this article is disabled
example: false
files:
type: array
description: List of up to 10 article files.
items:
$ref: '#/components/schemas/PublicFile'
folder_structure:
type: object
properties: {}
description: Mapping of file ids to folder paths, if folders are used
example:
'3000002': Test Folder
authors:
type: array
description: List of article authors
items:
$ref: '#/components/schemas/Author'
custom_fields:
type: array
description: List of custom fields values
items:
$ref: '#/components/schemas/CustomArticleField'
embargo_options:
type: array
description: List of embargo options
items:
$ref: '#/components/schemas/GroupEmbargoOptions'
allOf:
- $ref: '#/components/schemas/ProjectArticle'
x-tag: articles
ArticleVersions:
required:
- url
- version
type: object
properties:
version:
type: integer
description: Version number
example: 1
url:
type: string
description: Api endpoint for the item version
format: url
example: https://api.figshare.com/v2/articles/2000005/versions/1
x-tag: articles
ProjectArticle:
required:
- categories
- citation
- confidential_reason
- created_date
- description
- embargo_reason
- embargo_title
- funding
- funding_list
- has_linked_file
- is_confidential
- is_embargoed
- is_metadata_record
- is_public
- keywords
- license
- metadata_reason
- references
- size
- status
- tags
- version
properties:
citation:
type: string
description: Article citation
example: "lilliput, figshare admin (2017): first project item. figshare.\n \n Retrieved: 14 01, May 22, 2017 (GMT)"
confidential_reason:
type: string
description: Confidentiality reason
example: none
is_confidential:
type: boolean
description: Article Confidentiality
example: true
size:
type: integer
description: Article size
example: 69939
funding:
type: string
description: Article funding
example: none
funding_list:
type: array
description: Full Article funding information
items:
$ref: '#/components/schemas/FundingInformation'
tags:
type: array
description: List of article tags. Keywords can be used instead
example:
- t1
- t2
- t3
items:
type: string
keywords:
type: array
description: List of article keywords. Tags can be used instead
example:
- t1
- t2
- t3
items:
type: string
version:
type: integer
description: Article version
example: 1
is_metadata_record:
type: boolean
description: True if article has no files
example: false
metadata_reason:
type: string
description: Article metadata reason
example: hosted somewhere else
status:
type: string
description: Article status
example: public
description:
type: string
description: Article description
example: article description
is_embargoed:
type: boolean
description: True if article is embargoed
example: true
is_public:
type: boolean
description: True if article is published
example: true
created_date:
type: string
description: Date when article was created
example: '2017-05-18T11:49:03Z'
has_linked_file:
type: boolean
description: True if any files are linked to the article
example: true
categories:
type: array
description: List of categories selected for the article
items:
$ref: '#/components/schemas/Category'
license:
$ref: '#/components/schemas/License'
embargo_title:
type: string
description: Title for embargo
example: File(s) under embargo
embargo_reason:
type: string
description: Reason for embargo
example: not complete
references:
type: array
description: List of references
example:
- http://figshare.com
- http://figshare.com/api
items:
type: string
format: url
related_materials:
type: array
description: List of related materials; supersedes references and resource DOI/title.
example:
- id: 10432
identifier: 10.6084/m9.figshare.1407024
identifier_type: DOI
relation: IsSupplementTo
title: Figshare for institutions brochure
is_linkout: false
items:
$ref: '#/components/schemas/RelatedMaterial'
allOf:
- $ref: '#/components/schemas/Article'
x-tag: articles
Category:
required:
- id
- parent_id
- path
- source_id
- taxonomy_id
- title
type: object
properties:
parent_id:
type: integer
description: Parent category
example: 1
id:
type: integer
description: Category id
example: 11
title:
type: string
description: Category title
example: Anatomy
path:
type: string
description: Path to all ancestor ids
example: /450/1024/6532
source_id:
type: string
description: ID in original standard taxonomy
example: '300204'
taxonomy_id:
type: integer
description: Internal id of taxonomy the category is part of
example: 4
x-tag: common
RelatedMaterial:
type: object
properties:
id:
type: integer
description: The ID of the related material; can be used to add existing materials of the same account to items.
example: 10432
identifier:
type: string
description: The related material identifier (e.g., DOI, Handle, ISBN). Mandatory if creating a new material.
example: 10.6084/m9.figshare.1407024
title:
type: string
description: The related material title
example: 'Rooter: A Methodology for the Typical Unification of Access Points and Redundancy'
relation:
type: string
description: The relation between the item and the related material; defaults to 'References'. Mandatory if creating a new material.
example: IsSupplementTo
default: References
enum:
- IsCitedBy
- Cites
- IsSupplementTo
- IsSupplementedBy
- IsContinuedBy
- Continues
- Describes
- IsDescribedBy
- HasMetadata
- IsMetadataFor
- HasVersion
- IsVersionOf
- IsNewVersionOf
- IsPreviousVersionOf
- IsPartOf
- HasPart
- IsPublishedIn
- IsReferencedBy
- References
- IsDocumentedBy
- Documents
- IsCompiledBy
- Compiles
- IsVariantFormOf
- IsOriginalFormOf
- IsIdenticalTo
- IsReviewedBy
- Reviews
- IsDerivedFrom
- IsSourceOf
- IsRequiredBy
- Requires
- IsObsoletedBy
- Obsoletes
identifier_type:
type: string
description: The type of the identifier of the related material; defaults to 'URL'. Mandatory if creating a new material.
example: DOI
default: URL
enum:
- ARK
- arXiv
- bibcode
- DOI
- EAN13
- EISSN
- Handle
- IGSN
- ISBN
- ISSN
- ISTC
- LISSN
- LSID
- PMID
- PURL
- UPC
- URL
- URN
- w3id
is_linkout:
type: boolean
description: Flag for highlighting this related material in the call-out box
example: true
link:
type: string
description: The full hyperlink for the identifier. Automatically generated by Figshare.
readOnly: true
example: https://doi.org/10.6084/m9.figshare.1407024
Article:
required:
- created_date
- defined_type
- defined_type_name
- doi
- handle
- id
- resource_doi
- resource_title
- thumb
- timeline
- title
- url
- url_private_api
- url_private_html
- url_public_api
- url_public_html
type: object
properties:
id:
type: integer
description: Unique identifier for article
example: 1434614
title:
type: string
description: Title of article
example: Test article title
doi:
type: string
description: DOI
example: 10.6084/m9.figshare.1434614
handle:
type: string
description: Handle
example: 111184/figshare.1234
url:
type: string
description: Api endpoint for article
format: url
example: http://api.figshare.com/articles/1434614
url_public_html:
type: string
description: Public site endpoint for article
format: url
example: https://figshare.com/articles/media/Test_article_title/1434614
url_public_api:
type: string
description: Public Api endpoint for article
format: url
example: https://api.figshare.com/articles/1434614
url_private_html:
type: string
description: Private site endpoint for article
format: url
example: https://figshare.com/account/articles/1434614
url_private_api:
type: string
description: Private Api endpoint for article
format: url
example: https://api.figshare.com/account/articles/1434614
timeline:
$ref: '#/components/schemas/Timeline'
thumb:
type: string
description: Thumbnail image
format: url
example: https://ndownloader.figshare.com/files/123456789/preview/12345678/thumb.png
defined_type:
type: integer
description: Type of article identifier
example: 3
defined_type_name:
type: string
description: Name of the article type identifier
example: media
resource_doi:
type: string
description: Deprecated by related materials. Not applicable to regular users. In a publisher case, this is the publisher article DOI.
default: ''
resource_title:
type: string
description: Deprecated by related materials. Not applicable to regular users. In a publisher case, this is the p
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/la-trobe-university/refs/heads/main/openapi/la-trobe-university-articles-api-openapi.yml