Quick Start

Authentication
Rate Limiting
Error Handling

Endpoints

HyprLnk API

RESTful API for managing bookmarks, sessions, and browsing history. Built for developers who want to integrate HyprLnk with their tools and workflows.

Getting Started

The HyprLnk API is available at http://localhost:4381/api when running locally. All endpoints return JSON and follow REST conventions.

Authentication

Currently, HyprLnk API doesn't require authentication when running locally. For production deployments, consider using a reverse proxy with authentication.

Security Note

When exposing the API publicly, always use HTTPS and consider implementing API keys or OAuth for security.

Rate Limiting

The API currently doesn't implement rate limiting, but it's recommended for production deployments.

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

Code	Meaning
200	OK - Request successful
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Bookmarks

GET /bookmarks

Retrieve all bookmarks with optional filtering and pagination.

Query Parameters

limit - Number of results (default: 50, max: 100)
offset - Pagination offset (default: 0)
tag - Filter by tag
search - Search in title, description, and URL
sort - Sort by: created_desc, created_asc, title_asc, title_desc

Example Request

curl -X GET "http://localhost:4381/api/bookmarks?limit=10&tag=development"

Example Response

POST /bookmarks

Create a new bookmark.

Request Body

Example Response

GET /bookmarks/search

Search bookmarks with query parameters.

Query Parameters

q - Search query string
limit - Number of results (default: 50)

Example Request

curl -X GET "http://localhost:4381/api/bookmarks/search?q=javascript&limit=10"

PUT /bookmarks/:id

Update an existing bookmark.

DELETE /bookmarks/:id

Delete a bookmark.

Example Request

curl -X DELETE "http://localhost:4381/api/bookmarks/123"

Sessions

GET /sessions

Retrieve all browser sessions.

Example Response

POST /sessions

Create a new browser session.

Request Body

History

GET /history

Retrieve browsing history.

Query Parameters

limit - Number of results (default: 50)
date - Filter by date (YYYY-MM-DD)
search - Search in title and URL

GET /history/today

Retrieve today's browsing history.

GET /history/week

Retrieve this week's browsing history.

GET /history/month

Retrieve this month's browsing history.

GET /history/count

Get count of history entries.

POST /history/sync

Sync browsing history data.

Link Clicks

GET /link-clicks

Retrieve all link click tracking data.

POST /link-clicks/sync

Sync link click data from browser extension.

Import

POST /import/browser

Import bookmarks and data from browser export files.

POST /segment

Bulk segment and categorize bookmarks using AI.

System

GET /health

Health check endpoint for monitoring.

Example Response

GET /ping

Ping endpoint with timestamp for connectivity testing.

Example Response

SDKs & Examples

JavaScript

// Create a bookmark
const response = await fetch('/api/bookmarks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    title: 'Example Site',
    tags: ['web', 'example']
  })
});

const bookmark = await response.json();

Python

import requests

# Create a bookmark
response = requests.post(
    'http://localhost:4381/api/bookmarks',
    json={
        'url': 'https://example.com',
        'title': 'Example Site',
        'tags': ['web', 'example']
    }
)

bookmark = response.json()