Article endpoints

Article public endpoints

List public articles

GET /v2/articles

Input

Accepts pagination, sorting, filtering params. See API feature list for details.

Accepted filters:

field type notes
institution int only return collections from this institution
group int only return collections from this group
published_since date(ISO 8601) Only collections published after the date
modified_since date(ISO 8601) Only collections published after the date
item_type int Only return collections with the respective type. Mapping for item_type is: 1 - Figure, 2 - Media, 3 - Dataset, 4 - Fileset, 5 - Poster, 6 - Paper, 7 - Presentation, 8 - Thesis, 9 - Code, 11 - Metadata, 12 - Preprint

Defaults:

field value
order published_date
order_direction desc
page_size 10

Success Response (list of articles) Status: 200 OK

[ArticlePresenter]

Error Response (Max page number reached)

Status: 400 Bad request

{"message": "Max page reached. Please narrow down your search"}

Search public articles

POST /v2/articles/search

Input

Accepts pagination, sorting, filtering and search params. See API feature list for details.

Filters and defaults are the same as for the list public articles

Additional filters:

field type notes
resource_doi str only return collections with this doi

To search by resource title include it in the search_for parameter as such: "search_for":":resource_title: title"

Success Response (list of articles) Status: 200 OK

[ArticlePresenter]

Error Response (invalid input)

Status: 400 Bad request

{"message": "Invalid value received for order"}

Error Response (Max page number reached)

Status: 400 Bad request

{"message": "Max page reached. Please narrow down your search"}

Read public article

GET /v2/articles/{id}

Success Response (article object) Status: 200 OK

ArticlePresenter.L2

Error Response (article not found)

Status: 404 Not Found

{"message": "Article with specified ID does not exist"}

Download public files

A public article might contain files - a list of PublicFilePresenter dictionaries. In order to download such a public file, one should perform an HTTP GET to the download_url value.

Article versions subsection

List versions

GET /v2/articles/{id}/versions

Success Response

Status: 200 OK

[ArticleVersionPresenter]

Error Response (article ID not found)

Status: 404 Not found

{"message": "Entity not found: article",
"code": "EntityNotFound"}

Read public article version

Read public article that has {id} and {v_number}

GET /v2/articles/{id}/versions/{v_number}

Success Response (article object for specified version)

Status: 200 OK

ArticlePresenter.L2

Error Response (Version not found)

Status: 404 Not Found

{"message": "Entity not found: ArticleVersion",
"code": "EntityNotFound"}

Read public article version embargo

Read public article embargo that has {id} and {v_number}

GET /v2/articles/{id}/versions/{v_number}/embargo

Success Response (article object for specified version)

Status: 200 OK

ArticleEmbargoPresenter

Error Response (Version not found)

Status: 404 Not Found

{"message": "Entity not found: ArticleVersion",
"code": "EntityNotFound"}

Read public article version confidentiality

Read public article confidentiality that has {id} and {v_number}

GET /v2/articles/{id}/versions/{v_number}/confidentiality

Success Response (article object for specified version)

Status: 200 OK

ArticleConfidentialityPresenter

Error Response (Version not found)

Status: 404 Not Found

{"message": "Version does not exist"}

Article private endpoints (OAuth required)

Get own articles

GET /v2/account/articles

Input

Name Type Description
page int Show specified page only. Default is 1. Max page is 100. To see more than 100 pages, the search endpoint must be used to narrow down the results
page_size int How many entries per page to show. Default is 10.

OR

Name Type Description
offset int The first entry to return. The offset of the initial entry is 0 (not 1).
limit int The number of returned entries. Default is 10.

By default the items are sorted by created_date, not published_date.

Success Response (list of articles) Status: 200 OK

[ArticlePresenter]

Error Response (Max page number reached)

Status: 400 Bad request

{"message": "Max page reached. Please narrow down your search"}

Search own articles

POST /v2/account/articles/search

Input

