Collection endpoints

Public endpoints

The following public endpoints don't require authentication/authorization.

===========================

List public collections

Request

GET /v2/collections

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

Defaults:

field value
order published_date
order_direction desc
page_size 10

Response

Errors

Standard error responses.

=============================

Search public collections

Request

POST /v2/collections/search

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

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

Additional filters:

field type notes
resource_doi str only return collections with this resource_doi

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

The response body will use the collection light presenter.

Response

Errors

Standard error responses.

==========================

Read public collection

Request

GET /v2/collections/{id}

Response

The collection detailed presenter will be used.

Errors

Standard error responses.

===================================

List collection public articles

Request

GET /v2/collections/{id}/articles

Accepts pagination params. See API feature list for details.

Response

Errors

Standard error responses.

===================================

List public collection versions

Request

GET /v2/collections/{id}/versions

Response

Errors

Standard error responses.

===================================

Read public collection version

GET /v2/collections/{id}/versions/{version_number}

Response

Errors:

Standard error responses.

Private endpoints

These requests require authorization/authentication. Missing valid auth will result in 403 and 401 errors.

The attribute own means resources owned(created or authored) by the authenticated account.

==========================

List own collections

GET /v2/account/collections

Almost identical to list public collections, but default sorting is by created_date, not published_date.

==========================

Search own collections

POST /v2/account/collections/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

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

[CollectionPresenter]

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 collection

POST /v2/account/collections

Request

Name Type Description
title str The title for this collection - mandatory
description str The collection description. In a publisher case, usually this is the resource article description
articles array of int List of articles to be associated with the collection (e.g [1, 4])
authors array of dictionaries {"id": int} or {"name": str} List of new authors to be assosciated with the collection. Each element identifies an author by id OR name (e.g [{"id":1212}, {"name":"John Doe"}])
categories array of int List of category ids to be associated with the collection (e.g [5, 7, 9])
tags array of str List of tags to be associated with the collection (e.g ["tag1", "tag2"]). 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 references to be associated with the collection (e.g ["http://figshare.com", "http://figshare.com/articles/browse"])
resource_id str Not applicable to regular users. In a publisher case, this is the publisher article id
resource_doi str Not applicable to regular users. In a publisher case, this is the publisher article DOI
resource_link str Not applicable to regular users. In a publisher case, this is the publisher article link
resource_title str Not applicable to regular users. In a publisher case, this is the publisher article title
resource_version int Not applicable to regular users. In a publisher case, this is the publisher article version
custom_fields dict List of key, values pairs to be associated with the collection. Similar to custom article fields

Response

Errors

Standard error responses.

=======================

Read own collection

GET /v2/account/collections/{id}

Response

Errors

Standard error responses.

Update collection

PUT /v2/account/collections/{id}

Input

Name Type Description
title str The title for this collection
description str The collection description. In a publisher case, usually this is the resource article description
articles array of int List of articles to be associated with the collection (e.g [1, 4])
authors array of dictionaries {"id": int} or {"name": str} List of new authors to be assosciated with the collection. Each element identifies an author by id OR name.(e.g [{"id":1212}, {"name":"John Doe"}])
categories array of int List of category ids to be associated with the collection (e.g [5, 7, 9])
tags array of str List of tags to be associated with the collection (e.g ["tag1", "tag2"])
references array of str List of references to be associated with the collection (e.g ["http://figshare.com", "http://figshare.com/articles/browse"])
resource_id str Not applicable to regular users. In a publisher case, this is the publisher article id
resource_doi str Not applicable to regular users. In a publisher case, this is the publisher article DOI
resource_link str Not applicable to regular users. In a publisher case, this is the publisher article link
resource_title str Not applicable to regular users. In a publisher case, this is the publisher article title
resource_version int Not applicable to regular users. In a publisher case, this is the publisher article version
custom_fields dict List of key, values pairs to be associated with the collection. Similar to custom article fields

Success Response

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

Error Response (Id not found)

Status: 404 Not found

{"message": "Collection not found"}

Delete own private collection

DELETE /v2/account/collections/{id}

Success Response

Status: 204 No content

Error Response (Id not found)

Status: 404 Not found

{"message": "Collection not found"}

Reserve DOI for collection**

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

Success Response

Status: 200 OK

{"doi": "doi link"}

Error Response (Id not found)

Status: 404 Not found

