@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Figshare API
@base https://api.figshare.com/v2
@version 2.0
@auth OAuth2
@endpoints 157
@hint download_for_search
@toc altmetric(1), articles(12), account(121), collections(6), institutions(1), institution(1), token(2), item_types(1), categories(1), licenses(1), file(1), projects(4), symplectic(5)

@group altmetric
@endpoint GET /altmetric/institutions
@optional {offset: int=0}
@returns(200)
@errors {400, 500}

@endgroup

@group articles
@endpoint GET /articles
@optional {X-Cursor: str, page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/created_date/modified_date/views/shares/downloads/cites)=published_date, order_direction: str(asc/desc)=desc, institution: int, published_since: str, modified_since: str, group: int, resource_doi: str, item_type: int, doi: str, handle: str}
@returns(200)
@errors {400, 422, 500}

@endpoint POST /articles/search
@optional {X-Cursor: str, resource_doi: str, item_type: int, doi: str, handle: str, project_id: int, order: str(created_date/published_date/modified_date/views/shares/downloads/cites)=created_date}
@returns(200)
@errors {400, 422, 500}

@endpoint GET /articles/{article_id}
@required {article_id: int}
@returns(200) {figshare_url: str(url), download_disabled: bool, files: [map], folder_structure: map, authors: [map], custom_fields: [map], embargo_options: [map]}
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/versions
@required {article_id: int}
@returns(200)
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/versions/{version_id}
@required {article_id: int, version_id: int}
@returns(200) {figshare_url: str(url), download_disabled: bool, files: [map], folder_structure: map, authors: [map], custom_fields: [map], embargo_options: [map]}
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/versions/{version_id}/files
@required {article_id: int, version_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/download
@required {article_id: int}
@optional {folder_path: str}
@returns(200)
@errors {500}

@endpoint GET /articles/{article_id}/versions/{version_id}/download
@required {article_id: int, version_id: int}
@optional {folder_path: str}
@returns(200)
@errors {500}

@endpoint GET /articles/{article_id}/versions/{version_id}/embargo
@required {article_id: int, version_id: int}
@returns(200) {is_embargoed: bool, embargo_title: str, embargo_reason: str, embargo_options: [map]}
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/versions/{version_id}/confidentiality
@required {article_id: int, version_id: int}
@returns(200) {is_confidential: bool, reason: str}
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/files
@required {article_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 404, 500}

@endpoint GET /articles/{article_id}/files/{file_id}
@required {article_id: int, file_id: int}
@returns(200) {id: int, name: str, size: int, is_link_only: bool, download_url: str(url), supplied_md5: str, computed_md5: str, mimetype: str}
@errors {400, 404, 500}

@endgroup

@group account
@endpoint POST /account/articles/search
@optional {resource_id: str}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/articles
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/articles
@required {title: str}
@optional {description: str=, is_metadata_record: bool, metadata_reason: str, tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], categories: [int], categories_by_source_id: [str], authors: [map{}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], defined_type: str, funding: str=, funding_list: [map{id: int, title: str}], license: int=0, doi: str=, handle: str=, resource_doi: str=, resource_title: str=, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}, group_id: int}
@returns(201) {entity_id: int, location: str(url), warnings: [str]}
@errors {400, 403, 500}

@endpoint GET /account/articles/{article_id}
@required {article_id: int}
@returns(200) {account_id: int, curation_status: str}
@errors {400, 403, 404, 500}

@endpoint PUT /account/articles/{article_id}
@required {article_id: int}
@optional {title: str, description: str=, is_metadata_record: bool, metadata_reason: str, tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], categories: [int], categories_by_source_id: [str], authors: [map{}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], defined_type: str, funding: str=, funding_list: [map{id: int, title: str}], license: int=0, doi: str=, handle: str=, resource_doi: str=, resource_title: str=, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}, download_disabled: bool, group_id: int}
@returns(205) {location: str(url), warnings: [str]}
@errors {403, 404, 500}

