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": "video",
  "pin_config": {
    "url": "https://example.com/demo.mp4",
    "fileName": "demo.mp4",
    "mimeType": "video/mp4",
    "caption": "Product walkthrough"
  },
  "metadata": { "title": "Demo video" }
}

{
  "pin_type": "audio",
  "pin_config": {
    "url": "https://example.com/podcast.mp3",
    "fileName": "podcast.mp3",
    "mimeType": "audio/mpeg",
    "caption": "Episode 12"
  },
  "metadata": { "title": "Podcast clip" }
}

{
  "pin_type": "business-card",
  "pin_config": {
    "sectionTitle": "Contact",
    "fields": [
      { "id": "f1", "key": "Name", "value": "Jane Doe" },
      { "id": "f2", "key": "E-Mail", "value": "jane@example.com" }
    ],
    "imageConfig": { "url": "https://example.com/photo.jpg", "alt": "Jane Doe" },
    "imagePosition": "right"
  },
  "metadata": { "title": "Team contact" }
}

{
  "pin_type": "notes",
  "pin_config": {
    "notes": [
      { "id": "n1", "title": "Meeting takeaway", "content": "Ship API v1 by Friday.", "order": 0 },
      { "id": "n2", "title": "Follow-up", "content": "Schedule design review.", "order": 1 }
    ]
  },
  "metadata": { "title": "Scratchpad" }
}

{
  "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": "qr-code",
  "pin_config": {
    "url": "https://pindown.ai",
    "label": "Visit Pindown"
  },
  "metadata": { "title": "QR — Website" }
}

{
  "pin_type": "social-handles",
  "pin_config": {
    "title": "Follow us",
    "showLabels": true,
    "handles": [
      { "platform": "x", "url": "https://x.com/pindownai", "label": "@pindownai" },
      { "platform": "linkedin", "url": "https://linkedin.com/company/pindown", "label": "Pindown" }
    ]
  },
  "metadata": { "title": "Social links" }
}

{
  "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": "trace",
  "pin_config": {
    "title": "Workflow run",
    "live": false,
    "spans": [
      {
        "id": "1",
        "type": "system",
        "name": "Initialization",
        "status": "completed",
        "timestamp": "10:42:01.005",
        "duration": "12ms",
        "details": "Initialized context"
      },
      {
        "id": "2",
        "type": "tool",
        "name": "workspace_query",
        "status": "completed",
        "timestamp": "10:42:01.468",
        "duration": "1.2s",
        "details": "Searching workspace"
      }
    ]
  },
  "metadata": { "title": "Agent trace" }
}

{
  "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": "plan",
  "pin_config": {
    "title": "Implementation Plan",
    "status": "in-progress",
    "phases": [
      {
        "id": "p1",
        "title": "Phase 1: Setup",
        "status": "in-progress",
        "tasks": [
          {
            "id": "t1",
            "number": "1.1",
            "title": "Install dependencies",
            "blocks": [{ "type": "command", "command": "npm install @pindownai/client-js" }]
          }
        ]
      }
    ]
  },
  "metadata": { "title": "Rollout plan" }
}

{
  "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": "comparison",
  "pin_config": {
    "title": "Tech stack",
    "left": {
      "label": "Our stack",
      "body": "Next.js\nTypeScript\nFirebase"
    },
    "right": {
      "label": "Their stack",
      "body": "React\nJavaScript\nMongoDB"
    },
    "highlightedLines": { "left": [0], "right": [0] },
    "matches": [{ "left": 0, "right": 0 }, { "left": 1, "right": 1 }],
    "showVsBadge": true
  },
  "metadata": { "title": "Stack comparison" }
}

