Collaboration API

The Collaboration API enables real-time collaborative features in Trae, allowing multiple developers to work together seamlessly.

Overview

The Collaboration API provides endpoints for:

• Real-time code sharing
• Live cursor tracking
• Collaborative editing sessions
• Team workspace management
• Permission control

Authentication

All collaboration API endpoints require authentication using your Trae API key.

Authorization: Bearer YOUR_API_KEY

Endpoints

Sessions

Create Collaboration Session

POST /api/v1/collaboration/sessions

Request Body:

{
  "name": "Project Review Session",
  "description": "Code review for feature branch",
  "workspace_id": "workspace_123",
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  }
}

Response:

{
  "session_id": "session_456",
  "name": "Project Review Session",
  "description": "Code review for feature branch",
  "workspace_id": "workspace_123",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T18:30:00Z",
  "invite_link": "https://trae.ai/collaborate/session_456",
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  }
}

Join Collaboration Session

POST /api/v1/collaboration/sessions/{session_id}/join

Response:

{
  "success": true,
  "session_info": {
    "session_id": "session_456",
    "name": "Project Review Session",
    "participants": [
      {
        "user_id": "user_123",
        "username": "alice",
        "role": "admin",
        "joined_at": "2024-01-15T10:30:00Z"
      }
    ],
    "permissions": {
      "read": true,
      "write": true,
      "admin": false
    }
  }
}

Leave Collaboration Session

POST /api/v1/collaboration/sessions/{session_id}/leave

Real-time Events

WebSocket Connection

wss://api.trae.ai/v1/collaboration/sessions/{session_id}/ws

Event Types:

1. Cursor Movement

{
  "type": "cursor_move",
  "user_id": "user_123",
  "file_path": "/src/main.js",
  "position": {
    "line": 42,
    "column": 15
  },
  "timestamp": "2024-01-15T10:35:00Z"
}

2. Code Changes

{
  "type": "code_change",
  "user_id": "user_123",
  "file_path": "/src/main.js",
  "changes": [
    {
      "type": "insert",
      "position": {
        "line": 42,
        "column": 15
      },
      "text": "console.log('Hello');"
    }
  ],
  "timestamp": "2024-01-15T10:35:00Z"
}

3. File Operations

{
  "type": "file_operation",
  "user_id": "user_123",
  "operation": "create",
  "file_path": "/src/utils.js",
  "timestamp": "2024-01-15T10:35:00Z"
}

Participants

Get Session Participants

GET /api/v1/collaboration/sessions/{session_id}/participants

Response:

{
  "participants": [
    {
      "user_id": "user_123",
      "username": "alice",
      "role": "admin",
      "status": "active",
      "joined_at": "2024-01-15T10:30:00Z",
      "last_seen": "2024-01-15T10:35:00Z"
    },
    {
      "user_id": "user_456",
      "username": "bob",
      "role": "collaborator",
      "status": "active",
      "joined_at": "2024-01-15T10:32:00Z",
      "last_seen": "2024-01-15T10:35:00Z"
    }
  ]
}

Update Participant Permissions

PUT /api/v1/collaboration/sessions/{session_id}/participants/{user_id}

Request Body:

{
  "role": "collaborator",
  "permissions": {
    "read": true,
    "write": false,
    "admin": false
  }
}

Comments and Annotations

Add Comment

POST /api/v1/collaboration/sessions/{session_id}/comments

Request Body:

{
  "file_path": "/src/main.js",
  "position": {
    "line": 42,
    "column": 15
  },
  "content": "This function could be optimized",
  "type": "suggestion"
}

Get Comments

GET /api/v1/collaboration/sessions/{session_id}/comments

Query Parameters:

• file_path (optional): Filter by file
• type (optional): Filter by comment type

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Rate Limited
• 500 - Internal Server Error

Error Response Format:

{
  "error": {
    "code": "INVALID_SESSION",
    "message": "The specified session does not exist or has expired",
    "details": {}
  }
}

Rate Limits

• API calls: 1000 requests per hour per user
• WebSocket connections: 10 concurrent connections per user
• File operations: 100 operations per minute per session

SDKs and Libraries

• JavaScript SDK
• Python SDK
• Go SDK

Examples

Starting a Collaboration Session

const trae = require('@trae/sdk');

const client = new trae.Client('your-api-key');

const session = await client.collaboration.createSession({
  name: 'Code Review',
  workspace_id: 'workspace_123',
  permissions: {
    read: true,
    write: true,
    admin: false
  }
});

console.log('Session created:', session.invite_link);

Real-time Collaboration

const ws = new WebSocket(`wss://api.trae.ai/v1/collaboration/sessions/${sessionId}/ws`);

ws.on('message', (data) => {
  const event = JSON.parse(data);
  
  switch (event.type) {
    case 'cursor_move':
      updateCursor(event.user_id, event.position);
      break;
    case 'code_change':
      applyChanges(event.changes);
      break;
  }
});