// Integration with protocols.io API for managing scientific protocols. This skill should be used when working with protocols.io to search, create, update, or publish protocols; manage protocol steps and materials; handle discussions and comments; organize workspaces; upload and manage files; or integrate protocols.io functionality into workflows. Applicable for protocol discovery, collaborative protocol development, experiment tracking, lab protocol management, and scientific documentation.
| name | protocolsio-integration |
| description | Integration with protocols.io API for managing scientific protocols. This skill should be used when working with protocols.io to search, create, update, or publish protocols; manage protocol steps and materials; handle discussions and comments; organize workspaces; upload and manage files; or integrate protocols.io functionality into workflows. Applicable for protocol discovery, collaborative protocol development, experiment tracking, lab protocol management, and scientific documentation. |
Protocols.io is a comprehensive platform for developing, sharing, and managing scientific protocols. This skill provides complete integration with the protocols.io API v3, enabling programmatic access to protocols, workspaces, discussions, file management, and collaboration features.
Use this skill when working with protocols.io in any of the following scenarios:
This skill provides comprehensive guidance across five major capability areas:
Manage API authentication using access tokens and OAuth flows. Includes both client access tokens (for personal content) and OAuth tokens (for multi-user applications).
Key operations:
Reference: Read references/authentication.md for detailed authentication procedures, OAuth implementation, and security best practices.
Complete protocol lifecycle management from creation to publication.
Key operations:
Reference: Read references/protocols_api.md for comprehensive protocol management guidance, including API endpoints, parameters, common workflows, and examples.
Enable community engagement through comments and discussions.
Key operations:
Reference: Read references/discussions.md for discussion management, comment threading, and collaboration workflows.
Organize protocols within team workspaces with role-based permissions.
Key operations:
Reference: Read references/workspaces.md for workspace organization, permission management, and team collaboration patterns.
Upload, organize, and manage files associated with protocols.
Key operations:
Reference: Read references/file_manager.md for file upload procedures, organization strategies, and storage management.
Supplementary functionality including profiles, notifications, and exports.
Key operations:
Reference: Read references/additional_features.md for profile management, publication discovery, experiment tracking, and data export.
Before using any protocols.io API functionality:
references/authentication.md for detailed authentication proceduresAuthorization: Bearer YOUR_TOKENDetermine which capability area addresses your needs:
references/protocols_api.mdreferences/workspaces.mdreferences/discussions.mdreferences/file_manager.mdreferences/additional_features.mdFollow the guidance in the relevant reference files:
All API requests use the base URL:
https://protocols.io/api/v3
All requests require the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN
Most endpoints support JSON request/response format with Content-Type: application/json.
Many endpoints support a content_format parameter to control how protocol content is returned:
json: Draft.js JSON format (default)html: HTML formatmarkdown: Markdown formatInclude as query parameter: ?content_format=html
Be aware of API rate limits:
Implement exponential backoff for rate limit errors (HTTP 429).
To analyze an existing protocol from protocols.io:
GET /protocols with keywords to find relevant protocolsGET /protocols/{protocol_id}GET /protocols/{id}/comments for user feedbackReference files: protocols_api.md, discussions.md
To create a new protocol and publish with DOI:
authentication.md)POST /protocols with title and descriptionPOST /protocols/{id}/stepsPOST /protocols/{id}/publishReference files: protocols_api.md, authentication.md
To set up team protocol management:
workspaces.md)file_manager.md)POST /workspaces/{id}/protocols for team protocolsReference files: workspaces.md, file_manager.md, protocols_api.md, discussions.md, additional_features.md
To track protocol executions and results:
file_manager.md)POST /protocols/{id}/runsReference files: additional_features.md, file_manager.md, protocols_api.md
To find and cite protocols in research:
GET /publicationsPOST /protocols/{id}/bookmarksReference files: protocols_api.md, additional_features.md
import requests
token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}
# Search for CRISPR protocols
response = requests.get(
"https://protocols.io/api/v3/protocols",
headers=headers,
params={
"filter": "public",
"key": "CRISPR",
"page_size": 10,
"content_format": "html"
}
)
protocols = response.json()
for protocol in protocols["items"]:
print(f"{protocol['title']} - {protocol['doi']}")
import requests
token = "YOUR_ACCESS_TOKEN"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# Create protocol
data = {
"title": "CRISPR-Cas9 Gene Editing Protocol",
"description": "Comprehensive protocol for CRISPR gene editing",
"tags": ["CRISPR", "gene editing", "molecular biology"]
}
response = requests.post(
"https://protocols.io/api/v3/protocols",
headers=headers,
json=data
)
protocol_id = response.json()["item"]["id"]
print(f"Created protocol: {protocol_id}")
import requests
token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}
# Upload file
with open("data.csv", "rb") as f:
files = {"file": f}
data = {
"folder_id": "root",
"description": "Experimental results",
"tags": "experiment,data,2025"
}
response = requests.post(
"https://protocols.io/api/v3/workspaces/12345/files/upload",
headers=headers,
files=files,
data=data
)
file_id = response.json()["item"]["id"]
print(f"Uploaded file: {file_id}")
Implement robust error handling for API requests:
import requests
import time
def make_request_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code == 429: # Rate limit
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
continue
elif response.status_code >= 500: # Server error
time.sleep(2 ** attempt) # Exponential backoff
continue
else:
response.raise_for_status()
except requests.exceptions.RequestException as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
raise Exception("Max retries exceeded")
Load the appropriate reference file based on your task:
authentication.md: OAuth flows, token management, rate limitingprotocols_api.md: Protocol CRUD, steps, materials, publishing, PDFsdiscussions.md: Comments, replies, collaborationworkspaces.md: Team workspaces, permissions, organizationfile_manager.md: File upload, folders, storage managementadditional_features.md: Profiles, publications, experiments, notificationsTo load a reference file, read the file from the references/ directory when needed for specific functionality.
Authentication Issues:
Bearer YOUR_TOKENRate Limiting:
Permission Errors:
File Upload Failures:
For detailed troubleshooting guidance, refer to the specific reference files covering each capability area.