List Bookmarks

Search and retrieve bookmarks from your SaveIt.now account.

API Reference

Method: GET
Endpoint: /api/v1/bookmarks

Query Parameters

Parameter	Type	Required	Description
`query`	string	No	Search query to filter bookmarks
`tags`	string	No	Comma-separated list of tags to filter by
`types`	string	No	Comma-separated list of bookmark types to filter by
`special`	string	No	Special filter: `READ`, `UNREAD`, or `STAR`
`limit`	integer	No	Number of results per page (default: 20, max: 100)
`cursor`	string	No	Cursor for pagination (used for fetching next page)

Examples

Bash (cURL)

curl -X GET "https://saveit.now/api/v1/bookmarks?query=javascript&tags=web,development&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://saveit.now/api/v1/bookmarks?query=javascript&tags=web,development&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Results

Success Response

{
  "success": true,
  "bookmarks": [
    {
      "id": "bm_1234567890",
      "url": "https://example.com/article",
      "title": "Interesting Article",
      "summary": "An article about web development",
      "type": "ARTICLE",
      "status": "COMPLETED",
      "starred": true,
      "read": false,
      "preview": "Article preview text...",
      "faviconUrl": "https://example.com/favicon.ico",
      "ogImageUrl": "https://example.com/og-image.jpg",
      "ogDescription": "Article description from meta tags",
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {},
      "matchedTags": ["web", "development"],
      "score": 0.95,
      "matchType": "CONTENT"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6ImJtXzEyMzQ1Njc4OTAiLCJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9"
}

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

400 Bad Request - Invalid query parameters

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid limit parameter. Must be between 1 and 100"
  }
}

Search Functionality

The search query (query parameter) supports:

Full-text search: Searches in title, description, and URL
Exact phrases: Use quotes for exact matches: "web development"
Boolean operators: Use AND, OR, NOT operators
Wildcards: Use * for partial matches

Search Examples

# Search for exact phrase
curl -X GET "https://saveit.now/api/v1/bookmarks?query=\"web development\"" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search with boolean operators
curl -X GET "https://saveit.now/api/v1/bookmarks?query=javascript AND NOT react" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search with wildcards
curl -X GET "https://saveit.now/api/v1/bookmarks?query=javasc*" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination

Use cursor-based pagination with limit and cursor parameters:

# Get first 20 bookmarks
curl -X GET "https://saveit.now/api/v1/bookmarks?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get next 20 bookmarks using cursor from previous response
curl -X GET "https://saveit.now/api/v1/bookmarks?limit=20&cursor=eyJpZCI6ImJtXzEyMzQ1Njc4OTAiLCJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9" \
  -H "Authorization: Bearer YOUR_API_KEY"

Notes

Search is case-insensitive
Results are sorted by creation date (newest first) by default
Empty search queries return all bookmarks
Tag filtering is exact match (case-insensitive)
Type filtering supports: ARTICLE, VIDEO, IMAGE, AUDIO, PDF, DOCUMENT, OTHER
Special filters allow filtering by read status or starred bookmarks