Add Pin to Pinboard

Add an existing pin to a pinboard with layout position.

Endpoint


POST /v1/pinboards/:boardId/pins

Authentication

Requires API key with pinboards:write scope.

Request Body

Field	Type	Required	Description
`pin_id`	string	Yes	The pin ID to add
`position`	object	No	Grid layout position `{x, y, w, h}` in grid slots (not pixels)

Position Object

Grid-based positioning using slots:

Field	Type	Description
`x`	number	Horizontal position in grid slots
`y`	number	Vertical position in grid slots
`w`	number	Width in grid slots (1 = 1x slot, 2 = 2x slot, etc.)
`h`	number	Height in grid slots (1 = 1x slot, 2 = 2x slot, etc.)

Note: Grid slots are logical units, not pixels. The actual pixel size is determined by the UI rendering.

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Add pin to pinboard
await client.pinboards.addPin('pb-abc123', {
  pin_id: 'p-xyz789',
  position: { x: 0, y: 0, w: 2, h: 1 }
})
 
console.log('Pin added to pinboard')

cURL


curl -X POST https://api.pindown.ai/v1/pinboards/pb-abc123/pins \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_id": "p-xyz789",
    "position": { "x": 0, "y": 0, "w": 2, "h": 1 }
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pinboards/pb-abc123/pins', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pin_id: 'p-xyz789',
    position: { x: 0, y: 0, w: 2, h: 1 }
  })
})
 
const result = await response.json()
console.log('Pin added')

Response


{
  "success": true
}

Rate Limiting

This endpoint costs 2 tokens per request.