Batch Create Pins

Create multiple pins in a single request. This is more efficient than making individual POST requests.

Endpoint


POST /v1/pins/batch

Authentication

Requires API key with pins:write scope.


Authorization: Bearer pk_live_your_api_key

Request Body

Field	Type	Required	Description
`pins`	object[]	Yes	Array of pin objects (max 50)

Each pin object follows the same structure as Create Pin.

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const result = await client.pins.batchCreate([
  {
    pin_type: 'markdown',
    pin_config: { content: '# First Pin' },
    metadata: { title: 'First Pin' }
  },
  {
    pin_type: 'stat-cards',
    pin_config: {
      cards: [{ title: 'Revenue', value: '$100k' }]
    },
    metadata: { title: 'Revenue Stats' }
  }
])
 
console.log(`Created: ${result.created.length}`)
console.log(`Failed: ${result.failed.length}`)

cURL


curl -X POST https://api.pindown.ai/v1/pins/batch \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pins": [
      {
        "pin_type": "markdown",
        "pin_config": { "content": "# First Pin" },
        "metadata": { "title": "First Pin" }
      },
      {
        "pin_type": "stat-cards",
        "pin_config": {
          "cards": [{ "title": "Revenue", "value": "$100k" }]
        },
        "metadata": { "title": "Revenue Stats" }
      }
    ]
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pins: [
      {
        pin_type: 'markdown',
        pin_config: { content: '# First Pin' },
        metadata: { title: 'First Pin' }
      },
      {
        pin_type: 'stat-cards',
        pin_config: {
          cards: [{ title: 'Revenue', value: '$100k' }]
        },
        metadata: { title: 'Revenue Stats' }
      }
    ]
  })
})
 
const result = await response.json()
console.log(`Created: ${result.data.created.length}`)

Response


{
  "success": true,
  "data": {
    "created": [
      {
        "id": "p-abc123",
        "index": 0,
        "created_at": 1703123456789
      },
      {
        "id": "p-xyz789",
        "index": 1,
        "created_at": 1703123456789
      }
    ],
    "failed": [
      {
        "index": 2,
        "error": "metadata.title is required"
      }
    ]
  },
  "message": "Created 2 pins"
}

Response Fields

created: Array of successfully created pins with their IDs and original index
failed: Array of pins that failed to create with error messages

Notes

Maximum 50 pins per batch request
Each pin is processed independently - if one fails, others still succeed
The index field in responses corresponds to the position in your input array

Next Steps

Batch Get Pins - Retrieve multiple pins
Batch Update Pins - Update multiple pins
Create Pin - Create a single pin