Skip to Content
Pindown.ai is in early alpha - features may change
Pins APIUpdate Pin

Update Pin

Update pin content and metadata (real-time updates).

Endpoint

PUT /v1/pins/:pinId

Authentication

Requires API key with pins:write scope.

Authorization: Bearer pk_live_your_api_key

Path Parameters

ParameterTypeRequiredDescription
pinIdstringYesThe pin ID (e.g., p-abc123def456)

Request Body

Update pin content and/or metadata. All fields are optional - only include what you want to change.

FieldTypeRequiredDescription
is_publicbooleanNoMake pin public or private
allow_editbooleanNoAllow viewers to edit (only if public)
require_sign_inbooleanNoRequire sign-in to view (only if public)
allow_commentsbooleanNoEnable comments on pin
metadataobjectNoPin metadata (title, tags, pin card config)

Metadata Update Example

{
  "metadata": {
    "title": "Updated Dashboard Title",
    "tags": ["sales", "updated", "q4"]
  }
}

Pin Card Content Update

{
  "metadata": {
    "pin_config": {
      "cards": [{
        "title": "Total Sales",
        "value": "$145,890",
        "change": "+32.1%",
        "trend": "up"
      }]
    }
  }
}

Permissions Update

{
  "is_public": true,
  "allow_comments": true,
  "require_sign_in": false
}

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "id": "p-abc123def456",
    "updated_at": 1730476800000
  }
}

Examples

Update Stat Card Value (Real-time)

curl -X PUT https://api.pindown.ai/v1/pins/p-abc123def456 \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "pin_config": {
        "cards": [{
          "title": "Live Users",
          "value": "1,234",
          "change": "+5.2%",
          "trend": "up"
        }]
      }
    }
  }'

Update Table Data

curl -X PUT https://api.pindown.ai/v1/pins/p-def456ghi789 \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "pin_config": {
        "columns": [
          { "id": "product", "label": "Product", "type": "text" },
          { "id": "sales", "label": "Sales", "type": "number" }
        ],
        "rows": [
          { "product": "Widget A", "sales": 1520 },
          { "product": "Widget B", "sales": 980 }
        ]
      }
    }
  }'

Update Only Metadata

curl -X PUT https://api.pindown.ai/v1/pins/p-abc123def456 \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "Q4 Revenue Dashboard",
      "tags": ["revenue", "q4", "2024"]
    }
  }'

Code Examples

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
const pinId = 'p-abc123def456'
 
// Update content only
await client.pins.update(pinId, {
  metadata: {
    pin_config: {
      cards: [{
        title: 'Live Users',
        value: '1,234',
        change: '+5.2%',
        trend: 'up'
      }]
    }
  }
})
 
// Update metadata only
await client.pins.update(pinId, {
  metadata: {
    title: 'Q4 Revenue Dashboard',
    tags: ['revenue', 'q4', '2024']
  }
})
 
// Real-time update every 5 seconds
setInterval(async () => {
  const metrics = await fetchMetrics() // Your data source
  
  await client.pins.update(pinId, {
    metadata: {
      pin_config: {
        cards: [{
          title: 'Live Users',
          value: metrics.users.toString(),
          change: `+${metrics.change}%`,
          trend: 'up'
        }]
      }
    }
  })
  
  console.log(`Updated pin at ${new Date().toISOString()}`)
}, 5000)

Error Responses

404 Not Found

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

400 Bad Request

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid content structure for pin card type 'stat-cards'"
  }
}

403 Forbidden

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

Rate Limiting

This endpoint costs 2 tokens per request.

Tip: For frequent updates, consider using the Batch API (coming soon) to update multiple pins in one request.

Real-time Update Best Practices

  1. Use appropriate intervals: Update every 5-30 seconds for live dashboards
  2. Batch updates: When updating multiple pins, use batch endpoint when available
  3. Error handling: Implement retry logic for failed updates
  4. Rate limits: Be aware of your tier’s rate limits (see Rate Limits)

Next Steps

List PinsDelete Pin