Workspaces API

Overview

Workspaces in protocols.io enable team collaboration by organizing protocols, managing members, and controlling access permissions. The Workspaces API allows you to list workspaces, manage memberships, and access workspace-specific protocols.

Base URL

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

Workspace Operations

List User Workspaces

Retrieve all workspaces the authenticated user has access to.

Endpoint: GET /workspaces

Query Parameters: - page_size: Number of results per page (default: 10, max: 50) - page_id: Page number for pagination (starts at 0)

Response includes: - Workspace ID and name - Workspace type (personal, group, institutional) - Member count - Access level (owner, admin, member, viewer) - Creation date

Example Request:

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

Get Workspace Details

Retrieve detailed information about a specific workspace.

Endpoint: GET /workspaces/{workspace_id}

Path Parameters: - workspace_id: The workspace's unique identifier

Response includes: - Complete workspace metadata - Member list with roles - Workspace settings and permissions - Protocol count and categories

Workspace Membership

List Workspace Members

Retrieve all members of a workspace.

Endpoint: GET /workspaces/{workspace_id}/members

Query Parameters: - page_size: Number of results per page - page_id: Page number for pagination

Response includes: - Member name and email - Role (owner, admin, member, viewer) - Join date - Activity status

Request Workspace Access

Request to join a workspace.

Endpoint: POST /workspaces/{workspace_id}/join-request

Request Body: - message (optional): Message to workspace admins explaining the request

Example Request:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I am collaborating with Dr. Smith on the CRISPR project and would like to access the shared protocols."
  }' \
  "https://protocols.io/api/v3/workspaces/12345/join-request"

Join Public Workspace

Directly join a public workspace without approval.

Endpoint: POST /workspaces/{workspace_id}/join

Note: Only available for workspaces configured to allow public joining

Workspace Protocols

List Workspace Protocols

Retrieve all protocols in a workspace.

Endpoint: GET /workspaces/{workspace_id}/protocols

Query Parameters: - filter: Filter protocols - all: All protocols in the workspace - own: Only protocols you created - shared: Protocols shared with you - key: Search keywords - order_field: Sort field (activity, created_on, modified_on, name) - order_dir: Sort direction (desc, asc) - page_size: Number of results per page - page_id: Page number for pagination - content_format: Content format (json, html, markdown)

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://protocols.io/api/v3/workspaces/12345/protocols?filter=all&order_field=modified_on&order_dir=desc"

Create Protocol in Workspace

Create a new protocol within a specific workspace.

Endpoint: POST /workspaces/{workspace_id}/protocols

Request Body: Same parameters as standard protocol creation (see protocols_api.md)

Note: The protocol will be created within the workspace and inherit workspace permissions

Workspace Types and Permissions

Workspace Types

1. Personal Workspace
2. Default workspace for individual users
3. Private by default

4. Can share specific protocols

5. Group Workspace

6. Collaborative workspace for teams
7. Shared access for all members

8. Role-based permissions

9. Institutional Workspace

10. Organization-wide workspace
11. Often includes branding
12. Centralized protocol management

Permission Levels

1. Owner
2. Full workspace control
3. Manage members and permissions

4. Delete workspace

5. Admin

6. Manage protocols and members
7. Configure workspace settings

8. Cannot delete workspace

9. Member

10. Create and edit protocols
11. View all workspace protocols

12. Comment and collaborate

13. Viewer

14. View-only access
15. Can comment on protocols
16. Cannot create or edit

Common Use Cases

1. Lab Protocol Repository

Organize lab protocols in a shared workspace:

1. Create or join lab workspace: GET /workspaces
2. List existing protocols: GET /workspaces/{id}/protocols
3. Create new protocols: POST /workspaces/{id}/protocols
4. Invite lab members: Share workspace invitation
5. Organize by categories or tags

2. Collaborative Protocol Development

Develop protocols with team members:

1. Identify target workspace: GET /workspaces
2. Create draft protocol in workspace
3. Share with team members automatically via workspace
4. Gather feedback through comments
5. Iterate and publish final version

3. Cross-Institutional Collaboration

Work with external collaborators:

1. Create or identify shared workspace
2. Request access: POST /workspaces/{id}/join-request
3. Once approved, access shared protocols
4. Contribute new protocols or updates
5. Maintain institutional protocol copies in personal workspace

4. Protocol Migration

Move protocols between workspaces:

1. List source workspace protocols: GET /workspaces/{source_id}/protocols
2. For each protocol, retrieve full details
3. Create protocol in target workspace: POST /workspaces/{target_id}/protocols
4. Copy all steps and metadata
5. Update references and links

5. Workspace Audit

Review workspace activity and content:

1. List all workspaces: GET /workspaces
2. For each workspace, get member list
3. Retrieve protocol lists with activity dates
4. Identify inactive or outdated protocols
5. Generate activity reports

Workspace Management Best Practices

1. Organization
2. Use consistent naming conventions
3. Tag protocols by project or category

4. Maintain workspace directory or index

5. Access Control

6. Review member list regularly
7. Assign appropriate permission levels

8. Remove inactive members

9. Protocol Standards

10. Establish workspace-wide protocol templates
11. Define required metadata fields

12. Implement quality review process

13. Collaboration

14. Communicate workspace guidelines to members
15. Encourage protocol documentation

16. Facilitate knowledge sharing

17. Backup and Archival

18. Regularly export workspace protocols
19. Maintain protocol version history
20. Archive completed projects

Organizations and Workspaces

Organizations are higher-level entities that can contain multiple workspaces.

Export Organization Data

Endpoint: GET /organizations/{org_id}/export

Use case: Bulk export of all protocols and workspace data for institutional archives or backups

Notifications and Activity

Workspace activity may trigger notifications:

• New protocols added to workspace
• Protocol updates by team members
• New comments on workspace protocols
• Member joins or leaves workspace
• Permission changes

Configure notification preferences in account settings.

Error Handling

Common error responses:

• 400 Bad Request: Invalid workspace ID or parameters
• 401 Unauthorized: Missing or invalid access token
• 403 Forbidden: Insufficient workspace permissions
• 404 Not Found: Workspace not found or no access
• 429 Too Many Requests: Rate limit exceeded

Integration Considerations

When integrating workspace functionality:

1. Cache workspace list: Avoid repeated workspace list calls
2. Respect permissions: Check user's role before attempting operations
3. Handle join requests: Implement workflow for workspace access approval
4. Sync regularly: Update local workspace data periodically
5. Support offline access: Cache protocols for offline work with sync on reconnection