Get Pin

Retrieve a specific pin by ID.

Endpoint


GET /v1/pins/:pinId

Authentication

Requires API key with pins:read scope.


Authorization: Bearer pk_live_your_api_key

Path Parameters

Parameter	Type	Required	Description
`pinId`	string	Yes	The pin ID (e.g., `p-abc123def456`)

Response

Success (200 OK)


{
  "success": true,
  "data": {
    "id": "p-abc123def456",
    "owner_id": "usr_xyz",
    "data_type": "pin-card",
    "is_public": false,
    "pin_type": "stat-cards",
    "pin_layout": "1x1",
    "content": {
      "cards": [{
        "title": "Total Sales",
        "value": "$125,430",
        "change": "+18.2%",
        "trend": "up"
      }]
    },
    "metadata": {
      "title": "Sales Dashboard",
      "tags": ["sales", "kpi"],
      "allow_edit": false,
      "require_sign_in": false,
      "allow_comments": false,
      "created_at": "2024-11-01T15:30:00Z",
      "updated_at": "2024-11-01T16:45:00Z"
    }
  }
}

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Get pin details
const pin = await client.pins.get('p-abc123def456')
console.log(`Pin: ${pin.metadata.title}`)

cURL


curl -X GET https://api.pindown.ai/v1/pins/p-abc123def456 \
  -H "Authorization: Bearer pk_live_your_api_key"

Node.js Fetch


const PINDOWN_API_KEY = process.env.PINDOWN_API_KEY
 
async function getPin(pinId) {
  const response = await fetch(`https://api.pindown.ai/v1/pins/${pinId}`, {
    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 pin details
const pin = await getPin('p-abc123def456')
console.log(`Pin: ${pin.data.metadata.title}`)

undefined


import requests
import os
 
PINDOWN_API_KEY = os.environ.get('PINDOWN_API_KEY')
 
def get_pin(pin_id):
    response = requests.get(
        f'https://api.pindown.ai/v1/pins/{pin_id}',
        headers={
            'Authorization': f'Bearer {PINDOWN_API_KEY}'
        }
    )
    response.raise_for_status()
    return response.json()
 
# Get pin details
pin = get_pin('p-abc123def456')
print(f"Pin: {pin['data']['metadata']['title']}")

Error Responses

404 Not Found

Pin doesn’t exist or you don’t have access:


{
  "error": {
    "code": "NOT_FOUND",
    "message": "Pin not found or you don't have access"
  }
}

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.

Next Steps

Update Pin - Update pin content
Delete Pin - Remove a pin
List Pins - Get all your pins