Bookmarks

Overview

The Bookmarks module lets you save references to any record in the platform as typed, user-scoped bookmarks. A Bookmark stores a type (category), a record_id (the referenced record), and an optional title. Bookmarks are always owned by a user and organized by type, making them suitable for “favorites,” “watch later,” “saved items,” and similar patterns.

The module exposes a single resource: Bookmark. All operations are scoped to a user and a bookmark type. You can create, list, and remove bookmarks. There is no update operation – to change a bookmark, remove it and create a new one.

Before You Start

To use the Bookmarks module you need one of the following access methods configured:

• CLI – See: Getting Started with the CLI
• SDK – See: SDK Installation & Initialization
• REST API – See: API Authentication & Requests

All API requests require the app-id header and a valid Authorization: Bearer <token> header. See: Authentication & Authorization.

When to Use

• Saving references to platform records (forms, files, users) for quick access
• Implementing “favorites,” “watch later,” or “saved items” features per user
• Organizing bookmarks by type for category-based retrieval
• Letting users curate personal collections of platform resources
• Building admin dashboards that surface bookmarked records by user

How It Fits

    flowchart LR
  A[Auth] --> B[Bookmarks]
  B --> FM[File Manager]
  B --> F[Forms]
  B --> I[Identity]
  

Works Well With

• Auth – Associate bookmarks with authenticated users and enforce user-scoped access
• Forms – Bookmark frequently accessed forms or specific form entries for quick navigation
• File Manager – Save references to uploaded files or media assets as bookmarks
• Identity – Bookmark user profiles or account records for quick access

Quick Example

This example creates a bookmark for a form entry and retrieves it by type.

Creating a bookmark

Create a bookmark of type favorite pointing to a form entry record.

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { bookmarks } from "@oblax/bookmarks";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [bookmarks()],
});

const bookmark = await oblax.bookmarks.create("favorite", {
  record_id: "frm_ghi789jkl012",
  title: "Customer Feedback Form",
});

POST /api/v1/bookmarks/usr_abc123def456/type/favorite

{
  "record_id": "frm_ghi789jkl012",
  "title": "Customer Feedback Form"
}

{
  "id": "bkm_mno345pqr678",
  "type": "favorite",
  "record_id": "frm_ghi789jkl012",
  "user_id": "usr_abc123def456",
  "title": "Customer Feedback Form"
}

Retrieving bookmarks by type

List all bookmarks of a given type for the current user.

const bookmarks = await oblax.bookmarks.listForUser(
  "usr_abc123def456",
  "favorite",
);

GET /api/v1/bookmarks/usr_abc123def456/type/favorite

[
  {
    "id": "bkm_mno345pqr678",
    "type": "favorite",
    "record_id": "frm_ghi789jkl012",
    "user_id": "usr_abc123def456",
    "title": "Customer Feedback Form"
  }
]

Errors

Best Practices

• Use the me endpoint to retrieve the current user’s bookmarks without passing a user ID. This avoids leaking user identifiers on the client.
• Choose descriptive, stable type names (e.g., favorite, watch_later, reference). Type names are user-defined and used as path parameters.
• Use the record_id field to store the ID of the referenced record. The bookmarks service does not validate that the record exists.
• Set a human-readable title so bookmarks are meaningful in UI lists without requiring a follow-up lookup.
• Remove a bookmark and recreate it if you need to change its type or record reference. There is no update endpoint.
• Always provide the app-id header and a valid Bearer token on every request. Missing authentication returns a 401.

Related Modules

Auth, Forms, File Manager, Identity