Skip to Content
Pindown.ai is in early alpha - features may change
Client SDKPins API

Pins API

The Pins API provides methods to create, read, update, and delete pins with various types (stat-cards, line-chart, markdown, flexible-table, etc.).

Getting Started

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Access pins API
const pins = client.pins

Create Pin

Create a new pin with unified structure:

const pin = await client.pins.create({
  pin_type: 'stat-cards',
  pin_config: {
    cards: [{
      title: 'Total Sales',
      value: '$125,430',
      change: '+18.2%',
      trend: 'up'
    }]
  },
  pin_layout: '1x1',
  metadata: {
    title: 'Sales Dashboard',
    tags: ['sales', 'kpi']
  }
})
 
console.log(`Pin created: ${pin.id}`)

Get Pin

Retrieve a specific pin by ID:

const pin = await client.pins.get('p-abc123def456')
 
console.log(`Title: ${pin.metadata.title}`)
console.log(`Type: ${pin.metadata.pin_type}`)
console.log(`Config:`, pin.metadata.pin_config)

List Pins

Get all your pins with pagination:

// Simple list
const result = await client.pins.list()
console.log(`Total pins: ${result.total}`)
 
// With pagination
const result = await client.pins.list({
  limit: 50,
  offset: 0
})
 
result.data.forEach(pin => {
  console.log(`- ${pin.metadata.title}`)
})

Update Pin

Update pin content or metadata:

// Update pin config
await client.pins.update('p-abc123', {
  pin_config: {
    cards: [{
      title: 'Live Users',
      value: '1,234',
      change: '+5.2%',
      trend: 'up'
    }]
  }
})
 
// Update metadata
await client.pins.update('p-abc123', {
  metadata: {
    title: 'Updated Dashboard',
    tags: ['sales', 'updated', 'q4']
  }
})

Delete Pin

Delete a pin permanently:

try {
  await client.pins.delete('p-abc123')
  console.log('Pin deleted successfully')
} catch (error) {
  console.error('Failed to delete pin:', error.message)
}

Share Pin

Update sharing permissions:

// Make pin public with comments
const result = await client.pins.share('p-abc123', {
  is_public: true,
  allow_comments: true,
  require_sign_in: false,
  allow_edit: false
})
 
console.log(`Share URL: ${result.shareable_url}`)
 
// Make private again
await client.pins.share('p-abc123', {
  is_public: false
})

Pin Types

The Pins API supports various pin types with unified structure:

Stat Cards

{
  pin_type: 'stat-cards',
  pin_config: {
    cards: [{
      title: 'Revenue',
      value: '$125k',
      change: '+18%',
      trend: 'up'
    }]
  },
  pin_layout: '1x1'
}

Flexible Table

{
  pin_type: 'flexible-table',
  pin_config: {
    columns: ['Product', 'Sales', 'Revenue'],
    rows: [
      ['Widget A', '1,250', '$125,000'],
      ['Widget B', '890', '$89,000']
    ]
  },
  pin_layout: '2x2'
}

Line Chart

{
  pin_type: 'line-chart',
  pin_config: {
    title: 'API Calls',
    data: [
      { date: '2024-01-01', value: 1200 },
      { date: '2024-01-02', value: 1450 },
      { date: '2024-01-03', value: 1680 }
    ]
  },
  pin_layout: '2x2'
}

Markdown Pin

{
  pin_type: 'markdown',
  pin_config: {
    content: '# Weekly Report\n\n## Key Highlights\n\n- Revenue up 18%'
  },
  pin_layout: '2x2',
  metadata: {
    title: 'Weekly Report',
    tags: ['reports']
  }
}

Available Pin Types

  • stat-cards - Key metrics with trend indicators
  • charts - Data visualizations (line, bar, pie, radar, area, etc.)
  • markdown - Rich text content with formatting
  • table - Tabular data display
  • image - Single image display
  • gallery - Multiple images in a grid layout
  • embed - Video embeds (YouTube, Vimeo, etc.)
  • link - Link cards with previews
  • pdf - PDF document viewer
  • tree - Tree/hierarchy visualization
  • timeline - Timeline visualization
  • json - JSON data viewer
  • steps - Step-by-step processes
  • mermaid - Mermaid diagrams (flowcharts, kanban, sequence, etc.)

Error Handling

import { NotFoundError, ValidationError, RateLimitError } from '@pindownai/client-js'
 
try {
  const pin = await client.pins.get('p-invalid')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Pin not found')
  } else if (error instanceof ValidationError) {
    console.log('Invalid pin data:', error.message)
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limit hit! Wait ${error.retryAfter}ms`)
  }
}

Next Steps

OverviewPages API