Links API

Retrieve a paginated list of your saved links, ordered by creation date descending. Returns UI-ready metadata for cards and drawers, but not the raw extracted text 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",
      "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.

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

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

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.