Additional Features

Additional Features

Overview

This document covers additional protocols.io API features including user profiles, recently published protocols, experiment records, and notifications.

Base URL

All endpoints use the base URL: https://protocols.io/api/v3

User Profile Management

Get User Profile

Retrieve the authenticated user's profile information.

Endpoint: GET /profile

Response includes:

• User ID and username
• Full name
• Email address
• Affiliation/institution
• Bio and description
• Profile image URL
• Account creation date
• Protocol count and statistics

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/profile"

Update User Profile

Update profile information.

Endpoint: PATCH /profile

Request Body:

• first_name: First name
• last_name: Last name
• email: Email address
• affiliation: Institution or organization
• bio: Profile bio/description
• location: Geographic location
• website: Personal or lab website URL
• twitter: Twitter handle
• orcid: ORCID identifier

Example Request:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliation": "University of Example, Department of Biology",
    "bio": "Researcher specializing in CRISPR gene editing and molecular biology",
    "orcid": "0000-0001-2345-6789"
  }' \
  "https://protocols.io/api/v3/profile"

Upload Profile Image

Update profile picture.

Endpoint: POST /profile/image

Request Format: multipart/form-data

Form Parameters:

• image (required): Image file (JPEG, PNG)

Recommended specifications:

• Minimum size: 200x200 pixels
• Aspect ratio: Square (1:1)
• Format: JPEG or PNG
• Max file size: 5 MB

Recently Published Protocols

Query Published Protocols

Discover recently published public protocols.

Endpoint: GET /publications

Query Parameters:

• key: Search keywords
• category: Filter by category
  • Example categories: molecular-biology, cell-biology, biochemistry, etc.
• date_from: Start date (ISO 8601 format: YYYY-MM-DD)
• date_to: End date
• order_field: Sort field (published_on, title, views)
• order_dir: Sort direction (desc, asc)
• page_size: Number of results per page (default: 10, max: 50)
• page_id: Page number for pagination

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/publications?category=molecular-biology&date_from=2025-01-01&order_field=published_on&order_dir=desc"

Use Cases:

• Discover trending protocols
• Monitor new publications in your field
• Find recently published protocols for specific techniques
• Track citation-worthy protocols

Experiment Records

Overview

Experiment records allow users to document individual runs or executions of a protocol, tracking what worked, what didn't, and any modifications made.

Create Experiment Record

Document an execution of a protocol.

Endpoint: POST /protocols/{protocol_id}/runs

Path Parameters:

• protocol_id: The protocol's unique identifier

Request Body:

• title (required): Experiment run title
• date: Date of experiment execution (ISO 8601 format)
• status: Experiment outcome
  • success: Experiment succeeded
  • partial: Partially successful
  • failed: Experiment failed
• notes: Detailed notes about the experiment run
• modifications: Protocol modifications or deviations
• results: Summary of results
• attachments: File IDs for data files or images

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "CRISPR Editing - HEK293 Cells - Trial 3",
    "date": "2025-10-20",
    "status": "success",
    "notes": "Successfully achieved 87% editing efficiency. Increased sgRNA concentration from 100nM to 150nM based on previous trials.",
    "modifications": "Extended incubation time in step 3 from 30 min to 45 min",
    "results": "Flow cytometry confirmed 87% GFP+ cells after 72h. Western blot showed complete knockout in positive population."
  }' \
  "https://protocols.io/api/v3/protocols/12345/runs"

List Experiment Records

Retrieve all experiment records for a protocol.

Endpoint: GET /protocols/{protocol_id}/runs

Query Parameters:

• status: Filter by outcome (success, partial, failed)
• date_from: Start date
• date_to: End date
• page_size: Number of results per page
• page_id: Page number for pagination

Update Experiment Record

Endpoint: PATCH /protocols/{protocol_id}/runs/{run_id}

Request Body: Same parameters as create, all optional

Delete Experiment Record

Endpoint: DELETE /protocols/{protocol_id}/runs/{run_id}

Use Cases:

• Track reproducibility across multiple experiments
• Document troubleshooting and optimization
• Share successful modifications with collaborators
• Build institutional knowledge base
• Support lab notebook requirements

