scientific-skills/protocolsio-integration/references/discussions.md
The Discussions API enables collaborative commenting on protocols. Comments can be added at both the protocol level and the individual step level, with support for threaded replies, editing, and deletion.
All discussion endpoints use the base URL: https://protocols.io/api/v3
Retrieve all comments for a protocol.
Endpoint: GET /protocols/{protocol_id}/comments
Path Parameters:
protocol_id: The protocol's unique identifierQuery Parameters:
page_size: Number of results per page (default: 10, max: 50)page_id: Page number for pagination (starts at 0)Response includes:
Add a new comment to a protocol.
Endpoint: POST /protocols/{protocol_id}/comments
Request Body:
body (required): Comment text (supports HTML or Markdown)parent_comment_id (optional): ID of parent comment for threaded repliesExample Request:
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "This protocol worked excellently for our CRISPR experiments. We achieved 85% editing efficiency."
}' \
"https://protocols.io/api/v3/protocols/12345/comments"
To reply to an existing comment, include the parent comment ID:
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "What cell type did you use?",
"parent_comment_id": 67890
}' \
"https://protocols.io/api/v3/protocols/12345/comments"
Edit your own comment.
Endpoint: PATCH /protocols/{protocol_id}/comments/{comment_id}
Request Body:
body (required): Updated comment textAuthorization: Only the comment author can edit their comments
Remove a comment.
Endpoint: DELETE /protocols/{protocol_id}/comments/{comment_id}
Authorization: Only the comment author can delete their comments
Note: Deleting a parent comment may affect the entire thread, depending on API implementation
Retrieve all comments for a specific protocol step.
Endpoint: GET /protocols/{protocol_id}/steps/{step_id}/comments
Path Parameters:
protocol_id: The protocol's unique identifierstep_id: The step's unique identifierQuery Parameters:
page_size: Number of results per pagepage_id: Page number for paginationAdd a comment to a specific step.
Endpoint: POST /protocols/{protocol_id}/steps/{step_id}/comments
Request Body:
body (required): Comment textparent_comment_id (optional): ID of parent comment for repliesExample Request:
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"body": "At this step, we found that increasing the incubation time to 2 hours improved results significantly."
}' \
"https://protocols.io/api/v3/protocols/12345/steps/67890/comments"
Endpoint: PATCH /protocols/{protocol_id}/steps/{step_id}/comments/{comment_id}
Request Body:
body (required): Updated comment textEndpoint: DELETE /protocols/{protocol_id}/steps/{step_id}/comments/{comment_id}
To analyze discussions around a protocol:
GET /protocols/{id}/commentsparent_comment_idTo gather feedback on a protocol:
GET /protocols/{id}/commentsTo engage with protocol users:
To document troubleshooting experiences:
Comments support rich text formatting:
Example with Markdown:
{
"body": "## Important Note\n\nWe achieved better results with:\n\n- Increasing temperature to 37°C\n- Extending incubation to 2 hours\n- Using freshly prepared reagents\n\nSee our publication: [doi:10.xxxx/xxxxx](https://doi.org/...)"
}
Common error responses:
400 Bad Request: Invalid comment format or missing required fields401 Unauthorized: Missing or invalid access token403 Forbidden: Insufficient permissions (e.g., trying to edit another user's comment)404 Not Found: Protocol, step, or comment not found429 Too Many Requests: Rate limit exceededComments may trigger notifications: