openapi: 3.0.3
info:
title: Figshare altmetric institutions 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: []
tags:
- name: institutions
paths:
/institutions/{institution_string_id}/articles/filter-by:
get:
tags:
- institutions
summary: Public Institution Articles
description: Returns a list of articles belonging to the institution
operationId: institution_articles
parameters:
- name: institution_string_id
in: path
required: true
schema:
type: string
- name: resource_id
in: query
required: true
schema:
type: string
- name: filename
in: query
required: true
schema:
type: string
responses:
'200':
description: OK. An array of articles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
'500':
description: Internal Server Error
content: {}
/account/institution:
get:
tags:
- institutions
summary: Private Account Institutions
description: Account institution details
operationId: private_institution_details
responses:
'200':
description: OK. An array of institutions
content:
application/json:
schema:
$ref: '#/components/schemas/Institution'
'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
/account/institution/embargo_options:
get:
tags:
- institutions
summary: Private Account Institution embargo options
description: Account institution embargo options details
operationId: private_institution_embargo_options_details
responses:
'200':
description: OK. An array of embargo options
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GroupEmbargoOptions'
'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
/account/institution/articles:
get:
tags:
- institutions
summary: Private Institution Articles
description: Get Articles from own institution. User must be administrator of the institution
operationId: private_institution_articles
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
- 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
- modified_date
- name: order_direction
in: query
schema:
type: string
default: desc
enum:
- asc
- desc
- 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: status
in: query
description: only return collections with this status
schema:
type: integer
- name: resource_doi
in: query
description: only return collections 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: group
in: query
description: only return articles from this group
schema:
type: integer
responses:
'200':
description: OK. An array of articles belonging to the institution
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
/account/institution/custom_fields:
get:
tags:
- institutions
summary: Private account institution group custom fields
description: Returns the custom fields in the group the user belongs to, or the ones in the group specified, if the user has access.
operationId: custom_fields_list
parameters:
- name: group_id
in: query
description: Group_id
schema:
type: integer
responses:
'200':
description: OK. An array of custom fields
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShortCustomField'
'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
/account/institution/custom_fields/{custom_field_id}/items/upload:
post:
tags:
- institutions
summary: Custom fields values files upload
description: Uploads a CSV containing values for a specific custom field of type dropdown_large_list. The custom_field_id path parameter accepts both classic custom field IDs (legacy) and underlying field IDs (v2). The lookup is performed automatically — no additional parameter is required. More details in the Custom Fields section
operationId: custom_fields_upload
parameters:
- name: custom_field_id
in: path
description: Identifier of the custom field or underlying field (v2) of type dropdown_large_list
required: true
schema:
minimum: 1
type: integer
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
external_file:
type: string
description: CSV file to be uploaded
format: binary
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
example:
code: 200
message: OK
'400':
description: Bad Request
content: {}
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: Conflict
content: {}
'500':
description: Internal Server Error
content: {}
security:
- OAuth2:
- all
/account/categories:
get:
tags:
- institutions
summary: Private Account Categories
description: List institution categories (including parent Categories)
operationId: private_categories_list
responses:
'200':
description: OK. An array of categories
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CategoryList'
'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
/account/institution/groups:
get:
tags:
- institutions
summary: Private Account Institution Groups
description: Returns the groups for which the account has administrative privileges (assigned and inherited).
operationId: private_institution_groups_list
responses:
'200':
description: OK. An array of Groups
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Group'
'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
/account/institution/groups/{group_id}/embargo_options:
get:
tags:
- institutions
summary: Private Account Institution Group Embargo Options
description: Account institution group embargo options details
operationId: private_group_embargo_options_details
parameters:
- name: group_id
in: path
description: Group identifier
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. An array of embargo options
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GroupEmbargoOptions'
'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
/account/institution/roles:
get:
tags:
- institutions
summary: Private Account Institution Roles
description: Returns the roles available for groups and the institution group.
operationId: private_institution_roles_list
responses:
'200':
description: OK. An array of Roles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Role'
'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
/account/institution/accounts:
get:
tags:
- institutions
summary: Private Account Institution Accounts
description: Returns the accounts for which the account has administrative privileges (assigned and inherited).
operationId: private_institution_accounts_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
- name: is_active
in: query
description: Filter by active status
schema:
maximum: 1
minimum: 0
type: integer
- name: institution_user_id
in: query
description: Filter by institution_user_id
schema:
type: string
- name: email
in: query
description: Filter by email
schema:
type: string
- name: id_lte
in: query
description: Retrieve accounts with an ID lower or equal to the specified value
schema:
minimum: 0
type: integer
- name: id_gte
in: query
description: Retrieve accounts with an ID greater or equal to the specified value
schema:
minimum: 0
type: integer
responses:
'200':
description: OK. An array of Accounts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShortAccount'
'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:
- institutions
summary: Create new Institution Account
description: Create a new Account by sending account information. When the institution_user_id is provided, no verification email will be sent. The email_verified flag will automatically be set to true. If the institution_user_id is not provided, a verification email will be sent. The email_verified flag will be set to true once the account is created.
operationId: private_institution_accounts_create
requestBody:
description: Account description
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreate'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateResponse'
'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: Account
/account/institution/accounts/{account_id}:
get:
tags:
- institutions
summary: Private Institution Account information
description: Private Institution Account information
operationId: private_institution_account
parameters:
- name: account_id
in: path
description: Account identifier the user is associated to
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Account
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'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
put:
tags:
- institutions
summary: Update Institution Account
description: Update Institution Account
operationId: private_institution_accounts_update
parameters:
- name: account_id
in: path
description: Account identifier the user is associated to
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Account description
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUpdate'
required: true
responses:
'205':
description: Reset Content
headers:
Location:
description: Location of newly created article
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-codegen-request-body-name: Account
/account/institution/roles/{account_id}:
get:
tags:
- institutions
summary: List Institution Account Group Roles
description: List Institution Account Group Roles
operationId: private_institution_account_group_roles
parameters:
- name: account_id
in: path
description: Account identifier the user is associated to
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. Account Group Roles
content:
application/json:
schema:
$ref: '#/components/schemas/AccountGroupRoles'
'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
post:
tags:
- institutions
summary: Add Institution Account Group Roles
description: Add Institution Account Group Roles
operationId: private_institution_account_group_roles_create
parameters:
- name: account_id
in: path
description: Account identifier the user is associated to
required: true
schema:
minimum: 1
type: integer
requestBody:
description: Account description
content:
application/json:
schema:
$ref: '#/components/schemas/AccountGroupRolesCreate'
required: true
responses:
'201':
description: Created
content: {}
'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: Account
/account/institution/roles/{account_id}/{group_id}/{role_id}:
delete:
tags:
- institutions
summary: Delete Institution Account Group Role
description: Delete Institution Account Group Role
operationId: private_institution_account_group_role_delete
parameters:
- name: account_id
in: path
description: Account identifier for which to remove the role
required: true
schema:
minimum: 1
type: integer
- name: group_id
in: path
description: Group identifier for which to remove the role
required: true
schema:
minimum: 1
type: integer
- name: role_id
in: path
description: Role identifier
required: true
schema:
minimum: 1
type: integer
responses:
'204':
description: No Content
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
/account/institution/accounts/search:
post:
tags:
- institutions
summary: Private Account Institution Accounts Search
description: Returns the accounts for which the account has administrative privileges (assigned and inherited).
operationId: private_institution_accounts_search
requestBody:
description: Search Parameters
content:
application/json:
schema:
$ref: '#/components/schemas/InstitutionAccountsSearch'
required: true
responses:
'200':
description: OK. An array of Accounts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShortAccount'
'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/institution/users/{account_id}:
get:
tags:
- institutions
summary: Private Account Institution User
description: Retrieve institution user information using the account_id
operationId: private_account_institution_user
parameters:
- name: account_id
in: path
description: Account identifier the user is associated to
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. User representation
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'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
/account/institution/reviews:
get:
tags:
- institutions
summary: Institution Curation Reviews
description: Retrieve a list of curation reviews for this institution
operationId: account_institution_curations
parameters:
- name: group_id
in: query
description: Filter by the group ID
schema:
minimum: 0
type: integer
- name: article_id
in: query
description: Retrieve the reviews for this article
schema:
minimum: 0
type: integer
- name: status
in: query
description: Filter by the status of the review
schema:
type: string
enum:
- pending
- approved
- rejected
- closed
- 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. A list of curation reviews.
content:
application/json:
schema:
$ref: '#/components/schemas/Curation'
'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
/account/institution/review/{curation_id}:
get:
tags:
- institutions
summary: Institution Curation Review
description: Retrieve a certain curation review by its ID
operationId: account_institution_curation
parameters:
- name: curation_id
in: path
description: ID of the curation
required: true
schema:
minimum: 1
type: integer
responses:
'200':
description: OK. A curation review.
content:
application/json:
schema:
$ref: '#/components/schemas/CurationDetail'
'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
/account/institution/review/{curation_id}/comments:
get:
tags:
- institutions
summary: Institution Curation Review Comments
description: Retrieve a certain curation review's comments.
operationId: get_account_institution_curation_comments
parameters:
- name: curation_id
in: path
description: ID of the curation
required: true
schema:
minimum: 1
type: integer
- 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. A curation review's comments.
content:
application/json:
schema:
$ref: '#/components/schemas/CurationComment'
'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
post:
tags:
- institutions
summary: POST Institution Curation Review Comment
description: Add a new comment to the review.
operationId: post_account_institution_curation_comments
parameters:
- name: curation_id
in: path
description: ID of the curation
required: true
schema:
minimum: 1
type: integer
requestBody:
description: The content/value of the comment.
content:
application/json:
schema:
$ref: '#/components/schemas/CurationCommentCreate'
required: true
responses:
'200':
description: OK.
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-codegen-request-body-name: CurationComment
/institution/hrfeed/upload:
post:
tags:
- institutions
summary: Private Institution HRfeed Upload
description: More info in the HR Feed section
operationId: institution_hrfeed_upload
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
hrfeed:
type: string
description: You can find an example in the Hr Feed section
format: binary
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseMessage'
'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
components:
schemas:
CategoryList:
required:
- has_children
- is_selectable
properties:
is_selectable:
type: boolean
description: The selectable status
example: true
has_children:
type: boolean
description: True if category has children
example: false
allOf:
- $ref: '#/components/schemas/Category'
x-tag: common
AccountGroupRolesCreate:
type: object
example:
'2':
- 2
- 7
'3':
- 7
- 9
x-tag: institutions
InstitutionAccountsSearch:
type: object
properties:
search_for:
type: string
description: Search term
example: figshare
is_active:
maximum: 1
minimum: 0
type: integer
description: Filter by active status
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_user_id:
type: string
description: filter by institution_user_id
example: alan
email:
type: string
description: filter by email
example: alan@institution.com
x-tag: institutions
Institution:
required:
- id
- name
type: object
properties:
id:
type: integer
description: Institution id
example: 0
name:
type: string
description: Institution name
example: Institution
x-tag: institutions
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
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
Role:
required:
- category
- description
- id
- name
type: object
properties:
id:
type: integer
description: Role id
example: 1
name:
type: string
description: Role name
example: Curator
category:
type: string
description: Role category
example: group
description:
type: string
description: Role description
x-tag: institutions
User:
required:
- first_name
- id
- is_active
- is_public
- job_title
- last_name
- name
- orcid_id
- url_name
type: object
properties:
id:
type: integer
description: User id
example: 1495682
first_name:
type: string
description: First Name
example: Doe
last_name:
type: string
description: Last Name
example: John
name:
type: string
description: Full Name
example: John Doe
is_active:
type: boolean
description: Account activity status
example: true
url_name:
type: string
description: Name that appears in website url
example: John_Doe
is_public:
type: boolean
description: Account public status
example: true
job_title:
type: string
description: User Job title
example: programmer
orcid_id:
type: string
description: Orcid associated to this User
example: 1234-5678-9123-1234
x-tag: other
AccountCreate:
required:
- last_name
- email
type: object
properties:
email:
maxLength: 150
minLength: 3
type: string
description: Email of account
example: johndoe@example.com
first_name:
maxLength: 255
type: string
description: First Name
example: John
default: ''
last_name:
maxLength: 255
type: string
description: Last Name
example: Doe
default: ''
group_id:
type: integer
description: Not applicable to regular users. This field is reserved to institutions/publishers with access to assign to specific groups
institution_user_id:
maxLength: 50
type: string
description: Institution user id
example: johndoe
default: ''
symplectic_user_id:
maxLength: 50
type: string
description: Symplectic user id
example: johndoe
default: ''
quota:
type: integer
description: Account quota
example: 1000
is_active:
type: boolean
description: Is account active
x-tag: institutions
x-maxCombinedLength:
description: The combined length of first_name and last_name must not exceed 255 characters.
ShortAccount:
required:
- active
- email
- first_name
- id
- institution_id
- institution_user_id
- last_name
- orcid_id
- quota
- symplectic_user_id
- used_quota
- user_id
type: object
properties:
id:
type: integer
description: Account id
example: 1495682
first_name:
type: string
description: First Name
example: Doe
last_name:
type: string
description: Last Name
example: John
institution_id:
type: integer
description: Account institution
example: 1
email:
type: string
description: User email
example: user@domain.com
active:
type: integer
description: Account activity status
example: 0
institution_user_id:
type: string
description: Account institution user id
example: '1'
quota:
type: integer
description: Total storage available to account, in bytes
example: 1074000000
used_quota:
type: integer
description: Storage used by the account, in bytes
example: 1074000000
user_id:
type: integer
description: User id associated with account, useful for example for adding the account as an author to an item
example: 1000001
orcid_id:
type: string
description: ORCID iD associated to account
example: 0000-0001-2345-6789
symplectic_user_id:
type: string
description: Symplectic ID associated to account
example: djohn42
x-tag: other
TimelineUpdate:
type: object
properties:
firstOnline:
type: string
description: Online posted date
example: '2015-12-31'
publisherPublication:
type: string
description: Publish date
example: '2015-12-31'
publisherAcceptance:
type: string
description: Date when the item was accepted for publication
example: '2015-12-31'
x-tag: timeline_update
CurationCommentCreate:
required:
- text
type: object
properties:
text:
maxLength: 2000
minLength: 1
type: string
description: The contents/value of the comment
x-tag: institutions
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
CurationDetail:
required:
- item
properties:
item:
$ref: '#/components/schemas/ArticleComplete'
allOf:
- $ref: '#/components/schemas/Curation'
x-tag: institutions
Group:
required:
- association_criteria
- id
- name
- parent_id
- resource_id
type: object
properties:
id:
type: integer
description: Group id
example: 1
name:
type: string
description: Group name
example: Materials
resource_id:
type: string
description: Group resource id
example: ''
parent_id:
type: integer
description: Parent group if any
example: 0
association_criteria:
type: string
description: HR code associated with group, if code exists
example: IT
x-tag: institutions
GroupEmbargoOptions:
required:
- id
- ip_name
- type
type: object
properties:
id:
type: integer
description: Embargo option id
example: 364
type:
type: string
description: Embargo permission type
example: ip_range
enum:
- logged_in
- ip_range
- administrator
ip_name:
type: string
description: IP range name; value appears if type is ip_range
example: Figshare IP range
x-tag: institutions
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
ResponseMessage:
required:
- message
type: object
properties:
message:
type: string
description: Response message text
example: Project 1 has been published
x-tag: common
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
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
Curation:
required:
- account_id
- article_id
- assigned_to
- comments_count
- created_date
- group_id
- id
- modified_date
- request_number
- resolution_comment
- status
- version
type: object
properties:
id:
type: integer
description: The review id
group_id:
type: integer
description: The group in which the article is present.
account_id:
type: integer
description: The ID of the account of the owner of the article of this review.
assigned_to:
type: integer
description: The ID of the account to which this review is assigned.
article_id:
type: integer
description: The ID of the article of this review.
version:
type: integer
description: The Version number of the article in review.
comments_count:
type: integer
description: The number of comments in the review.
status:
type: string
description: The status of the review.
enum:
- pending
- approved
- rejected
- closed
created_date:
type: string
description: The creation date of the review.
modified_date:
type: string
description: The date the review has been modified.
request_number:
type: integer
description: The request number of the review.
resolution_comment:
type: string
description: The resolution comment of the review.
x-tag: institutions
AccountCreateResponse:
required:
- account_id
type: object
properties:
account_id:
type: integer
description: ID of created account
example: 33334444
x-tag: common
CurationComment:
required:
- account_id
- created_date
- id
- modified_date
- text
- type
type: object
properties:
id:
type: integer
description: The ID of the comment.
account_id:
type: integer
description: The ID of the account which generated this comment.
type:
type: string
description: The ID of the account which generated this comment.
enum:
- comment
- approved
- rejected
- closed
text:
type: string
description: The value/content of the comment.
created_date:
type: string
description: The creation date of the comment.
modified_date:
type: string
description: The date the comment has been modified.
x-tag: institutions
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
AccountUpdate:
required:
- is_active
- group_id
type: object
properties:
group_id:
type: integer
description: Not applicable to regular users. This field is reserved to institutions/publishers with access to assign to specific groups
is_active:
type: boolean
description: Is account active
x-tag: institutions
AccountGroupRoles:
type: object
example:
'2':
- category: group
id: 7
name: User
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
ShortCustomField:
required:
- field_type
- id
- name
type: object
properties:
id:
type: integer
description: Custom field id
example: 365
name:
type: string
description: Custom field name
example: my custom field
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 field in the group
example: 1
is_mandatory:
type: boolean
description: Whether the field is mandatory or not
example: false
x-tag: institutions
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
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
Timeline:
allOf:
- $ref: '#/components/schemas/TimelineUpdate'
x-tag: timeline
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
Account:
required:
- active
- created_date
- email
- first_name
- group_id
- id
- institution_id
- institution_user_id
- last_name
- maximum_file_size
- modified_date
- orcid_id
- pending_quota_request
- quota
- symplectic_user_id
- used_quota
- used_quota_private
- used_quota_public
- user_id
type: object
properties:
id:
type: integer
description: Account id
example: 1495682
first_name:
type: string
description: First Name
example: Doe
last_name:
type: string
description: Last Name
example: John
used_quota_private:
type: integer
description: Account used private quota
example: 0
modified_date:
type: string
description: Date of last account modification
example: '2018-05-22T04:04:04'
used_quota:
type: integer
description: Account total used quota
example: 0
created_date:
type: string
description: Date when account was created
example: '2018-05-22T04:04:04'
quota:
type: integer
description: Account quota
example: 0
group_id:
type: integer
description: Account group id
example: 0
institution_user_id:
type: string
description: Account institution user id
example: djohn42
institution_id:
type: integer
description: Account institution
example: 1
email:
type: string
description: User email
example: user@domain.com
used_quota_public:
type: integer
description: Account public used quota
example: 0
pending_quota_request:
type: boolean
description: True if a quota request is pending
example: true
active:
type: integer
description: Account activity status
example: 0
maximum_file_size:
type: integer
description: Maximum upload size for account
example: 0
user_id:
type: integer
description: User id associated with account, useful for example for adding the account as an author to an item
example: 1000001
orcid_id:
type: string
description: ORCID iD associated to account
example: 0000-0001-2345-6789
symplectic_user_id:
type: string
description: Symplectic ID associated to account
example: djohn42
x-tag: other
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'