Authentication
There are two types of access tokens: client and oauth
- CLIENT_ACCESS_TOKEN - The cleint token allows you to access public content and private content of client user(user who created the client). You can get the client token on
https://www.protocols.io/developers
. - OAUTH_ACCESS_TOKEN - The oauth token gives acccess to specific user's private content (as well as all public content). To get oauth token use OAuth authentication.
Most of endpoints require Authentication header with Bearer access token. Example:
Authentication: Bearer b2e9570895ae57efdc495e1ac27feb12e856aec9f354bb12aa0ceaa3b761f11a
Authorize protocols.io user (OAuth 2.0)
Example of authorize link
https://www.protocols.io/api/v3/oauth/authorize?client_id=[your_client_id]&redirect_url=[your_redirect_url]&response_type=code&scope=readwrite&state=[your_state]
- Open
http://www.protocols.io/developers
and copy yourclient_id
andclient_secret
. - Provide your redirect url under
private access
block. - Put authorization link inside your apication.
- Your requests will be redirected to
[your_redirect_url]?code=[new_code]&scope=[your_scope]
. - Use the code to get user OAUTH_ACCESS_TOKEN by calling
https://www.protocols.io/api/v3/oauth/token
withgrant_type: authorization_code
.
Attention Mac users
You can pass the --compressed
flag when performing curl command in the terminal. It will allow you to get the uncompressed text output instead of compressed binary data. Example:
curl “https://www.protocols.io/api/v3/publications?latest=1” -H “Authorization: CLIENT_ACCESS_TOKEN” --compressed
Refresh access token
You will receive a warning 1 month before OAUTH_ACCESS_TOKEN expires.
"HTTP/1.1 200 Ok"
{
"status_code": 0,
...
"warning_code": 1,
"warning_message": "Your access token expires in 24 days"
}
Once OAUTH_ACCESS_TOKEN expires you will get an error:
"HTTP/1.1 400 Bad Request"
{
"status_code": 1219,
"error_message": "token is expired"
}
Call https://www.protocols.io/api/v3/oauth/token
grant_type: refresh_token
to obtain a new OAUTH_ACCESS_TOKEN.
OAuth
Authorization Link
Authorization link redirects users to protocols.io and asks them to login with their credentials. Once done they will be redirected to "redirect_url" with the new access code.
Create an authorization link using the next template:
https://www.protocols.io/api/v3/oauth/authorize?client_id=[your_client_id]&redirect_url=[your_redirect_url]&response_type=code&scope=readwrite&state=[your_state]
Get access token
Example Request | obtain token by code
curl https://www.protocols.io/api/v3/oauth/token
-d client_id=<client_id>
-d client_secret=<client_secret>
-d grant_type=authorization_code
-d code=<code>
Example Request | obtain token by refresh token
curl https://www.protocols.io/api/v3/oauth/token
-d client_id=<client_id>
-d client_secret=<client_secret>
-d grant_type=refresh_token
-d refresh_token=<refresh_token>
returns the following JSON:
{
"access_token": "b3656ef91016d67bfc4bb9f983d4450f2baa99b0fca7f2665d456cc14e5d1441",
"token_type": "bearer",
"expires_in": "30681976",
"scope": "readwrite",
"refresh_token": "5acce557aebbd287cf371371ead660e44ebc889cb711c67c3b25b9af2beb0184",
"refresh_expires_in": "62217976",
"user": {
"name": "Vladimir Frolov",
"affiliation": null,
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
},
"status_code": 0
}
This method retrieves OAUTH_ACCESS_TOKEN
HTTP Request
POST https://www.protocols.io/api/v3/oauth/token
API Parameters
authorization_code
or refresh_token
.
authorization_code
grant_typerefresh_token
grant_type
Response
user
Get client
Example Request
curl https://www.protocols.io/api/v3/oauth/clients/<client_id>
-H "Authorization: Bearer [CLIENT_ACCESS_TOKEN]"
returns the following JSON:
{
"status_code": 0,
"client": {
"client_id": "pr_live_id_lhk123jlasd",
"client_secret": "pr_live_sc_d12gasdf12",
"grant_type": "authorization_code",
"scope": "readwrite",
"redirect_url": "http://www.protocols.io/api/v3/oauth/test",
"token": "8f0f5044f18ebdd0da480b423673ac35"
}
}
This method retrieves client information
HTTP Request
GET https://www.protocols.io/api/v3/oauth/clients/<id>
Objects
User object
Example Object: User
{
"name": "Vladimir Frolov",
"affiliation": null,
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
null
null
null
image
Small user object
Example Object: Small user
{
"name": "Vladimir Frolov",
"affiliation": null,
"username": "vladimir-frolov10"
}
null
null
Image object
Example Object: Image
{
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
}
null
null
Small File object
Example Object: File
{
"id": 20540,
"source": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"name": "5.png",
"icon": "https://www.protocols.io/img/extensions/png.png",
"content_type_id": 15,
"file_type": 13
}
13
- image
14
- video
15
- any other files
File object
Example Object: File
{
"id": 20540,
"source": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"name": "5.png",
"placeholder_id": 0,
"placeholder": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"icon": "https://www.protocols.io/img/extensions/png.png",
"type_id": 24
}
Badge object
Example Object: Badge
{
"id": 1,
"image": {
"source": "\/img\/ambassador.svg",
"placeholder": "\/img\/ambassador.svg"
},
"name": "Ambassador"
}
image
Reagent object
Example Object: Reagent
{
"id": 19751,
"mol_weight": 0.1,
"name": "2 mg Gastrin I, human",
"linfor": "C130H204N38O31S",
"url": "https://www.biorbyt.com/gastrin-i-human-orb321073",
"sku": "orb321073",
"vendor": {
"name": "biorbyt",
"affiliation": null,
"username": null,
"link": "https://www.biorbyt.com/",
"image": {
"source": "http://je-protocols/img/vendors/208.png",
"placeholder": "http://je-protocols/img/vendors/208.png"
}
}
}
null
user
Comment object
Example Object: Comment
{
"id": 16620,
"parent_id": 0,
"uri": "comment-on-step-1-of-untitled-protocol1",
"title": "Comment on step 1 of untitled protocol",
"body": "<p>Make if cool!</p>",
"created_on": 1517933093,
"changed_on": 0,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null,
"image": {
"source": "/img/avatars/005.png",
"placeholder": "/img/avatars/005.png"
}
},
"comments": [...]
}
user
comment
Message object
Example Object: Message
{
"guid": "E9444EA0D83E11E88166C3A02F4B3BC1",
"subject": "Message subject",
"body": "{\"blocks\":[{\"key\":\"c31q1\",\"text\":\"Message body\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"is_read": 0,
"created_on": 1540462534,
"last_modified": 0,
"type": "sent",
"sender": {
"name": "Ilyas Khayrullin",
"affiliation": null,
"username": "ilyas-khayrullin1",
"link": null,
"image": {
"source": "\/img\/avatars\/003.png",
"placeholder": "\/img\/avatars\/003.png"
},
"badges": [
],
"research_interests": null
},
"recipient": {
"name": "Edmund Chein",
"affiliation": null,
"username": "edmund-chein",
"link": null,
"image": {
"source": "https:\/\/s3.amazonaws.com\/zappy-avatars\/7136_avatar.jpeg",
"placeholder": "https:\/\/s3.amazonaws.com\/zappy-avatars\/7136_avatar.jpeg"
},
"badges": [
],
"research_interests": null
}
}
user
user
Unit object
Example Object: Unit
{
"id": 1,
"type_id": 3,
"name": "µL",
"can_manage": 0,
"read_only": 0
}
Extended user object
Example Object: User
{
"user": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov",
"link": "https://protocols.io",
"image": {
"source": "/img/avatars/014.png",
"placeholder": "/img/avatars/014.png"
},
"first_name": "Vladimir",
"last_name": "Frolov",
"email": "vladimir@protocols.io",
"bio": "developer"
},
"status_code": 0
}
image
Profile API
Get profile
Example Request | get profile data
curl https://www.protocols.io/api/v3/session/profile
-H "Authorization: Bearer ACCESS_TOKEN"
returns the following JSON:
{
"user": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov",
"link": "https://protocols.io",
"image": {
"source": "/img/avatars/014.png",
"placeholder": "/img/avatars/014.png"
},
"first_name": "Vladimir",
"last_name": "Frolov",
"email": "vladimir@protocols.io",
"bio": "developer"
},
"status_code": 0
}
HTTP Request
GET https://www.protocols.io/api/v3/session/profile
Header Parameters
Response
0
means OK
user
Update profile
Example Request
curl -X PUT https://www.protocols.io/api/v3/session/profile
-H "Authorization: Bearer ACCESS_TOKEN"
-d first_name=<new first_name>
-d last_name=<new last_name>
-d email=<new email>
-d password=<new password>
-d old_password=<old password>
-d bio=<new bio>
-d image=<new image>
-d affiliation=<new affiliation>
-d link=<new link>
returns the following JSON:
{
"user": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov",
"link": "https://protocols.io",
"image": {
"source": "/img/avatars/014.png",
"placeholder": "/img/avatars/014.png"
},
"first_name": "Vladimir",
"last_name": "Frolov",
"email": "vladimir@protocols.io",
"bio": "developer"
},
"status_code": 0
}
HTTP Request
PUT https://www.protocols.io/api/v3/session/profile
Header Parameters
PUT Parameters
Response
updated user object
0
means OK
user
Errors list
Protocols
Tiny Protocol object
Example Object: Tiny Protocol
{
"id": 8503,
"title": "Gene calling with Prodigal",
"title_html": "Gene calling with <em>Prodigal</em>",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"uri": "gene-calling-with-prodigal-kixcufn",
"type_id": 1,
"content_type_id": 1
}
image
1
- protocol
3
- collection
4
- document
Small Protocol object
Example Object: Small Protocol
{
"id": 8503,
"title": "Gene calling with Prodigal",
"title_html": "Gene calling with <em>Prodigal</em>",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"version_id": 0,
"doi": "dx.doi.org/10.17504/protocols.io.kixcufn",
"uri": "gene-calling-with-prodigal-kixcufn",
"published_on": 1509493090
}
null
image
0...n
. Version number of this protocol.
null
Protocol object
Example Object: Protocol
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"title_html": "<em>Lysis Buffer</em> (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": true,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"version_id": 1,
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0
}
],
"version_id": 0,
"link": "",
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
],
"guid": "6D11D26701CA4EBAA5CA56859CCA8AC3",
"materials": [...],
"documents": [...],
"units": [...],
}
image
null
user
true
means that this protocol is public and false
otherwise.
versions
0...n
. Version number of this protocol.
null
user
or empty array
reagent
or empty array
null
null
null
null
null
units
objects
attachments
, only present in Get Protocol
endpoint
Step object
Example Object: Draft step
{
"id": 623524,
"guid": "EB5FA750FE0B11E894D23F6E0BEC062D",
"previous_id": null,
"previous_guid": null,
"cases": [...],
"step": "{\"blocks\":[{\"key\":\"avkfi\",\"text\":\"\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[],\"guid\":\"EB5FA750FE0B11E894D23F6E0BEC062D\",\"id\":623524,\"previous_id\":null,\"previous_guid\":null,\"section\":null}",
"section": null,
"section_color": null
}
null
null
step cases
.
Step case object
Example Object: Step case
{
"title": "case 1",
"description": "{\"blocks\":[{\"key\":\"fqjgj\",\"text\":\"case description\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}}],\"entityMap\":{}}",
"first_step_guid": "D9AA5890FE1811E898FD796FADB3FB4E"
}
draft object
Protocol comment object
Example Object: Comment
{
"comment_id": 16620,
"discussion_id": 20697,
"parent_id": 0,
"uri": "comment-on-step-1-of-untitled-protocol1",
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1517933093,
"changed_on": 0,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null,
"image": {
"source": "/img/avatars/005.png",
"placeholder": "/img/avatars/005.png"
}
},
"comments": [...],
"can_delete" : 0,
"can_edit": 1,
"step_id": 1,
"is_dicsussion": 0,
"is_private" : 0
}
user
protocol-comment
Protocol attachment
Example Object: Small Protocol
{
"thumb_url": "https://www.protocols.io/img/extensions/pdf.png",
"url": "https://protocols-files.s3.amazonaws.com/files/l12h3j1.pdf",
"ofn": "sample.pdf"
}
Protocols API
Get List
Example Request | all public protocols
curl "https://www.protocols.io/api/v3/protocols?filter=public&key=<SEARCH-KEY>"
-H "Authorization: Bearer ACCESS_TOKEN"
Example Request | user private | shared with user protocols
curl "https://www.protocols.io/api/v3/protocols?filter=user_private&key=<SEARCH-KEY>"
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0,
"version_id": 1,
"created_on": 1518089537,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"pagination": {
"current_page": 0,
"total_pages": 2,
"total_results": 14,
"next_page": "https://protocols.io/api/v3/researchers/vladimir-frolov20/protocols?page_size=10&page_id=1",
"prev_page": null,
"page_size": 10,
"first": 0,
"last": 14,
"changed_on": null
}
}
This method retrieves the list of protocols separated by pages.
HTTP Request
GET https://www.protocols.io/api/v3/protocols
Header Parameters
API Parameters
1. public
- list of all public protocols;
2. user_public
- list of public protocols that was publiches by concrete user;
3. user_private
- list of private protocols that was created by concrete user;
4. shared_with_user
- list of public protocols that was shared with concrete user.
activity
- index of protocol popularity;
relevance
- returns most relevant to the search key results at the top;
date
- date of publication;
name
- protocol name;
id
- id of protocol.
asc
or desc
.
item
. Fields should be comma-separated.
1...100
.
1...n
.
Response
protocol
objects.
pagination
0
means OK
Status Codes HTTP/1.1 400
Get Protocol
Example Request
curl https://www.protocols.io/api/v4/protocols/[id]
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"payload": {
"access": {
"can_view": true,
"can_edit": false,
"can_remove": false,
"can_add": false,
"can_publish": false,
"can_get_doi": false,
"can_share": false,
"can_move": false,
"can_move_outside": false,
"can_transfer": false,
"can_download": true,
"limited_run": false,
"is_locked": false
},
"authors": [
{
"name": "Sabine St-Jean",
"affiliation": "Université de Sherbrooke",
"username": "sabine-stjean",
"link": "",
"image": {
"source": "https://s3.amazonaws.com/protocols-files/public/dcd02b52e2b8000ccaa294d45ca55d2fbc56024d9b097a6b1f35debd70ef1399/bpqi5r3w.jpg",
"placeholder": "https://s3.amazonaws.com/protocols-files/public/dcd02b52e2b8000ccaa294d45ca55d2fbc56024d9b097a6b1f35debd70ef1399/bpqi5r3w.jpg",
"webp_source": ""
},
"note": null
},
{
"name": "Anna L Crofts",
"affiliation": "Université de Sherbrooke",
"username": "anna-crofts",
"link": "",
"image": {
"source": "https://s3.amazonaws.com/protocols-files/public/2a007146d323b3bcb95c712971ab25c47d309e2373aee5613f507305b88e0497/bswv62te.jpg",
"placeholder": "https://s3.amazonaws.com/protocols-files/public/2a007146d323b3bcb95c712971ab25c47d309e2373aee5613f507305b88e0497/bswv62te.jpg",
"webp_source": ""
},
"note": null
}
],
"before_start": "...",
"created_on": 1575912496,
"creator": {
"name": "Vellend Cabo",
"affiliation": "",
"username": "vellend-cabo",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/protocols-files/public/624bcb927ac08105a0b8d3c8493c756d06e9b56ac5d9ee00044c70ef506476be/bvg9baqix.jpg",
"placeholder": "https://s3.amazonaws.com/protocols-files/public/624bcb927ac08105a0b8d3c8493c756d06e9b56ac5d9ee00044c70ef506476be/bvg9baqix.jpg",
"webp_source": ""
},
"badges": [
{
"id": 2,
"name": "Author",
"image": {
"source": "/img/badges/bronze.svg",
"placeholder": "/img/badges/bronze.svg"
}
}
]
},
"description": "...",
"doi": "dx.doi.org/10.17504/protocols.io.baaciaaw",
"fork_id": null,
"guid": "24AC21F01AA811EA8DEC55A89007A8FD",
"guidelines": "",
"id": 30756,
"image": {
"source": "https://s3.amazonaws.com/protocols-files/public/624bcb927ac08105a0b8d3c8493c756d06e9b56ac5d9ee00044c70ef506476be/bvgmbaqix.jpg",
"webp_source": "",
"placeholder": "",
"webp_placeholder": ""
},
"is_doi_reserved": false,
"is_in_pending_publishing": false,
"is_in_transfer": null,
"item_id": 557557,
"link": "http://www.caboscience.org",
"materials": [...],
"materials_text": "...",
"public": true,
"published_on": 1586383032,
"reserved_doi": "",
"stats": {
"number_of_views": 176,
"number_of_steps": 11,
"number_of_bookmarks": 0,
"number_of_comments": 1,
"number_of_bookmarked_comments": 0,
"number_of_steps_comments": 1,
"number_of_protocol_comments": 0,
"number_of_exports": 118,
"number_of_runs": 0,
"number_of_votes": 0,
"number_of_reagents": 0,
"number_of_equipments": 6,
"number_of_collections": 0,
"number_of_forks": {
"private": 0,
"public": 0
},
"number_of_accessible_forks": 0
},
"steps": [...],
"title": "Tree Mapping for Leaf Collection (Megantic Only)",
"title_html": "\u003cp\u003eTree Mapping for Leaf Collection (Megantic Only)\u003c/p\u003e",
"type_id": 1,
"units": [
{
"id": 1,
"type_id": 3,
"name": "µL",
"can_manage": 0,
"read_only": 0
},
...
],
"uri": "tree-mapping-for-leaf-collection-megantic-only-baaciaaw",
"url": "https://www.protocols.io/view/tree-mapping-for-leaf-collection-megantic-only-baaciaaw",
"version_class": 30756,
"version_id": 0,
"version_uri": "tree-mapping-for-leaf-collection-megantic-only-kxygxe97ov8j/v1",
"versions": [...],
"documents": [...],
"warning": ""
},
"status_code": 0
}
This method retrieves a protocol.
HTTP Request
GET https://www.protocols.io/api/v4/protocols/[id]
Header Parameters
GET Parameters
1. Integer protocol id
2. String protocol URI e.g. tree-mapping-for-leaf-collection-megantic-only-baaciaaw
3. DOI e.g. 10.17504/protocols.io.baaciaaw or protocols.io.baaciaaw
To get exact version of the protocol - version postfix can be provided along with the DOI or URI, e.g. 10.17504/protocols.io.baaciaaw/v1
To get the latest version of the protocol - version postfix of the URI or DOI can be replaced with the "latest" keyword, e.g.
10.17504/protocols.io.baaciaaw/latest
json - draft object
html - plain html
markdown - plain markdown
Response
protocol
0
means OK
Get Steps
Example Request
curl https://www.protocols.io/api/v4/protocols/[id]/steps
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"steps": [
{
"id": 595209,
"guid": "E70FDFE632504ADFB0ED519ABB5449B1",
"previous_id": 0,
"previous_guid": null,
"modified_on": 1517933242,
"components": [...]
},
{
"id": 595210,
"guid": "1167CDCBFDB64CD4BA50A5016F4474B6",
"previous_id": 595209,
"previous_guid": "E70FDFE632504ADFB0ED519ABB5449B1",
"modified_on": 1517933232,
"components": [...]
}
],
"status_code": 0
}
This method retrieves protocol steps list.
HTTP Request
GET https://www.protocols.io/api/v4/protocols/[id]/steps
Header Parameters
GET Parameters
1) Integer protocol id
2) String protocol uri
3) DOI e.g. 10.17504/protocols.io.baaciaaw or protocols.io.baaciaaw
json - draft object
html - plain html
markdown - plain markdown
Response
steps
.
0
means OK
Get Researcher Protocols List
Example Request | researcher public protocols
curl https://www.protocols.io/api/v3/researchers/<username>/protocols?filter=user_public
-H "Authorization: Bearer ACCESS_TOKEN"
Example Request | all researcher protocols
curl https://www.protocols.io/api/v3/researchers/<username>/protocols?filter=user_all
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0,
"version_id": 1,
"created_on": 1518089537,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"pagination": {
"current_page": 0,
"total_pages": 2,
"total_results": 14,
"next_page": "https://protocols.io/api/v3/researchers/vladimir-frolov20/protocols?page_size=10&page_id=1",
"prev_page": null,
"page_size": 10,
"first": 0,
"last": 14,
"changed_on": null
}
}
This method retrieves the list of researcher public protocols separated by pages.
filter user_all
works only when username user is the same with access token user otherwise API returns error with status_code
132
HTTP Request
GET https://www.protocols.io/api/v3/researchers/<username>/protocols
Header Parameters
API Parameters
1. user_all
- list of all public protocols;
2. user_public
- list of public protocols that was publiches by concrete user;
activity
- index of protocol popularity;
date
- date of publication;
name
- protocol name;
id
- id of protocol.
asc
or desc
.
1...100
.
1...n
.
Response
protocol
objects.
pagination
0
means OK
Status Codes HTTP/1.1 400
Get Workspace Protocols List
Example Request | workspace public protocols
curl https://www.protocols.io/api/v3/workspaces/<workspace_uri>/protocols
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0,
"version_id": 1,
"created_on": 1518089537,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"pagination": {
"current_page": 0,
"total_pages": 2,
"total_results": 14,
"next_page": "https://protocols.io/api/v3/workspaces/verve-net/protocols?page_size=10&page_id=1",
"prev_page": null,
"page_size": 10,
"first": 0,
"last": 14,
"changed_on": null
}
}
This method retrieves the list of workspace public protocols separated by pages.
To obtain private protocols from a workspace, check out the File Manager API.
HTTP Request
GET https://www.protocols.io/api/v3/workspaces/<workspace_uri>/protocols
Header Parameters
API Parameters
activity
- index of protocol popularity;
date
- date of publication;
name
- protocol name;
id
- id of protocol.
asc
or desc
.
1...100
.
1...n
.
Response
protocol
objects.
pagination
0
means OK
Status Codes HTTP/1.1 400
Get Materials
Example Request
curl https://www.protocols.io/api/v3/protocols/[id]/materials
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"materials": [
{
"id": 1144,
"mol_weight": 0,
"name": "Quick Ligation Kit - 30 rxns",
"linfor": "",
"url": "https://www.neb.com/M2200",
"sku": "M2200S",
"vendor": {
"name": "New England Biolabs",
"affiliation": null,
"username": null,
"link": "https://www.neb.com/",
"image": {
"source": "http://je-protocols/img/vendors/2.png",
"placeholder": "http://je-protocols/img/vendors/2.png"
}
}
},
{
"id": 46948,
"mol_weight": 0,
"name": "(+) Abscisic acid (Dormin, ABA)",
"linfor": "",
"url": "https://www.biobasic.com/us/abscisic-acid-dormin-aba-3945",
"sku": "AB0001.SIZE.100mg",
"vendor": {
"name": "Bio Basic Inc.",
"affiliation": null,
"username": null,
"link": "http://biobasic.com/",
"image": {
"source": "http://je-protocols/img/vendors/120.png",
"placeholder": "http://je-protocols/img/vendors/120.png"
}
}
}
],
"status_code": 0
}
This method retrieves protocol materials list.
HTTP Request
GET https://www.protocols.io/api/v3/protocols/[id]/materials
Header Parameters
Response
materials
.
0
means OK
Create a protocol
Example Request | Create a protocol
curl https://www.protocols.io/api/v3/protocols/<guid>
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d type_id=<type_id>
Example Response
{
"status_code": 0,
"protocol": <protocol object>
}
This method creates a new protocol
HTTP Request
POST https://www.protocols.io/api/v3/protocols/<guid>
Header Parameters
URI Parameters
POST Parameters
1 - protocol
3 - collection
4 - document
Response
0
means OK
protocol
Status Codes HTTP/1.1 400
Save protocol changes
Example Request | Save protocol changes
curl https://www.protocols.io/api/v3/protocols/<guid>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
-d actions=<actions array>
Example Response
{
"status_code": 0,
"actions": <actions list or null>
}
This method saves protocol changes
HTTP Request
PUT https://www.protocols.io/api/v3/protocols/<guid>
Header Parameters
URI Parameters
POST Parameters
actions array
Response
0
means OK
actions array
or null
Status Codes HTTP/1.1 400
Protocol saving error
Example Object: Protocol saving error
{
"status_code": 254,
"error_message": {
"path": "stack[0]",
"error": "wrong data type, must be on of base,step,component,files"
}
}
Protocol Actions
Example
{
"guid": "28C5E0F0D96211E9A8EB9746B7AE966Ф",
"up": [
{
"path": ["description"],
"value": "new description"
}
],
"down": [
{
"path": ["description"],
"value": "current description"
}
],
"marker": "draft:change-description",
"microtime": 1568735122558
}
Protocol actions is an array of actions that was applied on default protocol object to change protocol data.
Each action must have GUID, up/down, marker and microtime.
Up/Down
Up and Down object represents changes that must be applied on the protocol object. They always should has path and value fields. path represents path in the protocol object that value has to be changes. Value represents new value. In Up/Down combination Up.value is a new value, Down.value is an old value.
list of marker and up/down rules
image object
user objects
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
draft json
step object
step object
Publish protocol
Example Request | Publish protocol
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/publish
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
Example Response
{
"status_code": 0
}
This method issues DOI to a protocol and optionally makes it publicly accessible
HTTP Request
POST https://www.protocols.io/api/v3/protocols/<protocol_uri>/publish
Header Parameters
URI Parameters
POST Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Bookmark protocol
Example Request | Bookmark workspace
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/bookmarks
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
Example Response
{
"status_code": 0
}
This method add needed protocol into bookmarks
HTTP Request
POST https://www.protocols.io/api/v3/protocols/<protocol_uri>/bookmarks
Header Parameters
URI Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Delete bookmarked protocol
Example Request | delete bookmarked protocol
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/bookmarks
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
Example Response
{
"status_code": 0
}
This method delete needed protocol from bookmarks
HTTP Request
DELETE https://www.protocols.io/api/v3/protocols/<protocol_uri>/bookmarks
Header Parameters
URI Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Publications API
Get Latest Publications
Example Request | latest publications
curl https://www.protocols.io/api/v3/publications?latest=1
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0,
"version_id": 1,
"created_on": 1518089537,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"status_code": 0
}
This method retrieves the list of last published protocols ordered by publish date.
HTTP Request
GET https://www.protocols.io/api/v3/publications?latest=1
Header Parameters
API Parameters
1..100
Response
protocol
objects.
0
means OK
Get publications for a period
Example Request | Publications for a period
curl "https://www.protocols.io/api/v3/publications?from=1571097600&to=1571961600"
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0,
"version_id": 1,
"created_on": 1518089537,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov10",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/djqbjf6.jpg"
}
}
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"status_code": 0
}
This method retrieves a list of protocols published during a specified period ordered by publish date.
HTTP Request
GET https://www.protocols.io/api/v3/publications?from=1571097600&to=1571961600
Header Parameters
API Parameters
Response
protocol
objects.
0
means OK
Draft
Draft object
Draft.js raw json object
{
"blocks": [
{
"key": "d7u0g",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"type": "unstyled",
"inlineStyleRanges": [
{
"offset": 12,
"length": 5,
"style": "bold"
}
],
"entityRanges": [
{
"offset": 40,
"length": 1,
"key": 0
}
]
}
],
"entityMap": {
"0": {
"type": "temperature",
"data": {
"temperature": "10",
"unit": 10,
"label": "temperature label"
}
}
}
}
content blocks
Content block objects are largely analogous to block-level HTML elements like paragraphs and list items
entities
Content block object
{
"key": "d7u0g",
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"type": "unstyled",
"inlineStyleRanges": [
{
"offset": 12,
"length": 5,
"style": "bold"
}
],
"entityRanges": [
{
"offset": 40,
"length": 1,
"key": 0
}
]
}
entityMap
object
Entity object
{
"type": "temperature",
"data": {
"temperature": "10",
"unit": 10,
"label": "temperature label"
}
}
amount object
duration object
link object
software object
dataset object
command object
result object
protocol object
safety information object
reagent object
go to step object
temperature object
concentration object
comment
document object
has structure identical to protocol object
equipment object
formula object
embed object
code object
image object
image object
video object
Draft entities types
Formula draft object
Example Object: Formula draft object
{
"formula": "x^2 + y^2"
}
Embed draft object
Example Object: Embed draft object
{
"embed": "<iframe width=\"560\" height=\"315\" src=\"https:\/\/www.youtube.com\/embed\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen><\/iframe>"
}
Code draft object
Code is represented by draft object
.
Example Object: Code draft object
{
"blocks": [
{
"key": "cg0tm",
"text": "Code insert",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
],
"entityRanges": [
],
"data": [
]
}
],
"entityMap": [
]
}
Image draft object
Example Object: Image draft object
{
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/wfwfwfwf.png",
"original_name": "5.png",
"mime": "image\/png",
"width": 180,
"legend": ""
}
draft object
, can be empty string or null
Draft object for legend can contains only following content objects:
link
,
formula
Video draft object
Example Object: Video draft object
{
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/wdxa.mp4",
"original_name": "video.mp4",
"mime": "video\/mp4"
}
File draft object
Example Object: File draft object
{
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/wdya.docx",
"placeholder": "http:\/\/www.protocols.io\/img\/extensions\/docx.png",
"original_name": "document.docx"
}
Table draft object
Example Object: Table draft object
{
"colWidths": [
72,
50,
50,
50
],
"rowHeights": [
23,
23,
23,
23
],
"cellsMeta": {
"0_0": "_dt-v-middle",
"0_1": "",
"0_2": "_dt-bold",
"0_3": "",
"1_0": "_dt-v-middle",
"1_1": "",
"1_2": "",
"1_3": "",
"2_0": "",
"2_1": "_dt-italic",
"2_2": "",
"2_3": "",
"3_0": "_dt-bold _dt-italic",
"3_1": "",
"3_2": "_dt-h-right",
"3_3": "_dt-h-right"
},
"data": [
[
"vertical",
"b1",
"c1",
null
],
[
null,
null,
null,
null
],
[
null,
"b3",
null,
null
],
[
"a1",
null,
"right",
null
]
],
"mergeCells": [
{
"row": 0,
"col": 0,
"rowspan": 2,
"colspan": 1
},
{
"row": 3,
"col": 2,
"rowspan": 1,
"colspan": 2
}
],
"legend": ""
}
key: row
_col
,
value: combination of classes described below
first dimension - table rows,
second - table columns
row
- row index,
col
- column index,
rowspan
- number of rows to merge,
colspan
- number of columns to merge
draft object
, can be empty string
Draft object for legend can contains only following content objects:
link
,
formula
Equipment draft object
Example Object: Equipment draft object
{
"brand": "BrandedEquipment",
"sku": "SKU",
"specifications": "Spec",
"link": "https:\/\/www.protocols.io",
"type": "Type",
"name": "Name",
"image": {
"id": 20612,
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/weea.png",
"name": "circle.png",
"icon": "http:\/\/localhost:81\/img\/extensions\/png.png",
"content_type_id": 15,
"file_type": 13
},
"file": {
"id": 20611,
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/weda.docx",
"name": "document.docx",
"icon": "http:\/\/localhost:81\/img\/extensions\/docx.png",
"content_type_id": 15,
"file_type": 15
}
}
file object
file object
Amount draft object
A quantity of something, typically the total of a reagent, size, value etc.
Example Object: Amount draft object
{
"amount": 11,
"unit": "µl",
"label": "of MGH"
}
unit
id
Duration draft object
Example Object: Duration draft object
{
"duration": 11,
"label": "boil"
}
Link draft object
Example Object: Link draft object
{
"url": "https://www.protocols.io"
}
Software package draft object
Example Object: Software package draft object
{
"name": "what",
"developer": "me",
"repository": "https://google.com",
"link": "https://google.com",
"os_name": "win",
"os_version": "10"
}
Dataset package draft object
Example Object: Dataset package draft object
{
"name": "DataTable",
"link": "https://protocols.io"
}
Command package draft object
Example Object: Command package draft object
{
"name": "Code",
"command": "echo 'hello world!'",
"os_name": "windows",
"os_version": "10",
"description": "desc"
}
Expected result draft object
Expected result is represented by draft object
.
Example Object: Expected result draft object
{
"blocks": [
{
"key": "eaj3k",
"text": "Expected results",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
],
"entityRanges": [
],
"data": [
]
}
],
"entityMap": [
]
}
Safety information draft object
Safety information is represented by draft object
.
Example Object: Safety information, type id 19
{
"blocks": [
{
"key": "87aiq",
"text": "Safety information",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
],
"entityRanges": [
],
"data": [
]
}
],
"entityMap": [
]
}
Go to previous step draft object
Example Object: Go to previous step draft object
{
"title": "Reason for repeating the step",
"step_guid": "E70FDFE632504ADFB0ED519ABB5449B1"
}
Temperature draft object
Example Object: Temperature draft object
{
"temperature": 12,
"unit": "°C",
"label": "boil"
}
unit
id
Concentration draft object
Example Object: Concentration draft object
{
"concentration": 12,
"unit": "°C",
"label": "boil"
}
unit
id
Note draft object
Note is represented by draft object
.
Example Object: Note, type id 26
{
"blocks": [
{
"key": "d8ihj",
"text": "Note",
"type": "unstyled",
"depth": 0,
"inlineStyleRanges": [
],
"entityRanges": [
],
"data": [
]
}
],
"entityMap": [
]
}
Discussions API
Get protocol comments
Example Request | Get protocol comments
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"comments": [
{
"comment_id": 0,
"discussion_id": 20706,
"is_discussion": 1,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"4rcfq\",\"text\":\"step 1 discussion\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540295702,
"changed_on": 0,
"can_edit": 1,
"can_delete": 0,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null,
},
"step_number": 1,
"step_id": 623276,
"is_public": 0,
"is_private": 0,
"comments": [...]
}
],
"status_code": 0
}
This method return all protocol comments as tree. Step-level comments can be determined by step_id flag in first level of the tree, protocol-level comments has step_id = 0.
HTTP Request
GET https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments
Header Parameters
Response
protocol-comment
objects
0
means OK
Add protocol comment
Example Request | Add protocol comment
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d body=<comment body>
-d is_private=<private flag>
Example Response
{
"comment": {
"comment_id": 3488,
"discussion_id": 20697,
"is_discussion": 0,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540208010,
"changed_on": 0,
"can_edit": 1,
"can_delete": 1,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null
},
"step_id": 0,
"is_private": 0,
"comments": null
},
"status_code": 0
}
This method add protocol-level comment
HTTP Request
POST https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments
Header Parameters
POST Parameters
Response
protocol-comment
0
means OK
Status Codes HTTP/1.1 400
Add reply to protocol comment
Example Request | Add reply to protocol comment
curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments/<parent_comment_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d body=<comment body>
Example Response
{
"comment": {
"comment_id": 3488,
"discussion_id": 20697,
"is_discussion": 0,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540208010,
"changed_on": 0,
"can_edit": 1,
"can_delete": 1,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null
},
"step_id": 0,
"is_private": 0,
"comments": null
},
"status_code": 0
}
This method add reply to protocol comment
HTTP Request
POST https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments/<parent_comment_id>
Header Parameters
POST Parameters
Response
protocol-comment
0
means OK
Status Codes HTTP/1.1 400
Add step discussion
Example Request | Add step discussion
curl https://www.protocols.io/api/v3/steps/<step_id>/discussions
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d body=<comment body>
-d protocol_uri=<uri of a protocol>
-d is_private=<private flag>
Example Response
{
"comment": {
"comment_id": 3488,
"discussion_id": 20697,
"is_discussion": 0,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540208010,
"changed_on": 0,
"can_edit": 1,
"can_delete": 1,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null
},
"step_id": 0,
"is_private": 0,
"comments": null
},
"status_code": 0
}
This method add step discussion
HTTP Request
POST https://www.protocols.io/api/v3/steps/<step_id>/discussions
Header Parameters
POST Parameters
Response
protocol-comment
0
means OK
Status Codes HTTP/1.1 400
Add comment to step discussion
Example Request | Add comment to step discussion
curl https://www.protocols.io/api/v3/steps/<step_id>/discussions/<discussion_id>/comments
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d body=<comment body>
-d protocol_uri=<uri of a protocol>
Example Response
{
"comment": {
"comment_id": 3488,
"discussion_id": 20697,
"is_discussion": 0,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540208010,
"changed_on": 0,
"can_edit": 1,
"can_delete": 1,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null
},
"step_id": 0,
"is_private": 0,
"comments": null
},
"status_code": 0
}
This method add comment to step discussion
HTTP Request
POST https://www.protocols.io/api/v3/steps/<step_id>/discussions/<discussion_id>/comments
Header Parameters
POST Parameters
Response
protocol-comment
0
means OK
Status Codes HTTP/1.1 400
Add reply to step comment
Example Request | Add reply to step comment
curl https://www.protocols.io/api/v3/steps/<step_id>/discussions/<discussion_id>/comments/<parent_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d body=<comment body>
-d protocol_uri=<uri of a protocol>
Example Response
{
"comment": {
"comment_id": 3488,
"discussion_id": 20697,
"is_discussion": 0,
"parent_id": 0,
"body": "{\"blocks\":[{\"key\":\"a83f3\",\"text\":\"Text of a comment\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"created_on": 1540208010,
"changed_on": 0,
"can_edit": 1,
"can_delete": 1,
"creator": {
"name": "Lenny Teytelman",
"affiliation": "protocols.io",
"username": "lenny-teytelman",
"link": null
},
"step_id": 0,
"is_private": 0,
"comments": null
},
"status_code": 0
}
This method add reply to step comment
HTTP Request
POST https://www.protocols.io/api/v3/steps/<step_id>/discussions/<discussion_id>/comments/<parent_id>
Header Parameters
POST Parameters
Response
protocol-comment
0
means OK
Status Codes HTTP/1.1 400
Edit comment
Example Request | Edit comment
curl https://www.protocols.io/api/v3/discussions/comments/<comment_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
-d body=<comment body>
Example Response
{
"status_code": 0
}
This method change comment
HTTP Request
PUT https://www.protocols.io/api/v3/discussions/comments/<comment_id>
Header Parameters
PUT Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Edit discussion
Example Request | Edit discussion
curl https://www.protocols.io/api/v3/discussions/<discussion_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
-d body=<discussion body>
Example Response
{
"status_code": 0
}
This method change discussion
HTTP Request
PUT https://www.protocols.io/api/v3/discussions/<discussion_id>
Header Parameters
PUT Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Delete comment
Example Request | Delete comment
curl https://www.protocols.io/api/v3/discussions/comments/<comment_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
Example Response
{
"status_code": 0
}
This method delete comment
HTTP Request
DELETE https://www.protocols.io/api/v3/discussions/comments/<comment_id>
Header Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Delete discussion
Example Request | Delete discussion
curl https://www.protocols.io/api/v3/discussions/<discussion_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
Example Response
{
"status_code": 0
}
This method delete discussion
HTTP Request
DELETE https://www.protocols.io/api/v3/discussions/<discussion_id>
Header Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Experiment records API
Record object
Example Object: Record
{
"id": 1,
"guid": "4E47E83EC1CD11EEA5EB8A0FA45ECEF7",
"title": "Lorem Ipsum is simply dummy text of the printing and typesetting industry.",
"title_html": "<p>Lorem Ipsum is simply dummy text of the printing and typesetting industry.</p>",
"item_id": 100,
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"created_on": 1706879802,
"changed_on": 1706879802,
"total_steps": 10,
"finished_steps": 5,
"scale_multiplier": 1.0,
"creator": {
"name": "John Doe",
"affiliation": "University of California",
"username": "johndoe",
"link": "https://exmaple.com/johndoe",
"image": {
"source": "/img/avatars/012.png",
"placeholder": "/img/avatars/012.png"
}
},
"location": [
{
"id": 1,
"guid": "63DAC23AA40811EE86F68A0FA45ECEF6",
"title": "Parent folder",
"type_id": 0,
"created_on": 1703606643,
"content_type_id": 10
},
{
"id": 2,
"guid": "5D28141AA40811EE86F68A0FA45ECEF6",
"title": "Parent folder 2",
"type_id": 0,
"created_on": 1703606632,
"content_type_id": 10
}
],
"steps": [
{
"id": 16,
"guid": "4E4DAEFEC1CD11EEA5EB8A0FA45ECEF7",
"previous_id": 0,
"previous_guid": null,
"cases": [],
"step": "{\"blocks\":[{\"key\":\"5jdtn\",\"text\":\"Step 1\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}},{\"key\":\"9k2a3\",\"text\":\" \",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[{\"key\":0,\"offset\":0,\"length\":1}],\"data\":{}},{\"key\":\"95lpo\",\"text\":\"\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}}],\"entityMap\":{\"0\":{\"type\":\"amount\",\"mutability\":\"MUTABLE\",\"data\":{\"amount\":\"\",\"error\":false,\"guid\":\"\",\"id\":0,\"label\":\"\",\"scientificNotation\":false,\"unit\":1}}}}",
"section": "",
"section_color": "",
"is_checked": false,
"checked_on": null,
"is_skipped": false,
"skippedn_on": null
},
{
"id": 17,
"guid": "4E4DAF1CC1CD11EEA5EB8A0FA45ECEF7",
"previous_id": 0,
"previous_guid": "4E4DAEFEC1CD11EEA5EB8A0FA45ECEF7",
"cases": [],
"step": "{\"blocks\":[{\"key\":\"3c6a1\",\"text\":\"Step 2\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}},{\"key\":\"dv2v9\",\"text\":\" \",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[{\"key\":0,\"offset\":0,\"length\":1}],\"data\":{}},{\"key\":\"678m3\",\"text\":\"\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":{}}],\"entityMap\":{\"0\":{\"type\":\"duration\",\"mutability\":\"MUTABLE\",\"data\":{\"duration\":0,\"guid\":\"\",\"id\":0,\"label\":\"\",\"pause\":0,\"preset\":[],\"start\":0}}}}",
"section": "",
"section_color": "",
"is_checked": false,
"checked_on": null,
"is_skipped": false,
"skippedn_on": null
}
]
}
image
user
small folder
protocol step
with additional fields, described below1
- step checked
0
- step not checked
1
- step skipped
0
- step not skipped
Record note object
Example Object: Record note
{
"id": 775,
"note": "Note text",
"created_on": 1541682802,
"modified_on": 1541683315,
"file": {
"id": 20540,
"source": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"original_name": "5.png",
"placeholder_id": 0,
"placeholder": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"icon": "http://www.protocols.io/img/extensions/png.png",
"type_id": 24
}
}
file object
, can be null
Experiment records
Get list of active records
Example Request | user porjects
curl https://www.protocols.io/api/v3/records?active
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"changed_on": 1446001771,
"created_on": 1446001771,
"creator": {
"affiliation": "protocols.io",
"badges": null,
"image": {
"source": "\/img\/avatars\/003.png",
"placeholder": "\/img\/avatars\/003.png"
},
"link": "",
"name": "Vladimir Frolov",
"username": "vladimir-frolov12"
},
"finished_steps": 0,
"folder": {
"content_type_id": 10,
"created_on": 1483926561,
"guid": "710DEFBFBD4B3DEFBFBD4933EFBFBD1F",
"id": 245365,
"title": "Experiments",
"type_id": 14
},
"guid": "2A195AC3AFC2BFC2BDC3AFC2BFC2BDC3",
"id": 484784,
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png"
},
"item_id": 5271,
"protocol": {
"created_on": 1405030055,
"creator": {
"affiliation": null,
"image": {
"source": "",
"placeholder": "",
"webp_source": ""
},
"link": null,
"name": "",
"username": ""
},
"doi": "dx.doi.org\/10.17504\/protocols.io.cdms45",
"id": 484784,
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png"
},
"modified_on": null,
"public": 1,
"published_on": 1422407784,
"stats": {
"number_of_accessible_forks": 0,
"number_of_bookmarked_comments": 0,
"number_of_bookmarks": 0,
"number_of_collections": 0,
"number_of_comments": 0,
"number_of_equipments": 0,
"number_of_exports": 0,
"number_of_forks": {
"private": 0,
"public": 0
},
"number_of_protocol_comments": 0,
"number_of_reagents": 0,
"number_of_runs": 0,
"number_of_steps": 0,
"number_of_step_comments": 0,
"number_of_views": 10298,
"number_of_votes": 0
},
"title": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
"title_html": "Gibson Assembly\u00ae Protocol (E5510)",
"type_id": 1,
"uri": "Gibson-Assembly-Protocol-E5510-imss45",
"version_id": 0
},
"scale_multiplier": 1,
"title": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
"title_html": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
"total_steps": 4
}
],
"pagination": {
"current_page": 0,
"total_pages": 6,
"total_results": 30,
"next_page": "http://localhost:81/api/v3/records?active&page_size=5&page_id=1",
"prev_page": null,
"page_size": 5,
"first": 0,
"last": 30,
"changed_on": 1522839972
},
"status_code": 0
}
This method retrieves the list of user records.
HTTP Request
GET https://www.protocols.io/api/v3/records?active
Header Parameters
API Parameters
1...100
.
1...n
.
Response
records
objects.
pagination
Get record
Example Request | load record by guid
curl "https://www.protocols.io/api/v4/records/<record_guid>?with_protocol=1&content_format=json"
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"payload": {
"protocol": {
"authors": [...],
"before_start": "Before start",
"created_on": 1703606652,
"creator": {
"affiliation": "",
"image": {
"placeholder": "/img/avatars/012.png",
"source": "/img/avatars/012.png"
},
"link": null,
"name": "recod",
"username": "m4"
},
"description": "Description of the protocol",
"doi": "",
"guid": "ADDE06F39C1C421F8B0EC0D50DB34A79",
"guidelines": "Guidelines ",
"id": 23,
"image": {
"placeholder": "https://www.protocols.io/img/default_protocol.png",
"source": "https://www.protocols.io/img/default_protocol.png"
},
"link": "",
"materials": [...],
"materials_text": "",
"peer_reviewed": null,
"public": false,
"published_on": null,
"stats": {...},
"title": "Record protocol",
"title_html": "<p>Record protocol</p>",
"units": [...],
"uri": "record-protocol-b9xr7m",
"url": "http://localhost:900/view/record-protocol-b9xr7m",
"version_id": 0,
"versions": [...],
"warning": "Safety"
},
"record": {
"id": 6,
"guid": "4E47E83EC1CD11EEA5EB8A0FA45ECEF7",
"title": "Record protocol",
"title_html": "Record protocol",
"item_id": 141,
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"created_on": 1706879802,
"changed_on": 1706879802,
"total_steps": 2,
"finished_steps": 0,
"scale_multiplier": 1,
"creator": {
"name": "recod",
"affiliation": null,
"username": "m4",
"link": null,
"image": {
"source": "/img/avatars/012.png",
"placeholder": "/img/avatars/012.png"
}
},
"location": [...],
"steps": [...]
}
},
"status_code": 0
}
This method return record by guid.
HTTP Request
GET https://www.protocols.io/api/v4/records
Header Parameters
API Parameters
1
- return record with related protocol data
0
- return only record data
json - draft object
html - plain html
markdown - plain markdown
Response
record object
protocol object
Create record
Example Request | create new record
curl https://www.protocols.io/api/v3/record
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d folder_data=<data of record folder>
-d stack=<data for save after record will be created>
Example Response
{
"record": {
"id": 508765,
"guid": "CAF711DB285B4F6EAE02CF460AFE4A5D",
"protocol_id": 16310,
"title": "TestInlineComponents",
"title_html": "TestInlineComponents",
"is_archived": 0,
"number_of_finished_steps": 0,
"scale_multiplier": 1,
"created_on": 1541083646,
"changed_on": 1541083646,
"can_edit": 1
},
"status_code": 0
}
This method creates a new record from protocol.
When you create new record, you need to run get record API
and rerender screen with new record data if you need to continue running this experiment, this should be done to avoid collisions in steps.
HTTP Request
POST https://www.protocols.io/api/v3/records
Header Parameters
API Parameters
record stack objects
Example Object: existed record stack base
{
"type": "base",
"data": {
"title": "converter debug"
}
},
Example Object: existed record stack notes
{
"type": "notes",
"data": {
"id": 775,
"note": "test1234",
"step_id": 0
}
},
Example Object: existed record stack step
{
"type": "step",
"data": {
"guid": "EAA54C8AFDCD4D51AFFF12DF9C76F332",
"is_checked": 1,
}
},
base
changes affect record itself
notes
changes affect notes of the record
step
changes affect steps of the record
base data object
, notes data object
or step data object
base data object
notes data object
if note adding to the whole record should be 0
specify this parameter only when id
is null
step data object
Response
record-object
0
means OK
Save record changes
Example Request | apply record changes from stack
curl https://www.protocols.io/api/v3/record/<guid>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
-d stack=<stack of changes>
Example Response
{
"status_code": 0
}
This method changes record by stack
HTTP Request
PUT https://www.protocols.io/api/v3/records/<guid>
Header Parameters
URL Parameters
API Parameters
record stack objects
Example Object: existed record stack base
{
"type": "base",
"data": {
"title": "converter debug"
}
},
Example Object: existed record stack notes
{
"type": "notes",
"data": {
"id": 775,
"note": "test1234",
"step_id": 0
}
},
Example Object: existed record stack step
{
"type": "step",
"data": {
"guid": "EAA54C8AFDCD4D51AFFF12DF9C76F332",
"is_checked": 1,
}
},
base
changes affect record itself
notes
changes affect notes of the record
step
changes affect steps of the record
base data object
, notes data object
or step data object
base data object
notes data object
if note adding to the whole record should be 0
specify this parameter only when id
is null
step data object
Response
0
means OK
Workspaces
Workspace object
Example Object: Workspace
{
"id": 45,
"uri": "verve-net",
"title": "VERVE Net",
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/cdqcwwe.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/cdqcwwe.png"
},
"description": "Welcome to the Viral Ecology Research and Virtual Exchange network<strong> (VERVE Net)<\/strong>. This is an online forum to increase connectivity and collaboration among virus ecology researchers. Funded by the <a href=\"https:\/\/www.moore.org\/grant-detail?grantId=GBMF4733\" target=\"_blank\">Gordon and Betty Moore Foundation<\/a>.",
"research_interests": "viral ecology",
"website": "https:\/\/www.moore.org\/grants\/list\/GBMF4733",
"location": "",
"affiliation": "",
"status": {
"is_visible": true,
"access_level": 2
},
"stats": {
"files": {
"publish": 272,
"forks": 41,
"shared": 0,
"archived": 0
},
"total_members": 249
},
"user_status": {
"is_member": false,
"is_confimed": false,
"is_invited": false,
"is_owner": false
}
}
image
true
this workspace is public
user status
Small workspace object
Example Object: Workspace
{
"id": 45,
"uri": "verve-net",
"title": "VERVE Net",
"image": {
"source": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png"
},
"is_member": 0,
"description": "Welcome to the Viral Ecology Research and Virtual Exchange network<strong> (VERVE Net)</strong>. This is an online forum to increase connectivity and collaboration among virus ecology researchers. Funded by the <a href=\"https://www.moore.org/grant-detail?grantId=GBMF4733\" target=\"_blank\">Gordon and Betty Moore Foundation</a>."
}
image
1
or 0
. 1
means that current user is a member of this workspace.
Workspace user status object
{
"is_member": true,
"is_confimed": true,
"is_invited": false,
"is_owner": false
}
true
mean that user is workspace member
true
mean that user is confirmed workspace member
true
mean that user is invited workspace member
true
mean that user is owner of this workspace
Workspaces API
Get Workspaces List
Example Request | all public workspaces
curl https://www.protocols.io/api/v3/workspaces
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"id": 45,
"uri": "verve-net",
"title": "VERVE Net",
"image": {
"source": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png"
},
"is_member": 0,
"description": "Welcome to the Viral Ecology Research and Virtual Exchange network<strong> (VERVE Net)</strong>. This is an online forum to increase connectivity and collaboration among virus ecology researchers. Funded by the <a href=\"https://www.moore.org/grant-detail?grantId=GBMF4733\" target=\"_blank\">Gordon and Betty Moore Foundation</a>."
}
],
"pagination": {
"current_page": 0,
"total_pages": 2,
"total_results": 14,
"next_page": "https://protocols.io/api/v3/workspaces?page_size=10&page_id=1",
"prev_page": null,
"page_size": 10,
"first": 0,
"last": 14,
"changed_on": null
}
}
This method retrieves the list of public workspaces separated by pages.
HTTP Request
GET https://www.protocols.io/api/v3/workspaces
Header Parameters
GET Parameters
1...100
.
1...n
.
Response
workspace
objects.
pagination
0
means OK
Status Codes HTTP/1.1 400
Get Researcher Workspaces
Example Request | researcher workspaces
curl https://www.protocols.io/api/v3/researchers/<username>/workspaces
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/cj.jpg",
"placeholder": "https://s3.amazonaws.com/pr-journal/cj.jpg"
},
"badges": [],
"research_interests": "web"
},
{
"name": "Monica Hassan",
"affiliation": "protocols.io",
"username": "monica-hassan",
"link": null,
"image": {
"source": "https://pr-journal.s3.amazonaws.com/gwt.jpeg",
"placeholder": "https://pr-journal.s3.amazonaws.com/gwt.jpeg"
},
"badges": [],
"research_interests": ""
}
],
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_results": 2,
"next_page": null,
"prev_page": null,
"page_size": 10,
"first": 0,
"last": 2,
"changed_on": null
},
"status_code": 0
}
This method retrieves the list of researcher public workspaces separated by pages.
HTTP Request
GET https://www.protocols.io/api/v3/researchers/<username>/workspaces
Header Parameters
GET Parameters
1...100
.
1...n
.
Response
workspace
objects.
pagination
0
means OK
Status Codes HTTP/1.1 400
Get workspace
Example Request
curl https://www.protocols.io/api/v3/workspaces/[uri]
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"group": {
"id": 45,
"uri": "verve-net",
"title": "VERVE Net",
"image": {
"source": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/cdqcwwe.png"
},
"is_member": 0,
"description": "Welcome to the Viral Ecology Research and Virtual Exchange network<strong> (VERVE Net)</strong>. This is an online forum to increase connectivity and collaboration among virus ecology researchers. Funded by the <a href=\"https://www.moore.org/grant-detail?grantId=GBMF4733\" target=\"_blank\">Gordon and Betty Moore Foundation</a>.",
"research_interests": "viral ecology",
"website": "https://www.moore.org/grants/list/GBMF4733",
"location": "",
"affiliation": "",
"status": {
"is_visible": true,
"access_level": 2
},
"stats": {
"files": {
"publish": 272,
"forks": 41,
"shared": 0,
"archived": 0
},
"total_members": 249
},
"user_status": {
"is_member": false,
"is_confimed": false,
"is_invited": false,
"is_owner": false
}
},
"status_code": 0
}
This method retrieves a workspace.
HTTP Request
GET https://www.protocols.io/api/v3/workspaces/[uri]
GET Parameters
Header Parameters
Response
workspace
0
means OK
Join workspace
Request to join workspace
Example Request
curl https://www.protocols.io/api/v3/workspaces/[uri]/members
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
Example Response
{
"user_status": {
"is_member": true,
"is_confimed": true,
"is_invited": false,
"is_owner": false
},
"status_code": 0
}
This method should be used to join or request to join workspace
HTTP Request
POST https://www.protocols.io/api/v3/workspaces/<uri>/members
Header Parameters
URL Parameters
Response
user status
0
means OK
Confirm invite into workspace
Example Request
curl https://www.protocols.io/api/v3/workspaces/[uri]/members
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
Example Response
{
"user_status": {
"is_member": true,
"is_confimed": true,
"is_invited": false,
"is_owner": false
},
"status_code": 0
}
This method should be used to confirm invitation into a workspace
HTTP Request
PUT https://www.protocols.io/api/v3/workspaces/<uri>/members
Header Parameters
URL Parameters
Response
user status
0
means OK
Leave workspace
Reject invite into workspace
Example Request
curl https://www.protocols.io/api/v3/workspaces/[uri]/members
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
Example Response
{
"user_status": {
"is_member": false,
"is_confimed": false,
"is_invited": false,
"is_owner": false
},
"status_code": 0
}
This method should be used to:
- leave a workspace
- reject invitation into a workspace
- reject request into a workspace
HTTP Request
DELETE https://www.protocols.io/api/v3/workspaces/<uri>/members
Header Parameters
URL Parameters
Response
user status
0
means OK
Messages API
Get researcher conversations
Example Request | Get researcher conversations
curl https://www.protocols.io/api/v3/conversations
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"conversations": [
{
"id": 574,
"guid": "EEA605F0D83E11E88166C3A02F4B3BC1",
"parent_guid": null,
"subject": "asdf",
"body": "{\"blocks\":[{\"key\":\"b2us5\",\"text\":\"asfd\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"is_read": 1,
"created_on": 1540462543,
"last_modified": 1540462543,
"type": "sent",
"sender": {
"name": "Ilyas Khayrullin",
"affiliation": null,
"username": "ilyas-khayrullin1",
"link": null,
"image": {
"source": "\/img\/avatars\/003.png",
"placeholder": "\/img\/avatars\/003.png"
},
"badges": [
],
"research_interests": null
},
"recipient": {
"name": "Giorgio Grassi",
"affiliation": null,
"username": "giorgio-grassi",
"link": null,
"image": {
"source": "https:\/\/s3.amazonaws.com\/zappy-avatars\/5744_avatar.jpg",
"placeholder": "https:\/\/s3.amazonaws.com\/zappy-avatars\/5744_avatar.jpg"
},
"badges": [
],
"research_interests": null
}
},
...
],
"pagination": {
"current_page": 1,
"total_pages": 0,
"total_results": null,
"next_page": null,
"prev_page": null,
"page_size": 99999,
"first": 0,
"last": null,
"changed_on": null
},
"status_code": 0
}
This method returns a list of last messages in each conversation. GUID in this list is the GUID of conversation.
HTTP Request
GET https://www.protocols.io/api/v3/conversations
Header Parameters
Query Partameters
Response
message
objects for all researcher conversations
pagination
0
means OK
Get conversation messages
Example Request | Get conversation messages
curl https://www.protocols.io/api/v3/conversations/<conversation_guid>/messages
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"messages": [
{
"id": 0,
"guid": "708FBBC0D83E11E8A5E01F4E8D036E92",
"parent_guid": "86389209B9E44D3CB4B8837A167073A5",
"subject": "RE: Dear Vladimir",
"body": "{\"blocks\":[{\"key\":\"4urf1\",\"text\":\"fasdf\",\"type\":\"unstyled\",\"depth\":0,\"inlineStyleRanges\":[],\"entityRanges\":[],\"data\":[]}],\"entityMap\":[]}",
"is_read": 1,
"created_on": 1540462332,
"last_modified": 0,
"type": "inbox",
"sender": {
"name": "Vladimir Frolov",
"affiliation": null,
"username": "vladimir-frolov1",
"link": null,
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/pztbjf6.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/pztbjf6.png"
},
"badges": [
],
"research_interests": null
},
"recipient": {
"name": "Ilyas Khayrullin",
"affiliation": null,
"username": "ilyas-khayrullin1",
"link": null,
"image": {
"source": "\/img\/avatars\/003.png",
"placeholder": "\/img\/avatars\/003.png"
},
"badges": [
],
"research_interests": null
}
},
...
],
"status_code": 0
}
This method return list of messages of conversation
HTTP Request
GET https://www.protocols.io/api/v3/conversations/<conversation_guid>/messages
Header Parameters
Response
message
objects for conversation
0
means OK
Check for new messages
Example Request | Get new messages guids and count of new messages
curl https://www.protocols.io/api/v3/conversations?new
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"total": 0,
"guids": [],
"status_code": 0
}
This method return new messages count and array of related conversation GUIDs
HTTP Request
GET https://www.protocols.io/api/v3/conversations?new
Header Parameters
Response
0
means OK
Set message as read
Example Request | Set message as read
curl https://www.protocols.io/api/v3/conversations/messages/<message_guid>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
Example Response
{
"status_code": 0
}
This method set message as read
HTTP Request
PUT https://www.protocols.io/api/v3/conversations/messages/<message_guid>
Header Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Send a message
Example Request | Send a message to user
curl https://www.protocols.io/api/v3/conversations/<conversation_guid>/messages
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d guid=<message guid>
-d subject=<message subject>
-d body=<message body>
-d username=<recipient username>
Example Response
{
"status_code": 0
}
This method send a message to user.
HTTP Request
POST https://www.protocols.io/api/v3/conversations/<conversation_guid>/messages
URL Parameters
Header Parameters
POST Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
Delete conversation
Example Request | Set message as read
curl https://www.protocols.io/api/v3/conversations/<conversation_guid>
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
Example Response
{
"status_code": 0
}
This method delete conversation.
HTTP Request
DELETE https://www.protocols.io/api/v3/conversations/<conversation_guid>
Header Parameters
Response
0
means OK
Status Codes HTTP/1.1 400
File Manager
File Manager has 3 API's that you need to use to load it properly:
1. get top folders
returns list of top folders that doesn't have parent folder
2. get folder ids
this API should be used for active folder.
It controlls ordering, sorting and pagination of the folder items.
After you call this API you should also call get items by ids
but only for items that wasn't loaded before.
e.c. user opens active folder, this API returns next ids: [1, 2, 3, 4, 5]
, app loads this items with get items by ids
API. Then user chang sorting, this API retunrs next: ids: [5, 2, 7, 8, 3]
, because 5, 3, 2
was loaded before app should send only 7, 8
to get items by ids
3. get items by ids
this API should be used only to loaded items by their ids
File Manager objects
OBjects list
{
"items": [
{
"item_id": 6017,
"content_type_id": 10,
"kind": "Folder",
"access": {
"can_view": 1,
"can_remove": 0,
"can_add": 1,
"can_edit": 0,
"can_publish": 0,
"can_get_doi": 0,
"can_share": 0,
"can_move": 0,
"can_transfer": 0,
"can_download": 1,
"is_locked": 0,
"can_upload": 1,
"can_edit_space": 0
},
"icon": {
"name": "/img/folders/MyFiles.svg",
"type": "svg",
"source": "/img/folders/MyFiles.svg",
"code": "MyFiles"
},
"id": 492911,
"title": "My files",
"guid": "BA565B15A9FE423ABC933ADB41847B62",
"parent_guid": "7E8474892766430DA73DF923F6819CAD",
"default_id": 0,
"type_id": 9,
"parent_type_id": 6,
"created_on": 1542634693,
"is_shared": 0,
"is_space": 0,
"subfolders_item_ids": [],
"visibility": 1,
"space": {
"is_member_folder": 0,
"is_members": 0,
"username": null,
"group": {
"id": 0,
"uri": null,
"title": null
}
}
},
{
"id": 17421,
"title": "untitled protocol",
"title_html": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": null,
"uri": "untitled-protocol-u9mez46",
"type_id": 1,
"published_on": null,
"stats": {
"number_of_views": 0,
"number_of_steps": 1,
"number_of_bookmarks": 0,
"number_of_comments": 0
},
"version_id": 0,
"created_on": 1542889816,
"creator": {
"name": "Invan Petrov",
"affiliation": "",
"username": "invan-petrov",
"link": null,
"image": {
"source": "https://s3.amazonaws.com/pr-journal/p77is9w.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/p77is9w.png"
},
"badges": [],
"research_interests": null
},
"public": 0,
"link": null,
"number_of_steps": 1,
"authors": [],
"versions": [],
"steps": [],
"materials": [],
"description": null,
"guidelines": null,
"before_start": null,
"collections": [],
"warning": null,
"keywords": null,
"manuscript_citation": null,
"documents": null,
"is_archived": 0,
"is_comparable": 0,
"is_locked": 0,
"is_locked_by": null,
"is_retracted": 0,
"fork_id": null,
"item_id": 6059,
"fork_info": [],
"public_fork_note": null,
"status": {
"id": 0,
"info": null
},
"is_donations_disabled": 0,
"ownership_history": null,
"last_modified": null,
"show_version": 0,
"can_add_version": 0,
"can_reassign": 0,
"is_donations_disabled_by_user": 0,
"is_contact_suspended": 0,
"has_guidelines": 0,
"transfer_to_user": [],
"access": {
"can_view": 1,
"can_remove": 1,
"can_add": 1,
"can_edit": 1,
"can_publish": 1,
"can_get_doi": 1,
"can_share": 1,
"can_move": 1,
"can_transfer": 1,
"can_download": 1,
"is_locked": 0,
"can_edit_space": 0
},
"comparable_forks": null,
"original_protocol_available": 0,
"shared_access_id": null,
"materials_text": null,
"show_comparison": false,
"content_type_id": 1,
"kind": "Private Protocol",
"icon": {
"code": "PrivateProtocol"
}
},
{
"id": 14272,
"title": "test.png",
"note": null,
"created_on": 1542901871,
"icon": {
"source": "http://localhost:81/img/extensions/png.png",
"placeholder": "http://localhost:81/img/extensions/png.png"
},
"file": {
"name": "test.png",
"type_id": 31,
"source": "https://s3.amazonaws.com/pr-journal/p8ais9w.png",
"placeholder": "http://localhost:81/img/extensions/png.png",
"original_type_id": 13
},
"item_id": 6062,
"content_type_id": 15,
"kind": "PNG Image",
"access": {
"can_view": 1,
"can_remove": 1,
"can_add": 1,
"can_edit": 1,
"can_publish": 1,
"can_get_doi": 1,
"can_share": 1,
"can_move": 1,
"can_transfer": 1,
"can_download": 1,
"is_locked": 0,
"can_edit_space": 0
}
},
{
"id": 506728,
"guid": "BA565B15A9FE423ABC933ADB41847B22",
"protocol_id": 17413,
"title": "my record #1",
"title_html": "my record #1",
"is_archived": 0,
"total_steps": 15,
"finished_steps": 10,
"scale_multiplier": 0,
"created_on": 1542634891,
"changed_on": 0,
"item_id": 6028,
"content_type_id": 11,
"kind": "Experiment",
"access": {
"can_view": 1,
"can_remove": 1,
"can_add": 1,
"can_edit": 1,
"can_publish": 1,
"can_get_doi": 1,
"can_share": 1,
"can_move": 1,
"can_transfer": 1,
"can_download": 1,
"is_locked": 0,
"can_edit_space": 0
},
"icon": {
"code": "PrivateProtocol"
}
}
],
"status_code": 0
}
folders can contain different types of items, for each type it return standard object structure with additional fields
Additional fields
for each type 1
- means user has such access
right now file manager suports next types of items:
folder
content_type_id: 10
protocol
but without steps and attachments
content_type_id: 1
record
but without steps and protocol
content_type_id: 11
file manager files
content_type_id: 15
File Manager file object
File Manager file object
{
"id": 14272,
"title": "test.png",
"note": null,
"created_on": 1542901871,
"file": {
"id": 20540,
"source": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"name": "5.png",
"placeholder_id": 0,
"placeholder": "https://s3.amazonaws.com/pr-journal/wb6h8en.png",
"icon": "https://www.protocols.io/img/extensions/png.png",
"type_id": 24
}
}
file
Base folder object
Example Object: Base Folder
{
"id": 492911,
"title": "My files",
"guid": "BA565B15A9FE423ABC933ADB41847B62",
"parent_guid": null,
"type_id": 2,
"parent_type_id": 0,
"created_on": 1542634693,
"icon": {
"type": "svg",
"source": "/img/folders/MyFiles.svg"
}
}
null
Small folder object
Example Object: Small Folder
{
"id": 245365,
"title": "Experiments",
"guid": "710DEFBFBD4B3DEFBFBD4933EFBFBD1F",
"type_id": 14,
"created_on": 1483926561,
"content_type_id": 10
},
Filemanager API
Get top folders
Example Request | get top folders
curl https://www.protocols.io/api/v3/filemanager/folders?top
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"folders": [
{
"item_id": 6017,
"content_type_id": 10,
"kind": null,
"access": {
"can_view": 1,
"can_remove": 0,
"can_add": 1,
"can_edit": 0,
"can_publish": 0,
"can_get_doi": 0,
"can_share": 0,
"can_move": 0,
"can_transfer": 0,
"can_download": 1,
"is_locked": 0,
"can_upload": 1,
"can_edit_space": 0
},
"icon": {
"name": "/img/folders/MyFiles.svg",
"type": "svg",
"source": "/img/folders/MyFiles.svg",
"code": "MyFiles"
},
"id": 492911,
"title": "My files",
"guid": "BA565B15A9FE423ABC933ADB41847B62",
"parent_guid": null,
"type_id": 2,
"parent_type_id": 0,
"created_on": 1542634693,
"visibility": 1
}
],
"status_code": 0
}
This method returns the list of folders from the file manager’s root folder.
HTTP Request
GET https://www.protocols.io/api/v3/filemanager/folders?top
Header Parameters
GET Parameters
not applicable to "my files", "shared with me" and "boomarks" folders
Response
array of file manager folders
0
means OK
Get folder ids
Example Request | get folder ids
curl https://www.protocols.io/api/v3/folders/<folder_guid>/ids
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"ids": [6032, 6020, 6060, 6059, 6026, 6025],
"pagination": {
"current_page": 1,
"total_pages": 1,
"total_results": 7,
"next_page": null,
"prev_page": null,
"page_size": "50",
"first": 0,
"last": 7,
"changed_on": null
},
"status_code": 0
}
This method returns file manager folder items ids
HTTP Request
GET https://www.protocols.io/api/v3/folders/<folder_guid>/ids
Header Parameters
URL Parameters
GET Parameters
50
1...100
.
1...n
.
sort_date
can be: sort_date
, sort_name
, sort_size
desc
asc
or desc
Response
empty
pagination
0
means OK
Get items by ids
Example Request | get items by uds
curl https://www.protocols.io/api/v3/filemanager/items?ids[]=1
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"items": [
{
"item_id": 6017,
"content_type_id": 10,
"kind": "Folder",
"access": {
"can_view": 1,
"can_remove": 0,
"can_add": 1,
"can_edit": 0,
"can_publish": 0,
"can_get_doi": 0,
"can_share": 0,
"can_move": 0,
"can_transfer": 0,
"can_download": 1,
"is_locked": 0,
"can_upload": 1,
"can_edit_space": 0
},
"icon": {
"type": "svg",
"source": "/img/folders/MyFiles.svg"
},
"id": 492911,
"title": "My files",
"guid": "BA565B15A9FE423ABC933ADB41847B62",
"parent_guid": "7E8474892766430DA73DF923F6819CAD",
"type_id": 9,
"parent_type_id": 6,
"created_on": 1542634693
},
{
"content_type_id": 1,
"kind": "Private Protocol",
"access": {
"can_view": 1,
"can_remove": 1,
"can_add": 1,
"can_edit": 1,
"can_publish": 1,
"can_get_doi": 1,
"can_share": 1,
"can_move": 1,
"can_transfer": 1,
"can_download": 1,
"is_locked": 0,
"can_edit_space": 0
},
"icon": {
"type": "svg",
"source": "/img/folders/PrivateProtocol.svg"
},
"id": 872,
"title": "Lysis Buffer (20 mL)",
"title_html": "<em>Lysis Buffer</em> (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"version_id": 1,
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0
}
],
"version_id": 0,
"link": "",
"number_of_steps": 3,
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
]
}
],
"status_code": 0
}
This method returns items by ids
HTTP Request
GET https://www.protocols.io/api/v3/filemanager/items?ids[]=1
Header Parameters
URL Parameters
GET Parameters
50
1...100
.
1...n
.
sort_date
can be: sort_date
, sort_name
, sort_size
desc
asc
or desc
Response
array of file manager items
0
means OK
Delete filemanager files
Example Request | delete files
curl https://www.protocols.io/api/v3/filemanager/trash
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
-d ids=<array of item_id's>
Example Response
{
"deleted": [6032, 6020, 6060, 6059, 6026, 6025],
"status_code": 0
}
This method put files into Trash folder
HTTP Request
PUT https://www.protocols.io/api/v3/filemanager/trash
Header Parameters
POST Parameters
Response
empty
0
means OK
Restore filemanager files
Example Request | restore files
curl https://www.protocols.io/api/v3/filemanager/trash
-H "Authorization: Bearer ACCESS_TOKEN"
-X DELETE
-d ids=<array of item_id's>
Example Response
{
"restored": [6032, 6020, 6060, 6059, 6026, 6025],
"status_code": 0
}
This method restores files from Trash folder
HTTP Request
DELETE https://www.protocols.io/api/v3/filemanager/trash
Header Parameters
POST Parameters
Response
empty
0
means OK
Files
to upload files we use AWS s3 but to begin and finish upload we need to run 2 APIs:
Prepare file upload
Example Request | prepare file upload
curl https://www.protocols.io/api/v3/files
-H "Authorization: Bearer ACCESS_TOKEN"
-X POST
-d filename=<original file name>
-d original_file_id=<id of thumbnail>
-d width=<img width>
-d height=<img height>
-d color=<img avg color>
Example Response
{
"formData": {
"key": "p48bjf6.jpg",
"s3_bucket": "pr-journal",
"AWSAccessKeyId": "AKIAIO6NV3DL7OZZGH3Q",
"Policy": "eyJleHBpcmF0aW9uIjoiMjAxOC0xMC0wOVQxMTozNzoxMFoiLCJjb25kaXRpb25zIjpbeyJhY2wiOiJwdWJsaWMtcmVhZCJ9LHsiY29udGVudC10eXBlIjoiaW1hZ2VcL2pwZWcifSx7ImJ1Y2tldCI6InByLWpvdXJuYWwifSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIiJdXX0=",
"Signature": "iHkf05vPC6cTMJBxOr5VfZE0i3Y=",
"ContentType": "image/jpeg",
"acl": "public-read"
},
"metaData": {
"file_id": "14174",
"file_type": "32",
"thumb_url": "http://localhost:81/img/extensions/jpg.png"
},
"status_code": 0
}
This method prepare file records and returns meta data for AWS s3 upload
HTTP Request
POST https://www.protocols.io/api/v3/files
Header Parameters
POST Parameters
Response
Status Codes HTTP/1.1 400
Verify file upload
Example Request | verify file upload
curl https://www.protocols.io/api/v3/files/<file_id>
-H "Authorization: Bearer ACCESS_TOKEN"
-X PUT
Example Response
{
"status_code": 0
}
This method verify file in database
HTTP Request
PUT https://www.protocols.io/api/v3/files/<file_id>
Header Parameters
URL Parameters
Status Codes HTTP/1.1 400
Pagination
Pagination object
Example Object: Pagination
{
"current_page": 0,
"total_pages": 6,
"total_results": 30,
"next_page": "https:\/\/www.protocols.io\/api\/v3\/records?active&page_size=5&page_id=1",
"prev_page": null,
"page_size": 5,
"first": 0,
"last": 30,
"changed_on": 1522839972
}
null
null
Notifications
Notification object
Example Object: Notification
{
"id": 50693,
"pattern": "You joined @group",
"type_id": 51,
"created_on": 1544017709,
"name": "Joining group",
"list_name": "list of items",
"objects": {
"user": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov1",
"link": "https:\/\/protocols.io",
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/pztbjf6.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/pztbjf6.png"
},
"badges": [
{
"id": 4,
"image": {
"source": "\/img\/badges\/gold.svg",
"placeholder": "\/img\/badges\/gold.svg"
},
"name": "Gold power author!"
},
{
"id": 5,
"image": {
"source": "\/img\/badges\/earlyadopter.svg",
"placeholder": "\/img\/badges\/earlyadopter.svg"
},
"name": "Early adopter"
},
{
"id": 6,
"image": {
"source": "\/img\/badges\/socialbutterfly.svg",
"placeholder": "\/img\/badges\/socialbutterfly.svg"
},
"name": "Social butterfly"
}
],
"research_interests": "WEB"
},
"group": {
"id": 2811,
"uri": "newpublicgroupilyas",
"title": "NewPublicGroupIlyas",
"image": {
"source": "https:\/\/s3.amazonaws.com\/pr-journal\/wcvh8en.png",
"placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/wcvh8en.png"
},
"tech_support": {
"email": null,
"phone": null,
"hide_contact": 0,
"use_email": 0
},
"is_member": 0
}
},
"placeholders": {
"user": {
"name": "Vladimir Frolov",
"link": "http:\/\/localhost:81\/researchers\/vladimir-frolov1"
},
"group": {
"name": "NewPublicGroupIlyas",
"link": "http:\/\/localhost:81\/workspace\/newpublicgroupilyas"
}
}
}
objects
, each placeholder object has the same key (e.c. user
, protocol
etc) but always has standard structure with name
& link
that described below:
user object
group object
comment object
message object
protocol object
protocol
, folder
, record
, file
name
& link
that described below:
Get Notifications List
Example Request | all user notifications
curl https://www.protocols.io/api/v3/researchers/notifications
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"list": [
{
"id": 50693,
"pattern": "You joined @group",
"type_id": 51,
"created_on": 1544017709,
"name": "Joining group",
"objects": {
"user": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov1",
"link": "https://protocols.io",
"image": {
"source": "https://s3.amazonaws.com/pr-journal/pztbjf6.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/pztbjf6.png"
},
"badges": [
{
"id": 4,
"image": {
"source": "/img/badges/gold.svg",
"placeholder": "/img/badges/gold.svg"
},
"name": "Gold power author!"
},
{
"id": 5,
"image": {
"source": "/img/badges/earlyadopter.svg",
"placeholder": "/img/badges/earlyadopter.svg"
},
"name": "Early adopter"
},
{
"id": 6,
"image": {
"source": "/img/badges/socialbutterfly.svg",
"placeholder": "/img/badges/socialbutterfly.svg"
},
"name": "Social butterfly"
}
],
"research_interests": "WEB"
},
"group": {
"id": 2811,
"uri": "newpublicgroupilyas",
"title": "NewPublicGroupIlyas",
"image": {
"source": "https://s3.amazonaws.com/pr-journal/wcvh8en.png",
"placeholder": "https://s3.amazonaws.com/pr-journal/wcvh8en.png"
},
"tech_support": {
"email": null,
"phone": null,
"hide_contact": 0,
"use_email": 0
},
"is_member": 0
}
},
"placeholders": {
"user": {
"name": "Vladimir Frolov",
"link": "http://localhost:81/researchers/vladimir-frolov1"
},
"group": {
"name": "NewPublicGroupIlyas",
"link": "http://localhost:81/workspace/newpublicgroupilyas"
}
},
"list_name": "list of items"
}
],
"pagination": {
"current_page": 1,
"total_pages": 261,
"total_results": 521,
"next_page": "http://localhost:81/api/v3/researchers/notifications?page_size=2&page_id=2",
"prev_page": null,
"page_size": 2,
"first": 0,
"last": 521,
"changed_on": null
},
"status_code": 0
}
This method retrieves the list of notifications.
HTTP Request
GET https://www.protocols.io/api/v3/researchers/notifications
Header Parameters
GET Parameters
1...100
.
1...n
.
Response
notification
objects.
pagination
0
means OK
Archive
Get Protocol Archived
Example Request
curl https://www.protocols.io/api/v3/protocols/[id]
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"protocol": {
"id": 872,
"title": "Lysis Buffer (20 mL)",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"doi": "dx.doi.org/10.17504/protocols.io.c4gytv",
"uri": "lysis-buffer-20-ml-c4gytv",
"published_on": 1487372466,
"created_on": 1434670606,
"creator": {
"name": "Celina Gomez",
"affiliation": null,
"username": "celina-gomez",
"link": "",
"image": {
"source": null,
"placeholder": null
}
},
"public": 1,
"versions": [
{
"id": 10091,
"title": "untitled protocol",
"image": {
"source": "https://www.protocols.io/img/default_protocol.png",
"placeholder": "https://www.protocols.io/img/default_protocol.png"
},
"version_id": 1,
"doi": null,
"uri": "untitled-protocol-m4jc8un",
"published_on": 0
}
],
"version_id": 0,
"link": "",
"guid": "6D11D26701CA4EBAA5CA56859CCA8AC3",
"authors": [
{
"name": "Matt Sullivan Lab",
"affiliation": "Matt Sullivan Lab",
"username": null,
"link": null,
"image": {
"source": null,
"placeholder": null
}
}
],
"steps": [...],
"materials": [...]
},
"status_code": 0
}
This method retrieves a protocol.
HTTP Request
GET https://www.protocols.io/api/v3/protocols/[id]
GET Parameters
1) Integer protocol id
2) String protocol uri
3) DOI e.g. 10.17504/protocols.io.baaciaaw or protocols.io.baaciaaw
Header Parameters
Response
protocol
0
means OK
Get Record Archived
Example Request | load record by guid
curl "https://www.protocols.io/api/v3/records/<record_guid>?with_protocol=1&as_draft=1"
-H "Authorization: Bearer ACCESS_TOKEN"
Example Response
{
"record": {
"before_start": null,
"can_edit": "0",
"changed_on": "1541159777",
"content_type_id": 11,
"created_on": "1541159777",
"creator": {
"affiliation": "",
"badges": [],
"image": {
"placeholder": "",
"source": "",
"webp_source": ""
},
"link": "",
"name": "",
"username": ""
},
"guid": "6970DBF2F3EA4CE4AB3AB77B54C90A21",
"id": "507283",
"image": {
"placeholder": "https://www.protocols.io/img/default_protocol.png",
"source": "https://www.protocols.io/img/default_protocol.png"
},
"in_trash": false,
"is_archived": "0",
"is_locked": "1",
"item_id": "38",
"location": null,
"notes": [],
"number_of_finished_steps": "0",
"protocol_id": "21",
"protocol_json": {...},
"scale_multiplier": "1.000",
"steps": [...],
"title": "Prot for run record",
"title_html": "Prot for run record",
"total_steps": "3",
"units": [...]
},
"protocol": {
"id": 506709,
"guid": "1526B6F645EE4B4A985D253E13813923",
"title": "untitled protocol",
"title_html": "untitled protocol",
"item_id": 5737,
"image": {
"source": "https:\/\/www.protocols.io\/img\/default_protocol.png",
"placeholder": "https:\/\/www.protocols.io\/img\/default_protocol.png"
},
"created_on": 1536868966,
"changed_on": 1536868966,
"is_archived": 0,
"total_steps": 4,
"finished_steps": 0,
"scale_multiplier": 1,
"creator": {
"name": "Vladimir Frolov",
"affiliation": "protocols.io",
"username": "vladimir-frolov12",
"link": "https:\/\/protocols.io",
"image": {
"source": "\/img\/avatars\/003.png",
"placeholder": "\/img\/avatars\/003.png"
},
"badges": [
]
},
"steps": [...]
},
"status_code": 0
}
This method return record by guid.
HTTP Request
GET https://www.protocols.io/api/v3/records
Header Parameters
API Parameters
1
- return record with related protocol data
0
- return only record data
1
- return new formatted data (steps and some other text fields will be in stringified draft json format)
0
- return old formatted data
Response
record object
protocol object
with additional fields, described belowrecord step notes
1
- step checked
0
- step not checked
1
- step skipped
0
- step not skipped
HTTP Errors
- 200 - OK
- 400 - Bad Request
- 500 - Internal Server Error