Skip to Content
Pindown.ai is in early alpha - features may change
API GuidePinboard with Pins

Pinboard with Pins

Learn how to create a visual dashboard with pins - stat cards, charts, tables, markdown, and more.

Overview

This guide shows you how to build a complete dashboard:

  1. Create a Pinboard - Your dashboard canvas
  2. Create Pins - Various pin types (stats, charts, tables, markdown)
  3. Add Pins to Pinboard - Layout your visual dashboard

Step 1: Create a Pinboard

First, create a pinboard for your dashboard.

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const pinboard = await client.pinboards.create({
  title: 'Sales Dashboard Q1 2024'
})
 
console.log('Pinboard created:', pinboard.id)

Step 2: Create Stat Cards Pin

Create a pin with stat cards showing key metrics.

const pin = await client.pins.create({
  pin_type: 'stat-cards',
  pin_config: {
    cards: [
      {
        title: 'Total Revenue',
        value: '$125,430',
        change: '+23.5%',
        trend: 'up',
        subtitle: 'vs last quarter'
      },
      {
        title: 'New Customers',
        value: '847',
        change: '+12.3%',
        trend: 'up',
        subtitle: 'this month'
      },
      {
        title: 'Conversion Rate',
        value: '3.24%',
        change: '-0.5%',
        trend: 'down',
        subtitle: 'needs attention'
      },
      {
        title: 'Avg Order Value',
        value: '$148',
        change: '+8.2%',
        trend: 'up',
        subtitle: 'increasing'
      }
    ]
  },
  pin_layout: '2x2',
  metadata: {
    title: 'Key Metrics'
  }
})
 
console.log('Stat Cards created:', pin.id)

Step 3: Create Line Chart Pin

Create a line chart showing revenue trends.

const chartPin = await client.pins.create({
  pin_type: 'line-chart',
  pin_config: {
    title: 'Revenue Trend',
    data: [
      { date: '2024-01-01', value: 42000 },
      { date: '2024-02-01', value: 51000 },
      { date: '2024-03-01', value: 48000 },
      { date: '2024-04-01', value: 62000 },
      { date: '2024-05-01', value: 75000 },
      { date: '2024-06-01', value: 89000 }
    ]
  },
  pin_layout: '2x2',
  metadata: {
    title: '6-Month Revenue Trend'
  }
})
 
console.log('Chart Pin created:', chartPin.id)

Step 4: Create Table Pin

Create a table showing top customers.

const tablePin = await client.pins.create({
  pin_type: 'flexible-table',
  pin_config: {
    columns: ['Customer', 'Revenue', 'Orders', 'Status'],
    rows: [
      ['Acme Corp', '$45,230', '127', 'Active'],
      ['TechStart Inc', '$38,920', '94', 'Active'],
      ['Global Solutions', '$32,150', '78', 'Active'],
      ['Innovation Labs', '$28,640', '65', 'Pending']
    ]
  },
  pin_layout: '2x2',
  metadata: {
    title: 'Top 5 Customers by Revenue'
  }
})
 
console.log('Table Pin created:', tablePin.id)

Step 5: Create Alert Pin

Create an alert pin for important notifications.

const alertPin = await client.pins.create({
  pin_type: 'alert-action',
  pin_config: {
    severity: 'warning',
    title: 'Conversion Rate Dropping',
    message: 'Conversion rate has decreased by 0.5% this week. Review marketing campaigns and checkout flow.'
  },
  pin_layout: '1x1',
  metadata: {
    title: 'System Alert'
  }
})
 
console.log('Alert Pin created:', alertPin.id)

Step 6: Add All Pins to Pinboard

Finally, add all pins to your pinboard.

// Add stat cards pin
await client.pinboards.addPin(pinboard.id, {
  pin_id: pin.id
})
 
// Add chart pin
await client.pinboards.addPin(pinboard.id, {
  pin_id: chartPin.id
})
 
// Add table pin
await client.pinboards.addPin(pinboard.id, {
  pin_id: tablePin.id
})
 
// Add alert pin
await client.pinboards.addPin(pinboard.id, {
  pin_id: alertPin.id
})
 
console.log('✅ Dashboard complete!')
console.log(`🔗 View at: https://pindown.ai/pinboard/${pinboard.id}`)

Available Pin Types

Pin TypeDescriptionUse Case
stat-cardsKey metrics with trend indicatorsKPIs, metrics overview
chartsData visualizations (line, bar, pie, radar, etc.)Trends, comparisons, distributions
markdownRich text content with formattingReports, documentation, notes
tableTabular data displayLists, detailed data, comparisons
imageSingle image displayCharts, screenshots, photos
galleryMultiple images in a grid layoutPhoto collections, visual galleries
embedVideo embeds (YouTube, Vimeo, etc.)Video content, presentations
linkLink cards with previewsResource links, references
pdfPDF document viewerDocuments, reports, manuals
treeTree/hierarchy visualizationOrg charts, folder structures
timelineTimeline visualizationEvents, project milestones
jsonJSON data viewerAPI responses, data inspection
stepsStep-by-step processesTutorials, workflows, guides
mermaidMermaid diagrams (flowcharts, kanban, etc.)Process flows, system diagrams

Next Steps

Creating a PageSharing Pins