List Pins

Get all pins for the authenticated user.

Endpoint


GET /v1/pins

Authentication

Requires API key with pins:read scope.


Authorization: Bearer pk_live_your_api_key

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Number of pins to return (max: 100, default: 50)
`offset`	integer	No	Number of pins to skip (default: 0)

Response

Success (200 OK)


{
  "success": true,
  "data": {
    "pins": [
      {
        "pin_id": "p-abc123",
        "data_type": "pin-card",
        "pin_type": "stat-cards",
        "pin_layout": "1x1",
        "metadata": {
          "title": "Sales Dashboard",
          "tags": ["sales", "kpi"]
        },
        "created_at": 1730472600000,
        "updated_at": 1730476200000
      },
      {
        "pin_id": "p-def456",
        "data_type": "pin-card",
        "pin_type": "line-chart",
        "pin_layout": "2x2",
        "metadata": {
          "title": "Monthly Trends",
          "tags": ["analytics"]
        },
        "created_at": 1730468400000,
        "updated_at": 1730476200000
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// List pins with pagination
const result = await client.pins.list({ limit: 20, offset: 0 })
console.log(`Total pins: ${result.total}`)
console.log(`Returned: ${result.data.length}`)
 
// Get all pins (auto-pagination)
let allPins = []
let offset = 0
let hasMore = true
 
while (hasMore) {
  const result = await client.pins.list({ limit: 50, offset })
  allPins.push(...result.data)
  hasMore = result.data.length === 50
  offset += 50
}
 
console.log(`Total pins: ${allPins.length}`)

cURL


# Get first 20 pins
curl -X GET "https://api.pindown.ai/v1/pins?limit=20&offset=0" \
  -H "Authorization: Bearer pk_live_your_api_key"
 
# Get next 20 pins (pagination)
curl -X GET "https://api.pindown.ai/v1/pins?limit=20&offset=20" \
  -H "Authorization: Bearer pk_live_your_api_key"

Node.js Fetch


const PINDOWN_API_KEY = process.env.PINDOWN_API_KEY
 
async function listPins(limit = 50, offset = 0) {
  const response = await fetch(
    `https://api.pindown.ai/v1/pins?limit=${limit}&offset=${offset}`,
    {
      headers: {
        'Authorization': `Bearer ${PINDOWN_API_KEY}`
      }
    }
  )
  
  if (!response.ok) {
    const error = await response.json()
    throw new Error(`API Error: ${error.error.message}`)
  }
  
  return response.json()
}
 
// Get all pins with pagination
let allPins = []
let offset = 0
let hasMore = true
 
while (hasMore) {
  const result = await listPins(50, offset)
  allPins.push(...result.data.pins)
  
  hasMore = result.data.pins.length === 50
  offset += 50
}
 
console.log(`Total pins: ${allPins.length}`)

undefined


import requests
import os
 
PINDOWN_API_KEY = os.environ.get('PINDOWN_API_KEY')
 
def list_pins(limit=50, offset=0):
    response = requests.get(
        'https://api.pindown.ai/v1/pins',
        headers={
            'Authorization': f'Bearer {PINDOWN_API_KEY}'
        },
        params={
            'limit': limit,
            'offset': offset
        }
    )
    response.raise_for_status()
    return response.json()
 
# Get all pins with pagination
all_pins = []
offset = 0
 
while True:
    result = list_pins(limit=50, offset=offset)
    all_pins.extend(result['data']['pins'])
    
    if len(result['data']['pins']) < 50:
        break
    offset += 50
 
print(f"Total pins: {len(all_pins)}")

Error Responses

401 Unauthorized


{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden


{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "This endpoint requires the 'pins:read' scope"
  }
}

Rate Limiting

This endpoint costs 1 token per request.

Pagination Tips

Use limit to control page size (max 100)
Use offset for pagination: offset = page * limit
Check total in response to know total count
Stop when returned pins < limit

Next Steps

Get Pin - Get a specific pin
Create Pin - Create a new pin
Update Pin - Update pin content