Notifications

Get User Notifications

Retrieve notifications for the authenticated user.

Endpoint: GET /notifications

Query Parameters:

• type: Filter by notification type
  • comment: New comments on your protocols
  • mention: You were mentioned in a comment
  • protocol_update: Protocol you follow was updated
  • workspace: Workspace activity
  • publication: Protocol was published
• read: Filter by read status
  • true: Only read notifications
  • false: Only unread notifications
  • Omit for all notifications
• page_size: Number of results per page (default: 20, max: 100)
• page_id: Page number for pagination

Response includes:

• Notification ID and type
• Message/description
• Related protocol/comment/workspace
• Timestamp
• Read status

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/notifications?read=false&type=comment"

Mark Notification as Read

Endpoint: PATCH /notifications/{notification_id}

Request Body:

• read: Set to true

Mark All Notifications as Read

Endpoint: POST /notifications/mark-all-read

Delete Notification

Endpoint: DELETE /notifications/{notification_id}

Organization Management

Export Organization Data

Export all protocols and workspace data from an organization.

Endpoint: GET /organizations/{organization_id}/export

Path Parameters:

• organization_id: The organization's unique identifier

Query Parameters:

• format: Export format
  • json: JSON format with full metadata
  • csv: CSV format for spreadsheet import
  • xml: XML format
• include_files: Include associated files (true/false)
• include_comments: Include discussions (true/false)

Response: Download URL for export package

Use Cases:

• Institutional archival
• Compliance and audit requirements
• Migration to other systems
• Backup and disaster recovery
• Data analysis and reporting

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/organizations/12345/export?format=json&include_files=true&include_comments=true"

Common Integration Patterns

1. Protocol Discovery and Import

Build a protocol discovery workflow:

# Search for relevant protocols
response = requests.get(
    'https://protocols.io/api/v3/publications',
    headers={'Authorization': f'Bearer {token}'},
    params={'key': 'CRISPR', 'category': 'molecular-biology'}
)

# For each interesting protocol
for protocol in response.json()['items']:
    # Get full details
    details = requests.get(
        f'https://protocols.io/api/v3/protocols/{protocol["id"]}',
        headers={'Authorization': f'Bearer {token}'}
    )
    # Import to local system
    import_protocol(details.json())

2. Experiment Tracking

Track all protocol executions:

1. Execute protocol in lab
2. Document execution: POST /protocols/{id}/runs
3. Upload result files to workspace
4. Link files in experiment record
5. Analyze success rates across runs

3. Notification System Integration

Build custom notification system:

1. Poll for new notifications: GET /notifications?read=false
2. Process each notification type
3. Send to internal communication system
4. Mark as read: PATCH /notifications/{id}

4. Profile Synchronization

Keep profiles synchronized across systems:

1. Retrieve profile: GET /profile
2. Compare with internal system
3. Update discrepancies
4. Sync profile images and metadata

API Response Formats

Standard Response Structure

Most API responses follow this structure:

{
  "status_code": 0,
  "status_message": "Success",
  "item": { /* single item data */ },
  "items": [ /* array of items */ ],
  "pagination": {
    "current_page": 0,
    "total_pages": 5,
    "page_size": 10,
    "total_items": 42
  }
}

Error Response Structure

{
  "status_code": 400,
  "status_message": "Bad Request",
  "error_message": "Missing required parameter: title",
  "error_details": {
    "field": "title",
    "issue": "required"
  }
}

Best Practices

1. Profile Completeness

   • Complete all profile fields
   • Add ORCID for research attribution
   • Keep affiliation current

2. Experiment Documentation

   • Document all protocol executions
   • Include both successes and failures
   • Note all modifications
   • Attach relevant data files

3. Notification Management

   • Review notifications regularly
   • Enable relevant notification types
   • Disable notification types you don't need
   • Respond to comments promptly

4. Publication Discovery

   • Set up regular searches for your research area
   • Follow prolific authors in your field
   • Bookmark useful protocols
   • Cite protocols in publications

5. Data Export

   • Export organization data regularly
   • Test restore procedures
   • Store exports securely
   • Document export procedures