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

unknown

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

unknown

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
description
string
name
string
Photo
Object
original
string
standard
string
square
string
Types: Group Profile
UserRole
Object
profile_id
string
role
joined
string
Group
Object
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
name
string
subdisciplines
Array of string
Person
Object
first_name
string
last_name
string
UserDocument
Object
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
uri
string
entities
Array of EntityWrapper
empty
string
NamedEntity
Object
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
entity
type
string
created
integer
lastModified
integer
empty
string
id
string
profileId
integer
Category
Object
url
string
label
string
Types: NamedEntity
DocumentLookupResponse
Object
catalog_id
string
score
integer
Follow
Object
id
string
follower_id
string
followed_id
string
status
com.mendeley.follower.api.Follow$Status
relation_id
string

DEPRECATED (use id instead)

FollowAcceptance
Object
status
com.mendeley.follower.api.Follow$Status
FollowRequest
Object
followed
string
File
Object
id
string
document_id
string
catalog_id
string
filehash
string
mime_type
string
file_name
string
size
integer
Location
Object
id
string
latitude
number
longitude
number
name
string
city
string
state
string
country
string
Institution
Object
id
string
name
string
city
string
state
string
country
string
uuid
string

DEPRECATED (use id instead)

ProfileAmendment
Object
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
verification_code
string
verification_email
string
Profile
Object
id
string
first_name
string
last_name
string
display_name
string
email
string
link
string
institution
string

BETA

institution_details

BETA

research_interests
string

DEPRECATED

research_interests_list
Array of string

BETA

academic_status
string
discipline

DEPRECATED

disciplines
Array of Discipline

BETA

photo

DEPRECATED

photos
Array of Image

BETA

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

BETA

biography
string

BETA

Education
Object
id
string
institution
string

DEPRECATED (use institution_details)

institution_details

BETA

degree
string
start_date
string
end_date
string
website
string
Types: Profile
Image
Object
width
integer
height
integer
original
string
url
string
Types: Profile
Employment
Object
id
string
institution
string

DEPRECATED (use institution_details)

institution_details

BETA

position
string
start_date
string
end_date
string
website
string
classes
Array of string
is_main_employment
string
Types: Profile
EmailAddress
Object
email
string
Folder
Object
id
string
name
string
created
string
modified
string
parent_id
string
group_id
string
PatchFolder
Object
name
string
parent_id
string
CatalogueDocument
Object
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
description
string
name
string
UserDocumentAmendment
Object
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
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
description
string
StructureElement
Object
id
integer
positions
Array of PdfPosition
label
string
annotationIds
Array of string
BoundingBox
Object
minx
number
miny
number
maxx
number
maxy
number
TOCWrapper
Object
type
string
created
integer
lastModified
integer
empty
string
PdfPosition
Object
offsets
Array of int
boundingBox
pageId
integer
TableOfContents
Object
elements
Types: TOCWrapper
Position
Object
x
number
y
number
Types: NamedEntity
AnnotationPatch
Object
color
text
string
positions
Array of BoundingBox
privacy_level
com.mendeley.platform.PrivacyLevel
filehash
string
Annotation
Object
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
r
integer
g
integer
b
integer
role
string
Enumeration:
owner
admin
normal
invited
follower
Types: UserRole
access_level
string
Enumeration:
public
private
invite_only
Types: Group