Create a Pin

Create a new pin with markdown content or various pin types (stats, charts, tables, etc.).

Endpoint


POST /v1/pins

Authentication

Requires API key with pins:write scope.


Authorization: Bearer pk_live_your_api_key

Request Body

Field	Type	Required	Description
`pin_type`	string	No	Type of pin: `"markdown"` (default), `"stat-cards"`, `"image"`, `"indicator-table"`, `"score-gauge"`, `"alert-action"`, `"bottom-detector"`, `"long-short-pie"`, `"flexible-table"`, `"embed"`, `"line-chart"`
`pin_config`	object	No	Pin configuration (content, settings, etc.)
`pin_layout`	string	No	Layout size: `"1x1"`, `"1x2"`, `"2x1"`, `"2x2"`, `"3x1"`, `"3x2"`, `"3x3"`, `"4x4"`
`is_public`	boolean	No	Public visibility (default: `false`)
`allow_edit`	boolean	No	Allow editors to modify (default: `false`)
`require_sign_in`	boolean	No	Require sign-in to view (default: `false`)
`allow_comments`	boolean	No	Enable comments (default: `false`)
`metadata`	object	Yes	Pin metadata including title
`pending_invites`	object	No	Email-to-role mapping for pending collaborators

Metadata Object

Field	Type	Required	Description
`title`	string	Yes	Pin title (minimum required field)
`description`	string	No	Pin description
`tags`	string[]	No	Tags for organization
`pin_type`	string	No	Pin type (can also be specified at root level)
`pin_config`	object	No	Pin configuration (can also be specified at root level)
`pin_layout`	string	No	Pin layout (can also be specified at root level)

Pending Invites Object

Optional email-to-role mapping for inviting collaborators upon pin creation:


{
  "user@example.com": "editor",
  "viewer@example.com": "viewer"
}

Examples

Minimum Required: Simple Markdown Pin

The absolute minimum to create a pin - just a title:

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const pin = await client.pins.create({
  metadata: {
    title: 'My First Pin'
  }
})
 
console.log('Pin created:', pin.id)

cURL


curl -X POST https://api.pindown.ai/v1/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "My First Pin"
    }
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      title: 'My First Pin'
    }
  })
})
 
const data = await response.json()
console.log('Pin created:', data.data.id)

Markdown Pin with Permissions

Create a public pin with comments enabled:

Client-JS


const pin = await client.pins.create({
  pin_type: 'markdown',
  is_public: true,
  allow_comments: true,
  require_sign_in: false,
  metadata: {
    title: 'Public Documentation',
    tags: ['docs', 'team']
  }
})

cURL


curl -X POST https://api.pindown.ai/v1/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_type": "markdown",
    "is_public": true,
    "allow_comments": true,
    "require_sign_in": false,
    "metadata": {
      "title": "Public Documentation",
      "tags": ["docs", "team"]
    }
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pin_type: 'markdown',
    is_public: true,
    allow_comments: true,
    require_sign_in: false,
    metadata: {
      title: 'Public Documentation',
      tags: ['docs', 'team']
    }
  })
})

Pin with Pending Invites

Create a pin and invite collaborators immediately:

Client-JS


const pin = await client.pins.create({
  metadata: {
    title: 'Team Project Pin'
  },
  pending_invites: {
    'editor@team.com': 'editor',
    'viewer@team.com': 'viewer'
  }
})

cURL


curl -X POST https://api.pindown.ai/v1/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "Team Project Pin"
    },
    "pending_invites": {
      "editor@team.com": "editor",
      "viewer@team.com": "viewer"
    }
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      title: 'Team Project Pin'
    },
    pending_invites: {
      'editor@team.com': 'editor',
      'viewer@team.com': 'viewer'
    }
  })
})

Pin Types

Pins support various types for displaying different content. Here’s an example with stat cards:

Client-JS


const pin = await client.pins.create({
  pin_type: 'stat-cards',
  pin_layout: '2x1',
  pin_config: {
    cards: [{
      title: 'Total Revenue',
      value: '$125,430',
      change: '+18.2%',
      trend: 'up'
    }, {
      title: 'New Customers',
      value: '1,234',
      change: '+12%',
      trend: 'up'
    }]
  },
  metadata: {
    title: 'Revenue Dashboard',
    tags: ['sales', 'kpi']
  }
})

cURL


curl -X POST https://api.pindown.ai/v1/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_type": "stat-cards",
    "pin_layout": "2x1",
    "pin_config": {
      "cards": [{
        "title": "Total Revenue",
        "value": "$125,430",
        "change": "+18.2%",
        "trend": "up"
      }, {
        "title": "New Customers",
        "value": "1,234",
        "change": "+12%",
        "trend": "up"
      }]
    },
    "metadata": {
      "title": "Revenue Dashboard",
      "tags": ["sales", "kpi"]
    }
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pin_type: 'stat-cards',
    pin_layout: '2x1',
    pin_config: {
      cards: [{
        title: 'Total Revenue',
        value: '$125,430',
        change: '+18.2%',
        trend: 'up'
      }, {
        title: 'New Customers',
        value: '1,234',
        change: '+12%',
        trend: 'up'
      }]
    },
    metadata: {
      title: 'Revenue Dashboard',
      tags: ['sales', 'kpi']
    }
  })
})

Available Pin Types

Pins support 14+ different 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.)

Response


{
  "success": true,
  "data": {
    "id": "p-abc123def456",
    "pin_type": "stat-cards",
    "created_at": 1699027800000,
    "is_public": false,
    "allow_edit": false,
    "require_sign_in": false,
    "allow_comments": false
  },
  "message": "Pin created successfully"
}

Error Responses

400 Bad Request


{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "metadata.title is required"
  }
}

401 Unauthorized


{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Next Steps

Update pin - Modify pin data
Share pin - Configure sharing & permissions
Add to page - Add pin to a page
Add to pinboard - Organize pins