Pin Types & Schemas

{
  "pin_type": "<type-id>",
  "pin_config": { /* shape depends on type — see below */ },
  "metadata": { "title": "Required title" }
}

{
  "pin_type": "markdown",
  "pin_config": {
    "content": "# Weekly report\n\n- Revenue up 18%\n- 3 new customers"
  },
  "metadata": { "title": "Weekly report" }
}

{
  "pin_type": "text-media",
  "pin_config": {
    "title": "Product launch",
    "text": "Summary of the Q1 launch initiative.",
    "subtext": "Shipped to all workspace customers.",
    "textPosition": "left",
    "mediaType": "image",
    "imageConfig": {
      "url": "https://example.com/hero-screenshot.png",
      "alt": "Dashboard screenshot"
    }
  },
  "metadata": { "title": "Launch hero" }
}

{
  "pin_type": "text-media",
  "pin_config": {
    "title": "Product demo",
    "text": "Watch the 2-minute walkthrough.",
    "textPosition": "right",
    "mediaType": "embed",
    "embedConfig": {
      "type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "aspectRatio": "16:9"
    }
  },
  "metadata": { "title": "Demo video" }
}

{
  "pin_type": "intro",
  "pin_config": {
    "heading": "Project overview",
    "subheading": "Q1 initiative"
  },
  "metadata": { "title": "Intro" }
}

{
  "pin_type": "image",
  "pin_config": {
    "url": "https://example.com/photo.png",
    "altText": "Dashboard screenshot",
    "fit": "cover"
  },
  "metadata": { "title": "Screenshot" }
}

{
  "pin_type": "gallery",
  "pin_config": {
    "images": [
      { "url": "https://example.com/a.png", "alt": "Slide A" },
      { "url": "https://example.com/b.png", "alt": "Slide B" }
    ]
  },
  "metadata": { "title": "Photo gallery" }
}

{
  "pin_type": "stat-cards",
  "pin_config": {
    "cards": [
      { "title": "Revenue", "value": "$125,430", "change": "+18.2%", "trend": "up" },
      { "title": "Users", "value": 1234, "change": "+5%", "trend": "up" }
    ]
  },
  "pin_layout": "2x1",
  "metadata": { "title": "KPI dashboard" }
}

{
  "pin_type": "charts",
  "pin_config": {
    "chartType": "line",
    "title": "API calls",
    "xAxis": "name",
    "yAxis": "value",
    "dataKeys": ["value"],
    "data": [
      { "name": "Mon", "value": 1200 },
      { "name": "Tue", "value": 1450 },
      { "name": "Wed", "value": 1680 }
    ]
  },
  "pin_layout": "2x2",
  "metadata": { "title": "API traffic" }
}

{
  "pin_type": "table",
  "pin_config": {
    "columns": [
      { "id": "product", "name": "Product", "type": "text" },
      { "id": "sales", "name": "Sales", "type": "number" }
    ],
    "rows": [
      { "id": "r1", "cells": { "product": "Widget A", "sales": 1250 } },
      { "id": "r2", "cells": { "product": "Widget B", "sales": 890 } }
    ]
  },
  "pin_layout": "2x2",
  "metadata": { "title": "Sales table" }
}

{
  "pin_type": "json-viewer",
  "pin_config": {
    "json": { "status": "ok", "count": 42 },
    "jsonString": "{\"status\":\"ok\",\"count\":42}",
    "title": "API response"
  },
  "metadata": { "title": "Payload viewer" }
}

{
  "pin_type": "json-list",
  "pin_config": {
    "json": [{ "id": 1, "name": "Alpha" }, { "id": 2, "name": "Beta" }],
    "jsonString": "[{\"id\":1,\"name\":\"Alpha\"}]"
  },
  "metadata": { "title": "Records list" }
}

{
  "pin_type": "csv-viewer",
  "pin_config": {
    "csvText": "name,value\nalpha,1\nbeta,2",
    "csvData": [
      { "name": "alpha", "value": 1 },
      { "name": "beta", "value": 2 }
    ],
    "fileName": "export.csv"
  },
  "metadata": { "title": "CSV export" }
}

{
  "pin_type": "embed",
  "pin_config": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "type": "youtube"
  },
  "metadata": { "title": "Demo video" }
}