Name Type Description
page int Show specified page only. Default is 1. Max is 100
page_size int How many entries per page to show. Default is 10. Max is 100
search_for str (query)String to perform search for. Minimum of 4 characters
published_since date (filter)Narrow search to articles published since the specified date
modified_since date (filter)Narrow search to articles modified since the specified date
institution int (filter)Filter results for this instritution only
group int (filter)Filter results for this institution group only
order str (sort)Perform a sort using the order. Valid values are: published_date, modified_date
order_direction str (sort)How to sort. Descending or ascending. Valid values are: desc, asc
resource_id str only return collections with this resource_id
resource_doi str only return collections with this resource_doi
item_type int Only return collections with the respective type. Mapping for item_type is: 1 - Figure, 2 - Media, 3 - Dataset, 4 - Fileset, 5 - Poster, 6 - Paper, 7 - Presentation, 8 - Thesis, 9 - Code, 11 - Metadata, 12 - Preprint

To search by resource title include it in the search_for parameter as such: "search_for":":resource_title: title"

Alternatively, instead of page and page_size, one can use the following params for pagination:

Name Type Description
offset int The first entry to return. The offset of the initial entry is 0 (not 1).
limit int The number of returned entries. Default is 10.

Success Response (list of articles)

Status: 200 OK

[ArticlePresenter]

Error Response (invalid input)

Status: 400 Bad request

{"message": "Invalid value received for order"}

Error Response (Max page number reached)

Status: 400 Bad request

{"message": "Max page reached. Please narrow down your search"}

Create a new article

POST /v2/account/articles

Input

Name Type Description
title str The title for this article
description str The article description. In a publisher case, usually this is the remote article description
tags array of str List of tags to be associated with the article (e.g ["tag1", "tag2", "tagn"]). Keywords can be used instead
keywords array of str List of keywords to be associated with the article (e.g ["tag1", "tag2", "tagn"]). Tags can be used instead
references array of str List of links to be associated with the article (e.g ["http://link1", "http://link2", "http://link3"])
categories array of int List of category ids to be associated with the article(e.g [1, 23, 33, 66])
authors array List of authors to be assosciated with the article. The list can contain author ids or author names [{"id": 12121}, {"id": 34345}, {"name": "John Doe"}]. No more than 10 authors. For adding more authors use the specific authors endpoint.
custom_fields dict List of key, values pairs to be associated with the article
defined_type str Article type, one of ['figure', 'media', 'dataset', 'fileset', 'poster', 'paper', 'presentation', 'thesis', 'code', 'metadata']
funding str Grant number or funding authority
license int License id for this article. Licenses listing endpoints are described here.
doi str Not appliable for regular users. In an institutional case, make sure your group supports setting DOIs. This setting is applied by figshare via opening a ticket through our support/helpdesk system.
resource_doi str Not applicable to regular users. In a publisher case, this is the publisher article DOI.
resource_title str Not applicable to regular users. In a publisher case, this is the publisher article title.

Success Response

Status: 201 Created
Location: https://api.figshare.com/v2/account/articles/123

Read own article

GET /v2/account/articles/{id}

Success Response Status: 200 OK

ArticlePresenterL2

Error Response (Id not found)

Status: 404 Not found

{"message": "Article not found"}

Update article

PUT /v2/account/articles/{id}

Input

Name Type Description
title str The title for this article - mandatory
description str The article description. In a publisher case, usually this is the remote article description
tags array of str List of tags to be associated with the article (e.g ["tag1", "tag2", "tagn"])
references array of str List of links to be associated with the article (e.g ["http://link1", "http://link2", "http://link3"])
categories array of int List of category ids to be associated with the article(e.g [1, 23, 33, 66])
authors array List of authors to be assosciated with the article. The list can contain author ids or author names [{"id": 12121}, {"id": 34345}, {"name": "John Doe"}]. No more than 10 authors. For adding more authors use the specific authors endpoint.
custom_fields dict List of key, values pairs to be associated with the article
defined_type str Article type, one of ['figure', 'media', 'dataset', 'fileset', 'poster', 'paper', 'presentation', 'thesis', 'code', 'metadata']
funding str Grant number or funding authority
license int License id for this article. Licenses listing endpoints are described here.
doi str Not appliable for regular users. In an institutional case, make sure your group supports setting DOIs. This setting is applied by figshare via opening a ticket through our support/helpdesk system.
resource_doi str Not applicable to regular users. In a publisher case, this is the publisher article DOI.
resource_title str Not applicable to regular users. In a publisher case, this is the publisher article title.

