Glasp API Documentation

---

Authentication

To use the Glasp API, you'll need an access token. Include it in your requests as a Bearer token. You can get your access token from here: glasp.co/settings/access_token

Authorization: Bearer your_access_token

 

Rate Limiting

The default rate limit is 50 requests per minute. If you make too many requests, you'll receive a 429 status code. Simply wait a bit and try again.

 

Available Endpoints

• Highlight Export (GET): https://api.glasp.co/v1/highlights/export
• Highlight Create (POST): coming soon...

 

Highlight Export (GET)

Retrieve your Glasp highlights with optional filtering and pagination. If you want to get all of your highlights, you can use the following code snippet.

Request: GET to https://api.glasp.co/v1/highlights/export

Query Parameters:

• updatedAfter (optional): ISO date string to get highlights updated after this date.
• pageCursor (optional): Pagination cursor from previous response.

Example Request:

• JavaScript

const token = "XXX"; // use your access token here

async function getAllHighlights(updatedAfter = null) {
  let allHighlights = [];
  let nextPageCursor = null;

  do {
    const queryParams = new URLSearchParams();
    if (nextPageCursor) {
      queryParams.append("pageCursor", nextPageCursor);
    }
    if (updatedAfter) {
      queryParams.append("updatedAfter", updatedAfter);
    }
    try {
      const response = await fetch(
        `https://api.glasp.co/v1/highlights/export?${queryParams.toString()}`,
        {
          headers: {
            Authorization: `Bearer ${token}`,
          },
        }
      );
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const data = await response.json();
      if (data.results && data.results.length > 0) {
        const highlights = data.results.map((result) => result);
        allHighlights = allHighlights.concat(highlights);
      }
      nextPageCursor = data?.nextPageCursor || null;
      if (!nextPageCursor) {
        break;
      }
    } catch (error) {
      console.error("Error fetching highlights:", error);
      break;
    }
  } while (nextPageCursor);
  return allHighlights;
}

// Get all of a user's highlights from all time
const allHighlights = await getAllHighlights();

// If you want to get new highlights updated since your last fetch, do this:
const lastFetchedAt = new Date(Date.now() - 24 * 60 * 60 * 1000);
const newHighlights = await getAllHighlights(lastFetchedAt.toISOString());

Example Response:

{
  "count": 1,
  "nextPageCursor": "2024-01-06T12:00:00Z",
  "results": [
    {
      "id": "page123",
      "title": "Example Article",
      "thumbnail_url": "https://example.com/thumbnail.jpg",
      "url": "https://example.com/article",
      "glasp_url": "https://glasp.co/user/p/page123",
      "domain": "example.com",
      "category": "article",
      "document_note": "Important article about...",
      "summary": "This article discusses...",
      "tags": ["tech", "api"],
      "is_favorite": true,
      "created_at": "2024-01-06T12:00:00Z",
      "updated_at": "2024-01-06T12:00:00Z",
      "highlights": [
        {
          "id": "highlight123",
          "text": "This is a highlighted text",
          "note": "My note about this highlight",
          "color": "yellow",
          "highlighted_at": "2024-01-06T12:00:00Z",
          "created_at": "2024-01-06T12:00:00Z",
          "updated_at": "2024-01-06T12:00:00Z",
          "url": "https://example.com/article",
          "yt_playback_position": null
        }
      ]
    }
  ]
}

Response Schema:

interface HighlightsResponse {
  count: number;
  nextPageCursor: string | null;
  results: {
    id: string;
    title: string;
    thumbnail_url: string;
    url: string;
    glasp_url: string;
    domain: string;
    category: "article" | "video" | "tweet" | "pdf" | "book"
    document_note: string | null;
    summary: string;
    tags: string[];
    is_favorite: boolean;
    created_at: string; // ISO date string
    updated_at: string; // ISO date string
    highlights: {
      id: string;
      text: string;
      note: string;
      color: "pink" | "yellow" | "blue" | "green"
      highlighted_at: string; // ISO date string
      created_at: string; // ISO date string
      updated_at: string; // ISO date string
      url: string;
      yt_playback_position: number | null; // YouTube timestamp in seconds
    }[];
  }[];
}

 

Highlight Create (POST)

Coming soon...