API Documentation

URLStasher provides a simple REST API for saving and managing your links programmatically. Perfect for browser extensions, mobile apps, and automation workflows.

Authentication

All API requests require authentication using session-based auth. You must be logged in to make API requests.

Make sure to include your session cookie in requests:

fetch('/api/links', {
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  }
});

Endpoints

GET/api/links

Fetch all links for the authenticated user.

Query Parameters:

tagId - Filter by tag ID
search - Search query
favorite - Filter favorites (true/false)
archived - Filter archived (true/false)

Example Response:

{
  "links": [
    {
      "id": "clx123abc",
      "url": "https://example.com",
      "title": "Example Site",
      "summary": "A great example website",
      "thumbnailUrl": "https://alvarotrigo.com/blog/assets/imgs/2022-08-17/various-thumbnail-of-google-icon.jpeg",
      "isFavorite": false,
      "isArchived": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "linkTags": [
        {
          "tag": {
            "id": "tag123",
            "name": "tech"
          }
        }
      ]
    }
  ]
}

POST/api/links

Save a new link. Automatically extracts title, summary, and thumbnail.

Request Body:

{
  "url": "https://example.com",
  "title": "Optional custom title",
  "summary": "Optional custom summary",
  "thumbnailUrl": "Optional custom thumbnail",
  "tags": ["tech", "article"]
}

Example:

fetch('/api/links', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    tags: ['tech', 'tutorial']
  })
});

PATCH/api/links/:id

Update a link's properties.

Request Body:

{
  "isFavorite": true,
  "isArchived": false,
  "title": "Updated title",
  "tags": ["updated", "tags"]
}

DELETE/api/links/:id

Delete a link permanently.

Example:

fetch('/api/links/clx123abc', {
  method: 'DELETE',
  credentials: 'include'
});

GET/api/tags

Fetch all tags for the authenticated user.

Example Response:

{
  "tags": [
    {
      "id": "tag123",
      "name": "tech",
      "_count": {
        "linkTags": 5
      }
    }
  ]
}

Notes

All timestamps are in ISO 8601 format (UTC)
The API automatically extracts metadata from URLs when saving links
Tags are automatically created if they don't exist
Session-based authentication requires including credentials in requests