Skip to Content
Pins APICreate a Pin

Create a Pin

Create a new pin with markdown content or any of the 43 pin types.

Endpoint

POST /v1/pins

Authentication

Requires API key with pins:write scope.

Authorization: Bearer pk_live_your_api_key

Request Body

FieldTypeRequiredDescription
data_typestringNoLegacy field (json, markdown, text, pin-card). Prefer pin_type instead. Defaults to markdown.
pin_typestringNoOne of 43 product types — see Pin types overview (defaults to markdown)
pin_configobjectNoPin configuration (content, settings, etc.)
pin_layoutstringNoLayout size: "1x1", "1x2", "2x1", "2x2", "3x1", "3x2", "3x3", "4x4"
is_publicbooleanNoPublic visibility (default: false)
allow_editbooleanNoAllow editors to modify (default: false)
require_sign_inbooleanNoRequire sign-in to view (default: false)
allow_commentsbooleanNoEnable comments (default: false)
metadataobjectYesPin metadata including title
pending_invitesobjectNoEmail-to-role mapping for pending collaborators

Metadata Object

FieldTypeRequiredDescription
titlestringYesPin title (minimum required field)
tagsstring[]NoTags for organization
pin_typestringNoPin type (can also be specified at root level)
pin_configobjectNoPin configuration (can also be specified at root level)
pin_layoutstringNoPin 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:

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)

Markdown Pin with Permissions

Create a public pin with comments enabled:

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']
  }
})

Pin with Pending Invites

Create a pin and invite collaborators immediately:

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

Pin Types

Pins support 43 typed pin_type values, each with a validated pin_config. See Pin Types & Schemas for required fields and full examples per type.

Example with stat cards:

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']
  }
})

Response

{
  "success": true,
  "data": {
    "id": "p-abc123def456",
    "data_type": "pin-card",
    "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": "PIN_CONFIG_INVALID",
    "message": "Invalid pin_config for pin_type \"stat-cards\" at cards: …"
  }
}

401 Unauthorized

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

Next Steps

Pin Types & SchemasGet Pin