Pins API Overview

The v1 Pins API (/v1/pins) lets you create, read, update, delete, batch, and share pins programmatically. Requires a Workspace plan API key (pk_…).

Use pin_type + pin_config for typed content, plus metadata.title (required on create).

Endpoints

Client SDK: @pindownai/client-js — client.pins.* only.

Authentication

Authorization: Bearer pk_live_your_api_key

Scopes: pins:read (GET), pins:write (POST/PUT/PATCH/DELETE), pins:share (share endpoint).

Request shape

{
  "pin_type": "markdown",
  "pin_config": { "content": "# Hello" },
  "pin_layout": "2x2",
  "is_public": false,
  "metadata": {
    "title": "My pin",
    "tags": ["api"]
  }
}

• pin_type — optional on create; defaults to markdown if omitted.
• pin_config — validated per type (see below). Invalid configs return 400 with PIN_CONFIG_INVALID or INVALID_PIN_TYPE.
• pin_layout — "1x1", "1x2", "2x1", "2x2", "3x1", "3x2", "3x3", "4x4".
• metadata.title — required on create.

You can also nest pin_type, pin_config, and pin_layout inside metadata instead of at the root.

Rate limits

Server-enforced rolling 60-second windows per API key identity on all /v1/pins* routes. When exceeded, the API returns HTTP 429 with code RATE_LIMITED.

Pin types (27)

Each type has a validated pin_config schema with required fields, optional fields, and a full create example.

Pin Types & Schemas → — complete reference for all 27 types.

Supported pin_type values:

markdown · image · gallery · table · charts · mermaid · embed · pdf-viewer · excel-viewer · stat-cards · timeline · json-viewer · json-list · links · steps · csv-viewer · user-story · chat · intro · mastra · text-media · file-upload · kanban-board · checklist · calendar · roadmap · realtime-canvas

Quick example

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({ apiKey: process.env.PINDOWN_API_KEY! })
 
const pin = await client.pins.create({
  pin_type: 'stat-cards',
  pin_config: {
    cards: [{ title: 'Users', value: '1,234', change: '+5%', trend: 'up' }],
  },
  metadata: { title: 'Live metrics' },
})
 
console.log(pin.id)

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

Next steps

• Pin Types & Schemas — pin_config for every type
• Create a Pin — full create reference
• Client SDK — typed helpers (createMarkdown, createStatCards, …)
• Formats → Pins — product context for pins