Skip to Content
Pins APIList Pins

List Pins

Get all pins for the authenticated user (personal pin index — not dashboard workspace pins).

Endpoint

GET /v1/pins

Authentication

Requires API key with pins:read scope.

Authorization: Bearer pk_live_your_api_key

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoNumber of pins to return (max: 100, default: 50)
offsetintegerNoNumber of pins to skip (default: 0)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "p-abc123",
        "title": "Sales Dashboard",
        "data_type": "pin-card",
        "is_public": false,
        "created_at": 1730472600000,
        "updated_at": 1730476200000
      },
      {
        "id": "p-def456",
        "title": "Monthly Trends",
        "data_type": "markdown",
        "is_public": true,
        "created_at": 1730468400000,
        "updated_at": 1730476200000
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

List items are summaries — use Get Pin or Batch Get for full metadata.pin_config.

Example

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const result = await client.pins.list({ limit: 20, offset: 0 })
console.log(`Total pins: ${result.total}`)
console.log(`Returned: ${result.items.length}`)
 
result.items.forEach((pin) => {
  console.log(`- ${pin.title ?? pin.metadata?.title} (${pin.id})`)
})

Error Responses

401 Unauthorized

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

429 Too Many Requests

Rolling 60-second limit (120 reads/min for this endpoint). See Overview → Rate limits.

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 items.length < limit

Next Steps

Get PinUpdate Pin