Success Response

Status: 205 Reset Content
Location: https://api.figshare.com/v2/account/articles/123

Error Response (Id not found)

Status: 404 Not found

    {"message": "Article not found"}

Delete own private article

DELETE /v2/account/articles/{id}

Success Response

Status: 204 No Content

Error Response (Id not found)

Status: 404 Not found

    {"message": "article not found"}

Reserve DOI for article**

POST /v2/account/articles/{id}/reserve_doi

Success Response

Status: 200 OK

{"doi": "10.5072/FK2.FIGSHARE.20345"}

Error Response (Id not found)

Status: 404 Not found

{"message": "article not found"}

Publish article

POST /v2/account/articles/{id}/publish

Notes: - If the whole article is under embargo, it will not be published immediatly, but when the embargo expires or is lifted.
- When an article is published, a new public version will be generated. Any further updates to the article will affect the private article data. In order to make these changes publicly visible, an explicit publish operation is needed.

Success Response

Status: 201 Created
Location: https://api.figshare.com/v2/articles/123

Error Response (Id not found)

Status: 404 Not found

{"message": "article not found"}

Error Response (Missing mandatory fields for publish (e.g authors))

Status: 400 Bad request

{"message": "Missing mandatory field for publication - authors"}

Article authors subsection

List authors

GET /v2/account/articles/{id}/authors

Success Response

Status: 200 OK

[AuthorPresenter]

Error Response (article Id not found)

Status: 404 Not found

{"message": "article not found"}

Associate new authors with the article

POST /v2/account/articles/{id}/authors

Input

Name Type Description
authors array List of authors to be assosciated with the article. The list can contain author ids or author names [{"id": 12121}, {"id": 34345}, {"name": "John Doe"}]. No more than 10 authors. For adding more authors use the specific authors endpoint.

Success Response

Status: 205 Reset Content
Location: https://api.figshare.com/v2/account/articles/123/authors

Error Response (Author(s) id not found)

Status: 400 Bad request

{"message": "Author with ID not found"}

Associate and replace existing authors of this article

PUT /v2/account/articles/{id}/authors

Input

Name Type Description
authors array List of authors to be assosciated with the article. The list can contain author ids or author names [{"id": 12121}, {"id": 34345}, {"name": "John Doe"}]. No more than 10 authors. For adding more authors use the specific authors endpoint.

Success Response

Status: 205 Reset Content
Location: https://api.figshare.com/v2/account/articles/123/authors

Error Response (Author(s) id not found)

Status: 400 Bad request

{"message": "Author with ID  not found"}

De-associate author from article

DELETE /v2/account/articles/{id}/authors/{author_id}

Success Response

Status: 204 No Content

Error Response (Author(s) id not found)

Status: 400 Bad request

{"message": "Author with ID  not found"}

article categories subsection

List categories

GET /v2/account/articles/{id}/categories

Success Response

Status: 200 OK

[CategoryPresenter]

Associate new categories with the article

POST /v2/account/articles/{id}/categories

Input

Name Type Description
categories array of int List of new categories to be assosciated with the article

Success Response

Status: 205 Reset Content

CategoryPresenter

Error Response (Category ID not found)

Status: 400 Bad request

{"message": "Category with ID not found"}

Associate and replace existing categories of this article

PUT /v2/account/articles/{id}/categories

Input

Name Type Description
categories array of int List of categories to be assosciated with the article. Existing categories will be replaced

Success Response

Status: 205 Reset Content

CategoryPresenter

Error Response (Catgeory ID not found)

Status: 400 Bad request

{"message": "Category with ID  not found"}

De-associate category from article

DELETE /v2/account/articles/{id}/categories/{category_id}

Success Response

Status: 204 No Content

Error Response (Category id not found)

Status: 404 Bad request

{"message": "Category with ID  not found"}

Article files subsection

Steps to upload file

  • Initiate file upload - this request returns an endpoint with file data
  • Send a GET request to the Uploader Service with the upload_url (which also contains theupload_token) provided in previous step and receive the number of file parts
  • Upload / Delete / Retry uploading file parts until all parts are uploaded successfully
  • Complete file upload

List files

GET /v2/account/articles/{id}/files

Success Response

Status: 200 OK

