Figshare-hosted institutional research data repository for the University of Auckland. The Figshare v2 REST API exposes public articles, datasets, collections, and projects; University of Auckland records are filtered via the institution=12 parameter (confirmed by k6.auckland DOIs). Figshare recommends no more than one request per second.
openapi: 3.0.3
info:
title: Figshare API
description: 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
description: Figshare API v2 (University of Auckland records via institution=12)
paths:
/altmetric/institutions:
get:
tags:
- altmetric
summary: List Altmetric Institutions
description: Returns a list of institutions available for Altmetric reporting
operationId: altmetric_institutions_list
x-internal: true
parameters:
- name: offset
in: query
description: Where to start the listing. The offset of the first item.
schema:
minimum: 0
type: integer
default: 0
responses:
'200':
description: OK. An array of Altmetric institutions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AltmetricInstitution'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: Internal Server Error
content: {}
/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}/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
/articles/{article_id}/versions/{version_id}/files:
get:
tags:
- articles
summary: Public Article version files
description: Article version file details
operationId: article_version_files
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 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}/download:
get:
tags:
- articles
summary: Public Article Download
description: Download files from a public article preserving the folder structure
operationId: public_article_download
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
- name: folder_path
in: query
description: Folder path to download. If not provided, all files from the article will be downloaded
schema:
type: string
responses:
'200':
description: OK
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article
/articles/{article_id}/versions/{version_id}/download:
get:
tags:
- articles
summary: Public Article Version Download
description: Download files from a certain version of an public article preserving the folder structure
operationId: public_article_version_download
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
- name: version_id
in: path
description: Version Number
required: true
schema:
minimum: 1
type: integer
- name: folder_path
in: query
description: Folder path to download. If not provided, all files from the article will be downloaded
schema:
type: string
responses:
'200':
description: OK
content: {}
'500':
description: Internal Server Error
content: {}
security: []
x-subcategory: Public Article
/articles/{article_id}/versions/{version_id}/embargo:
get:
tags:
- articles
summary: Public Article Embargo for article version
description: Embargo for article version
operationId: article_version_embargo
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
- name: version_id
in: path
description: Version Number
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Embargo representation
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleEmbargo'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
/articles/{article_id}/versions/{version_id}/confidentiality:
get:
tags:
- articles
summary: Public Article Confidentiality for article version
description: Confidentiality for article version. The confidentiality feature is now deprecated. This has been replaced
by the new extended embargo functionality and all items that used to be confidential have now been migrated to items
with a permanent embargo on files. All API endpoints related to this functionality will remain for backwards compatibility,
but will now be attached to the new extended embargo workflows.
operationId: article_version_confidentiality
parameters:
- name: article_id
in: path
description: Article Unique identifier
required: true
schema:
minimum: 1
type: integer
- name: version_id
in: path
description: Version Number
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Confidentiality representation
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleConfidentiality'
'400':
description: Bad Request
content: {}
'404':
description: Not Found
content: {}
'500':
description: Internal Server Error
content: {}
security: []
/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
/account/articles/search:
post:
tags:
- articles
summary: Private Articles search
description: Returns a list of private articles filtered by the search parameters
operationId: private_articles_search
requestBody:
description: Search Parameters
content:
application/json:
schema:
$ref: '#/components/schemas/PrivateArticleSearch'
required: true
responses:
'200':
description: OK. An array of articles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArticleWithProject'
'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/articles:
get:
tags:
- articles
summary: Private Articles
description: Get Own Articles
operationId: private_articles_list
parameters:
- 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 account
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
'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
post:
tags:
- articles
summary: Create new Article
description: Create a new Article by sending article information
operationId: private_article_create
requestBody:
description: Article description
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleCreate'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/LocationWarnings'
'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-subcategory: Private Article
x-codegen-request-body-name: Article
/account/articles/{article_id}:
get:
tags:
- articles
summary: Article details
description: View a private article
operationId: private_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/ArticleCompletePrivate'
'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
x-subcategory: Private Article
put:
tags:
- articles
summary: Update article
description: Update an article by passing full body parameters.
operationId: private_article_update
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Full article representation
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleUpdate'
required: true
responses:
'205':
description: Reset Content
headers:
Location:
description: Location of newly created article
schema:
type: string
format: link
content:
application/json:
schema:
$ref: '#/components/schemas/LocationWarningsUpdate'
'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
x-subcategory: Private Article
x-codegen-request-body-name: Article
delete:
tags:
- articles
summary: Delete article
description: Delete an article
operationId: private_article_delete
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'204':
description: No Content
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
x-subcategory: Private Article
patch:
tags:
- articles
summary: Partially update article
description: Partially update an article by sending only the fields to change.
operationId: private_article_partial_update
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Subset of article fields to update
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleUpdate'
required: true
responses:
'205':
description: Reset Content
headers:
Location:
description: Location of the updated article
schema:
type: string
format: link
content:
application/json:
schema:
$ref: '#/components/schemas/LocationWarningsUpdate'
'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
x-subcategory: Private Article
x-codegen-request-body-name: Article
/account/articles/{article_id}/embargo:
get:
tags:
- articles
summary: Article Embargo Details
description: View a private article embargo details
operationId: private_article_embargo_details
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Embargo for article
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleEmbargo'
'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
x-subcategory: Private Article Embargo
put:
tags:
- articles
summary: Update Article Embargo
description: 'Note: setting an article under whole embargo does not imply that the article will be published when the
embargo will expire. You must explicitly call the publish endpoint to enable this functionality.'
operationId: private_article_embargo_update
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Embargo description
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleEmbargoUpdater'
required: true
responses:
'205':
description: Reset Content
headers:
Location:
description: Location of embargo
schema:
type: string
format: link
content: {}
'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
x-subcategory: Private Article Embargo
x-codegen-request-body-name: Embargo
delete:
tags:
- articles
summary: Delete Article Embargo
description: Will lift the embargo for the specified article
operationId: private_article_embargo_delete
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
responses:
'204':
description: No Content
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
x-subcategory: Private Article Embargo
/account/articles/{article_id}/resource:
post:
tags:
- articles
summary: Private Article Resource
description: Edit article resource data.
operationId: private_article_resource
parameters:
- name: article_id
in: path
description: Article unique identifier
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Resource data
c
# --- truncated at 32 KB (329 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-auckland/refs/heads/main/openapi/university-of-auckland-figshare-rest.yaml