NAV Navbar
json
  • Authentication
  • OAuth
  • Objects
  • Profile
  • Protocols
  • Publications
  • Draft
  • Experiment records (run)
  • Groups
  • Messages
  • File Manager
  • Pagination
  • Notifications
  • Publisher Widget
  • Archive
  • HTTP Errors
  • Authentication

    protocols.io API v3 uses OAuth 2.0 authentication standarts.

    There are two types of access: public and private

    Most of the endpoints require Authentication header with Bearer access token. Example:

    Authentication: Bearer b2e9570895ae57efdc495e1ac27feb12e856aec9f354bb12aa0ceaa3b761f11a

    Authorize protocols.io user

    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 authorize link inside your apication or use our sign-in button.
    4. Your requests will be redirected to [your_redirect_url]?code=[new_code]&scope=[your_scope].
    5. Use the code to get user access_token by calling https://www.protocols.io/api/v3/oauth/token with grant_type: authorization_code.

    Refresh access token

    You will receive a warning 1 month before access_token expires.

    "HTTP/1.1 200 Ok"
    {
      "status_code": 0,
      ...
      "warning_code": 1,
      "warning_message": "Your access token expires in 24 days"
    }
    

    Once 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 access_token.

    OAuth

    Get client

    Example Request

    
    curl https://www.protocols.io/api/v3/oauth/clients/<client_id>
       -H "Authorization: Bearer [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>

    Get access code

    You can recive access code by calling:

    https://www.protocols.io/api/v3/oauth/authorize?client_id=[your_client_id]&redirect_url=[tour_redirect_url]&response_type=code&scope=readwrite&state=[your_state]

    The users will be presented with protocols.io sign in form. Once authenticated, the users will be redirected to your redirect_url with the new access code. Use the access code to obtain access_token.

    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 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 optional, required for authorization_code grant_type string code which you recive when client complite authentication on protocols.io. refresh_token optional, 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.

    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.

    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

    Get profile

    Example Request | get profile data

    curl https://www.protocols.io/api/v3/session/profile
      -H "Authorization: Bearer <PRIVATE_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

    Authorization Required private Bearer access_token.

    Response

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

    Create profile

    Example Request

    curl -X POST https://www.protocols.io/api/v3/session/profile
      -H "Authorization: Bearer <PRIVATE_ACCESS_TOKEN>"
      -d first_name=<new first_name>
      -d last_name=<new last_name>
      -d email=<new email>
      -d password=<new password>
    

    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

    POST https://www.protocols.io/api/v3/session/profile

    POST Parameters

    email requried string new user email password requried string new user password first_name optional string new user first name last_name optional string new user last name

    Response

    new user object

    status_code int Satus 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.

    Update profile

    Example Request

    curl -X PUT https://www.protocols.io/api/v3/session/profile
      -H "Authorization: Bearer <PRIVATE_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

    Authorization Required private Bearer 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 Satus 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.

    Reset password

    Example Request

    curl -X PUT https://www.protocols.io/api/v3/session/password
      -d email=<email>
    

    returns the following JSON:

    {
        "status_code": 0
    }
    

    HTTP Request

    PUT https://www.protocols.io/api/v3/session/password

    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. title string protocol title. title_html string 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": 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
          }
        }
      ],
      "steps": [...],
      "guid": "6D11D26701CA4EBAA5CA56859CCA8AC3",
      "materials": [...]
    }
    

    id int unique protocol integer identifier. guid string unique protocol guid w/o dashes. title string protocol title. title string protocol title with html tags. image image protocol image. 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. created_on int unix timestamp. date/time of protocol creation. creator user protocol creator public int 1 or 0. 1 means that this protocol is public and 0 otherwise. versions array, can be empty list of versions version_id int 0...n. Version number of this protocol. link string, can be empty External protocol link url string protocol url on protocols.io number_of_steps int, can be null number of steps of this protocol. authors array, can be empty list of user or empty array steps array, can be empty list of step or empty array materials list of reagent or empty array description string, can be empty Description (abstract) guidelines string, can be empty guidelines before_start string, can be empty Before start instructions warning string, can be empty Warnings materials_text string, can be empty Materials text. stats object List of protocol stats such as number of views or number of bookmarks.

    Step object

    Example Object: Step

    {
      "id": 595209,
      "guid": "E70FDFE632504ADFB0ED519ABB5449B1",
      "previous_id": 0,
      "previous_guid": null,
      "modified_on": 1517933242,
      "components": [...]
    }
    

    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. modified_on int unix timestamp. date/time when step was modified. components array, can be empty list of step components.

    Draft step object

    Example Object: Draft step

    {
      "id": 595209,
      "guid": "E70FDFE632504ADFB0ED519ABB5449B1",
      "previous_id": 0,
      "previous_guid": null,
      "modified_on": 1517933242,
      "components": [...]
    }
    {
      "id": 623524,
      "guid": "EB5FA750FE0B11E894D23F6E0BEC062D",
      "previous_id": null,
      "previous_guid": null,
      "modified_on": 0,
      "cases": [...],
      "data": "{\"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. modified_on int unix timestamp. date/time when step was modified. cases array, can be empty or null list of step cases. data string, can be empty or null step data, represented as stringified draft object 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 int linked step guid

    Step Component object

    Example Object: Step Component

    {
      "id": 1023444,
      "guid": "A38362CBC954458FB069F821B6526B38",
      "order_id": 2,
      "type_id": 3,
      "title": "Amount",
      "source": {...}
    }
    

    id int unique step integer identifier. guid string unique step guid. order_id int sequence number of component in the list starting from 0. type_id int type of of component, one of step component types title string name of component source step component type Object that has varying properties depending on the step component type used. The step component type for this obejct can be determined by type_id

    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

    Step Component Types

    Description, type id 1

    Description of the step, can contain html tags.

    Example Object: Description, type id 1

    {
      "description": "<p>step to make smth</p>"
    }
    

    description string, can be empty html

    Amount, type id 3

    A quantity of something, typically the total of a reagent, size, value etc.

    Example Object: Amount, type id 3

    {
      "amount": 11,
      "unit": "µl",
      "title": "of MGH"
    }
    

    amount int amount quantity. unit string unit. title string, can be empty title of amount.

    Duration, type id 4

    Example Object: Duration, type id 4

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

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

    Title, type id 6

    Example Object: Title, type id 6

    {
      "title": "boil"
    }
    

    title string, can be empty title of step.

    Example Object: Link, type id 7

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

    link string, can be empty external url.

    Software package, type id 8

    Example Object: Software package, type id 8

    {
      "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, type id 9

    Example Object: Dataset package, type id 9

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

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

    Comment, type id 13

    Step comments. This object is a comment.

    Example Object: Comment, type id 13

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

    source object comment source object represents usual comment object.

    Command package, type id 15

    Example Object: Command package, type id 15

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

    name string name of software. 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.

    Expected result, type id 17

    Example Object: Expected result, type id 17

    {
      "body": "<p>should be something</p>"
    }
    

    body string, can be empty body can contain html tags.

    Protocol, type id 18

    Step can contain protocols as components. This object is a protocol.

    Example Object: Protocol, type id 18

    {
      "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": "",
      "number_of_steps": 3,
      "authors": [
        {
          "name": "Matt Sullivan Lab",
          "affiliation": "Matt Sullivan Lab",
          "username": null,
          "link": null,
          "image": {
            "source": null,
            "placeholder": null
          }
        }
      ],
      "steps": [...],
      "materials": [...]
    }
    

    source object protocol source object represents usual protocol object.

    Safety information, type id 19

    Example Object: Safety information, type id 19

    {
      "body": "<p>dont' do something</p>",
      "link": "https://protocols.io"
    }
    

    body string, can be empty body can contain html tags. link string, can be empty external url.

    Reagent, type id 20

    This object is a Reagent.

    Example Object: Reagent, type id 20

    {
      "id": 19751,
      "mol_weight": 0,
      "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"
        }
      }
    }
    

    source object reagent source object represents usual reagent object.

    Step cases, type id 21

    Example Object: Step cases, type id 21

    {
      "cases": [
        {
          "title": "Measurement A",
          "label": "Case 1",
          "step_id": 595210,
          "step_guid": "1167CDCBFDB64CD4BA50A5016F4474B6"
        },
        {
          "title": "Measurement B",
          "label": "Case 2",
          "step_id": 595211,
          "step_guid": "DE9EA0FAF6E149528A4DAEFCA2DCC927"
        }
      ]
    }
    

    cases array list of case objects. case object: title string, can be empty title of a case. label string, can be empty label of a case. step_id int linked step id. step_guid string, can be null linked step guid.

    Go to previous step, type id 22

    Example Object: Go to previous step, type id 22

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

    File, type id 23

    Example Object: Temperature, type id 23

    {
      "source": "https://s3.amazonaws.com/pr-journal/pwybjf6.txt",
      "placeholder": "http://localhost:81/img/extensions/txt.png",
      "original_name": "emails.txt"
    }
    

    source string link to the file. placeholder string, can be empty link to file placeholder. original_name string, can be empty original file name.

    Temperature, type id 24

    Example Object: Temperature, type id 24

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

    temperature int temperature value. unit string unit. title string, can be empty title of component.

    Concentration, type id 25

    Example Object: Concentration, type id 25

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

    concentration int concentration value. unit string unit. title string, can be empty title of concentration.

    Note, type id 26

    Author notes. This object is a Comment.

    Example Object: Note, type id 26

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

    source object comment source object represents usual comment object.

    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

    Get List

    Example Request | all public protocols

    curl https://www.protocols.io/api/v3/protocols?filter="public"
       -H "Authorization: Bearer <PUBLIC_ACCESS_TOKEN>"
    

    Example Request | user public/private | shared with user protocols

    curl https://www.protocols.io/api/v3/protocols?filter="user_public"
       -H "Authorization: Bearer <PRIVATE_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,
              "categories": null,
              "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

    Authorization Required Bearer user 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 Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs 1302 Wrong order field

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

    Example Request | all researcher protocols

    curl https://www.protocols.io/api/v3/researchers/<username>/protocols?filter="user_all"
       -H "Authorization: Bearer <PRIVATE_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,
              "categories": null,
              "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 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

    Authorization Required Bearer user 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 Satus 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 Group Protocols List

    Example Request | group public protocols

    curl https://www.protocols.io/api/v3/groups/<group_uri>/protocols
       -H "Authorization: Bearer <PUBLIC_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,
              "categories": null,
              "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\/groups\/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 group public protocols separated by pages.

    HTTP Request

    GET https://www.protocols.io/api/v3/groups/<group_uri>/protocols

    Header Parameters

    Authorization Required Bearer user 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 Satus 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 Protocol

    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": "",
        "number_of_steps": 3,
        "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
    as_draft int If set to 1 server returns steps for this protocol as draft steps objects last_version int If set to 1 server returns last version of this protocol

    Header Parameters

    Authorization Required Bearer user access_token.

    Response

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

    Get Steps

    Example Request

    curl https://www.protocols.io/api/v3/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/v3/protocols/[id]/steps

    GET Parameters

    as_draft int If set to 1 server returns steps as draft steps objects

    Header Parameters

    Authorization Required Bearer user access_token.

    Response

    steps array, can be empty List of steps. status_code int Satus code of request, 0 means OK

    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

    Authorization Required Bearer user access_token.

    Response

    materials array, can be empty List of materials. status_code int Satus 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 <PUBLIC_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

    Authorization Required Private bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Private bearer user 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 Satus 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 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    URI Parameters

    title optional string new protocol title authors optional Array(string) Array of new protocol authors. Each record can be username of protocols.io use or author full name. 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 Satus 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 group

    curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/bookmarks
       -H "Authorization: Bearer <PUBLIC_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

    Authorization Required Bearer user access_token.

    URI Parameters

    protocol_uri int uri of a protocol

    Response

    status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    URI Parameters

    protocol_uri int uri of a protocol

    Response

    status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    Publications

    Get Latest Publications

    Example Request | latest publications

    curl https://www.protocols.io/api/v3/publications?latest=1"
       -H "Authorization: Bearer <PUBLIC_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,
              "categories": null,
              "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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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,
              "categories": null,
              "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

    Authorization Required Bearer user 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 Satus 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. 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. 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. 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": [
    
      ]
    }
    

    Get protocol comments

    Example Request | Get protocol comments

    curl https://www.protocols.io/api/v3/protocols/<protocol_uri>/comments
       -H "Authorization: Bearer <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    comments list of protocol-comment objects array status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    POST Parameters

    body required string Body of the comment

    Response

    comment protocol-comment added comment object status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    PUT Parameters

    body required string Body of the comment

    Response

    status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    PUT Parameters

    body required string Body of the discussion

    Response

    status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus 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 (run)

    Tiny Record object

    Example Object: Tiny Record

    {
      "id": 484784,
      "guid": "2A195AC3AFC2BFC2BDC3AFC2BFC2BDC3",
      "title": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
      "title_html": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
      "created_on": 1446001771,
      "content_type_id": 11
    },
    

    id int unique record integer identifier. guid string unique record gray identifier. title string record title. title_html string record title with html tags. created_on int unix timestamp of record creation content_type_id int content type id (used in list of items)

    Record object

    Example Object: Record

    {
      "id": 484784,
      "guid": "2A195AC3AFC2BFC2BDC3AFC2BFC2BDC3",
      "title": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
      "title_html": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
      "item_id": 5271,
      "image": {
        "source": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png",
        "placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png"
      },
      "created_on": 1446001771,
      "changed_on": 1446001771,
      "is_archived": 1,
      "total_steps": 4,
      "finished_steps": 0,
      "scale_multiplier": 1,
      "notes": [...]
      "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": [
    
        ]
      },
      "protocol": {
        "id": 484784,
        "title": "Gibson Assembly\u00c2\u00ae Protocol (E5510)",
        "title_html": "Gibson Assembly\u00ae Protocol (E5510)",
        "image": {
          "source": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png",
          "placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png"
        },
        "doi": "dx.doi.org\/10.17504\/protocols.io.cdms45",
        "doi_status": "2",
        "uri": "Gibson-Assembly-Protocol-E5510-imss45",
        "type_id": 1,
        "published_on": 1422407784,
        "stats": {
          "views": "10298",
          "number_of_steps": "4",
          "number_of_bookmarks": null,
          "number_of_comments": null
        },
        "version_id": null,
        "created_on": 1405030055,
        "categories": null,
        "creator": {
          "name": "New England Biolabs",
          "affiliation": "New England Biolabs",
          "username": "new-england-biolabs",
          "link": "http:\/\/www.neb.com",
          "image": {
            "source": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png",
            "placeholder": "https:\/\/s3.amazonaws.com\/pr-journal\/caybvew.png"
          },
          "badges": [
    
          ]
        }
      },
      "folder": {
        "id": 245365,
        "title": "Experiments",
        "guid": "710DEFBFBD4B3DEFBFBD4933EFBFBD1F",
        "type_id": 14,
        "created_on": 1483926561
      }
    },
    

    id int unique record integer identifier. guid string unique record gray 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. is_archived int 1 or 0. 1 means that this record is archived and 0 otherwise. 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. notes list of record notes record notes creator user record creator protocol protocol protocol that was used to create this record. folder small folder folder that contatins this record.

    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

    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": [
        {
          "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": [
    
            ]
          },
          "protocol": {
            "id": 506709,
            "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,
            "doi_status": "0",
            "uri": "untitled-protocol-serebd6",
            "type_id": 1,
            "published_on": null,
            "stats": {
              "views": "0",
              "number_of_steps": "4",
              "number_of_bookmarks": null,
              "number_of_comments": null
            },
            "version_id": null,
            "created_on": 1536854563,
            "categories": null,
            "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": [
    
              ]
            }
          },
          "folder": {
            "id": 245365,
            "title": "Experiments",
            "guid": "710DEFBFBD4B3DEFBFBD4933EFBFBD1F",
            "type_id": 14,
            "created_on": 1483926561
          }
        }
      ],
      "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

    Authorization Required Bearer user 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 return, 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/v3/records/<record_guid>?with_protocol=1&with_comments=1&as_draft=1"
       -H "Authorization: Bearer <ACCESS_TOKEN>"
    

    Example Response

    {
      "record": {
        "id": 507283,
        "guid": "6970DBF2F3EA4CE4AB3AB77B54C90A21",
        "protocol_id": 11415,
        "title": "Before data acquisition -- Start MRI Project Spinoza REC",
        "title_html": "Before data acquisition -- Start MRI Project Spinoza REC",
        "is_archived": 0,
        "number_of_finished_steps": 1,
        "scale_multiplier": 1,
        "created_on": 1541159777,
        "changed_on": 1541159777,
        "can_edit": 1,
        "notes": [...],
        "item_id": 41759
      },
      "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": [...],
        "comments_by_protocols": {
          "11415": [...]
        }
      },
      "status_code": 0
    }
    

    This method return record by guid.

    HTTP Request

    GET https://www.protocols.io/api/v3/records

    Header Parameters

    Authorization Required Bearer user access_token.

    API Parameters

    with_protocol optional, default is null int 1 - return record with related protocol data
    0 - return only record data
    with_comments optional, default is null int 1 - return additional object comments_by_protocols in protocol object
    0 - doesn't return object comments_by_protocols
    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 fields: comments_by_protocols object key-value object, where
    key - sub protocol id
    value - array of sub protocol step comments
    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

    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

    Authorization Required Bearer user 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 root folder folder object: guid optional string guid of existed folder title optional string title of new folder (if guid is empty) stack optional array described below

    stack objects

    Example Object: new record stack base

    {
      "type": "base",
      "data": {
        "title": "converter debug"
      }
    },
    

    Example Object: existed record stack notes

    {
      "type": "notes",
      "data": {
        "file": {
          "id": 123
        },
        "id": 775,
        "note": "test1234",
        "should_delete": 1,
        "step_id": 0
      }
    },
    

    Example Object: new record stack step

    {
      "type": "step",
      "data": {
        "guid": "EAA54C8AFDCD4D51AFFF12DF9C76F332",
        "is_checked": 0,
        "is_skipped": 0,
        "shoudld_delete": 0
      }
    },
    

    type required string unique record integer identifier in file manager system.
    step - means, changes applied to step level base - means, changes applied to base (protocol or record) level
    data required object described below

    base data object

    title optional string new record title

    notes data object

    file optional, can be null object file of record note file object: id int file id id optional, can be null int id of record note, if adding a new note - should be null note optional string note text should_delete optional int flag shows should server delete the note
    1 - delete
    0 - shouldn't delete
    step_id optional int step id, if note adding to whole record should be null or 0

    step data object

    guid required string protocol step guid that should be changed is_checked required default is 0 flag shows step is checked
    1 - checked
    0 - unchecked
    is_skipped required default is 0 flag shows step is skipped
    1 - skipped
    0 - not skipped
    should_delete required optional, default is 0 flag shows should server delete step or not
    1 - delete
    0 - do not delete

    Response

    record record-object status_code int Satus 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

    Authorization Required Bearer user access_token.

    URL Parameters

    guid Required record guid

    API Parameters

    stack optional array 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": {
        "file": {
          "id": 123
        },
        "id": 775,
        "note": "test1234",
        "should_delete": 1,
        "step_id": 0
      }
    },
    

    Example Object: existed record stack step

    {
      "type": "step",
      "data": {
        "guid": "EAA54C8AFDCD4D51AFFF12DF9C76F332",
        "is_checked": 0,
        "is_skipped": 0,
        "shoudld_delete": 0
      }
    },
    

    type required string unique record integer identifier in file manager system.
    step - means, changes applied to step level base - means, changes applied to base (protocol or record) level
    data required object described below

    base data object

    title optional string new record title

    notes data object

    file optional, can be null object file of record note file object: id int file id id optional, can be null int id of record note, if adding a new note - should be null note optional string note text should_delete optional int flag shows should server delete the note
    1 - delete
    0 - shouldn't delete
    step_id optional int step id, if note adding to whole record should be null or 0

    step data object

    guid required string record step guid that should be changed is_checked required default is 0 flag shows step is checked
    1 - checked
    0 - unchecked
    is_skipped required default is 0 flag shows step is skipped
    1 - skipped
    0 - not skipped
    should_delete required optional, default is 0 flag shows should server delete step or not
    1 - delete
    0 - do not delete

    Response

    status_code int Satus code of request, 0 means OK

    Groups

    Group object

    Example Object: 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"
      },
      "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 group integer identifier. uri string unique group string identifier. title string group title. image image group image. description string group description. research_interests string group research interests. website string group website. location string group location. affiliation string group affiliation. status object group statuses. group status object: is_visible bool true this group 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 group stats group stats object: files object group 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 group members user_status user status this object reporesents statuses of access token user to this group

    Small group object

    Example Object: 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>."
    }
    

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

    Group user status object

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

    is_member bool true mean that user is group member is_confimed bool true mean that user is confirmed group member is_invited bool true mean that user is invited group member is_owner bool true mean that user is owner of this group

    Get Groups List

    Example Request | all public groups

    curl https://www.protocols.io/api/v3/groups
       -H "Authorization: Bearer <PUBLIC_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\/groups?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 groups separated by pages.

    HTTP Request

    GET https://www.protocols.io/api/v3/groups

    Header Parameters

    Authorization Required Bearer user 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 group 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 group objects. pagination pagination pagination object status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    Get Members

    Example Request | researcher groups

    curl https://www.protocols.io/api/v3/researchers/<username>/groups
       -H "Authorization: Bearer <PUBLIC_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 groups separated by pages.

    HTTP Request

    GET https://www.protocols.io/api/v3/researchers/<username>/groups

    Header Parameters

    Authorization Required Bearer user 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 group 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 group objects. pagination pagination pagination object status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    Get group

    Example Request

    curl https://www.protocols.io/api/v3/groups/[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
        },
        "categories": null
      },
      "status_code": 0
    }
    

    This method retrieves a group.

    HTTP Request

    GET https://www.protocols.io/api/v3/groups/[uri]

    GET Parameters

    uri Required string gropu uri on protocols.io

    Header Parameters

    Authorization Required access token

    Response

    group group group object. status_code int Satus code of request, 0 means OK

    Join group

    Request to join group

    Example Request

    curl https://www.protocols.io/api/v3/groups/[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 group

    HTTP Request

    POST https://www.protocols.io/api/v3/groups/<uri>/members

    Header Parameters

    Authorization Required 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 group status_code int Satus code of request, 0 means OK

    Confirm invite into group

    Example Request

    curl https://www.protocols.io/api/v3/groups/[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 group

    HTTP Request

    PUT https://www.protocols.io/api/v3/groups/<uri>/members

    Header Parameters

    Authorization Required 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 group status_code int Satus code of request, 0 means OK

    Leave group

    Reject invite into group

    Example Request

    curl https://www.protocols.io/api/v3/groups/[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/groups/<uri>/members

    Header Parameters

    Authorization Required 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 group status_code int Satus code of request, 0 means OK

    Follow group

    Example Request | follow group

    curl https://www.protocols.io/api/v3/groups/<group_uri>/followers
       -H "Authorization: Bearer <PUBLIC_ACCESS_TOKEN>"
       -X POST
    

    Example Response

    {
      "status_code": 0
    }
    

    This method make you a follower of a group

    HTTP Request

    POST https://www.protocols.io/api/v3/groups/<group_uri>/followers

    Header Parameters

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    Unfollow group

    Example Request | unfollow group

    curl https://www.protocols.io/api/v3/groups/<group_uri>/followers
       -H "Authorization: Bearer <PUBLIC_ACCESS_TOKEN>"
       -X DELETE
    

    Example Response

    {
      "status_code": 0
    }
    

    This method unfollow group

    HTTP Request

    DELETE https://www.protocols.io/api/v3/researchers/<group_uri>/followers

    Header Parameters

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 Missing or empty parametrs

    Messages

    Get researcher conversations

    Example Request | Get researcher conversations

    curl https://www.protocols.io/api/v3/conversations
       -H "Authorization: Bearer <PUBLIC_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

    Authorization Required Bearer user access_token. 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    conversation list of message objects for conversation array status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    total int number of new messages guids array new conversation GUIDs status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user access_token.

    Response

    status_code int Satus 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,
          "doi_status": 0,
          "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,
          "categories": null,
          "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
          },
          "journal": null,
          "journal_name": null,
          "journal_link": null,
          "public": 0,
          "has_versions": 0,
          "link": null,
          "number_of_steps": 1,
          "authors": [
    
          ],
          "versions": [
    
          ],
          "groups": [
    
          ],
          "has_subprotocols": 0,
          "is_subprotocol": 0,
          "is_bookmarked": 0,
          "forks_count": {
            "private": 0,
            "public": 0
          },
          "steps": [
    
          ],
          "materials": [
    
          ],
          "description": null,
          "guidelines": null,
          "before_start": null,
          "collections": [
    
          ],
          "warning": null,
          "keywords": null,
          "manuscript_citation": null,
          "documents": null,
          "is_owner": 1,
          "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_unlisted": 0,
          "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
    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)

    Get top folders

    Example Request | get top folders

    curl https://www.protocols.io/api/v3/filemanager/folders?top
       -H "Authorization: Bearer <PUBLIC_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 file manager root folder e.c. My Files, Shared with me etc

    HTTP Request

    GET https://www.protocols.io/api/v3/filemanager/folders?top

    Header Parameters

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 Satus 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 <PUBLIC_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

    Authorization Required Bearer user 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 int avg color of 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 <PUBLIC_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

    Authorization Required Bearer user 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\/groups\/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 <PUBLIC_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\/groups\/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 public groups separated by pages.

    HTTP Request

    GET https://www.protocols.io/api/v3/researchers/notifications

    Header Parameters

    Authorization Required Bearer user 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. newer_than optional, default is null int timestamp, time lower bound for reponse

    Response

    list array, can be empty List of notification objects. pagination pagination pagination object status_code int Satus code of request, 0 means OK

    Publisher Widget

    Publisher Wiget allows you to access protocols.io user's public and unlisted protocols directly from your publishing system. Use the Publisher Widget to add DOIs of the detailed methods directly into article's Materials and Methods section.

    Widget object

    Example object

    {
      "id": "C52C117AECE84DE1891FFD436F3E0F35",
      "created_on": 1514384304,
      "last_modified": 1514384304,
      "type_id": 1,
      "type": "list",
      "client_id": "pr_live_id_e272a3c012d759981af5b3d967a37539",
      "protocols": [
        {
          "id": 8503,
          "title": "Gene calling with Prodigal",
          "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.kixcufn",
          "uri": "gene-calling-with-prodigal-kixcufn",
          "published_on": 1509493090
        },
        {
          "id": 8504,
          "title": "sdjkf",
          "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.kiycufw",
          "uri": "sdjkf-kiycufw",
          "published_on": 1509493050
        }
      ]
    }
    

    id string unique widget text identifier. created_on int unix timestamp. date/time of widget creation. last_modified int unix timestamp. date/time when widget was modified last time. client_id string id of dev client. protocols array, can be null list of small protocol

    JavaScript plugin

    Use the JavaScript plugin to integrate Publisher Widget.

    More here: https://www.protocols.io/developers

    JavaScript plugin bundle is located on protocols.io CDN:

    <script type="text/javascript" src="https://www.protocols.io/js/widgets/js/protocolsiojs.min.js"></script>
    

    JavaScript plugin is accessible by using _protocolsio(for widgets) and _protocolsio_connect(for sign in) global variables.

    Authentication

    sign in button inizialization

      _protocolsio_connect.init({
        "client_id" : "your client id",
        "redirect_url" : "your redirect url",
        "scope": "readwrite",
        "response_type" : "code",
        "state" : "your state",
        "selector" : "id of html tag"
      }); 
    

    Use this JavaScript method to render Sign in with protocols.io button.

    JS Method

    _protocolsio_connect.init(config)

    Config Parameters

    client_id Required your client id. redirect_url Required access code will be sent to this url. scope Required should be readwrite. response_type Required should be code. state Required any string which will be sent to redirect_url together with the access code. selector Required id attribute if html tag where widget will be rendered.

    Inizialization

    The Publisher Widget provides access to user's published protocols. It has two modes: edit mode - to selecet public protocols. view mode - to view selected protocols.

    Publisher Widget inizialization using JavaScript

      let MyWidget = _protocolsio.init({
        "id": "id of widget",
        "type": "list",
        "access_token": "client of user access token",
        "selector": "id of html tag where widget will be rendered",
        "doi": "DOI of your article",
        "mode": "view or edit",
        "on_create": (widget) => {console.log(widget)},
        "on_save": (widget) => {console.log(widget)},
        "on_sign_out": () => {},
      });
    

    JS Method

    _protocolsio.init(config)

    Config Parameters

    access_token Required user's private access_token for edit mode and private or public access_token for view mode. type Required type of widget. The only supported type at the moment is list. selector Required id attribute of the html tag where widget will be rendered. id optional, default is null if widget id is null a new widget is created otherwise plugin will try to use existent widget. doi Required DOI of your article. mode optional, default is view Widget mode. view or edit. on_create(widget) optional, default is null callback function is called when a new widget is created. The function returns a widget object as first parameter. on_change(widget) optional, default is null callback function is called when a new widget is changed. The function returns a widget object as first parameter. on_sign_out optional, default is null callback function is called when the user clicks sign out button.

    get widget data

      let MyWidget = _protocolsio.init(config);
      let data = MyWidget.get();
    

    returns wdiget

    JS Method

    widget.get()

    Using without sign in

    JS Method to initialize

    _protocolsio.init(config);

        let widget = _protocolsio.init({
            doi           : 'DOI of your article',
            type          : 'list',
            mode          : 'view',
            selector      : 'id of html element where to push widget',
            access_token  : 'client of user access token'
          });
    

    get widget data

      let MyWidget = _protocolsio.init(config);
      let data = MyWidget.get();
    

    returns wdiget

    JS Method

    widget.get()

    Config Prameters

    selector Required id attribute of html tag where widget will be rendered. access_token Required public access_token for viewing protocols. doi Required Digital Object Ideftifier (DOI) of your article mode Required This parameter must be set to 'view' if only DOI is provided

    Get widget data

    Example request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets/[id]
      -H "Authorization: Bearer [ACCESS_TOKEN]"
    

    Example response

    {
      "widget": {
        "id": "C52C117AECE84DE1891FFD436F3E0F35",
        "created_on": 1514384304,
        "last_modified": 1514384304,
        "type_id": 1,
        "type": "list",
        "client_id": "pr_live_id_e272a3c012d759981af5b3d967a37539",
        "protocols": [
          {
            "id": 8503,
            "title": "Gene calling with Prodigal",
            "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.kixcufn",
            "uri": "gene-calling-with-prodigal-kixcufn",
            "published_on": 1509493090
          },
          {
            "id": 8504,
            "title": "sdjkf",
            "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.kiycufw",
            "uri": "sdjkf-kiycufw",
            "published_on": 1509493050
          }
        ]
      },
      "status_code": 0
    }
    

    HTTP Request

    GET https://www.protocols.io/api/v3/widgets/[id]

    Header Parameters

    Authorization Required public or private Bearer access_token.

    API Parameters

    id Required string Unique text id of widget.

    Response

    widget widget requested widget status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1402 Widget with this id doesn't exists

    Get widgets by DOI

    GET https://www.protocols.io/api/v3/widgets?doi=[DOI]

    Example request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets?doi=[DOI]
      -H "Authorization: Bearer [ACCESS_TOKEN]"
    

    Example response

    {
      "widgets": [
        {
          "id": "C52C117AECE84DE1891FFD436F3E0F35",
          "created_on": 1514384304,
          "last_modified": 1514384304,
          "type_id": 1,
          "type": "list",
          "client_id": "pr_live_id_e272a3c012d759981af5b3d967a37539",
          "protocols": [
            {
              "id": 8503,
              "title": "Gene calling with Prodigal",
              "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.kixcufn",
              "uri": "gene-calling-with-prodigal-kixcufn",
              "published_on": 1509493090
            },
            {
              "id": 8504,
              "title": "sdjkf",
              "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.kiycufw",
              "uri": "sdjkf-kiycufw",
              "published_on": 1509493050
            }
          ]
        }
      ],
      "status_code": 0
    }
    

    Header Parameters

    Authorization Required public or private Bearer access_token.

    API Parameters

    doi Required string DOI of your article

    Response

    widgets array list of widget status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1404 Widget GET parameter (doi) is not specified

    Get widgets protocols list by DOI

    GET https://www.protocols.io/api/v3/widgets/protocols?doi=[DOI]

    Example request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets/protocols?doi=[DOI]
      -H "Authorization: Bearer [ACCESS_TOKEN]"
    

    Example Response

    {
        "protocols": [
            {
                "id": 7058,
                "title": "test",
                "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.i5scg6e",
                "uri": "test-i5scg6e",
                "publish_date": 1514311257,
                "widgets": [
                    {
                        "id": 1,
                        "created_on": 1516634164,
                        "last_modified": 1516886065,
                        "type_id": 1,
                        "type": "list",
                        "client_id": "pr_live_id_645dc746785d48490676872340059577"
                    },
                    {
                        "id": 2,
                        "created_on": 1516634164,
                        "last_modified": 1516876208,
                        "type_id": 1,
                        "type": "list",
                        "client_id": "pr_live_id_645dc746785d48490676872340059576"
                    }
                ]
            }
        ],
        "status_code": 0
    }
    

    Header Parameters

    Authorization Required public or private Bearer access_token.

    API Parameters

    doi Required string DOI of your article

    Response

    protocols array list of small protocol with extra field widgets - list of related widget status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1404 Widget GET parameter (doi) is not specified

    Create widget

    Example Request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets
      -H "Authorization: Bearer [ACCESS_TOKEN]"
      -d type="list"
      -d doi="dx.doi.org/10.17504/protocols.io.kiycufw"
      -d protocols[0]=[id_1]
      -d protocols[1]=[id_2]
    

    Example Response

    {
      "widget": {
        "id": "C52C117AECE84DE1891FFD436F3E0F35",
        "created_on": 1514384304,
        "last_modified": 1514384304,
        "type_id": 1,
        "type": "list",
        "client_id": "pr_live_id_e272a3c012d759981af5b3d967a37539",
        "protocols": [
          {
            "id": 8503,
            "title": "Gene calling with Prodigal",
            "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.kixcufn",
            "uri": "gene-calling-with-prodigal-kixcufn",
            "published_on": 1509493090
          },
          {
            "id": 8504,
            "title": "sdjkf",
            "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.kiycufw",
            "uri": "sdjkf-kiycufw",
            "published_on": 1509493050
          }
        ]
      },
      "status_code": 0
    }
    

    HTTP Request

    POST https://www.protocols.io/api/v3/widgets

    Header Parameters

    Authorization Required private Bearer access_token.

    API Parameters

    type Required string type of widget, only list is supported. doi Required string DOI of the article where the widget is implemented. protocols optional, default is null array array of ids of published protocols. id optional, default is null string widget guid. If null, a new guid will be genereated.

    Response

    widget widget created widget status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 missing or empty parametrs. 1401 widget with this id already exists. 1403 widget type does not exist.

    Update widget

    Example Request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets/[id]
      -H "Authorization: Bearer [ACCESS_TOKEN]"
      -d protocols[0]=[id_1]
      -d protocols[1]=[id_2]
    

    Example Response

    {
      "widget": {
        "id": "C52C117AECE84DE1891FFD436F3E0F35",
        "created_on": 1514384304,
        "last_modified": 1514384304,
        "type_id": 1,
        "type": "list",
        "client_id": "pr_live_id_e272a3c012d759981af5b3d967a37539",
        "protocols": [
          {
            "id": 8503,
            "title": "Gene calling with Prodigal",
            "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.kixcufn",
            "uri": "gene-calling-with-prodigal-kixcufn",
            "published_on": 1509493090
          },
          {
            "id": 8504,
            "title": "sdjkf",
            "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.kiycufw",
            "uri": "sdjkf-kiycufw",
            "published_on": 1509493050
          }
        ]
      },
      "status_code": 0
    }
    

    HTTP Request

    PUT https://www.protocols.io/api/v3/widgets/[id]

    Header Parameters

    Authorization Required private Bearer access_token.

    API Parameters

    id Required string unique widget text id. protocols Required array array of ids of published protocols (will replace existing list) doi Required string DOI of the article where the widget is implemented.

    Response

    widget widget changed widget status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1 missing or empty parametrs. 1402 widget with this id doesn't exists

    Delete widget

    Example Request | published protocols widget

    curl https://www.protocols.io/api/v3/widgets/[id]
      -H "Authorization: Bearer [ACCESS_TOKEN]"
    

    Example Response

    {
      "status_code": 0
    }
    

    HTTP Request

    DELETE https://www.protocols.io/api/v3/widgets/[id]

    Header Parameters

    Authorization Required private Bearer access_token.

    API Parameters

    id Required string unique widget text id.

    Response

    status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    1402 widget with this id doesn't exists

    Archive

    Save Protocol Archived

    Example Request

    curl https://www.protocols.io/api/v3/protocols"
       -H "Authorization: Bearer <ACCESS_TOKEN>"
       -X POST
       -d stack=<stack of changes>
    

    Example Response

    {
      "status_code": 0
    }
    

    This method creates or changes protocols from stack

    HTTP Request

    POST https://www.protocols.io/api/v3/protocols

    Header Parameters

    Authorization Required Bearer user access_token.

    API Parameters

    stack optional array described below

    protocol stack objects

    Example Object: protocol stack base

    {
      "type": "base",
      "data_guid": "A49E7E70FE1C11E898FD796FADB3FB4E",
      "protocol_uri": "uri-of-a-protocol",
      "data": {
        "protocol_name": "new protocol name"
      }
    },
    

    Example Object: protocol stack step

    {
      "type": "base",
      "data_guid": "A49E7E70FE1C11E898FD796FADB3FB4E",
      "protocol_uri": "uri-of-a-protocol",
      "data": {
        "cases": [...],
        "data": "{\"blocks\":[{\"key\":\"avkfi\",\"text\":....}",
        "guid": "EB5FA750FE0B11E894D23F6E0BEC062D",
        "previous_guid": null,
        "section": "section name",
        "section_color": "#ff0000"
      }
    },
    

    type required string stack type:
    step - means, changes applied to step level
    base - means, changes applied to base protocol level
    protocol_uri required string uri of a protocol that should be changed, null for new protocols data_guid required string unique string identifier of stack object data required array stack data, described below

    base data object

    protocol_name optional string new protocol title description optional string protocol description, stringified draft object
    before_start optional string before start instructions, stringified draft object
    guidelines optional string protocol guidelines, stringified draft object
    warning optional string protocol safety warnings, stringified draft object
    materials_text optional string protocol materials text, stringified draft object
    reagents optional array protocol reagents, array of protocols.io reagents ids
    authors_list optional array protocol authors, array of users objects

    step data object

    guid required string protocol step guid that should be changed data required string step data, stringified draft object cases array, can be null step cases, array of case objects previous_guid required string guid of previous step, can be null if step is first section required string, can be null step section name section_color string color of step section, HEX color code

    step deletion data object

    guid required string protocol step guid that should be deleted should_delete int should be set to 1

    Response

    status_code int Satus code of request, 0 means OK

    Status Codes HTTP/1.1 400

    254 protocol saving error

    HTTP Errors