Mendeley API

NOT OFFICIAL! Demonstrates import specification in swagger format only (from https://api.mendeley.com/apidocs)

Base URI

https://api.mendeley.com/apidocs/apis
API Methods
Document_types
GET /document_types
V1 Get available document types
GET /document_types

Responses

200 OK
Body
V1 - Get all groups where the current user is a member
GET /groups

Request parameters

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 Success
Body
Array of Group
V1 - Get details for a group
GET /groups/{id}

Path variables

id
string required

Responses

200 Success
Body
404 Group not found
403 Insufficient permissions to view group details
V1 - List members of group
GET /groups/{id}/members

Path variables

id
string required

Request parameters

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 Members found
Body
Array of UserRole
404 Group not found
403 Insufficient permissions to list members in this group
Disciplines
V1 - Get available disciplines
GET /disciplines

Responses

200 OK
Body
Array of Discipline
V1 Get documents in trash
GET /trash

Request parameters

group_id
string optional

Group ID. If not supplied, returns user documents

modified_since
string optional

Returns only documents modified since this timestamp. Should be supplied in ISO 8601 format

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

order
string optional

The sort order

Enumeration:
asc
desc
sort
string optional

The field to sort on

Enumeration:
document_id
deleted_at
view
string optional

View

Enumeration:
bib
patent
client
tags
all

Responses

200 OK
Body
Array of UserDocument
V1 Get a document from the trash
GET /trash/{id}

Path variables

id
string required

Document ID

Request parameters

view
string optional

View

Enumeration:
bib
patent
client
tags
all

Responses

200 Document found
400 Invalid view requested
404 Document not found
V1 Delete a document from the trash
DELETE /trash/{id}

Path variables

id
string required

Document ID

Responses

204 Document deleted
404 Document not found
V1 Restore a document from the trash
POST /trash/{id}/restore

Path variables

id
string required

Document ID

Responses

204 Document restored from trash
404 Document not found
Entities
GET /enrichments/entities/{fileHash}/system
Get system entities for a document
GET /enrichments/entities/{fileHash}/system

Path variables

fileHash
string required

Filehash of the document

Responses

200 Entities have been found for the given document
204 Your request has been accepted, and the document is being processed
200 The document is already being processed
400 Invalid request
500 Error processing request
Metadata
V1 Get document metadata
GET /metadata

You should specify a filehash OR at least 1 identifier OR a title for a successful match.Looking up ONLY by authors OR year OR source would not return a result.If matching on 'title' then providing authors OR year OR source would improve the lookup.

Request parameters

arxiv
string optional
doi
string optional
pmid
string optional
title
string optional
filehash
string optional
authors
string optional
year
string optional
source
string optional

Responses

200 Get document by id metadata
404 Document not found
BETA - Accept a pending follow request
PATCH /followers/{id}

Path variables

id
string required

Request body

Responses

200 Follow request accepted
404 Follow request not found
422 Follow acceptance invalid
BETA - Stop following a profile, cancel a follow request, or reject a follow
DELETE /followers/{id}

BETA - Stop following a profile, cancel a follow request, or reject a follow request

Path variables

id
string required

Responses

204 Follow relationship or request successfully removed
400 Bad Request
403 Follow relationship previously accepted and cannot be removed
404 Follow relationship or request not found
BETA - Get follower information
GET /followers

Request parameters

follower
string optional
followed
string optional
status
unknown optional
limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 Found follower information
Body
Array of Follow
400 Bad Request
BETA - Start following another profile
POST /followers

Request body

Responses

201 Follower relationship successfully created
Body
400 Bad Request
422 Invalid Request
Files
GET /files
DELETE /files/{file_id}
GET /files/{file_id}
V1 - Get files
GET /files

Gets a set of files. At most one of document ID and group ID can be supplied. If neither is supplied, then documents for the logged-in user are returned.

Request parameters

document_id
string optional

The document ID

catalog_id
string optional

The catalog document ID

group_id
string optional

The group ID

added_since
string optional

Returns only files added since this timestamp. Should be supplied in ISO 8601 format

deleted_since
string optional

Returns files deleted since this timestamp. Should be supplied in ISO 8601 format

include_trashed
string optional

Returns files that have been trashed.

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 Files found
Body
Array of File
400 Bad request
403 Forbidden
404 Group or document not found
V1 - Upload a file to a user document
POST /files

Request headers

Content-Disposition
string required

The content disposition, including the filename (see RFC 1806)

Content-Type
string required

The media type of the file

Link
string required

The URL of the document. This should have relation "document" (see RFC 5988)

Request body

Responses

201 Created, the file has been successfully uploaded and the Location header will contain the file downl

Created, the file has been successfully uploaded and the Location header will contain the file download URL

Body
400 Bad request
403 Forbidden
404 Document not found
413 File is too large
V1 - Delete a file
DELETE /files/{file_id}

Path variables

file_id
unknown required

File ID

Responses

204 Success, the file is deleted
400 Bad request
403 Forbidden
404 File not found
V1 - Download a file
GET /files/{file_id}

Path variables

file_id
unknown required

File ID

Responses

303 Success, the Location header will contain the file download URL
400 Bad request
403 Forbidden
404 File not found
451 Blocked for legal reasons
Profiles
POST /profiles/{id}/actions/send_password_reset_email
POST /profiles/me/resend_verification_email
POST /profiles/me/verify
GET /profiles
GET /profiles/{id}
PATCH /profiles/me
GET /profiles/me
BETA - Initiate a password reset
POST /profiles/{id}/actions/send_password_reset_email

Path variables

id
string required

Request body

Responses

202 Password reset email sent to the supplied email address
400 Given email address does not match that of the profile
403 Not allowed from this client
404 Profile not found
429 A recently issue password reset token still exists for this email address
BETA - Resend verification email
POST /profiles/me/resend_verification_email

Responses

200 Verification email sent
400 Account is already verified
404 Profile not found
BETA - Verify my profile
POST /profiles/me/verify

Request body

Responses

200 Profile verified
Body
400 Verification code is invalid
404 Profile not found
BETA - Get profiles
GET /profiles

Request parameters

link
string optional

Link

email
string optional

Email

Responses

200 Request successful
Body
Array of Profile
400 Invalid request
V1 - Get a profile
GET /profiles/{id}

Path variables

id
string required

Profile ID

Responses

200 Profile found
Body
400 Invalid request
404 Profile not found
BETA - Update my profile
PATCH /profiles/me

Request body

Responses

200 Profile updated
Body
404 Profile not found
409 Email address already in use
422 Profile amendment is invalid
V1 - Get my profile
GET /profiles/me

Responses

200 Profile found
Body
404 Profile not found
Folders
DELETE /folders/{id}
GET /folders/{id}
POST /folders/{id}/documents
GET /folders/{id}/documents
POST /folders
DELETE /folders/{id}/documents/{document_id}
V1 - Delete a folder
DELETE /folders/{id}

Path variables

id
string required

Responses

204 Deleted, the folder has been deleted
400 Bad request
403 Forbidden
404 Folder not found
V1 - Update a folder's name, or move it to a new parent
PATCH /folders/{id}

Path variables

id
string required

Request body

Responses

200 OK
Body
400 Bad request
403 Forbidden
404 Folder not found
409 A folder with the same name already exists
V1 - Get a folder
GET /folders/{id}

Path variables

id
string required

Responses

200 OK, body contains the folder
Body
403 Forbidden
V1 - Add a document to a folder
POST /folders/{id}/documents

Path variables

id
string required

Request body

Responses

201 Created, the document has been added to the folder
403 Forbidden
404 Folder or document not found
409 Conflict because document already exists in folder
V1 - Get all document ids from a folder
GET /folders/{id}/documents

Path variables

id
string required

Request parameters

include_trashed
string optional

Whether to include trashed document IDs. Defaults to false.

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 OK, body contains the document IDs
Body
Array of DocumentId
403 Forbidden
V1 - Create a folder
POST /folders

Request body

Responses

201 Created, the folder has been successfully created
Body
400 Invalid folder
403 Forbidden
404 Parent folder not found
409 A folder with the same name already exists
V1 - Get folders for the logged-in user or a group
GET /folders

Request parameters

group_id
string optional

Group ID. If not supplied, returns user documents

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

Responses

200 OK, body contains the folders
Body
Array of Folder
400 Bad request
403 Forbidden
404 Folder not found
V1 - Delete a document from a folder
DELETE /folders/{id}/documents/{document_id}

Path variables

id
string required
document_id
string required

Responses

204 Deleted, the document has been deleted from the folder
403 Forbidden
404 Folder or document not found
409 Conflict because document does not exist in folder
Catalog1
GET /search/catalog
GET /catalog/{catalogId}
Search the catalog
GET /search/catalog

Multiple search fields may be specified. Callers must provide either a query, or at least one of title, author, source or abstract. Setting a minimum or maximum year excludes documents with no defined year.

Request parameters

query
string optional

Query, matches any field

title
string optional

Title

author
string optional

Author

source
string optional

Source, e.g. publication

abstract
string optional

Abstract

min_year
integer optional

Minimum year

max_year
integer optional

Maximum year

open_access
string optional

Open access

view
string optional

View

Enumeration:
bib
stats
client
all
limit
string optional

The maximum number of items on the page. If not supplied, the default is 10. The largest allowable value is 100.

Responses

200 Documents found
Body
400 Invalid parameters supplied
V1 - Get a catalog document
GET /catalog/{catalogId}

Path variables

catalogId
string required

Document ID

Request parameters

view
string optional

View

Enumeration:
bib
stats
client
all

Responses

200 Document found
400 Invalid view requested
404 Document not found
V1 - Get a list of catalog documents by filter
GET /catalog

Request parameters

arxiv
string optional
doi
string optional
isbn
string optional
issn
string optional
pmid
string optional
scopus
string optional
filehash
string optional
view
string optional

View

Enumeration:
bib
stats
client
all

Responses

200 Documents found
Body
400 Invalid view requested
400 No filter specified
Identifier_types
V1 Get available document identifier types
GET /identifier_types

Responses

200 OK
Body
Locations
BETA - Get locations for given prefix
GET /locations

Request parameters

prefix
string optional

First few characters of city name

limit
integer optional

Max results to return (up to 100)

Default:
10

Responses

200 Found locations
Body
Array of Location
400 Prefix missing or too short
403 Client not allowed to access this service
BETA - Get location by ID
GET /locations/{id}

Path variables

id
string required

UUID of the location to retrieve

Responses

200 Location found
Body
404 Location not found
403 Client not allowed to access this service
Documents
GET /documents/{id}
PATCH /documents/{id}
DELETE /documents/{id}
GET /documents
POST /documents
POST /documents/{id}/trash
V1 Get a document
GET /documents/{id}

Path variables

id
string required

Document ID

Request parameters

view
string optional

View

Enumeration:
bib
patent
client
tags
all

Responses

200 Document found
400 Invalid view requested
404 Document not found
V1 Update a document
PATCH /documents/{id}

Path variables

id
string required

Document ID

Request headers

If-Unmodified-Since
string optional

If specified, the document will not be updated if there have been any other changes since this timestamp. Should be specified in RFC 2822 format.

Request body

Responses

200 Document has been updated and the updated version returned
400 The document is invalid
403 Tried to modify the group ID
404 Document not found
412 Update rejected because there has been another update since the If-Unmodified-Since time
V1 Delete a document
DELETE /documents/{id}

Path variables

id
string required

Document ID

Responses

204 Document deleted
404 Document not found
V1 Get documents
GET /documents

Request parameters

group_id
string optional

Group ID. If not supplied, returns user documents

modified_since
string optional

Returns only documents modified since this timestamp. Should be supplied in ISO 8601 format

deleted_since
string optional

Returns only documents deleted since this timestamp. Should be supplied in ISO 8601 format

profile_id
string optional

Returns documents belonging to this profile ID, that do not belong to any group

authored
string optional

Returns publications belonging to the profile ID

starred
string optional

Returns only documents that are starred

view
string optional

View

Enumeration:
bib
patent
client
tags
all
limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 500.

order
string optional

The sort order

Enumeration:
asc
desc
sort
string optional

The field to sort on

Enumeration:
last_modified
created
title

Responses

200 Documents found
Body
Array of UserDocument
400 Invalid view requested
V1 Create a document
POST /documents

Request body

Responses

201 Document created. The URL of the new document can be found in the Location header.
400 The document is invalid.
V1 Move a document to the trash
POST /documents/{id}/trash

Path variables

id
string required

Document ID

Responses

204 Document moved to trash
404 Document not found
BETA - Get institutions matching given hint
GET /institutions

Request parameters

hint
string optional

Part of institution name

limit
integer optional

Max results to return (up to 100)

Default:
10

Responses

200 Found institutions
Body
Array of Institution
400 Hint missing
403 Client not allowed to access this service
BETA - Get institution matching given institution uuid
GET /institutions/{id}

Path variables

id
string required

Institution ID

Responses

200 Found institution
400 Invalid request
404 Institution not found
403 Client not allowed to access this service
Academic_statuses
GET /academic_statuses
V1 - Get available academic statuses
GET /academic_statuses

Responses

200 OK
Body
Catalog2
Get the table of contents, tables and figures for the given document
GET /enrichments/toc/{fileHash}

Get the table of contents, tables and figures for the given document

Path variables

fileHash
string required

Responses

200 TOC found
Body
204 Your request has been accepted, and the document is being processed
200 The document is already being processed
400 Invalid request
500 Error processing request
Annotations
PATCH /annotations/{annotation_id}
DELETE /annotations/{annotation_id}
GET /annotations/{annotation_id}
POST /annotations
V1 - Update an annotation
PATCH /annotations/{annotation_id}

Path variables

annotation_id
string required

Annotation Id

Request body

Responses

200 OK
Body
V1 - Delete an annotation
DELETE /annotations/{annotation_id}

Path variables

annotation_id
string required

Annotation Id

Responses

204 Success, the annotation is deleted
400 Bad request
403 Forbidden
404 Annotation not found
V1 - Get an annotation
GET /annotations/{annotation_id}

Path variables

annotation_id
string required

Annotation Id

Responses

200 OK
Body
V1 - Create an annotation
POST /annotations

Request body

Responses

200 OK
Body
V1 - Get all annotations for a document, profile or group
GET /annotations

Request parameters

document_id
string optional

Document Id

group_id
string optional

Group Id

include_trashed
string optional

Trashed flag

modified_since
string optional

Returns only annotations modified since this timestamp. Should be supplied in ISO 8601 format

deleted_since
string optional

Returns only annotations deleted since this timestamp. Should be supplied in ISO 8601 format

limit
string optional

The maximum number of items on the page. If not supplied, the default is 20. The largest allowable value is 200.

Responses

200 OK
Body
Array of Annotation
Document-from-file
v1 Create a document from an uploaded file
POST /documents

Request headers

Content-Disposition
string required

The content disposition, including the filename (see RFC 1806)

Content-Type
string required

The media type of the file

Link
string optional

To create a group document from a file, add the URL of the group to add this file to. This should have relation "group" (see RFC 5988)

Request body

Responses

201 Document created. The URL of the new document can be found in the Location header.
400 The document title is longer than 256 characters or empty.
403 Forbidden
Data Reference
DocumentTypeDefinition object

Properties

description
string
name
string
Photo object

Properties

original
string
standard
string
square
string
Types: Group Profile
UserRole object

Properties

profile_id
string
role
joined
string
Group object

Properties

id
string
created
string
owning_profile_id
string
link
string
role
string
access_level
photo
webpage
string
disciplines
Array of string
description
string
tags
Array of string
name
string
Discipline object

Properties

name
string
subdisciplines
Array of string
Person object

Properties

first_name
string
last_name
string
UserDocument object

Properties

profile_id
string
group_id
string
last_modified
string
tags
Array of string
read
string
starred
string
authored
string
confirmed
string
hidden
string
citation_key
string
source_type
string
language
string
short_title
string
reprint_edition
string
genre
string
country
string
translators
Array of Person
series_editor
string
code
string
medium
string
user_context
string
patent_owner
string
patent_application_number
string
patent_legal_status
string
accessed
string
created
string
file_attached
string
id
string
year
integer
month
integer
day
integer
source
string
title
string
revision
string
abstract
string
identifiers
Map[com.mendeley.documents.api.IdentifierType,java.lang.String]
authors
Array of Person
keywords
Array of string
pages
string
volume
string
issue
string
websites
Array of string
publisher
string
city
string
edition
string
institution
string
department
string
series
string
chapter
string
editors
Array of Person
type
com.mendeley.documents.api.DocumentType
AnnotatedDocument object

Properties

uri
string
entities
Array of EntityWrapper
empty
string
NamedEntity object

Properties

id
string
classLabel
string
text
string
normalized
string
uri
string
confidence
number
begin
integer
end
integer
positions
Array of Position
categories
Array of Category
description
string
@type
Array of string
nif:referenceContext
string
EntityWrapper object

Properties

entity
type
string
created
integer
lastModified
integer
empty
string
id
string
profileId
integer
Category object

Properties

url
string
label
string
Types: NamedEntity
DocumentLookupResponse object

Properties

catalog_id
string
score
integer
Follow object

Properties

id
string
follower_id
string
followed_id
string
status
com.mendeley.follower.api.Follow$Status
relation_id
string

<b>DEPRECATED</b> (use id instead)

FollowAcceptance object

Properties

status
com.mendeley.follower.api.Follow$Status
FollowRequest object

Properties

followed
string
File object

Properties

id
string
document_id
string
catalog_id
string
filehash
string
mime_type
string
file_name
string
size
integer
Location object

Properties

id
string
latitude
number
longitude
number
name
string
city
string
state
string
country
string
Institution object

Properties

id
string
name
string
city
string
state
string
country
string
uuid
string

<b>DEPRECATED</b> (use id instead)

ProfileAmendment object

Properties

email
string
title
string
password
string
old_password
string
password_reset_token
string
first_name
string
last_name
string
academic_status
string
institution_id
string
location_id
string
biography
string
marketing
string
disciplines
Array of Discipline
research_interests_list
Array of string
ProfileVerification object

Properties

verification_code
string
verification_email
string
Profile object

Properties

id
string
first_name
string
last_name
string
display_name
string
email
string
link
string
institution
string

<b>BETA</b>

institution_details

<b>BETA</b>

research_interests
string

<b>DEPRECATED</b>

research_interests_list
Array of string

<b>BETA</b>

academic_status
string
discipline

<b>DEPRECATED</b>

disciplines
Array of Discipline

<b>BETA</b>

photo

<b>DEPRECATED</b>

photos
Array of Image

<b>BETA</b>

verified
string
marketing
string
user_type
com.mendeley.profiles.api.UserType
location
created
string
education
Array of Education
employment
Array of Employment
title
string

<b>BETA</b>

biography
string

<b>BETA</b>

Education object

Properties

id
string
institution
string

<b>DEPRECATED</b> (use institution_details)

institution_details

<b>BETA</b>

degree
string
start_date
string
end_date
string
website
string
Types: Profile
Image object

Properties

width
integer
height
integer
original
string
url
string
Types: Profile
Employment object

Properties

id
string
institution
string

<b>DEPRECATED</b> (use institution_details)

institution_details

<b>BETA</b>

position
string
start_date
string
end_date
string
website
string
classes
Array of string
is_main_employment
string
Types: Profile
EmailAddress object

Properties

email
string
Folder object

Properties

id
string
name
string
created
string
modified
string
parent_id
string
group_id
string
DocumentId object

Properties

id
string
PatchFolder object

Properties

name
string
parent_id
string
CatalogueDocument object

Properties

link
string
reader_count
integer
reader_count_by_academic_status
Map[java.lang.String,java.lang.Integer]
reader_count_by_subdiscipline
Map[java.lang.String,Map[java.lang.String,java.lang.Integer]]
reader_count_by_country
Map[java.lang.String,java.lang.Integer]
group_count
integer
created
string
accessed
string
file_attached
string
id
string
year
integer
month
integer
day
integer
source
string
title
string
revision
string
abstract
string
identifiers
Map[com.mendeley.documents.api.IdentifierType,java.lang.String]
volume
string
authors
Array of Person
keywords
Array of string
pages
string
issue
string
websites
Array of string
publisher
string
city
string
edition
string
institution
string
department
string
series
string
chapter
string
editors
Array of Person
type
com.mendeley.documents.api.DocumentType
IdentifierTypeDefinition object

Properties

description
string
name
string
UserDocumentAmendment object

Properties

profile_id
string
tags
Array of string
read
string
starred
string
authored
string
confirmed
string
hidden
string
citation_key
string
source_type
string
language
string
short_title
string
reprint_edition
string
genre
string
country
string
translators
Array of Person
series_editor
string
code
string
medium
string
user_context
string
department
string
patent_owner
string
patent_application_number
string
patent_legal_status
string
year
integer
month
integer
day
integer
source
string
title
string
revision
string
abstract
string
identifiers
Map[com.mendeley.documents.api.IdentifierType,java.lang.String]
accessed
string
authors
Array of Person
keywords
Array of string
pages
string
volume
string
issue
string
websites
Array of string
publisher
string
city
string
edition
string
institution
string
series
string
chapter
string
editors
Array of Person
type
com.mendeley.documents.api.DocumentType
NewUserDocument object

Properties

profile_id
string
group_id
string
tags
Array of string
read
string
starred
string
authored
string
confirmed
string
hidden
string
citation_key
string
source_type
string
language
string
short_title
string
reprint_edition
string
genre
string
country
string
translators
Array of Person
series_editor
string
code
string
medium
string
user_context
string
department
string
patent_owner
string
patent_application_number
string
patent_legal_status
string
year
integer
month
integer
day
integer
source
string
title
string
revision
string
abstract
string
identifiers
Map[com.mendeley.documents.api.IdentifierType,java.lang.String]
accessed
string
authors
Array of Person
keywords
Array of string
pages
string
volume
string
issue
string
websites
Array of string
publisher
string
city
string
edition
string
institution
string
series
string
chapter
string
editors
Array of Person
type
com.mendeley.documents.api.DocumentType
AcademicStatusDefinition object

Properties

description
string
StructureElement object

Properties

id
integer
positions
Array of PdfPosition
label
string
annotationIds
Array of string
BoundingBox object

Properties

minx
number
miny
number
maxx
number
maxy
number
TOCWrapper object

Properties

type
string
created
integer
lastModified
integer
empty
string
PdfPosition object

Properties

offsets
Array of int
boundingBox
pageId
integer
TableOfContents object

Properties

elements
Types: TOCWrapper
Position object

Properties

x
number
y
number
Types: NamedEntity
AnnotationPatch object

Properties

color
text
string
positions
Array of BoundingBox
privacy_level
com.mendeley.platform.PrivacyLevel
filehash
string
Annotation object

Properties

id
string
type
com.mendeley.platform.model.AnnotationType
previous_id
string
color
text
string
profile_id
string
positions
Array of BoundingBox
created
string
last_modified
string
privacy_level
com.mendeley.platform.PrivacyLevel
filehash
string
document_id
string
Color object

Properties

r
integer
g
integer
b
integer
role string
string
Enumeration:
owner
admin
normal
invited
follower
Types: UserRole
access_level string
string
Enumeration:
public
private
invite_only
Types: Group