Links API

Retrieve a paginated list of your saved links, ordered by creation date descending. Returns UI-ready metadata for archive cards, but not the raw extracted text, markdown body, or embeddings.

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/links?limit=10"

{
  "items": [
    {
      "id": "uuid",
      "url": "https://example.com",
      "title": "Example Domain",
      "domain": "example.com",
      "tldr": "A sample description.",
      "keyInsights": ["Insight 1"],
      "tags": ["Tag1"],
      "contentType": "article",
      "videoSummary": null,
      "sourceType": "url",
      "fileKey": null,
      "status": "ready",
      "collectionId": "collection-uuid",
      "createdAt": "2024-03-26T12:00:00.000Z"
    }
  ],
  "nextCursor": "2024-03-25T14:30:00.000Z"
}

Submit a new URL to be saved and instantly queued for the AI extraction pipeline. Returns the initial processing row.

curl -X POST http://localhost:3000/api/links \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vercel.com/blog"}'

{
  "id": "new-uuid",
  "url": "https://vercel.com/blog",
  "title": null,
  "domain": "vercel.com",
  "status": "processing",
  "collectionId": null,
  "createdAt": "2024-03-26T12:05:00.000Z"
}

Upload a PDF file. The original PDF is stored, text is extracted for AI processing, and the item appears immediately in processing state. Limits are plan-based: Free uploads up to 5 MB each with 100 MB total PDF storage, Pro up to 30 MB per PDF, and Team up to 50 MB per PDF.

Retrieve a single link by its UUID. Returns the same metadata structure as the list endpoint, plus richer detail fields such as notes, markdown availability, and optional YouTube-specific videoSummary data when present.

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/links/123e4567-e89b-12d3"

{
  "id": "uuid",
  "url": "https://www.youtube.com/watch?v=abc123",
  "title": "Rendering Modes Compared",
  "domain": "youtube.com",
  "tldr": "A concise overview of the speaker's comparison between multiple React rendering strategies.",
  "contentType": "video",
  "sections": [
    {
      "type": "bullets",
      "title": "Key Takeaways",
      "items": ["The same example keeps each rendering strategy directly comparable."]
    }
  ],
  "videoSummary": {
    "worthWatching": {
      "verdict": "watch",
      "headline": "Worth it if you are evaluating modern React data-fetching architecture.",
      "rationale": "It compares several rendering models against the same flow, which makes the tradeoffs unusually clear."
    },
    "walkthrough": [
      {
        "timestamp": "0:54",
        "title": "Introduction",
        "summary": "Introduces the rendering variants and the comparison framework."
      }
    ]
  }
}

Update metadata for a specific link. Currently, only user notes are supported for updates.

curl -X PATCH "http://localhost:3000/api/links/123e4567-e89b-12d3" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Need to review this architecture later."}'

Soft-delete a link by setting its deletedAt timestamp. The link is immediately hidden from the dashboard, search, and AI features. It is moved to Trash and can be restored or permanently purged from there. For PDF-backed bookmarks on Pro and Team, the original PDF stays available until you permanently delete it from Trash.

curl -X DELETE "http://localhost:3000/api/links/123e4567-e89b-12d3" \
  -H "Authorization: Bearer <token>"

{ "success": true, "id": "123e4567-e89b-12d3" }

Retrieve the fully extracted, clean markdown representation of the article's body content. Requires authorization by session or Bearer token unless the bookmark currently has an active share link, in which case it can be fetched publicly.

curl "http://localhost:3000/api/links/123e4567-e89b-12d3/markdown" \
  -H "Authorization: Bearer <token>"

{
  "markdownContent": "# Main Title\n\nHere is the actual text of the article..."
}

Download the original uploaded PDF for PDF-backed memories.

Find mathematical nearest neighbors. Returns up to 5 other links in the user's archive that have high semantic similarity to this link.

[
  {
    "id": "uuid2",
    "url": "https://react.dev",
    "title": "React Docs",
    "tldr": "Frontend framework.",
    "score": 0.89,
    "reason": "Shares topics: Frontend"
  }
]

Re-queue a failed link for a fresh ingestion attempt. The link is reset to 'processing' status and passed through the full extraction and AI pipeline again. Useful when a YouTube transcript service was temporarily unavailable or a page was inaccessible at the time of the original ingest.

curl -X POST "http://localhost:3000/api/links/123e4567-e89b-12d3/retry" \
  -H "Authorization: Bearer <token>"

{ "success": true }

Generate or retrieve an AI concept map for a saved link. Returns immediately with a cached mindmap if one exists (unless regenerate is set). Requires a Pro or Team plan. The generated map is persisted on the link and reused across sessions.

curl -X POST "http://localhost:3000/api/links/123e4567-e89b-12d3/mindmap" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"regenerate":false}'

{
  "mindmap": {
    "source": "ai",
    "generatedAt": "2024-03-26T12:00:00.000Z",
    "root": {
      "id": "root",
      "label": "React Server Components",
      "kind": "root",
      "children": [
        { "id": "problem-space", "label": "Problem Space", "kind": "section", "children": [] }
      ]
    }
  },
  "cached": false
}

A Server-Sent Events (SSE) endpoint to monitor processing links. Emits full UI-relevant rows when items transition from 'processing' to 'ready' or 'failed', including collection assignment and content type.