SaveIt.now
Sign In
All Docs
APITags

List Tags

Retrieve tags from your SaveIt.now account using the API

4 min read
apitagslist

List Tags

Retrieve all tags from your SaveIt.now account with pagination support.

API Reference

Method: GET
Endpoint: /api/v1/tags

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoNumber of results per page (default: 20, max: 100)
cursorstringNoCursor for pagination (used for fetching next page)

Examples

Bash (cURL)

curl -X GET "https://saveit.now/api/v1/tags?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://saveit.now/api/v1/tags?limit=50', {
  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,
  "tags": [
    {
      "id": "cljk1234567890abcdef",
      "name": "javascript",
      "type": "IA",
      "bookmarkCount": 25
    },
    {
      "id": "cljk0987654321fedcba",
      "name": "programming",
      "type": "IA",
      "bookmarkCount": 45
    },
    {
      "id": "cljk5555555555555555",
      "name": "tutorial",
      "type": "USER",
      "bookmarkCount": 12
    }
  ],
  "hasMore": true,
  "nextCursor": "cljk5555555555555555"
}

Response Fields

FieldTypeDescription
successbooleanIndicates if the request was successful
tagsarrayArray of tag objects
tags[].idstringUnique identifier for the tag
tags[].namestringDisplay name of the tag
tags[].typestringTag type: USER (manually created) or IA (AI-generated)
tags[].bookmarkCountintegerNumber of bookmarks associated with this tag
hasMorebooleanIndicates if there are more results available
nextCursorstringCursor for fetching the next page (null if no more results)

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

Pagination

Use cursor-based pagination with limit and cursor parameters:

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

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

Pagination Example

let allTags = [];
let cursor = null;
let hasMore = true;

while (hasMore) {
  const url = cursor 
    ? `https://saveit.now/api/v1/tags?limit=50&cursor=${cursor}`
    : 'https://saveit.now/api/v1/tags?limit=50';
    
  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  });
  
  const data = await response.json();
  
  allTags.push(...data.tags);
  cursor = data.nextCursor;
  hasMore = data.hasMore;
}

console.log(`Retrieved ${allTags.length} tags total`);

Tag Types

SaveIt.now uses two types of tags:

  • IA (AI-generated): Tags automatically created by AI when processing bookmarks
  • USER: Tags manually created by users

Both types are returned in the API response and can be identified by the type field.

Use Cases

# Get tags sorted by bookmark count (most used first)
curl -X GET "https://saveit.now/api/v1/tags?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Build a Tag Cloud

const response = await fetch('https://saveit.now/api/v1/tags?limit=100', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

// Create a tag cloud based on bookmark count
const tagCloud = data.tags.map(tag => ({
  text: tag.name,
  value: tag.bookmarkCount,
  id: tag.id
}));

Notes

  • Tags are sorted by ID in ascending order for consistent pagination
  • Empty tag lists are valid responses (returns empty array)
  • The bookmarkCount field shows the total number of bookmarks associated with each tag
  • AI-generated tags (type: "IA") are created automatically during bookmark processing
  • User tags (type: "USER") are created manually by users

Next Steps