Batch Get Pins

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

Endpoint


POST /v1/pins/batch/get

Authentication

Requires API key with pins:read scope.


Authorization: Bearer pk_live_your_api_key

Request Body

Field	Type	Required	Description
`pin_ids`	string[]	Yes	Array of pin 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.pins.batchGet([
  'p-abc123',
  'p-xyz789',
  'p-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/pins/batch/get \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pin_ids": ["p-abc123", "p-xyz789", "p-def456"]
  }'

Node.js Fetch


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

Response


{
  "success": true,
  "data": {
    "found": [
      {
        "id": "p-abc123",
        "title": "My Pin",
        "pin_type": "markdown",
        "is_public": false,
        "metadata": {
          "title": "My Pin",
          "pin_type": "markdown",
          "pin_config": {
            "content": "# Hello World"
          }
        },
        "created_at": 1703123456789,
        "updated_at": 1703123456789,
        "owner_id": "user-xyz789"
      }
    ],
    "not_found": ["p-xyz789"],
    "permission_denied": ["p-def456"]
  },
  "message": "Retrieved 1 pins"
}

Response Fields

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

Notes

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

Next Steps

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