Body: List of PrivateFilePresenter

Initiate new file upload within the article

POST /v2/account/articles/{id}/files

Input

Name Type Description
link str Url for an existing file that will not be uploaded on figshare

or

Name Type Description
md5 str MD5 sum pre computed on the client side
name str File name including the extension
size int File size in bytes

Success Response

Status: 201 Created
Location: /v2/account/articles/{id}/files/{file_id}

Upload file content

Figshare Upload Service

Complete file upload

POST /v2/account/articles/{id}/files/{file_id}

Success Response

Status: 202 Accepted

Error Response (File_id not found)

Status: 404 Not found

{"message": "File not found"}

View file information

GET /v2/account/articles/{id}/files/{file_id}

Success Response

Status: 200 OK

Body: PrivateFilePresenter

Error Response (File_id not found)

Status: 404 Not found

{"message": "File not found"}

Download private files

Download private files hosted on figshare

The downloader subsystem handles all downloads for files hosted on figshare. The base URL is https://ndownloader.figshare.com.

In order to access private files, some form of authorization is needed. Most of the time, the session from the website will suffice but the app also supports oauth tokens and private links.

An oauth or private link token can be sent as a param in the query string:

GET /files/23434?token=28a7278bea87c HTTP/1.1 Host: ndownloader.figshare.com Accept: */*

Use ?private_link=VALUE for private links and ?token=VALUE for OAuth2 access tokens.

Download private linked files (not hosted on fighsare)

Use the download_url of the file linked to an article.

Delete file from article

DELETE /v2/account/articles/{id}/files/{file_id}

Success Response

Status: 204 No Content

Error Response (File_id not found)

Status: 404 Not found

{"message": "File not found"}

Article private links subsection

GET /v2/account/articles/{id}/private_links

Success Response

Status: 200 OK

[PrivateLinkPresenter]

Create new private link for this article

POST /v2/account/articles/{id}/private_links

Input

Name Type Description
expires_date date Date when this private link should expire - optional. By default private links expire in 365 days.

Success Response

Status: 201 OK
Location: https://api.figshare.com/v2/account/articles/123/private_links/kjkjhg234k53o4i45p2o3i456..

Update existing private link for this article

PUT /v2/account/articles/{id}/private_links/{private_link_token}

Input

Name Type Description
expires_date date Date when this private link should expire - optional. By default private links expire in 365 days.

Success Response

Status: 205 Reset Content
Location: https://api.figshare.com/v2/account/articles/123/private_links/kjkjhg234k53o4i45p2o3i456..

Error Response (Private Link ID not found)

Status: 404 Not found

{"message": "Private Link with ID  not found"}

Disable/delete private link for article

DELETE /v2/account/articles/{id}/private_links/{private_link_id}

Success Response

Status: 204 No Content

Error Response (Private link ID not found)

Status: 404 Not found

{"message": "Private link with ID not in article"}

Article embargo subsection

View embargo settings

GET /v2/account/articles/{id}/embargo

Success Response

Status: 200 OK

ArticleEmbargoPresenter

Update embargo settings

PUT /v2/account/articles/{id}/embargo

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.

Input

Name Type Description
is_embargoed bool Confidentiality status. True, False
embargo_type str Embargo can be enabled at the article or the file level. Possible values: article, file
embargo_date date Date when the embargo expires and the article gets published
embargo_reason str Reason for setting embargo

Success Response

Status: 205 Reset Content
Location: http://api.figshare.com/v2/account/articles/2000688/embargo

Input error

Status: 400 Bad request

{"message": "Invalid expires date"}

Delete embargo settings

DELETE /v2/account/articles/{id}/embargo

Success Response

Status: 204 No Content

Article confidentiality subsection

View confidentiality settings

GET /v2/account/articles/{id}/confidentiality

Success Response

Status: 200 OK

ArticleConfidentialityPresenter

Update confidentiality settings

PUT /v2/account/articles/{id}/confidentiality

Input

Name Type Description
reason str Confidentiality reason

Success Response

Status: 200 OK
Location: http://api.figshare.com/v2/account/articles/2000688/confidentiality

Delete confidentiality settings

DELETE /v2/account/articles/{id}/confidentiality

Success Response

Status: 204 No Content