Skip to main content

Plane Integration

Endpoints for managing Plane.so project management integration.

Integration Management​

GET /api/plane-integration​

Gets current Plane integration settings.

Response:

{
  "id": "plane-integration-123",
  "baseUrl": "https://your-workspace.plane.so",
  "apiKey": "pl_...",
  "workspaceSlug": "your-workspace",
  "isActive": true,
  "syncEnabled": true,
  "syncInterval": 300,
  "lastSync": "2024-01-01T12:00:00.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

GET /api/plane-integration/projects/preview​

Previews available Plane projects for selection.

Response:

{
  "projects": [
    {
      "id": "plane-project-123",
      "name": "Mobile App Development",
      "identifier": "MAD",
      "description": "Main mobile application project",
      "memberCount": 8,
      "workItemCount": 45,
      "isPrivate": false,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

Integration Setup​

POST /api/plane-integration​

Configures or updates Plane integration.

Request Body:

{
  "baseUrl": "https://your-workspace.plane.so",
  "apiKey": "pl_your_api_key_here",
  "workspaceSlug": "your-workspace",
  "syncEnabled": true,
  "syncInterval": 300,
  "selectedProjects": [
    {
      "planeId": "plane-project-123",
      "syncWorkItems": true,
      "syncLabels": true,
      "autoCreateFlows": false
    }
  ]
}

Response:

{
  "success": true,
  "integration": {
    "id": "plane-integration-456",
    "isActive": true,
    "projectsConfigured": 1
  }
}

POST /api/plane-integration/test​

Tests Plane integration connection.

Request Body:

{
  "baseUrl": "https://your-workspace.plane.so",
  "apiKey": "pl_test_key"
}

Response:

{
  "success": true,
  "connection": "ok",
  "workspace": {
    "name": "Your Workspace",
    "slug": "your-workspace",
    "projectCount": 5
  },
  "permissions": {
    "read": true,
    "write": true,
    "admin": false
  }
}

POST /api/plane-integration/fetch-projects​

Fetches and syncs projects from Plane.

Response:

{
  "success": true,
  "projectsFetched": 3,
  "projectsCreated": 2,
  "projectsUpdated": 1,
  "syncId": "sync-plane-projects-789"
}

POST /api/plane-integration/projects/selective-sync​

Performs selective sync for specific projects.

Request Body:

{
  "projectIds": ["plane-project-123", "plane-project-456"],
  "syncOptions": {
    "workItems": true,
    "labels": true,
    "members": false,
    "states": true
  }
}

Response:

{
  "success": true,
  "projectsProcessed": 2,
  "workItemsSynced": 45,
  "labelsSynced": 12,
  "errors": []
}

DELETE /api/plane-integration/:id​

Removes Plane integration.

Parameters:

  • id: Integration identifier

Request Body:

{
  "deleteSyncedData": false  // Keep or remove synced projects/work items
}

Response:

{
  "success": true,
  "deleted": "plane-integration-123",
  "affectedProjects": 3,
  "affectedWorkItems": 45
}

Work Item Mapping​

Plane to FYI Mapping​

Work Item States​

{
  "planeStates": {
    "Backlog": "todo",
    "Todo": "todo",
    "In Progress": "in_progress",
    "Done": "done",
    "Cancelled": "cancelled"
  }
}

Priority Mapping​

{
  "planePriorities": {
    "Urgent": "urgent",
    "High": "high",
    "Medium": "medium",
    "Low": "low"
  }
}

Custom Fields​

  • Plane labels → FYI labels
  • Plane assignees → FYI assignees
  • Plane due dates → FYI due dates
  • Plane descriptions → FYI descriptions

Sync Management​

Automatic Sync​

  • Configurable sync intervals (5 minutes to 24 hours)
  • Incremental sync to minimize API calls
  • Error handling with retry logic
  • Sync status tracking and notifications

Manual Sync​

  • On-demand sync for immediate updates
  • Selective sync for specific projects
  • Force full sync to reset data

Sync Status​

{
  "status": "running",
  "lastSync": "2024-01-01T12:00:00.000Z",
  "nextSync": "2024-01-01T12:05:00.000Z",
  "currentOperation": "syncing_work_items",
  "progress": {
    "processed": 25,
    "total": 100,
    "percentage": 25
  }
}

Usage Examples​

Setup Integration​

curl -X POST http://localhost:3001/api/plane-integration \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://your-workspace.plane.so",
    "apiKey": "pl_your_api_key",
    "workspaceSlug": "your-workspace"
  }'

Test Connection​

curl -X POST http://localhost:3001/api/plane-integration/test \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://your-workspace.plane.so",
    "apiKey": "pl_test_key"
  }'

Sync Projects​

curl -X POST http://localhost:3001/api/plane-integration/fetch-projects

Selective Sync​

curl -X POST http://localhost:3001/api/plane-integration/projects/selective-sync \
  -H "Content-Type: application/json" \
  -d '{
    "projectIds": ["plane-project-123"],
    "syncOptions": {
      "workItems": true,
      "labels": true
    }
  }'

Troubleshooting​

Common Issues​

Authentication Failed​

  • Verify API key is correct and active
  • Check workspace permissions
  • Ensure base URL includes protocol (https://)

Sync Not Working​

  • Check integration status and last sync time
  • Verify project access permissions
  • Review sync logs for error details

Data Not Updating​

  • Try manual sync
  • Check if Plane webhooks are configured
  • Verify network connectivity

Performance Issues​

  • Reduce sync frequency for large workspaces
  • Use selective sync instead of full sync
  • Configure sync during off-peak hours

Webhook Configuration​

For real-time sync, configure Plane webhooks:

{
  "url": "https://your-fyi-server.com/api/plane-integration/webhook",
  "events": [
    "work_item.created",
    "work_item.updated",
    "work_item.deleted",
    "label.created",
    "label.updated"
  ],
  "secret": "your-webhook-secret"
}

Rate Limiting​

  • Plane API has rate limits (varies by plan)
  • FYI implements automatic backoff and retry
  • Monitor sync logs for rate limit warnings
  • Consider upgrading Plane plan for higher limits