Sharing Pins
Learn how to share pins publicly or with specific collaborators using the Pindown API.
Overview
Sharing features allow you to:
- Make pins public - Share via URL
- Invite collaborators - Specific users with roles
- Control permissions - Owner, Editor, Viewer
- Manage access - Update or revoke access
Make Pin Public
Share a pin publicly with a shareable URL:
Client-JS
import { PindownClient } from '@pindownai/client-js'
const client = new PindownClient({
apiKey: 'pk_live_your_api_key'
})
// Make pin public
const result = await client.pins.share('p-abc123', {
is_public: true,
allow_comments: true,
require_sign_in: false
})
console.log(`Share URL: ${result.shareable_url}`)
// Output: https://pindown.ai/share/pin/p-abc123Invite Collaborator
Invite specific users to collaborate on a pin with role-based access:
Client-JS
// Invite editor
await client.pins.inviteCollaborator('p-abc123', {
email: 'colleague@example.com',
role: 'editor', // editor, viewer
message: 'Please review and edit this pin'
})
console.log('Invitation sent!')
// Invite viewer
await client.pins.inviteCollaborator('p-abc123', {
email: 'stakeholder@example.com',
role: 'viewer'
})List Collaborators
View all collaborators on a pin:
Client-JS
const collaborators = await client.pins.listCollaborators('p-abc123')
collaborators.forEach(collab => {
console.log(`- ${collab.email}: ${collab.role}`)
})Update Collaborator Role
Change a collaborator’s role:
Client-JS
// Upgrade viewer to editor
await client.pins.updateCollaborator('p-abc123', 'user-xyz789', {
role: 'editor'
})
console.log('Role updated to editor')
// Downgrade editor to viewer
await client.pins.updateCollaborator('p-abc123', 'user-abc123', {
role: 'viewer'
})Remove Collaborator
Revoke access from a collaborator:
Client-JS
await client.pins.removeCollaborator('p-abc123', 'user-xyz789')
console.log('Access revoked')Check Permissions
Check your current permissions on a pin:
Client-JS
const permissions = await client.pins.getPermissions('p-abc123')
console.log(`Role: ${permissions.role}`)
console.log(`Can edit: ${permissions.can_edit}`)
console.log(`Can delete: ${permissions.can_delete}`)
console.log(`Can share: ${permissions.can_share}`)Complete Example
Create a pin and share it with a team:
async function shareWithTeam() {
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 pin
const pinRes = 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'
}]
},
metadata: {
title: 'Q4 Financial Report'
}
})
})
const pin = await pinRes.json()
// 2. Make public for clients
await fetch(`${BASE_URL}/pins/${pin.data.pin_id}/share`, {
method: 'POST',
headers,
body: JSON.stringify({
is_public: true,
allow_comments: false,
require_sign_in: true // Require sign-in but public link
})
})
// 3. Invite CFO as editor
await fetch(`${BASE_URL}/pins/${pin.data.pin_id}/collaborators`, {
method: 'POST',
headers,
body: JSON.stringify({
email: 'cfo@company.com',
role: 'editor',
message: 'Please review Q4 numbers'
})
})
// 4. Invite board members as viewers
const boardMembers = [
'board.member1@company.com',
'board.member2@company.com',
'board.member3@company.com'
]
for (const email of boardMembers) {
await fetch(`${BASE_URL}/pins/${pin.data.pin_id}/collaborators`, {
method: 'POST',
headers,
body: JSON.stringify({
email,
role: 'viewer'
})
})
}
console.log('✅ Pin shared with team')
console.log(`🔗 Public URL: ${pin.data.shareable_url}`)
}
shareWithTeam()Permission Levels
| Role | View | Edit | Delete | Share | Invite |
|---|---|---|---|---|---|
| Owner | ✅ | ✅ | ✅ | ✅ | ✅ |
| Editor | ✅ | ✅ | ❌ | ❌ | ❌ |
| Viewer | ✅ | ❌ | ❌ | ❌ | ❌ |