Skip to Content
Client SDKOverview

Client SDK

The @pindownai/client-js package is a pins-only TypeScript/JavaScript client for the Pindown v1 Pins API.

Requires a Workspace plan API key (pk_…).

Installation

npm install @pindownai/client-js

Quick Start

import { PindownClient } from '@pindownai/client-js'
import type { MarkdownPinConfig } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY!,
})
 
const created = await client.pins.create({
  pin_type: 'markdown',
  pin_config: { content: '# Hello\n\nCreated via API.' },
  metadata: { title: 'My doc', tags: ['docs'] },
})
 
const pin = await client.pins.get(created.id)
const content = (pin.metadata?.pin_config as MarkdownPinConfig | undefined)?.content

Configuration

const client = new PindownClient({
  apiKey: 'pk_live_...',              // Required
  baseURL: 'https://api.pindown.ai/v1', // Optional (default)
  maxRetries: 3,                       // Optional
  timeout: 30000,                      // Optional (ms)
})

Pins API

client.pins.create(request)
client.pins.get(pinId)
client.pins.list({ limit, offset })
client.pins.update(pinId, request)
client.pins.delete(pinId)
client.pins.share(pinId, request)
client.pins.batchGet(pinIds)
client.pins.batchCreate(pins)
client.pins.batchUpdate(updates)
client.pins.batchDelete(pinIds)
 
// Helpers
client.pins.createMarkdown({ title, content, tags })
client.pins.createStatCards({ title, cards })
client.pins.createTable({ title, columns, rows })
client.pins.createEmbed({ title, url, type })

View full Pins SDK documentation →

Rate Limits (server-enforced)

The server applies rolling 60-second buckets on /v1/pins*. When exceeded you get HTTP 429 with error code RATE_LIMITED, thrown as RateLimitError in the client.

There is no client-side token bucket — limits are enforced on the server only.

Error Handling

import {
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  ValidationError,
  RateLimitError,
} from '@pindownai/client-js'
 
try {
  await client.pins.get('p-invalid')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Pin not found')
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited — retry later')
  }
}

TypeScript Support

Import typed pin configs per type:

import type {
  PinTypeId,
  PinConfigByType,
  MarkdownPinConfig,
  TablePinConfig,
  StatCardsPinConfig,
  CreatePinRequest,
} from '@pindownai/client-js'

Next Steps

KanbanPins API