{
  "pin_type": "pdf-viewer",
  "pin_config": {
    "pdf": {
      "url": "https://example.com/report.pdf",
      "fileName": "report.pdf",
      "title": "Q4 Report"
    }
  },
  "metadata": { "title": "PDF report" }
}

{
  "pin_type": "excel-viewer",
  "pin_config": {
    "excel": {
      "url": "https://example.com/data.xlsx",
      "fileName": "data.xlsx",
      "title": "Sales data"
    }
  },
  "metadata": { "title": "Spreadsheet" }
}

{
  "pin_type": "file-upload",
  "pin_config": {
    "files": [],
    "displayMode": "list"
  },
  "metadata": { "title": "Attachments" }
}

{
  "pin_type": "mermaid",
  "pin_config": {
    "code": "graph TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Done]\n  B -->|No| D[Retry]",
    "title": "Flow"
  },
  "metadata": { "title": "Architecture diagram" }
}

{
  "pin_type": "timeline",
  "pin_config": {
    "mode": "alternating",
    "items": [
      {
        "title": "2024-01-01",
        "cardTitle": "Launch",
        "cardDetailedText": "Shipped v1 to production"
      },
      {
        "title": "2024-06-01",
        "cardTitle": "Series A",
        "cardDetailedText": "Closed funding round"
      }
    ]
  },
  "metadata": { "title": "Company timeline" }
}

{
  "pin_type": "steps",
  "pin_config": {
    "steps": [
      { "title": "Install SDK", "description": "npm install @pindownai/client-js" },
      { "title": "Create API key", "description": "Workspace plan → Settings → API" },
      { "title": "Push first pin", "description": "POST /v1/pins" }
    ]
  },
  "metadata": { "title": "Getting started" }
}

{
  "pin_type": "roadmap",
  "pin_config": {
    "title": "Product roadmap",
    "months": [
      { "month": "May", "items": [{ "id": "m1", "text": "API v1" }] },
      { "month": "Jun", "items": [{ "id": "m2", "text": "Mobile app" }] }
    ]
  },
  "metadata": { "title": "Roadmap" }
}

{
  "pin_type": "calendar",
  "pin_config": {
    "weekStartsOn": 0,
    "events": [
      { "id": "e1", "title": "Sprint review", "start": "2026-05-01", "end": "2026-05-01" },
      { "id": "e2", "title": "Release", "start": "2026-05-15", "end": "2026-05-15" }
    ]
  },
  "metadata": { "title": "Team calendar" }
}

{
  "pin_type": "kanban-board",
  "pin_config": {
    "columns": [
      { "id": "todo", "title": "To do", "cards": [{ "id": "c1", "title": "Design API" }] },
      { "id": "done", "title": "Done", "cards": [] }
    ]
  },
  "metadata": { "title": "Sprint board" }
}

{
  "pin_type": "checklist",
  "pin_config": {
    "title": "Launch checklist",
    "items": [
      { "id": "c1", "name": "QA pass", "checked": false },
      { "id": "c2", "name": "Deploy prod", "checked": false }
    ]
  },
  "metadata": { "title": "Launch checklist" }
}

{
  "pin_type": "links",
  "pin_config": {
    "links": [
      { "title": "Documentation", "url": "https://pindown.ai" },
      { "title": "GitHub", "url": "https://github.com/pindownai" }
    ]
  },
  "metadata": { "title": "Useful links" }
}

{
  "pin_type": "user-story",
  "pin_config": {
    "title": "Login",
    "userStory": "As a user,\nI want to log in\nso that I can access my workspace.",
    "acceptanceCriteria": "Given valid credentials\nWhen I sign in\nThen I reach the home page"
  },
  "metadata": { "title": "US-101 Login" }
}

{
  "pin_type": "chat",
  "pin_config": {
    "title": "Team chat",
    "placeholder": "Write a message…"
  },
  "metadata": { "title": "Discussion" }
}

{
  "pin_type": "mastra",
  "pin_config": {
    "mode": "workflow",
    "workflowId": "my-workflow-id"
  },
  "metadata": { "title": "Automation runner" }
}

{
  "pin_type": "realtime-canvas",
  "pin_config": {
    "title": "Brainstorm",
    "description": "Sprint planning whiteboard",
    "roomId": "room-sprint-42"
  },
  "metadata": { "title": "Whiteboard" }
}