openapi: 3.0.3
info:
title: La Trobe University OPAL (Figshare) Public 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)
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
/collections:
get:
tags:
- collections
summary: Public Collections
description: Returns a list of public collections
operationId: collections_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
- cites
- name: order_direction
in: query
schema:
type: string
default: desc
enum:
- asc
- desc
- name: institution
in: query
description: only return collections from this institution
schema:
type: integer
- name: published_since
in: query
description: Filter by collection publishing date. Will only return collections published after
the date. date(ISO 8601) YYYY-MM-DD
schema:
type: string
- name: modified_since
in: query
description: Filter by collection modified date. Will only return collections modified after the
date. date(ISO 8601) YYYY-MM-DD
schema:
type: string
- name: group
in: query
description: only return collections from this group
schema:
type: integer
- name: resource_doi
in: query
description: only return collections with this resource_doi
schema:
type: string
- name: doi
in: query
description: only return collections with this doi
schema:
type: string
- name: handle
in: query
description: only return collections with this handle
schema:
type: string
responses:
'200':
description: OK. An array of collections
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/Collection'
'400':
description: Bad Request
content: {}
'422':
description: Bad Request
content: {}
'500':
description: Internal Server Error
content: {}
security: []
/collections/search:
post:
tags:
- collections
summary: Public Collections Search
description: Returns a list of public collections
operationId: collections_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/CollectionSearch'
required: false
responses:
'200':
description: OK. An array of collections
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/Collection'
'400':
description: Bad Request
content: {}
'422':
description: Bad Request
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-codegen-request-body-name: search
/collections/{collection_id}:
get:
tags:
- collections
summary: Collection details
description: View a collection
operationId: collection_details
parameters:
- name: collection_id
in: path
description: Collection Unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Collection representation
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionComplete'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Collection
/collections/{collection_id}/articles:
get:
tags:
- collections
summary: Public Collection Articles
description: Returns a list of public collection articles
operationId: collection_articles
parameters:
- name: collection_id
in: path
description: Collection 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. An array of articles belonging to the collection
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'422':
description: Bad Request
content: {}
'500':
description: Internal Server Error
content: {}
security: []
components:
schemas:
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 publisher article title.
default: ''
created_date:
type: string
description: Date when article was created
example: '2017-05-18T11:49:03Z'
x-tag: articles
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
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
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
ArticleWithProject:
required:
- project_id
properties:
project_id:
type: integer
description: Project id for this article.
example: 1
default: 0
allOf:
- $ref: '#/components/schemas/Article'
x-tag: articles_with_project
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
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
Collection:
required:
- doi
- handle
- id
- timeline
- title
- url
type: object
properties:
id:
type: integer
description: Collection id
example: 123
title:
type: string
description: Collection title
example: Sample collection
doi:
type: string
description: Collection DOI
example: 10.6084/m9.figshare.123
handle:
type: string
description: Collection Handle
example: 111184/figshare.1234
url:
type: string
description: Api endpoint
example: https://api.figshare.com/v2/collections/123
timeline:
$ref: '#/components/schemas/Timeline'
x-tag: collections
CollectionComplete:
required:
- articles_count
- authors
- categories
- citation
- created_date
- custom_fields
- description
- funding
- group_id
- institution_id
- keywords
- modified_date
- public
- references
- related_materials
- resource_doi
- resource_id
- resource_link
- resource_title
- resource_version
- tags
- timeline
- version
properties:
funding:
type: array
description: Full Collection funding information
items:
$ref: '#/components/schemas/FundingInformation'
resource_id:
type: string
description: Collection resource id
example: ''
resource_doi:
type: string
description: Collection resource doi
example: 10.6084/m9.figshare.123
resource_title:
type: string
description: Collection resource title
example: test
resource_link:
type: string
description: Collection resource link
example: http://figshare.com
resource_version:
type: integer
description: Collection resource version
example: 0
version:
type: integer
description: Collection version
example: 1
description:
type: string
description: Collection description
example: description
categories:
type: array
description: List of collection categories
items:
$ref: '#/components/schemas/Category'
references:
type: array
description: List of collection references
items:
type: string
format: url
related_materials:
type: array
description: List of related materials; supersedes references and resource DOI/title.
example:
- id: 10432
identifier:
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/la-trobe-university/refs/heads/main/openapi/la-trobe-university-opal-figshare.yaml