Batch Get Pinboards

Retrieve multiple pinboards by their IDs in a single request. This is more efficient than making individual GET requests.

Endpoint


POST /v1/pinboards/batch/get

Authentication

Requires API key with pinboards:read scope.


Authorization: Bearer pk_live_your_api_key

Request Body

Field	Type	Required	Description
`pinboard_ids`	string[]	Yes	Array of pinboard IDs (max 100)

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const result = await client.pinboards.batchGet([
  'pb-abc123',
  'pb-xyz789',
  'pb-def456'
])
 
console.log(`Found: ${result.found.length}`)
console.log(`Not found: ${result.not_found.length}`)
console.log(`Permission denied: ${result.permission_denied.length}`)

cURL


curl -X POST https://api.pindown.ai/v1/pinboards/batch/get \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pinboard_ids": ["pb-abc123", "pb-xyz789", "pb-def456"]
  }'

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pinboards/batch/get', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PINDOWN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pinboard_ids: ['pb-abc123', 'pb-xyz789', 'pb-def456']
  })
})
 
const result = await response.json()
console.log(`Found: ${result.data.found.length}`)

Response


{
  "success": true,
  "data": {
    "found": [
      {
        "id": "pb-abc123",
        "title": "My Pinboard",
        "pins": ["p-pin1", "p-pin2"],
        "layout": {},
        "is_public": false,
        "owner_id": "user-xyz789",
        "created_at": 1703123456789,
        "updated_at": 1703123456789
      }
    ],
    "not_found": ["pb-xyz789"],
    "permission_denied": ["pb-def456"]
  },
  "message": "Retrieved 1 pinboards"
}

Response Fields

found: Array of pinboards that were successfully retrieved
not_found: Array of pinboard IDs that don’t exist
permission_denied: Array of pinboard IDs you don’t have access to

Notes

Maximum 100 pinboards per batch request
Pinboards you don’t have access to will be in permission_denied, not not_found
More efficient than individual GET requests for multiple pinboards

Next Steps

Batch Add Pins - Add multiple pins to a pinboard
Get Pinboard - Get a single pinboard