Protocols.io Integration Studio

Integrate with the Protocols.io platform for managing, sharing, and versioning scientific protocols through the API. This skill covers protocol retrieval, creation, step management, workspace collaboration, and building automated protocol documentation pipelines.

When to Use This Skill

Choose Protocols.io Integration Studio when you need to:

• Programmatically create and update scientific protocols on Protocols.io
• Search and retrieve published protocols for research workflows
• Automate protocol versioning and fork management across teams
• Build integrations between Protocols.io and LIMS or lab automation systems

Consider alternatives when:

• You need general electronic lab notebook features without protocol focus (use LabArchives)
• You need SOPs for non-scientific business processes (use document management tools)
• You need protocol execution tracking with equipment integration (use lab automation platforms)

Quick Start

Copy
pip install requests python-dotenv

Copy
import requests
import os

class ProtocolsIO:
    BASE_URL = "https://www.protocols.io/api/v3"

    def __init__(self, token):
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    def search_protocols(self, query, page_size=10):
        """Search for protocols by keyword."""
        response = requests.get(
            f"{self.BASE_URL}/protocols",
            params={"filter": query, "page_size": page_size},
            headers=self.headers
        )
        return response.json()

    def get_protocol(self, protocol_id):
        """Get full protocol details including steps."""
        response = requests.get(
            f"{self.BASE_URL}/protocols/{protocol_id}",
            headers=self.headers
        )
        return response.json()

# Initialize client
client = ProtocolsIO(os.getenv("PROTOCOLS_IO_TOKEN"))
results = client.search_protocols("CRISPR gene editing")
for proto in results.get("items", [])[:5]:
    print(f"{proto['title']} (v{proto.get('version_id', '?')})")

Core Concepts

API Endpoints

Endpoint	Method	Description
/protocols	GET	Search and list protocols
/protocols/{id}	GET	Get protocol details
/protocols	POST	Create new protocol
/protocols/{id}	PUT	Update protocol
/protocols/{id}/steps	GET	List protocol steps
/protocols/{id}/steps	POST	Add step to protocol
/protocols/{id}/fork	POST	Fork/copy a protocol
/workspaces	GET	List user workspaces

Protocol Creation and Step Management

Copy
def create_protocol_with_steps(client, title, description, steps):
    """Create a complete protocol with ordered steps."""
    # Create the protocol
    protocol = client.create_protocol({
        "title": title,
        "description": description,
        "is_public": False
    })
    protocol_id = protocol["id"]

    # Add steps
    for i, step in enumerate(steps):
        client.add_step(protocol_id, {
            "title": step["title"],
            "description": step["description"],
            "duration": step.get("duration"),
            "temperature": step.get("temperature"),
            "order": i + 1,
            "components": step.get("components", [])
        })

    return protocol_id

# Example: create a PCR protocol
steps = [
    {
        "title": "Prepare Master Mix",
        "description": "Combine 10µL 2x buffer, 1µL each primer (10µM), 1µL template DNA, 7µL nuclease-free water.",
        "duration": {"value": 10, "unit": "min"},
        "temperature": {"value": 4, "unit": "°C"}
    },
    {
        "title": "Initial Denaturation",
        "description": "Heat to 95°C for 3 minutes in thermocycler.",
        "duration": {"value": 3, "unit": "min"},
        "temperature": {"value": 95, "unit": "°C"}
    },
    {
        "title": "Cycling (35 cycles)",
        "description": "Denature 95°C/30s → Anneal 58°C/30s → Extend 72°C/60s",
        "duration": {"value": 90, "unit": "min"}
    },
    {
        "title": "Final Extension",
        "description": "Hold at 72°C for 5 minutes, then 4°C indefinitely.",
        "duration": {"value": 5, "unit": "min"},
        "temperature": {"value": 72, "unit": "°C"}
    }
]

protocol_id = create_protocol_with_steps(
    client, "Standard PCR Protocol",
    "Standard PCR amplification for fragments 500-2000bp", steps
)

Configuration

Parameter	Description	Default
base_url	Protocols.io API endpoint	"https://www.protocols.io/api/v3"
token	API access token	Required
workspace_id	Default workspace for new protocols	User's default
is_public	Protocol visibility	false
page_size	Results per page	10
timeout	Request timeout (seconds)	30

Best Practices

1. Version protocols explicitly — Use the fork and versioning API to create new versions when modifying established protocols. This maintains a clear history and lets collaborators reference specific versions rather than a moving target.

2. Include reagent details in step components — Attach reagent names, catalog numbers, concentrations, and volumes as structured components rather than embedding them in free text. This enables automated reagent ordering and inventory checking.

3. Set duration and temperature on every applicable step — Structured time and temperature data enables automated protocol scheduling, equipment reservation, and thermocycler programming. Free-text descriptions of these values can't be parsed by automation tools.

4. Use workspaces for team organization — Create separate workspaces for different projects or teams. This controls access permissions and keeps protocol searches focused on relevant content.

5. Link protocols to publications — After publishing your paper, update the protocol with the DOI link. This bidirectional connection between methods and protocols improves reproducibility and gives credit to protocol authors.

Common Issues

API token returns 401 Unauthorized — Protocols.io tokens expire and must be refreshed. Generate a long-lived token from your account settings for server-side applications, or implement OAuth2 refresh flow for user-facing apps. Check that the token includes the required scopes for your API operations.

Protocol search returns irrelevant results — The search endpoint matches across all text fields including comments and metadata. Use field-specific filters (title, author, workspace) to narrow results. Combine filters with boolean logic for precise searches.

Step order becomes incorrect after edits — Inserting or deleting steps can leave gaps in the order numbering. After bulk step modifications, re-fetch the protocol and reorder steps sequentially to ensure correct display order in the UI.