{"message": "Collection not found"}

Publish collection

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

Note:
When a collection is published, a new public version will be generated.
Any further updates to the collection will affect the private collection 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/collections/123

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

Status: 428 Precondition failed

{
    "message": "Collection has no associated authors",
    "code": "MissingMandatoryFieldException",
    "data": {}
}

Collection authors subsection

List authors

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

To represent the authors, the author's light presenter will be used.

Success Response

Status: 200 OK

[AuthorPresenter]

Associate new authors with the collection

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

Input

Name Type Description
authors array of dictionaries {'id':int} or {'name':str} List of new authors to be assosciated with the collection. The list can contain author ids or names. Example {"authors": [ {"id": 1}, {"name": "Joe Doe"} ] } represents two authors: one identified by id and one by name.

Success Response

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

Error Response (Author(s) id not found)

Status: 422 Unprocessable Entity

{
    "message": "Author not found",
    "code": "EntityNotFoundException",
    "data": {}
}

Associate and replace existing authors of this collection

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

Input

Name Type Description
authors array of dictionaries {'id':int} or {'name':str} List of authors to be assosciated with the collection. The list can contain author ids or names. Example {"authors": [ {"id": 1}, {"name": "Joe Doe"} ] } represents two authors: one identified by id and one by name.

To represent the author entity, the light presenter will be used.

Success Response

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

Error Response (Author(s) id not found)

Status: 422 Unprocessable Entity

{
    "message": "Author not found",
    "code": "EntityNotFoundException",
    "data": {}
}

De-associate author from collection

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

Success Response

Status: 204 No content

Error Response (Author id not found)

Status: 422 Unprocessable Entity

{
    "message": "Author not found",
    "code": "EntityNotFoundException",
    "data": {}
}

Collection categories subsection

List categories

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

Success Response

Status: 200 OK

[CategoryPresenter]

Associate new categories with the collection

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

Input

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

Success Response

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

Error Response (Category ID not found)

Status: 422 Unprocessable Entity

{
    "message": "Category not found",
    "code": "EntityNotFoundException",
    "data": {}
}

Associate and replace existing categories of this collection

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

Input

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

Success Response

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

Error Response (Category ID not found)

Status: 422 Unprocessable Entity

{
    "message": "Category not found",
    "code": "EntityNotFoundException",
    "data": {}
}

De-associate category from collection

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

Success Response

Status: 204 No Content

Error Response (Category id not found)

Status: 404 Not found

{
    "message": "Category not found",
    "code": "EntityNotFoundException",
    "data": {}
}

Collection articles subsection

List articles

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

Success Response

Status: 200 OK

[ArticlePresenter]

Associate new articles with the collection

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

Input

Name Type Description
articles array of int List of new articles to be assosciated with the collection. No more then 10 article IDs per request

Success Response

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

Error Response (Article ID not found)

Status: 422 Unprocessable Entity

{
    "message": "Article not found",
    "code": "EntityNotFoundException",
    "data": {}
}

Associate and replace existing articles of this collection

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

Input

Name Type Description
articles array of int List of articles to be assosciated with the collection. Existing articles will be replaced. No more then 10 article IDs

To represent the article entity, the light presenter will be used.

Success Response

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

Error Response (Article ID not found in collection)

Status: 422 Unprocessable Entity

{
    "message": "Article not found",
    "code": "EntityNotFoundException",
    "data": {}
}

De-associate article from collection

DELETE /v2/account/collections/{id}/articles/{article_id}

Success Response

Status: 204 No content

Error Response (Article ID not found in collection)

Status: 404 Not found

{
    "message": "Private link not found in collection",
    "code": "EntityNotFoundException",
    "data": {}
}

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

Success Response

Status: 200 OK

[PrivateLinkPresenter]

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

Input

Name Type Description
read_only bool Optional, default true. Set to false to give private link users editing rights for this collection.
expires_date date Date when this private link should expire - optional. By default private links expire in 365 days.

Success Response

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

PUT /v2/account/collections/{id}/private_links/{p_id}

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/collections/123/private_links

Error Response (Private Link ID not found)

Status: 404 Not found

{
    "message": "Private link not found",
    "code": "EntityNotFoundException",
    "data": {}
}

DELETE /v2/account/collections/{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 not found",
    "code": "EntityNotFoundException",
    "data": {}
}