Get Pin

Retrieve a specific pin by ID.

Endpoint


GET /v1/pins/:pinId

Authentication

Requires API key with pins:read scope. You must be the owner or the pin must be public.


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",
    "title": "Sales Dashboard",
    "description": "",
    "data_type": "pin-card",
    "is_public": false,
    "owner_id": "usr_xyz",
    "metadata": {
      "title": "Sales Dashboard",
      "tags": ["sales", "kpi"],
      "pin_type": "stat-cards",
      "pin_layout": "1x1",
      "pin_config": {
        "cards": [{
          "title": "Total Sales",
          "value": "$125,430",
          "change": "+18.2%",
          "trend": "up"
        }]
      },
      "allow_edit": false,
      "require_sign_in": false,
      "allow_comments": false
    },
    "created_at": 1730472600000,
    "updated_at": 1730476200000
  }
}

Pin content lives in metadata.pin_type + metadata.pin_config. There is no separate top-level content field on v1 GET.

Example

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const pin = await client.pins.get('p-abc123def456')
console.log(`Title: ${pin.title ?? pin.metadata?.title}`)
console.log(`Type: ${pin.metadata?.pin_type}`)
console.log(`Config:`, pin.metadata?.pin_config)

cURL


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

Node.js Fetch


const response = await fetch('https://api.pindown.ai/v1/pins/p-abc123def456', {
  headers: {
    Authorization: `Bearer ${process.env.PINDOWN_API_KEY}`,
  },
})
 
const { data: pin } = await response.json()
console.log(`Title: ${pin.metadata.title}`)
console.log(`Config:`, pin.metadata.pin_config)

Error Responses

404 Not Found

Pin doesn’t exist:


{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Pin not found"
  }
}

403 Forbidden

Private pin owned by another user:


{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to access this pin"
  }
}

Next Steps

Update Pin — Modify pin content
Delete Pin — Remove a pin
Pin Types & Schemas — Valid pin_type values