Projects API endpoints
- Public
- list public projects
- search public projects
- view project details
- list project articles
- Private
- list private projects
- search private projects
- create new project
- read project information
- update project information
- publish project
- delete own project
- articles
- files
- collaborators
- notes
Public endpoints
List public projects
GET /v2/projects
Input
Accepts pagination, sorting, filtering params. See API feature list for details.
Accepted filters:
| Field | Type | Description |
|---|---|---|
institution |
int | Only return projects from this institution |
group |
int | Only return projects from this group |
published_since |
date(ISO 8601) | Only projects published after the date |
Defaults:
| Field | Value |
|---|---|
order |
published_date |
order_direction |
desc |
page_size |
10 |
Call example
curl "https://api.figshare.com/v2/projects?page=2&page_size=3&published_since=2016-01-01"
Success Response
Status: 200 OK
Body: List of Public Project Lite Presenter
Search public projects
POST /v2/projects/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 projects endpoint.
Success Response
Status: 200 OK
Body: List of Public Project Lite Presenter
View project details
GET /v2/projects/{id}
Success Response
Status: 200 OK
Body: Public Project Full Presenter
List project articles
GET /v2/projects/{id}/articles
Accepts pagination params (page and page_size).
See API feature list for details.
Success Response
Status: 200 OK
Body: List of Article Presenter
Private endpoints
These endpoints require authorization/authentication. Missing valid auth will result in 403 and 401 errors.
List private projects
GET /v2/account/projects
Input
Accepts pagination, sorting and filtering params, sent as request parameters.
See API feature list for details.
Accepted filters:
| Field | Type | Description |
|---|---|---|
storage |
str |
group or individual. |
roles |
str |
Any combination of owner, collaborator, viewer separated by comma. Examples: "owner" or "owner,collaborator". |
Success Response (list of projects)
Status: 200 OK
Body: List of Private Project Lite Presenter
Search private projects
POST /v2/account/projects/search
Input
Accepts pagination, sorting, filtering and search params.
See API feature list for details.
Accepted filters:
| Field | Type | Description |
|---|---|---|
storage |
str |
group or individual. |
roles |
str |
Any combination of owner, collaborator, viewer separated by comma. Examples: "owner" or "owner,collaborator". |
published_since |
date(ISO 8601) | Only projects published after the date |
modified_since |
date(ISO 8601) | Only projects published after the date |
status |
int |
1 for public projects, 0 for private projects. |
Success Response
Status: 200 OK
Body: List of Private Project Lite Presenter
Create a new project
POST /v2/account/projects
Input
Accepted parameters sent as JSON request body:
| Name | Type | Description |
|---|---|---|
title |
str |
The title for this project - mandatory. 3 - 500 characters. |
description |
str |
Project's description |
funding |
str |
Grant number or organization(s) that funded this project. Up to 2000 characters permitted. |
group_id |
int |
Only of project type is group. |
Success Response
Status: 201 Created
Headers: Location: https://api.figshare.com/v2/account/projects/123
Get project information
GET /v2/account/projects/{id}
Success Response
Status: 200 OK
Body: Private Project Full Presenter
Update project information
PUT /v2/account/projects/{id}
Input
Accepted parameters sent as JSON request body:
| Name | Type | Description |
|---|---|---|
title |
str |
The title for this project. |
description |
str |
The project description. |
funding |
str |
Grant number or organization(s) that funded this project. Up to 2000 characters permitted. |
Success Response
Status: 205 Reset Content
Headers: Location: https://api.figshare.com/v2/account/projects/123
Publish project
POST /v2/account/projects/{id}/publish
Success Response
Status: 201 Created
Body: Project {id} has been published.
Delete own project
DELETE /v2/account/projects/{id}
A project can be deleted only if: - it is not public - it does not have public articles
When an individual project is deleted, all the articles are moved to my data of each owner*.
When a group project is deleted, all the articles and files are deleted as well. Only project owner, group admin and above can delete a project.
Success Response
Status: 204 No content
Project articles subsection
List articles
GET /v2/account/projects/{id}/articles
Accepts pagination, sorting and filtering params, sent as request parameters.
See API feature list for details.
Success Response
Status: 200 OK
Body: List of Project Article Presenter
Get article
GET /v2/account/projects/{id}/articles/{article_id}
Success Response
Status: 200 OK
Body: ArticlePresenter
Create a new project article
POST /v2/account/projects/{id}/articles
Input
Accepted parameters sent as JSON request body:
| Name | Type | Description |
|---|---|---|
title |
str |
Article title - mandatory. |
description |
str |
Article description. |
tags |
array of str |
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 of dict |
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 then 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 of funding authority. Max of 2000 characters permitted. |
license |
str |
Licence id for this article. |
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
Headers: Location: https://api.figshare.com/v2/account/project/1234/articles/456
Delete project article
DELETE /v2/account/projects/{id}/articles/{article_id}
Success Response
Status: 204 No content
Move article from project
Currently, moving an article to a project or removing an article from a project actions are available only on our website platform https://figshare.com. We plan to deliver this functionality to the API system in the near future.
Project files subsection
List article files
GET /v2/account/projects/{id}/articles/{article_id}/files
Accepts pagination, sorting and filtering params, sent as request parameters.
See API feature list for details.
Success Response
Status: 200 OK
Body: List of PrivateFilePresenter
Get article file
GET /v2/account/projects/{id}/articles/{article_id}/files/{file_id}
Success Response
Status: 200 OK
Body: PrivateFilePresenter
Project collaborators subsection
List collaborators and invited users
GET /v2/account/projects/{id}/collaborators
Success Response
Status: 200 OK
Body: A list with CollaboratorPresenters and InvitedUserPresenters
Invite collaborator
POST /v2/account/projects/{id}/collaborators
Input
Accepted parameters sent as JSON request body:
| Name | Type | Description |
|---|---|---|
role_name |
str |
Valid roles: viewer, collaborator - mandatory |
user_id |
int |
|
email |
str |
|
comment |
str |
Text sent when inviting the user to the project - optional |
Please note that is mandatory to send either user_id or email JSON parameters.
Success Response
Status: 201 Created
Body: {"message": "User invited to project"}
Remove collaborator
DELETE /v2/account/projects/{id}/collaborators/{user_id}
Success Response
Status: 204 No content
Leave project
POST /v2/account/projects/{id}/leave
Please note: project's owner cannot leave the project.
Success Response
Status: 204 No content
Project notes subsection
List notes
GET /v2/account/projects/{id}/notes
Accepts pagination params (page and page_size), sent as request parameters.
See API feature list for details.
Success Response
Status: 200 OK
Body: ProjectNotePresenter
Get note
GET /v2/account/projects/{id}/notes/{note_id}
Success Response
Status: 200 OK
Body: ProjectNotePresenterL1
Add note
POST /v2/account/projects/{id}/notes
Input
Accepted parameter sent as JSON request body:
| Name | Type | Description |
|---|---|---|
text |
str |
Mandatory. At least 3 characters. |
Success Response
Status: 201 Created
Headers: Location: https://api.figshare.com/v2/account/projects/1/notes/2
Update note
PUT /v2/account/projects/{id}/notes/{note_id}
Input
Accepted parameter sent as JSON request body:
| Name | Type | Description |
|---|---|---|
text |
str |
Mandatory. At least 3 characters. |
Success Response
Status: 205 Reset Content
Headers: Location: https://api.figshare.com/v2/account/projects/1/notes/2
Delete note
DELETE /v2/account/projects/{id}/notes/{note_id}
Success Response
Status: 204 No Content