Update Sharing Settings

Control who can access your pin by updating sharing permissions.

Endpoint


POST /v1/pins/:pinId/share

Authentication

Requires API key with pins:share scope.


Authorization: Bearer pk_live_your_api_key

Path Parameters

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

Request Body

Field	Type	Required	Description
`is_public`	boolean	No	Make pin publicly accessible (default: `false`)
`allow_edit`	boolean	No	Allow viewers to edit the pin (default: `false`)
`require_sign_in`	boolean	No	Require sign-in to view (default: `false`)
`allow_comments`	boolean	No	Enable comments on the pin (default: `false`)

Response

Success (200 OK)


{
  "success": true,
  "data": {
    "id": "p-abc123def456",
    "is_public": true,
    "allow_edit": false,
    "require_sign_in": false,
    "allow_comments": true
  }
}

Examples

Make Pin Public


curl -X POST https://api.pindown.ai/v1/pins/p-abc123def456/share \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_public": true,
    "allow_comments": true
  }'

Enable Comments Only


curl -X POST https://api.pindown.ai/v1/pins/p-abc123def456/share \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_comments": true
  }'

Make Private Again


curl -X POST https://api.pindown.ai/v1/pins/p-abc123def456/share \
  -H "Authorization: Bearer pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_public": false,
    "allow_comments": false
  }'

Code Examples

Client-JS


import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Make pin public with comments
const result = await client.pins.share('p-abc123def456', {
  is_public: true,
  allow_comments: true
})
 
console.log(`Share URL: ${result.shareable_url}`)
 
// Make pin private again
await client.pins.share('p-abc123def456', {
  is_public: false,
  allow_comments: false
})

Node.js Fetch


const PINDOWN_API_KEY = process.env.PINDOWN_API_KEY
 
async function updateSharing(pinId, settings) {
  const response = await fetch(`https://api.pindown.ai/v1/pins/${pinId}/share`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${PINDOWN_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(settings)
  })
  
  if (!response.ok) {
    const error = await response.json()
    throw new Error(`API Error: ${error.error.message}`)
  }
  
  return response.json()
}
 
// Make pin public with comments
const result = await updateSharing('p-abc123def456', {
  is_public: true,
  allow_comments: true
})
 
console.log(`Share URL: ${result.data.shareable_url}`)

undefined


import requests
import os
 
PINDOWN_API_KEY = os.environ.get('PINDOWN_API_KEY')
 
def update_sharing(pin_id, settings):
    response = requests.post(
        f'https://api.pindown.ai/v1/pins/{pin_id}/share',
        headers={
            'Authorization': f'Bearer {PINDOWN_API_KEY}',
            'Content-Type': 'application/json'
        },
        json=settings
    )
    response.raise_for_status()
    return response.json()
 
# Make pin public
result = update_sharing('p-abc123def456', {
    'is_public': True,
    'allow_comments': True
})
 
print(f"Share URL: {result['data']['shareable_url']}")

Permission Combinations

`is_public`	`require_sign_in`	`allow_edit`	Behavior
`false`	-	-	Private (only you can access)
`true`	`false`	`false`	Public, no sign-in required, read-only
`true`	`true`	`false`	Public, sign-in required, read-only
`true`	`false`	`true`	Public, no sign-in, editable by anyone
`true`	`true`	`true`	Public, sign-in required, editable

Error Responses

404 Not Found


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

403 Forbidden


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

401 Unauthorized


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

Rate Limiting

This endpoint costs 3 tokens per request (email costs for notifications).

Next Steps

Get Pin - Retrieve pin details
Update Pin - Update pin content
Collaborators - Manage pin collaborators