{
  "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": "process-flow",
  "pin_config": {
    "title": "Developer Onboarding Flow",
    "defaultView": "onboarding",
    "swimlanes": [
      { "id": "po", "title": "Product Owner" },
      { "id": "dev", "title": "Developer" }
    ],
    "nodes": [
      { "id": "1", "swimlane": "po", "label": "Ticket Refinement", "status": "smooth" },
      { "id": "2", "swimlane": "dev", "label": "Implementation", "status": "smooth" }
    ],
    "edges": [{ "source": "1", "target": "2" }]
  },
  "metadata": { "title": "Onboarding flow" }
}

{
  "pin_type": "funnel",
  "pin_config": {
    "title": "Signup funnel",
    "subtitle": "Last 30 days",
    "valueFormat": "number",
    "highlightBiggestDrop": true,
    "stages": [
      { "id": "visit", "label": "Website Visits", "value": 12400 },
      { "id": "signup", "label": "Sign Up Started", "value": 4820 },
      { "id": "paid", "label": "Upgraded to Paid", "value": 640 }
    ]
  },
  "metadata": { "title": "Conversion funnel" }
}

{
  "pin_type": "decision-matrix",
  "pin_config": {
    "title": "Backend Framework Decision",
    "maxScore": 5,
    "options": [
      { "id": "next", "label": "Next.js" },
      { "id": "remix", "label": "Remix" }
    ],
    "criteria": [
      {
        "id": "dx",
        "label": "Developer experience",
        "weight": 2,
        "scores": { "next": 5, "remix": 4 }
      },
      {
        "id": "perf",
        "label": "Performance",
        "weight": 1,
        "scores": { "next": 4, "remix": 5 }
      }
    ]
  },
  "metadata": { "title": "Framework decision" }
}

{
  "pin_type": "okr",
  "pin_config": {
    "title": "Q2 Product OKRs",
    "period": "Apr – Jun 2026",
    "objectives": [
      {
        "id": "obj-1",
        "title": "Accelerate paid conversion",
        "keyResults": [
          {
            "id": "kr-1",
            "title": "Trial-to-paid rate",
            "current": 18,
            "target": 25,
            "unit": "%",
            "confidence": 65,
            "status": "at-risk"
          }
        ]
      }
    ]
  },
  "metadata": { "title": "Q2 OKRs" }
}

{
  "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" }
}

{
  "pin_type": "poll",
  "pin_config": {
    "question": "Which feature should we ship next?",
    "status": "open",
    "showVoteCount": true,
    "options": [
      { "id": "a", "label": "Mobile app" },
      { "id": "b", "label": "API v2" }
    ]
  },
  "metadata": { "title": "Feature poll" }
}

{
  "pin_type": "survey",
  "pin_config": {
    "title": "Sprint Retro",
    "description": "Quick feedback on the last sprint.",
    "status": "open",
    "allowEditResponse": false,
    "questions": [
      { "id": "q1", "label": "What went well?", "type": "long-text", "required": true },
      {
        "id": "q2",
        "label": "Team velocity",
        "type": "scale",
        "required": true,
        "scaleMin": 1,
        "scaleMax": 5
      },
      {
        "id": "q3",
        "label": "Biggest blocker",
        "type": "single-choice",
        "options": [
          { "id": "scope", "label": "Scope creep" },
          { "id": "none", "label": "No major blockers" }
        ]
      }
    ]
  },
  "metadata": { "title": "Sprint retro" }
}

{
  "scores": {
    "demo": 4.5,
    "clarity": 5,
    "overall": 4
  },
  "display_name": "Alex",
  "rated_at": 1718208000000
}

{
  "pin_type": "rating",
  "pin_config": {
    "title": "Session feedback",
    "description": "Rate each part of today's walkthrough.",
    "status": "open",
    "maxStars": 5,
    "allowHalfStars": true,
    "allowChangeRating": true,
    "showAverage": true,
    "items": [
      { "id": "demo", "label": "Demo usefulness", "required": true },
      { "id": "clarity", "label": "Clarity of explanation", "required": true },
      { "id": "overall", "label": "Overall experience", "required": true }
    ]
  },
  "metadata": { "title": "Demo rating" }
}