@endpoint DELETE /account/articles/{article_id}
@required {article_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint PATCH /account/articles/{article_id}
@required {article_id: int}
@optional {title: str, description: str=, is_metadata_record: bool, metadata_reason: str, tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], categories: [int], categories_by_source_id: [str], authors: [map{}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], defined_type: str, funding: str=, funding_list: [map{id: int, title: str}], license: int=0, doi: str=, handle: str=, resource_doi: str=, resource_title: str=, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}, download_disabled: bool, group_id: int}
@returns(205) {location: str(url), warnings: [str]}
@errors {403, 404, 500}

@endpoint GET /account/articles/{article_id}/embargo
@required {article_id: int}
@returns(200) {is_embargoed: bool, embargo_title: str, embargo_reason: str, embargo_options: [map]}
@errors {400, 403, 404, 500}

@endpoint PUT /account/articles/{article_id}/embargo
@required {article_id: int, is_embargoed: bool, embargo_date: str, embargo_type: str(article/file)}
@optional {embargo_title: str, embargo_reason: str, embargo_options: [map{}]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/articles/{article_id}/embargo
@required {article_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint POST /account/articles/{article_id}/resource
@required {article_id: int}
@optional {id: str=, title: str=, doi: str=, link: str=, status: str=, version: int=0}
@returns(205) {location: str(url)}
@errors {400, 403, 404, 422}

@endpoint POST /account/articles/{article_id}/publish
@required {article_id: int}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/unpublish
@required {article_id: int, reason: str}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/reserve_doi
@required {article_id: int}
@returns(200) {doi: str}
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/reserve_handle
@required {article_id: int}
@returns(200) {handle: str}
@errors {400, 403, 404, 500}

@endpoint GET /account/articles/{article_id}/download
@required {article_id: int}
@optional {folder_path: str}
@returns(200)
@errors {403, 500}

@endpoint PUT /account/articles/{article_id}/versions/{version_id}
@required {article_id: int, version_id: int}
@optional {supplementary_fields: [map{}], internal_metadata: map{}}
@returns(205) {location: str(url), warnings: [str]}
@errors {403, 404, 500}

@endpoint PATCH /account/articles/{article_id}/versions/{version_id}
@required {article_id: int, version_id: int}
@optional {supplementary_fields: [map{}], internal_metadata: map{}}
@returns(205) {location: str(url), warnings: [str]}
@errors {403, 404, 500}

@endpoint PUT /account/articles/{article_id}/versions/{version_id}/update_thumb
@required {article_id: int, version_id: int}
@optional {file_id: int}
@returns(205)
@errors {403, 404, 422}

@endpoint GET /account/articles/{article_id}/authors
@required {article_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint PUT /account/articles/{article_id}/authors
@required {article_id: int, authors: [map{}]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/authors
@required {article_id: int, authors: [map{}]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/articles/{article_id}/authors/{author_id}
@required {article_id: int, author_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint GET /account/articles/{article_id}/categories
@required {article_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint PUT /account/articles/{article_id}/categories
@required {article_id: int, categories: [int]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/categories
@required {article_id: int, categories: [int]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/articles/{article_id}/categories/{category_id}
@required {article_id: int, category_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint GET /account/articles/{article_id}/confidentiality
@required {article_id: int}
@returns(200) {is_confidential: bool, reason: str}
@errors {400, 403, 404, 500}

@endpoint PUT /account/articles/{article_id}/confidentiality
@required {article_id: int, reason: str}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/articles/{article_id}/confidentiality
@required {article_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/articles/{article_id}/private_links
@required {article_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/private_links
@required {article_id: int}
@optional {expires_date: str}
@returns(201) {location: str(url), html_location: str(url), token: str}
@errors {400, 403, 404, 422, 500}

@endpoint PUT /account/articles/{article_id}/private_links/{link_id}
@required {article_id: int, link_id: str}
@optional {expires_date: str}
@returns(205)
@errors {400, 403, 404, 422, 500}

@endpoint DELETE /account/articles/{article_id}/private_links/{link_id}
@required {article_id: int, link_id: str}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/articles/{article_id}/files
@required {article_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/files
@required {article_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int, link: str, md5: str, name: str, size: int, folder_path: str}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 422, 500}

@endpoint GET /account/articles/{article_id}/files/{file_id}
@required {article_id: int, file_id: int}
@returns(200) {viewer_type: str, preview_state: str, upload_url: str(url), upload_token: str, is_attached_to_public_version: bool}
@errors {400, 403, 404, 500}

@endpoint POST /account/articles/{article_id}/files/{file_id}
@required {article_id: int, file_id: int}
@returns(202)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/articles/{article_id}/files/{file_id}
@required {article_id: int, file_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/articles/export
@optional {group_id: int}
@returns(200)
@errors {400, 500}

@endpoint POST /account/articles/export
@returns(200) {id: int, account_id: int, created_date: str, status: str, download_url: str(url), group_id: int}
@errors {429, 500}

@endpoint POST /account/authors/search
@optional {search_for: str, page: int, page_size: int=10, limit: int, offset: int, institution_id: int, orcid: str, group_id: int, is_active: bool, is_public: bool}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/authors/{author_id}
@required {author_id: int}
@returns(200) {institution_id: int, group_id: int, first_name: str, last_name: str, is_public: int, job_title: str}
@errors {400, 403, 404, 500}

@endgroup

@group collections
@endpoint GET /collections
@optional {X-Cursor: str, page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/created_date/modified_date/views/shares/cites)=published_date, order_direction: str(asc/desc)=desc, institution: int, published_since: str, modified_since: str, group: int, resource_doi: str, doi: str, handle: str}
@returns(200)
@errors {400, 422, 500}

@endpoint POST /collections/search
@optional {X-Cursor: str, resource_doi: str, doi: str, handle: str, order: str(created_date/published_date/modified_date/views/shares/cites)=created_date}
@returns(200)
@errors {400, 422, 500}

@endpoint GET /collections/{collection_id}
@required {collection_id: int}
@returns(200) {funding: [map], resource_id: str, resource_doi: str, resource_title: str, resource_link: str, resource_version: int, version: int, description: str, categories: [map], references: [str(url)], related_materials: [map], tags: [str], keywords: [str], authors: [map], institution_id: int, group_id: int, articles_count: int, public: bool, citation: str, custom_fields: [map], modified_date: str, created_date: str, timeline: any}
@errors {400, 404, 500}

@endpoint GET /collections/{collection_id}/versions
@required {collection_id: int}
@returns(200)
@errors {400, 404, 500}

@endpoint GET /collections/{collection_id}/versions/{version_id}
@required {collection_id: int, version_id: int}
@returns(200) {funding: [map], resource_id: str, resource_doi: str, resource_title: str, resource_link: str, resource_version: int, version: int, description: str, categories: [map], references: [str(url)], related_materials: [map], tags: [str], keywords: [str], authors: [map], institution_id: int, group_id: int, articles_count: int, public: bool, citation: str, custom_fields: [map], modified_date: str, created_date: str, timeline: any}
@errors {400, 404, 500}

@endpoint GET /collections/{collection_id}/articles
@required {collection_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 404, 422, 500}

@endgroup

@group account
@endpoint GET /account/collections
@optional {page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/modified_date/views/shares/cites)=published_date, order_direction: str(asc/desc)=desc}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/collections
@required {title: str}
@optional {funding: str=, funding_list: [map{id: int, title: str}], description: str=, articles: [int], authors: [map{}], categories: [int], categories_by_source_id: [str], tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], doi: str=, handle: str=, resource_id: str, resource_doi: str=, resource_link: str, resource_title: str=, resource_version: int, group_id: int, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}}
@returns(201) {entity_id: int, location: str(url), warnings: [str]}
@errors {400, 403, 500}

@endpoint GET /account/collections/{collection_id}
@required {collection_id: int}
@returns(200) {account_id: int, funding: [map], resource_id: str, resource_doi: str, resource_title: str, resource_link: str, resource_version: int, version: int, description: str, categories: [map], references: [str(url)], related_materials: [map], tags: [str], keywords: [str], authors: [map], institution_id: int, group_id: int, articles_count: int, public: bool, citation: str, custom_fields: [map], modified_date: str, created_date: str, timeline: any}
@errors {400, 404, 500}

@endpoint PUT /account/collections/{collection_id}
@required {collection_id: int}
@optional {funding: str=, funding_list: [map{id: int, title: str}], title: str, description: str=, articles: [int], authors: [map{}], categories: [int], categories_by_source_id: [str], tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], doi: str=, handle: str=, resource_id: str, resource_doi: str=, resource_link: str, resource_title: str=, resource_version: int, group_id: int, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}}
@returns(205) {location: str(url), warnings: [str]}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/collections/{collection_id}
@required {collection_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint PATCH /account/collections/{collection_id}
@required {collection_id: int}
@optional {funding: str=, funding_list: [map{id: int, title: str}], title: str, description: str=, articles: [int], authors: [map{}], categories: [int], categories_by_source_id: [str], tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], doi: str=, handle: str=, resource_id: str, resource_doi: str=, resource_link: str, resource_title: str=, resource_version: int, group_id: int, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}}
@returns(205) {location: str(url), warnings: [str]}
@errors {400, 403, 404, 500}

@endpoint POST /account/collections/search
@optional {resource_id: str}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/collections/{collection_id}/reserve_doi
@required {collection_id: int}
@returns(200) {doi: str}
@errors {400, 403, 500}

@endpoint POST /account/collections/{collection_id}/reserve_handle
@required {collection_id: int}
@returns(200) {handle: str}
@errors {400, 403, 500}

@endpoint POST /account/collections/{collection_id}/resource
@required {collection_id: int}
@optional {id: str=, title: str=, doi: str=, link: str=, status: str=, version: int=0}
@returns(205) {location: str(url)}
@errors {403, 404, 422}

@endpoint POST /account/collections/{collection_id}/publish
@required {collection_id: int}
@returns(201) {location: str(url)}
@errors {400, 403, 500}

@endpoint GET /account/collections/{collection_id}/authors
@required {collection_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint PUT /account/collections/{collection_id}/authors
@required {collection_id: int, authors: [map{}]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint POST /account/collections/{collection_id}/authors
@required {collection_id: int, authors: [map{}]}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/collections/{collection_id}/authors/{author_id}
@required {collection_id: int, author_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint GET /account/collections/{collection_id}/categories
@required {collection_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint PUT /account/collections/{collection_id}/categories
@required {collection_id: int, categories: [int]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint POST /account/collections/{collection_id}/categories
@required {collection_id: int, categories: [int]}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/collections/{collection_id}/categories/{category_id}
@required {collection_id: int, category_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint GET /account/collections/{collection_id}/articles
@required {collection_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint PUT /account/collections/{collection_id}/articles
@required {collection_id: int, articles: [int]}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint POST /account/collections/{collection_id}/articles
@required {collection_id: int, articles: [int]}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/collections/{collection_id}/articles/{article_id}
@required {collection_id: int, article_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint GET /account/collections/{collection_id}/private_links
@required {collection_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/collections/{collection_id}/private_links
@required {collection_id: int}
@optional {expires_date: str}
@returns(201) {location: str(url), html_location: str(url), token: str}
@errors {400, 403, 404, 500}

@endpoint GET /account/collections/{collection_id}/private_links/{link_id}
@required {collection_id: int, link_id: str}
@returns(200) {id: str, is_active: bool, expires_date: str, html_location: str(url)}
@errors {400, 403, 404, 500}

@endpoint PUT /account/collections/{collection_id}/private_links/{link_id}
@required {collection_id: int, link_id: str}
@optional {expires_date: str}
@returns(205)
@errors {400, 403, 404, 422, 500}

@endpoint DELETE /account/collections/{collection_id}/private_links/{link_id}
@required {collection_id: int, link_id: str}
@returns(204)
@errors {400, 403, 404, 500}

@endgroup

@group institutions
@endpoint GET /institutions/{institution_string_id}/articles/filter-by
@required {institution_string_id: str, resource_id: str, filename: str}
@returns(200)
@errors {500}

@endgroup

@group account
@endpoint GET /account/institution
@returns(200) {id: int, name: str}
@errors {400, 403, 500}

@endpoint GET /account/institution/embargo_options
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/articles
@optional {page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/modified_date)=published_date, order_direction: str(asc/desc)=desc, published_since: str, modified_since: str, status: int, resource_doi: str, item_type: int, group: int}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/custom_fields
@optional {group_id: int}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/institution/custom_fields/{custom_field_id}/items/upload
@required {custom_field_id: int}
@returns(200)
@errors {400, 403, 409, 500}

@endpoint GET /account/categories
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/groups
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/groups/{group_id}/embargo_options
@required {group_id: int}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/roles
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/accounts
@optional {page: int, page_size: int=10, limit: int, offset: int, is_active: int, institution_user_id: str, email: str, id_lte: int, id_gte: int}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/institution/accounts
@required {email: str, last_name: str=}
@optional {first_name: str=, group_id: int, institution_user_id: str=, symplectic_user_id: str=, quota: int, is_active: bool}
@returns(201) {account_id: int}
@errors {400, 403, 500}

@endpoint GET /account/institution/accounts/{account_id}
@required {account_id: int}
@returns(200) {id: int, first_name: str, last_name: str, used_quota_private: int, modified_date: str, used_quota: int, created_date: str, quota: int, group_id: int, institution_user_id: str, institution_id: int, email: str, used_quota_public: int, pending_quota_request: bool, active: int, maximum_file_size: int, user_id: int, orcid_id: str, symplectic_user_id: str}
@errors {400, 403, 404, 500}

@endpoint PUT /account/institution/accounts/{account_id}
@required {account_id: int, group_id: int, is_active: bool}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint GET /account/institution/roles/{account_id}
@required {account_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/institution/roles/{account_id}
@required {account_id: int}
@returns(201)
@errors {400, 403, 500}

@endpoint DELETE /account/institution/roles/{account_id}/{group_id}/{role_id}
@required {account_id: int, group_id: int, role_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint POST /account/institution/accounts/search
@optional {search_for: str, is_active: int, page: int, page_size: int=10, limit: int, offset: int, institution_user_id: str, email: str}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account/institution/users/{account_id}
@required {account_id: int}
@returns(200) {id: int, first_name: str, last_name: str, name: str, is_active: bool, url_name: str, is_public: bool, job_title: str, orcid_id: str}
@errors {400, 403, 404, 500}

@endpoint GET /account/institution/reviews
@optional {group_id: int, article_id: int, status: str(pending/approved/rejected/closed), limit: int, offset: int}
@returns(200) {id: int, group_id: int, account_id: int, assigned_to: int, article_id: int, version: int, comments_count: int, status: str, created_date: str, modified_date: str, request_number: int, resolution_comment: str}
@errors {400, 403, 404, 500}

@endpoint GET /account/institution/review/{curation_id}
@required {curation_id: int}
@returns(200) {item: any}
@errors {400, 403, 404, 500}

@endpoint GET /account/institution/review/{curation_id}/comments
@required {curation_id: int}
@optional {limit: int, offset: int}
@returns(200) {id: int, account_id: int, type: str, text: str, created_date: str, modified_date: str}
@errors {400, 403, 404, 500}

@endpoint POST /account/institution/review/{curation_id}/comments
@required {curation_id: int, text: str}
@returns(200)
@errors {400, 403, 404, 500}

@endgroup

@group institution
@endpoint POST /institution/hrfeed/upload
@returns(200) {message: str}
@errors {400, 403, 500}

@endgroup

@group token
@endpoint GET /token
@optional {access_token: str}
@returns(200) {access_token: str, token: str, token_type: str, expires_in: int, refresh_token: str, scope: str}
@errors {400, 403}

@endpoint POST /token
@required {client_id: str, client_secret: str, grant_type: str(authorization_code/refresh_token/password/client_credentials)}
@optional {code: str, refresh_token: str, username: str, password: str}
@returns(200) {access_token: str, token: str, token_type: str, expires_in: int, refresh_token: str, scope: str}
@errors {400}

@endgroup

@group item_types
@endpoint GET /item_types
@optional {group_id: int=0}
@returns(200)
@errors {400, 403, 404, 500}

@endgroup

@group account
@endpoint POST /account/funding/search
@optional {search_for: str}
@returns(200)
@errors {400, 403, 500}

@endpoint GET /account
@returns(200) {id: int, first_name: str, last_name: str, used_quota_private: int, modified_date: str, used_quota: int, created_date: str, quota: int, group_id: int, institution_user_id: str, institution_id: int, email: str, used_quota_public: int, pending_quota_request: bool, active: int, maximum_file_size: int, user_id: int, orcid_id: str, symplectic_user_id: str}
@errors {403, 500}

@endgroup

@group categories
@endpoint GET /categories
@returns(200)
@errors {500}

@endgroup

@group licenses
@endpoint GET /licenses
@returns(200)
@errors {500}

@endgroup

@group account
@endpoint GET /account/licenses
@returns(200)
@errors {400, 403, 500}

@endgroup

@group file
@endpoint GET /file/download/{file_id}
@required {file_id: int}
@returns(200)
@errors {500}

@endgroup

@group account
@endpoint PUT /account/profile
@optional {user_id: int, institution_user_id: str, first_name: str, last_name: str, orcid: str, job_title: str, fields_of_interest: [int], fields_of_interest_by_source_id: [str], location: str, facebook: str(url), x: str(url), linkedin: str(url), bio: str, personal_profiles: [map{label: str, url: str(url)}]}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/profile/{user_id}/picture
@required {user_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endgroup

@group projects
@endpoint GET /projects
@optional {X-Cursor: str, page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/modified_date/views)=published_date, order_direction: str(asc/desc)=desc, institution: int, published_since: str, group: int}
@returns(200)
@errors {400, 422, 500}

@endpoint POST /projects/search
@optional {X-Cursor: str, order: str(published_date/modified_date/views)=published_date}
@returns(200)
@errors {400, 422, 500}

@endpoint GET /projects/{project_id}
@required {project_id: int}
@returns(200) {funding: str, funding_list: [map], description: str, collaborators: [map], custom_fields: [map], modified_date: str, created_date: str}
@errors {400, 404, 500}

@endpoint GET /projects/{project_id}/articles
@required {project_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 404, 500}

@endgroup

@group account
@endpoint POST /account/projects/search
@optional {order: str(published_date/modified_date/views)=published_date}
@returns(200)
@errors {400, 422, 500}

@endpoint GET /account/projects
@optional {page: int, page_size: int=10, limit: int, offset: int, order: str(published_date/modified_date/views)=published_date, order_direction: str(asc/desc)=desc, storage: str(group/individual), roles: str}
@returns(200)
@errors {400, 403, 500}

@endpoint POST /account/projects
@required {title: str}
@optional {description: str, funding: str, funding_list: [map{id: int, title: str}], group_id: int, custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}]}
@returns(201) {entity_id: int, location: str(url)}
@errors {400, 403, 500}

@endpoint GET /account/projects/{project_id}
@required {project_id: int}
@returns(200) {funding: str, funding_list: [map], description: str, collaborators: [map], quota: int, used_quota: int, created_date: str, modified_date: str, used_quota_private: int, used_quota_public: int, group_id: int, account_id: int, custom_fields: [map]}
@errors {400, 403, 404, 500}

@endpoint PUT /account/projects/{project_id}
@required {project_id: int}
@optional {title: str, description: str, funding: str, funding_list: [map{id: int, title: str}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}]}
@returns(205)
@errors {403, 404, 500}

@endpoint DELETE /account/projects/{project_id}
@required {project_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint PATCH /account/projects/{project_id}
@required {project_id: int}
@optional {title: str, description: str, funding: str, funding_list: [map{id: int, title: str}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}]}
@returns(205)
@errors {403, 404, 500}

@endpoint POST /account/projects/{project_id}/publish
@required {project_id: int}
@returns(200) {message: str}
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/notes
@required {project_id: int}
@optional {page: int, page_size: int=10, limit: int, offset: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/projects/{project_id}/notes
@required {project_id: int, text: str}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/notes/{note_id}
@required {project_id: int, note_id: int}
@returns(200) {text: str}
@errors {400, 403, 404, 500}

@endpoint PUT /account/projects/{project_id}/notes/{note_id}
@required {project_id: int, note_id: int, text: str}
@returns(205)
@errors {400, 403, 404, 500}

@endpoint DELETE /account/projects/{project_id}/notes/{note_id}
@required {project_id: int, note_id: int}
@returns(204)
@errors {403, 404, 500}

@endpoint POST /account/projects/{project_id}/leave
@required {project_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/collaborators
@required {project_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/projects/{project_id}/collaborators
@required {project_id: int, role_name: str(viewer/collaborator)}
@optional {user_id: int, email: str, comment: str}
@returns(201) {message: str}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/projects/{project_id}/collaborators/{user_id}
@required {project_id: int, user_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/articles
@required {project_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint POST /account/projects/{project_id}/articles
@required {project_id: int, title: str}
@optional {description: str=, tags: [str], keywords: [str], references: [str(link)], related_materials: [map{id: int, identifier: str, title: str, relation: str, identifier_type: str, is_linkout: bool, link: str}], categories: [int], categories_by_source_id: [str], authors: [map{}], custom_fields: map{}, custom_fields_list: [map{name!: str, value!: any}], defined_type: str, funding: str=, funding_list: [map{id: int, title: str}], license: int=0, doi: str=, handle: str=, resource_doi: str=, resource_title: str=, timeline: map{firstOnline: str, publisherPublication: str, publisherAcceptance: str}}
@returns(201) {location: str(url)}
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/articles/{article_id}
@required {project_id: int, article_id: int}
@returns(200) {account_id: int, curation_status: str}
@errors {400, 403, 404, 500}

@endpoint DELETE /account/projects/{project_id}/articles/{article_id}
@required {project_id: int, article_id: int}
@returns(204)
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/articles/{article_id}/files
@required {project_id: int, article_id: int}
@returns(200)
@errors {400, 403, 404, 500}

@endpoint GET /account/projects/{project_id}/articles/{article_id}/files/{file_id}
@required {project_id: int, article_id: int, file_id: int}
@returns(200) {viewer_type: str, preview_state: str, upload_url: str(url), upload_token: str, is_attached_to_public_version: bool}
@errors {400, 403, 404, 500}

@endgroup

@group symplectic
@endpoint GET /symplectic/articles
@required {since: str}
@optional {offset: int=0, limit: int=10, status: str(public/private/draft), is_embargoed: str(true/false)}
@returns(200)
@errors {400, 401, 403}

@endpoint GET /symplectic/users/{user_id}
@required {user_id: int}
@returns(200) {institutionUserId: str}
@errors {401, 403, 404}

@endpoint GET /symplectic/articles/{article_id}
@required {article_id: int}
@returns(200)
@errors {401, 403, 404}

@endpoint GET /symplectic/accounts/{external_user_id}/articles
@required {external_user_id: str}
@optional {offset: int=0, limit: int=10, status: str(public/private/draft), is_embargoed: str(true/false)}
@returns(200)
@errors {401, 403, 404}

@endpoint GET /symplectic/accounts
@required {since: str}
@returns(200)
@errors {400, 401, 403}

@endgroup

@end