NAV Navbar
json
  • Authentication
  • OAuth
  • Objects
  • Profile API
  • Protocols
  • Protocols API
  • Publications API
  • Draft
  • Discussions API
  • Experiment records API
  • Experiment records
  • Workspaces
  • Workspaces API
  • Messages API
  • File Manager
  • Filemanager API
  • Pagination
  • Notifications
  • Archive
  • HTTP Errors
  • Authentication

    There are two types of access tokens: client and oauth

    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]
    
    1. Open http://www.protocols.io/developers and copy your client_id and client_secret.
    2. Provide your redirect url under private access block.
    3. Put authorization link inside your apication.
    4. Your requests will be redirected to [your_redirect_url]?code=[new_code]&scope=[your_scope].
    5. Use the code to get user OAUTH_ACCESS_TOKEN by calling https://www.protocols.io/api/v3/oauth/token with grant_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 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

    client_id Required string The identifier of the client. client_secret Required string Secret key of the client. grant_type Required string should be authorization_code or refresh_token. code required for authorization_code grant_type string code which you recive when client complite authentication on protocols.io. refresh_token required for refresh_token grant_type string refresh token which you recive together with access_token.

    Response

    access_token string new access code. token_type string type of token. expires_in int time on seconds until token become expired. scope string granted scope type. refresh_token string new refresh token. refresh_expires_in int time on seconds until refresh token become expired. user user user data.

    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"
        }
    }
    

    name string user full name affiliation string, can be null user affiliation username string, can be null username link string, can be null external url. image image user profile image

    Small user object

    Example Object: Small user

    {
        "name": "Vladimir Frolov",
        "affiliation": null,
        "username": "vladimir-frolov10"
    }
    

    name string user full name affiliation string, can be null user affiliation username string, can be null username

    Image object

    Example Object: Image

    {
        "source": "https://www.protocols.io/img/default_protocol.png",
        "placeholder": "https://www.protocols.io/img/default_protocol.png"
    }
    

    source string, can be null link to the image placeholder string, can be null link to the image placeholder or original image link if a placeholder image does not exist

    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
    }
    

    id int file id source string link to the file name string original name of the file icon string link to the file icon image content_type_id int content type id (used in list of items) file_type int type of file:
    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
    }
    

    id int file id source string link to the file name string original name of the file placeholder_id int, can be 0 if file is not an image id of thumb for original file (if original file is image) placeholder string link to the file thumb or original file link if a placeholder file does not exist icon string link to the file icon image type_id int integer identifier of file type

    Badge object

    Example Object: Badge

    {
      "id": 1,
      "image": {
        "source": "\/img\/ambassador.svg",
        "placeholder": "\/img\/ambassador.svg"
      },
      "name": "Ambassador"
    }
    

    id int id of badge image image badge image name string name of badge

    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"
        }
      }
    }
    

    id int unique reagent integer identifier. mol_weight float molarity weight. name string name of reagent. linfor string, can be empty linear formula. url string, can be null external url. sku string reagent sku. vendor user reagent vendor.

    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": [...]
    }
    

    id int unique comment integer identifier. parent_id int id of parent comment. title string, can be empty title of comment. body string, can be empty body of comment. created_on int unix timestamp. date/time of comment creation. changed_on int unix timestamp. date/time when comment was modified last time. creator user comment creator. comments comment comment replies.

    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
      }
    }
    

    guid int unique message guid subject string message subject body string message body is_read int flag, shows was message read by recipient or not created_on int unix timestamp. date/time of message creation. last_modified int unix timestamp. date/time when message was modified last time. type string, can be sent/receive flag, show is message sent or received sender user message sender. recipient user message recipient.

    Unit object

    Example Object: Unit

    {
        "id": 1,
        "type_id": 3,
        "name": "µL",
        "can_manage": 0,
        "read_only": 0
    }
    

    id int unique unit id type_id int draft entity type_id name string unit name can_manage int flag, shows if user can edit/delete this unit read_only int if read_only = 1, this unit shouldn't be used in the editor

    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
    }
    

    name string user full name. affiliation string user affiliation. username string username link string link so some website. image image user profile image first_name string user first name. last_name string user last name. bio string user bio. email string user email.

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    status_code int Status code of request, 0 means OK user user extended user object

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    PUT Parameters

    first_name optional string new first name last_name optional string new last name email optional string new email password optional string new password old_password Required if password sent string old password bio optional string new bio image optional string new image url affiliation optional string new affiliation link optional string new link

    Response

    updated user object

    status_code int Status code of request, 0 means OK user user extended user object

    Errors list

    status code description 123 Provided email is already in use. 124 Invalid email address.

    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
    }
    

    id int unique protocol integer identifier. title string protocol title. title_html string protocol title with html tags. image image protocol image. uri string unique protocol text identifier. type_id int protocol type
    1 - protocol
    3 - collection
    4 - document
    content_type_id int content type id (used in list of items)

    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
    }
    

    id int unique protocol integer identifier. guid string unique protocol guid w/o dashes. title string protocol title. title_html string, can be null protocol title with html tags. image image protocol image. version_id int 0...n. Version number of this protocol. doi string, can be empty DOI of this protocol. uri string unique protocol text identifier. published_on int, can be null unix timestamp. date/time when this protocol was published.

    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": [...],
    }
    

    id int unique protocol integer identifier. guid string unique protocol guid w/o dashes. title string protocol title. title_html string protocol title with html tags. image image protocol image. doi string DOI of this protocol. uri string unique protocol text identifier. published_on int, can be null unix timestamp. date/time when this protocol was published. created_on int unix timestamp. date/time of protocol creation. creator user protocol creator public boolean (int 1|0 for v3 endpoints) true means that this protocol is public and false otherwise. versions array, can be empty list of versions version_id int 0...n. Version number of this protocol. link string, can be null External protocol link url string protocol url on protocols.io authors array, can be empty list of user or empty array materials list of reagent or empty array description string, can be null Description (abstract) guidelines string, can be null guidelines before_start string, can be null Before start instructions warning string, can be null Warnings materials_text string, can be null Materials text. units array Array of units objects stats object List of protocol stats such as number of views or number of bookmarks. stats object: number_of_steps int total number of steps number_of_votes int total number of votes ("Works for me" button) documents int list of 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
    }
    

    id int unique step integer identifier. guid string unique step guid. previous_id int, can be null id of previous step. previous_guid string, can be null guid of previous step. cases array, can be empty or null list of step cases. step string step content json (default), html, or markdown, depending on the API request parameter. section string, can be empty or null step section
    section_color string, can be empty or null color of step section, HEX color code

    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"
    }
    

    title string case title description string description of case, represented as stringified draft object
    first_step_guid string linked step guid

    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
    }
    

    comment_id int unique comment integer identifier. discussion_id int unique discussion integer identifier. parent_id int id of parent comment. uri comment uri body string, can be empty body of comment. created_on int unix timestamp. date/time of comment creation. changed_on int unix timestamp. date/time when comment was modified last time. creator user comment creator. comments protocol-comment comment replies. can_delete the flag shows ability to delete comment can_edit the flag shows ability to delete comment step_id protocol step id (for step-level comments), for protocol level comments step id = 0 is_discussion ?? the flag shows the comment is main comment of the discussion ?? is_private the flag shows the comment is private

    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"
    }
    

    thumb_url string url of the file thumbnail. url string url of the attachment ofn string original file name

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    filter Required string protocols filter, should one of:
    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.
    key Required string Search key. String may contatn any chars, numbers and special symbols. System will seach around protocol name, description, authors. If the search keywords are enclosed into double quotes, then result contains only the exact match of the combined term order_field optional, default is activity string one of next fields:
    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.
    order_dir optional, default is desc string order direction, should be asc or desc. fields optional, default is eveything string list of fields to return. You can put any fields from item. Fields should be comma-separated. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of protocol objects. total int Total number of items total_pages int Total number of pages pagination pagination pagination object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 1302 Wrong order field

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    id Required int or string One of the following:
    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
    last_version If set to 1 server returns last version of this protocol content_format json|html|markdown specify format for data fields: description, before_start, guidelines, warning, materials_text, steps[i].step

    json - draft object
    html - plain html
    markdown - plain markdown

    Response

    protocol protocol protocol object with steps and materials. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    id Required int or string One of the following:
    1) Integer protocol id
    2) String protocol uri
    3) DOI e.g. 10.17504/protocols.io.baaciaaw or protocols.io.baaciaaw
    last_version If set to 1 server returns last version of this protocol content_format json|html|markdown specify format for data fields: description, before_start, guidelines, warning, materials_text, steps[i].step

    json - draft object
    html - plain html
    markdown - plain markdown

    Response

    steps array, can be empty List of steps. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    filter Required string protocols filter, should one of:
    1. user_all - list of all public protocols;
    2. user_public - list of public protocols that was publiches by concrete user;
    key optional, default is empty string Search key. String may contatn any chars, numbers and special symbols. System will seach around protocol name, description, authors. order_field optional, default is activity string one of next fields:
    activity - index of protocol popularity;
    date - date of publication;
    name - protocol name;
    id - id of protocol.
    order_dir optional, default is desc string order direction, should be asc or desc. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of protocol objects. pagination pagination pagination object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 132 Access denied 1302 Wrong order field

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    key optional, default is empty string Search key. String may contatn any chars, numbers and special symbols. System will seach around protocol name, description, authors. order_field optional, default is activity string one of next fields:
    activity - index of protocol popularity;
    date - date of publication;
    name - protocol name;
    id - id of protocol.
    order_dir optional, default is desc string order direction, should be asc or desc. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of protocol objects. pagination pagination pagination object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 132 Access denied 1302 Wrong order field

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    materials array, can be empty List of materials. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URI Parameters

    guid string new GUID w/o dashes

    POST Parameters

    type_id optional, default is 1 int protocol type id
    1 - protocol
    3 - collection
    4 - document

    Response

    status_code int Status code of request, 0 means OK protocol protocol protocol object with steps and materials.

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URI Parameters

    guid string protocol GUID w/o dashes

    POST Parameters

    actions requried actions array array of actions to apply on a protocol

    Response

    status_code int Status code of request, 0 means OK actions actions array or null some changes may also produce actions that we done on the back-end, such actions will be returned as a response e.c. changes of protocol title also must change protocol uri, so such actions needed to sync your local protocol object

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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"
      }
    }
    

    status_code int error integer code error_message int error details Error message fields: path string stack path where error was occured error string error text

    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.

    guid string Unique action GUID w/o dashes microtime int UTC time in miliseconds when action happened marker string Action marker. Each marker has own rule for up/down path and value (see below) up/down object up & down controls changes that has to be applied on the protocol object (see below)

    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

    marker string description main:update-image update protocol image path [ "image" ] up value image object down value current value main:change-protocol-keywords update protocol keywords path [ keywords ] up value string down value current value main:change-protocol-external-link update protocol external link path [ keywords ] up value url string down value current value main:change-materials update protocol materials path [ materialsIDS ] up value array or reagents ids down value current value main:change-protocol-title update protocol title path [ title_html ] up value html string down value current value authors:change-authors update protocol authors path [ authors ] up value array of user objects down value current value guidelines:change-content-warning update protocol content warning status path [ is_content_warning ] up value int: 1 or 0 down value current value guidelines:change-content-confidential update protocol content confidential status path [ is_content_confidential ] up value int: 1 or 0 down value current value draft:change-step-section-<step guid> update protocol step section text path ["steps", <step guid>, "section"] up value new html string up value current html string draft:change-step-<step guid> update protocol step content path ["steps", <step guid>, "data"] up value new html string or draft json down value current html string or draft json draft:change-description update protocol description path ["description"] up value new html string or draft json down value current html string or draft json draft:change-document update document body (only applied when protocol type id is 4) path ["document"] up value new html string or draft json down value current html string or draft json draft:change-guidelines update protocol guidelines body path ["guidelines"] up value new html string or draft json down value current html string or draft json draft:change-before-start update protocol before start body path ["before_start"] up value new html string or draft json down value current html string or draft json draft:change-warning update protocol warning body path ["warning"] up value new html string or draft json down value current html string or draft json draft:change-manuscript update protocol manuscript citation body path ["manuscript_citation"] up value new html string down value current html string draft:change-materials-text update protocol materials text body path ["materials_text"] up value new html string or draft json down value current html string or draft json step:add-step add new protocol step path ["steps", "<step guid>"] up value step object down value empty step:delete-steps remove protocol step, don't forget to update next step previous guid, otherwise tree integrity will be broken path ["steps", "<step guid>"] up value empty down value step object step:update-step-previous-guid update protocol step previous guid path ["steps", "<step guid>", "previous_guid"] up value new GUID string down value current GUID string

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URI Parameters

    title optional string new protocol title prepublish optional int Set it to 1 if you need to get DOI for a protocol without making it publicly accessible.

    POST Parameters

    protocol_uri int uri of a protocol

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 101 Not authorized 255 protocol already public 256 protocol requries title to be published 257 protocol requries at least one author to be published

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URI Parameters

    protocol_uri int uri of a protocol

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URI Parameters

    protocol_uri int uri of a protocol

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    latest Required int number of last publications to return 1..100

    Response

    items array List of protocol objects. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    from Required int timestamp of the beginning of the period to Required int timestamp of the ending of the period

    Response

    items array List of protocol objects. status_code int Status code of request, 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"
          }
        }
      }
    }
    

    blocks array of content blocks Represents the full state of a single block of editable content.
    Content block objects are largely analogous to block-level HTML elements like paragraphs and list items
    entityMap array of entities Entities map. Contains all entities of blocks

    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
        }
      ]
    }
    

    key string Unique string block identifier text string Plain text contents of the block type string Block type block types (all styles described below should be applied to the whole block): atomic custom block that should be replaced with special block rendered from entity data unstyled Default block, has no styles align-center Centers the text align-left Aligns the text to the left align-right Aligns the text to the right align-justify Stretches the lines so that each line has equal width unordered-list-item this block is a part of unordered list ordered-list-item this block is a part of ordered list

    inlineStyleRanges array Array of styles should be applied to block text Inline style range object: offset int Offset from start of the block text length int Range length style string Style from list below Styles: bold Bold text italic Italic text sup Superscript sub Subscript entityRanges array Array of entities that should be inserted into block text Entity range object: offset int Offset from start of the block text length int Range length key int Key of entity from entityMap object

    Entity object

    {
      "type": "temperature",
      "data": {
        "temperature": "10",
        "unit": 10,
        "label": "temperature label"
      }
    }
    

    type string entity type data object entity data, contains different data objects depending on entity type Entities list: amount object amount object
    duration object duration object
    link object link object software object software object
    dataset object dataset object
    command object command object
    result object result object
    protocols object protocol object
    safety object safety information object
    reagents object reagent object
    gotostep object go to step object temperature object temperature object
    concentration object concentration object notes object note object has structure identical to comment
    documents object document object has structure identical to protocol object equipment object equipment object formula object formula object
    embed object embed object code_insert object code object image object image object imageblock object image object video object video object

    Draft entities types

    Formula draft object

    Example Object: Formula draft object

    {
      "formula": "x^2 + y^2"
    }
    

    formula string MathML/TeX formula representation

    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>"
    }
    

    embed string Embed code string

    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": ""
    }
    

    source string image url original_name string, can be null image title mime string, can be null file mime type
    width float, can be null resized image width in px legend draft object, can be empty string or null Legend that user provides to this image.
    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"
    }
    

    source string video url original_name string video title mime string file mime type

    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"
    }
    

    source string file url placeholder string file icon url original_name string file name

    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": ""
    }
    

    colWidths array array of table columns widths (left to right) rowHeights array array of table rows heights (top to bottom) cellsMeta object map of cells classes:
    key: row_col,
    value: combination of classes described below
    Cells classes: _dt-bold bold text _dt-italic italic text
    _dt-h-left left aligned _dt-h-right right aligned
    _dt-h-center centred horizontally text
    _dt-h-justify justified text
    _dt-v-top top aligned
    _dt-v-middle middle vertically aligned
    _dt-v-bottom bottom aligned
    data two dimensional array represents table data:
    first dimension - table rows,
    second - table columns

    mergeCells array describes merged cells:
    row - row index,
    col - column index,
    rowspan - number of rows to merge,
    colspan - number of columns to merge
    legend draft object, can be empty string Legend that user provides to this image.
    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
      }
    }
    

    brand string equipment brand sku string equipment sku specifications string equipment specifications link string equipment link type string equipment type name string equipment name image file object equipment image
    file file object equipment file

    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"
    }
    

    amount int amount quantity. unit string unit id label string, can be empty label of amount.

    Duration draft object

    Example Object: Duration draft object

    {
      "duration": 11,
      "label": "boil"
    }
    

    duration int duration in seconds. label string, can be empty label of duration.

    Example Object: Link draft object

    {
      "url": "https://www.protocols.io"
    }
    

    url string, can be empty external url.

    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"
    }
    

    name string name of software. developer string, can be empty developer of software. repository string, can be empty url or name of repository. link string, can be empty external url. os_name string, can be empty name of operating system. os_version string, can be empty version of operating system.

    Dataset package draft object

    Example Object: Dataset package draft object

    {
      "name": "DataTable",
      "link": "https://protocols.io"
    }
    

    name string name of software. link string, can be empty external url.

    Command package draft object

    Example Object: Command package draft object

    {
      "name": "Code",
      "command": "echo 'hello world!'",
      "os_name": "windows",
      "os_version": "10",
      "description": "desc" 
    }
    

    name string name of command. command string, can be empty executable command. os_name string, can be empty name of operating system. os_version string, can be empty version of operating system.
    description string, can be empty description of command.

    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"
    }
    

    title string, can be empty some text, usually explaining the reason to go to previous step. step_guid string linked step guid.

    Temperature draft object

    Example Object: Temperature draft object

    {
      "temperature": 12,
      "unit": "°C",
      "label": "boil"
    }
    

    temperature int temperature value. unit string unit id label string, can be empty label of temperature.

    Concentration draft object

    Example Object: Concentration draft object

    {
      "concentration": 12,
      "unit": "°C",
      "label": "boil"
    }
    

    concentration int concentration value. unit string unit id label string, can be empty label of concentration.

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    comments list of protocol-comment objects array status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    body required string Body of the comment is_private optional, default is null int private flag

    Response

    comment protocol-comment added comment object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    body required string Body of the comment

    Response

    comment protocol-comment added comment object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    body required string Body of the comment protocol_uri required string uri of a protocol is_private optional, default is null int private flag

    Response

    comment protocol-comment added comment object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    body required string Body of the comment protocol_uri required string uri of a protocol

    Response

    comment protocol-comment added comment object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    body required string Body of the comment protocol_uri required string uri of a protocol

    Response

    comment protocol-comment added comment object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    PUT Parameters

    body required string Body of the comment

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 5 Body of comment can`t be empty 5 Comment id must be an integer value

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    PUT Parameters

    body required string Body of the discussion

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 5 Body of discussion can`t be empty 5 Discussion id must be an integer value

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 5 Comment id must be an integer value

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 5 Discussion id must be an integer value

    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
        }
      ]
    }
    

    id int unique record integer identifier guid string unique record string identifier title string record title title_html string record title with html tags item_id int unique record integer identifier in file manager system image image record image created_on int unix timestamp. date/time when record was created changed_on int unix timestamp. date/time when record was modified total_steps int total number of record steps finished_steps int number of finished record steps scale_multiplier float scale multiplier for step components like amount creator user record creator location array of small folder record location steps array of protocol step with additional fields, described below record steps additional protocol steps fields: is_checked int 1 - step checked
    0 - step not checked
    checked_on int can be null timestamp shows when step was checked is_skipped int 1 - step skipped
    0 - step not skipped
    skipped_on int can be null timestamp shows when step was 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
      }
    }
    

    id int note id created_on int note cretion timestamp modified_on int note modification timestamp file file object, can be null image object for note

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    active Required string right now we support only one type of records - active porjects. Active means records that has total steps > finished steps. archived optional string if archived parameter is set archived records will be returned, otherwise not archived. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of records objects. pagination pagination pagination object

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    with_protocol optional, default is null int 1 - return record with related protocol data
    0 - return only record data
    content_format json|html|markdown specify format for data fields: description, before_start, guidelines, warning, materials_text, steps[i].step

    json - draft object
    html - plain html
    markdown - plain markdown

    Response

    record record object protocol 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    protocol_uri Required string uri of a protocol for which the record will be created folder_data optional object record folder data, if empty - record will be created in user's private folder of the active workspace folder object: guid optional string guid of existed folder stack optional array of objects described below

    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,
      }
    },
    

    type required string unique record integer identifier in file manager system.
    base changes affect record itself notes changes affect notes of the record step changes affect steps of the record
    data required object could be base data object, notes data object or step data object

    base data object

    title required string new record title

    notes data object

    note required string note text step_id required int id of the step for which the note changes
    if note adding to the whole record should be 0
    specify this parameter only when id is null

    step data object

    guid required string record step guid that should be changed is_checked optional boolean or int shows that the step is checked is_skipped optional boolean or int shows that step is skipped

    Response

    record record-object status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    guid Required string record guid

    API Parameters

    stack Required array of objects described below

    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,
      }
    },
    

    type required string unique record integer identifier in file manager system.
    base changes affect record itself notes changes affect notes of the record step changes affect steps of the record
    data required object could be base data object, notes data object or step data object

    base data object

    title required string new record title

    notes data object

    id optional, can be null int id of record note, if adding a new note - should be null note required string note text step_id optional int id of the step for which the note changes
    if note adding to the whole record should be 0
    specify this parameter only when id is null

    step data object

    guid required string record step guid that should be changed is_checked optional boolean or int shows that the step is checked is_skipped optional boolean or int shows that step is skipped

    Response

    status_code int Status code of request, 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
      }
    }
    

    id int unique workspace integer identifier. uri string unique workspace string identifier. title string workspace title. image image workspace image. description string workspace description. research_interests string workspace research interests. website string workspace website. location string workspace location. affiliation string workspace affiliation. status object workspace statuses. workspace status object: is_visible bool true this workspace is public access_level int 0 - anyone can join 1 - users must send requests to join 2 - users can join by invitation only stats object workspace stats workspace stats object: files object workspace files statistic files statistic object: publish int total publications forks int total forked files shared int total shared files archived int total archived files total_members int total workspace members user_status user status this object reporesents statuses of access token user to this workspace

    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>."
    }
    

    id int unique workspace integer identifier. uri string unique workspace string identifier. title string workspace title. image image workspace image. is_member int 1 or 0. 1 means that current user is a member of this workspace. description string workspace description.

    Workspace user status object

    {
      "is_member": true,
      "is_confimed": true,
      "is_invited": false,
      "is_owner": false
    }
    

    is_member bool true mean that user is workspace member is_confimed bool true mean that user is confirmed workspace member is_invited bool true mean that user is invited workspace member is_owner bool 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    key optional, default is empty string Search key. String may contatn any chars, numbers and special symbols. System will seach around workspace name, description. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of workspace objects. pagination pagination pagination object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    key optional, default is empty string Search key. String may contatn any chars, numbers and special symbols. System will seach around workspace name, description. page_size optional, default is 10 string number of items per one page. 1...100. page_id optional, default is 1 string id of page. 1...n.

    Response

    items array, can be empty List of workspace objects. pagination pagination pagination object status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    uri Required string gropu uri on protocols.io

    Header Parameters

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    workspace workspace workspace object. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    uri Required string gropu uri on protocols.io

    Response

    user_status user status this object reporesents new statuses of access token user to this workspace status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    uri Required string gropu uri on protocols.io

    Response

    user_status user status this object reporesents new statuses of access token user to this workspace status_code int Status code of request, 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:

    HTTP Request

    DELETE https://www.protocols.io/api/v3/workspaces/<uri>/members

    Header Parameters

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    uri Required string gropu uri on protocols.io

    Response

    user_status user status this object reporesents new statuses of access token user to this workspace status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Query Partameters

    page_id int, default null page id page_size int, default 99999 page size key string, default null search key for conversations

    Response

    messages list of last message objects for all researcher conversations array pagination pagination pagination object status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    conversation list of message objects for conversation array status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    total int number of new messages guids array new conversation GUIDs status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    conversation_guid optional if conversation_guid is not set new converstaion will be created otherwise message will be added to existed conversation

    Header Parameters

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    guid Required, string guid of new message subject Required, string subject of the message body Required. string body of the message username Required, string recipient username

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    status_code int Status code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    item_id int unique item id content_type_id int item ineger type id kind string item string type access object item access
    for each type 1 - means user has such access
    can_view int user can view this item can_remove int user can remove this item can_add int user can add smth into this item (e.c. new item into folder) can_edit int user can edit this item can_publish int user can publish this item can_get_doi int user can get DOI for this item can_share int user can share this item can_move int user can move this item between folders can_transfer int user can transfer this item can_download int user can export this item is_locked int this item locked by someone else

    right now file manager suports next types of items:

    folder folder
    content_type_id: 10
    protocol protocol but without steps and attachments
    content_type_id: 1
    records record but without steps and protocol
    content_type_id: 11
    files 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
      }
    }
    

    id int object id title string file title note string user note created_on int unix timestamp. date/time when file was created. file file attached 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"
      }
    }
    

    id int unique folder integer identifier. guid string unique folder guid identifier. parent guid string, can be null parent folder guid. title string folder title. type_id int folder type id. parent_type_id int parent folder type id. created_on int unix timestamp. date/time when folder was created. icon object folder icon type string icon type source string path to icon file on https://www.protocols.io

    Small folder object

    Example Object: Small Folder

    {
      "id": 245365,
      "title": "Experiments",
      "guid": "710DEFBFBD4B3DEFBFBD4933EFBFBD1F",
      "type_id": 14,
      "created_on": 1483926561,
      "content_type_id": 10
    },
    

    id int unique folder integer identifier. guid string unique folder guid identifier. title string folder title. type_id int folder type id. created_on int unix timestamp. date/time when folder was created. content_type_id int content type id (used in list of items)

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    top Required return only top folders without_empty optional do not return folders that doesn't contain sub folders
    not applicable to "my files", "shared with me" and "boomarks" folders

    Response

    folders array of file manager folders array of file manager folder folders status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    folder_guid Required string folder guid

    GET Parameters

    page_size optional, default is 50 int number of items per one page. 1...100. page_id optional, default is 1 int id of page. 1...n. sort_by optional, default is sort_date string field that should be used to sort folder items
    can be: sort_date, sort_name, sort_size
    sort_dir optional, default is desc string sort direction: asc or desc

    Response

    ids array, can be empty array of item ids pagination pagination pagination object status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    ids Required array array of item ids

    GET Parameters

    page_size optional, default is 50 int number of items per one page. 1...100. page_id optional, default is 1 int id of page. 1...n. sort_by optional, default is sort_date string field that should be used to sort folder items
    can be: sort_date, sort_name, sort_size
    sort_dir optional, default is desc string sort direction: asc or desc

    Response

    items array of file manager items array of file manager items status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    ids requried array array of files item_id's

    Response

    deleted array, can be empty array of deleted item ids status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    ids requried array array of files item_id's

    Response

    restored array, can be empty array of restored item ids status_code int Status code of request, 0 means OK

    Files

    to upload files we use AWS s3 but to begin and finish upload we need to run 2 APIs:

    1. preapre file upload
    2. verify file upload

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    POST Parameters

    filename required string Original file name. original_file_id optional, default is null int id of original file for thumbnails width optional, default is null int width of image file height optional, default is null int height of image file color optional, default is null string average color HEX code of the image file

    Response

    formData object meta data for AWS s3 upload key string s3 file key s3_bucket string s3 bucket id AWSAccessKeyId string s3 Access Key Policy string s3 Policy Signature string s3 Signature ContentType string s3 ContentType acl string s3 acl metaData object meta data of protocols.io file file_id int new file id file_type int file type thumb_url string default file thumbnail

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    URL Parameters

    file_id required int file id that should be verified

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    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
    }
    

    current_page int current page number. total_pages int number of total pages. total_results int number of total results. next_page string, can be null API of the to the next page. prev_page string, can be null API of the to the prev page. page_size int number of items per page. first int id of first item. last int id of last item. changed_on int unix timestamp. date/time when this list was changed last time.

    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"
        }
      }
    }
    

    id int unique notification integer identifier pattern string notification pattern type_id int notification type created_on int timestamp when notification was created name string notification name list_name string when notice pattern contains list of items this fields must be used as list name placeholders object placeholders: list of objects, that must be used if application can't parse/use object form objects, each placeholder object has the same key (e.c. user, protocol etc) but always has standard structure with name & link that described below: placeholder fields: name string name to render link string, can be null link for action

    objects object pattern objects, key of object = key of pattern, possible objects described below: pattern objects: user user object user object group group object group object comment comment object comment object message message object message object protocol protocol object protocol object items array list of next items: protocol, folder, record, file any other pattern objects object other pattern objects, always has standard structure (simple pattern object) with name & link that described below: simple pattern object: name string name to render link string link for action

    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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    GET Parameters

    page_size optional, default is 10 int number of items per one page. 1...100. page_id optional, default is 1 int id of page. 1...n.

    Response

    list array, can be empty List of notification objects. pagination pagination pagination object status_code int Status code of request, 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

    id Required int or string One of the following:
    1) Integer protocol id
    2) String protocol uri
    3) DOI e.g. 10.17504/protocols.io.baaciaaw or protocols.io.baaciaaw
    last_version int If set to 1 server returns last version of this protocol

    Header Parameters

    AuthorizationRequiredBearer ACCESS_TOKEN.

    Response

    protocol protocol protocol object with steps and materials. status_code int Status code of request, 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

    AuthorizationRequiredBearer ACCESS_TOKEN.

    API Parameters

    with_protocol optional, default is null int 1 - return record with related protocol data
    0 - return only record data
    as_draft optional, default is null int 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 record object protocol protocol object with additional fields, described below additional protocol steps fields: notes list of record step notes record step notes is_checked int 1 - step checked
    0 - step not checked
    checked_on int can be null timestamp shows when step was checked is_skipped int 1 - step skipped
    0 - step not skipped
    skipped_on int can be null timestamp shows when step was skipped

    HTTP Errors