protocolsio-integration

Protocols.io Integration

Overview

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.

When to Use This Skill

Use this skill when working with protocols.io in any of the following scenarios:

Core Capabilities

This skill provides comprehensive guidance across five major capability areas:

1. Authentication & Access

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.

2. Protocol Operations

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.

3. Discussions & Collaboration

Enable community engagement through comments and discussions.

Key operations:

Reference: Read references/discussions.md for discussion management, comment threading, and collaboration workflows.

4. Workspace Management

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.

5. File Operations

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.

6. Additional Features

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.

Getting Started

Step 1: Authentication Setup

Before using any protocols.io API functionality:

Step 2: Identify Your Use Case

Determine which capability area addresses your needs:

Step 3: Implement Integration

Follow the guidance in the relevant reference files:

Base URL and Request Format

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.

Content Format Options

Many endpoints support a content_format parameter to control how protocol content is returned:

Include as query parameter: ?content_format=html

Rate Limiting

Be aware of API rate limits:

Implement exponential backoff for rate limit errors (HTTP 429).

Common Workflows

Workflow 1: Import and Analyze Protocol

To analyze an existing protocol from protocols.io:

Reference files: protocols_api.md, discussions.md

Workflow 2: Create and Publish Protocol

To create a new protocol and publish with DOI:

Reference files: protocols_api.md, authentication.md

Workflow 3: Collaborative Lab Workspace

To set up team protocol management:

Reference files: workspaces.md, file_manager.md, protocols_api.md, discussions.md, additional_features.md

Workflow 4: Experiment Documentation

To track protocol executions and results:

Reference files: additional_features.md, file_manager.md, protocols_api.md

Workflow 5: Protocol Discovery and Citation

To find and cite protocols in research:

Reference files: protocols_api.md, additional_features.md

Python Request Examples

Basic Protocol Search

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']}")

Create New Protocol

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

Upload File to Workspace

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

Error Handling

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

Reference Files

Load the appropriate reference file based on your task:

To load a reference file, read the file from the references/ directory when needed for specific functionality.

Best Practices

Additional Resources

Troubleshooting

Authentication Issues:

Rate Limiting:

Permission Errors:

File Upload Failures:

For detailed troubleshooting guidance, refer to the specific reference files covering each capability area.