Skip to Content
Pindown.ai is in early alpha - features may change
API GuideSharing Pinboards

Sharing Pinboards

Learn how to share pinboards and manage team collaboration on dashboards.

Overview

Pinboard sharing allows you to:

  1. Share entire dashboards - All pins in one share
  2. Team collaboration - Multiple editors on one board
  3. Public dashboards - Client-facing or embedded boards
  4. Role-based access - Control who can edit or view

Make Pinboard Public

Share a pinboard publicly:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: 'pk_live_your_api_key'
})
 
// Make pinboard public
const result = await client.pinboards.share('pb-abc123', {
  is_public: true,
  allow_comments: true,
  require_sign_in: false
})
 
console.log(`Share URL: ${result.shareable_url}`)
// Output: https://pindown.ai/share/pinboard/pb-abc123

Invite Team Members

Invite specific users to collaborate:

// Invite editor (can edit pins and layout)
await client.pinboards.inviteCollaborator('pb-abc123', {
  email: 'teammate@example.com',
  role: 'editor',
  message: 'Let\'s work on this dashboard together'
})
 
// Invite viewer (read-only)
await client.pinboards.inviteCollaborator('pb-abc123', {
  email: 'stakeholder@example.com',
  role: 'viewer'
})
 
console.log('Invitations sent!')

List Collaborators

View all collaborators on a pinboard:

const collaborators = await client.pinboards.listCollaborators('pb-abc123')
 
console.log(`Total collaborators: ${collaborators.length}`)
 
collaborators.forEach(collab => {
  console.log(`- ${collab.email}: ${collab.role}`)
})

Update Collaborator Role

Change a collaborator’s role:

// Upgrade viewer to editor
await client.pinboards.updateCollaborator('pb-abc123', 'user-xyz789', {
  role: 'editor'
})
 
console.log('Role updated')

Remove Collaborator

Revoke access from a collaborator:

await client.pinboards.removeCollaborator('pb-abc123', 'user-xyz789')
 
console.log('Access revoked')

Complete Example

Create a team dashboard and share with team:

async function createTeamDashboard() {
  const API_KEY = process.env.PINDOWN_API_KEY
  const BASE_URL = 'https://api.pindown.ai/v1'
  
  const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
 
  // 1. Create pinboard
  const pinboardRes = await fetch(`${BASE_URL}/pinboards`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      title: 'Q4 Sales Dashboard',
      description: 'Real-time sales metrics for Q4',
      metadata: {
        tags: ['sales', 'q4', '2024']
      }
    })
  })
  const pinboard = await pinboardRes.json()
 
  // 2. Create and add pins
  const revenuePin = await fetch(`${BASE_URL}/pins`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      data_type: 'pin-card',
      pin_type: 'stat-cards',
      pin_layout: '1x1',
      content: {
        cards: [{
          title: 'Q4 Revenue',
          value: '$125,430',
          change: '+18.2%',
          trend: 'up'
        }]
      }
    })
  }).then(r => r.json())
 
  await fetch(`${BASE_URL}/pinboards/${pinboard.data.id}/pins`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      pin_id: revenuePin.data.pin_id,
      position: { x: 0, y: 0, w: 2, h: 1 }
    })
  })
 
  // 3. Make public for stakeholders
  await fetch(`${BASE_URL}/pinboards/${pinboard.data.id}/share`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      is_public: true,
      require_sign_in: true,  // Require login but share via link
      allow_comments: false
    })
  })
 
  // 4. Invite sales team as editors
  const salesTeam = [
    'sales.manager@company.com',
    'sales.rep1@company.com',
    'sales.rep2@company.com'
  ]
 
  for (const email of salesTeam) {
    await fetch(`${BASE_URL}/pinboards/${pinboard.data.id}/collaborators`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        email,
        role: 'editor',
        message: 'Please keep this dashboard updated with latest metrics'
      })
    })
  }
 
  // 5. Invite executives as viewers
  const executives = ['ceo@company.com', 'cfo@company.com']
 
  for (const email of executives) {
    await fetch(`${BASE_URL}/pinboards/${pinboard.data.id}/collaborators`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        email,
        role: 'viewer'
      })
    })
  }
 
  console.log('✅ Team dashboard created and shared')
  console.log(`🔗 Public URL: ${pinboard.data.shareable_url}`)
}
 
createTeamDashboard()

Permission Levels

RoleViewEdit PinsEdit LayoutDelete BoardShareInvite
Owner✅✅✅✅✅✅
Editor✅✅✅❌❌❌
Viewer✅❌❌❌❌❌

Use Cases

Client-Facing Dashboard

await client.pinboards.share('pb-abc123', {
  is_public: true,
  require_sign_in: false,  // No login required
  allow_comments: false
})

Team Collaboration Dashboard

// Internal team only
await client.pinboards.share('pb-abc123', {
  is_public: false  // Invite-only
})
 
// Invite team
await client.pinboards.inviteCollaborator('pb-abc123', {
  email: 'team@company.com',
  role: 'editor'
})

Executive Dashboard

// Public but requires login
await client.pinboards.share('pb-abc123', {
  is_public: true,
  require_sign_in: true,
  allow_comments: false
})

Next Steps

Sharing PinsCustom Roles & Permissions