GoodLinks API

https://goodlinks.app/api/
Admin
The GoodLinks API provides access to your local GoodLinks library, enabling the creation of...
Tokens:13,271
Snippets:93
Trust Score:8.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example API Response

Source: https://goodlinks.app/api

This is an example of a successful response when adding or updating a link. It includes all metadata fields.

```json
{
  "id": "abc123",
  "url": "https://example.com/article",
  "title": "Example Article Title",
  "summary": "This is a brief summary of the article.",
  "author": "John Doe",
  "tags": ["technology", "programming"],
  "starred": false,
  "highlighted": false,
  "addedAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T10:30:00Z",
  "readAt": "2025-01-16T14:20:00Z"
}

```

--------------------------------

### Example Request Body for Creating a Link

Source: https://goodlinks.app/api

When creating or updating resources via POST or PATCH requests, use UTF-8 encoded JSON. This example shows the structure for adding a new link.

```json
{
  "url": "https://example.com/article",
  "title": "Example Article"
}
```

--------------------------------

### Example Error Response Format

Source: https://goodlinks.app/api

Error responses provide a human-readable `error` message and optional `details` for diagnosing issues. This example shows a common validation error.

```json
{
  "error": "Invalid request",
  "details": {
    "field": "url",
    "message": "URL is required"
  }
}
```

--------------------------------

### Add or Update Link (Minimal Example)

Source: https://goodlinks.app/api

Use this snippet for the minimum required information to add a link. Only the URL is mandatory.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}' \
  http://localhost:9428/api/v1/links

```

--------------------------------

### Updated Highlight Response

Source: https://goodlinks.app/api

This is an example of the response returned after successfully updating a highlight. It includes all metadata fields of the highlight.

```json
{
  "id": "highlight123",
  "linkID": "abc123",
  "content": "This is an important quote from the article.",
  "markdownContent": "This is an **important** quote from the article.",
  "note": "This is an important insight about the highlighted text.",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

--------------------------------

### Get All Visible Lists

Source: https://goodlinks.app/api

Retrieves all lists that are visible in the user's library. This is a simple GET request to the /api/v1/lists endpoint.

```bash
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/lists
```

```json
[
  {
    "id": "all",
    "name": "All"
  },
  {
    "id": "starred",
    "name": "Starred"
  }
]
```

--------------------------------

### Add or Update Link (Full Example)

Source: https://goodlinks.app/api

Use this snippet to add a new link with all available metadata. If a link with the same URL exists, it will be updated.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "title": "Example Article",
    "summary": "This is an example article about something interesting.",
    "tags": ["technology", "programming"],
    "starred": false,
    "read": false
  }' \
  http://localhost:9428/api/v1/links

```

--------------------------------

### Link Object Structure

Source: https://goodlinks.app/api

This is an example of a link object returned by the API, detailing all available metadata fields.

```json
{
  "id": "abc123",
  "url": "https://example.com/article",
  "title": "Example Article Title",
  "summary": "This is a brief summary of the article.",
  "author": "John Doe",
  "tags": ["technology", "programming"],
  "wordCount": 1250,
  "starred": false,
  "highlighted": false,
  "addedAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T10:30:00Z",
  "readAt": "2025-01-16T14:20:00Z"
}
```

--------------------------------

### Get All Links with Pagination

Source: https://goodlinks.app/api

Fetches all links in the library with specified limit and offset for pagination. An API token must be provided in the header.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/lists/all?limit=20&offset=20"
```

--------------------------------

### Search Highlights by Text

Source: https://goodlinks.app/api

Searches for highlights using a query string. This example demonstrates a simple text search for 'important' with a limit of 20 results.

```bash
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/highlights?q=important&limit=20"
```

--------------------------------

### Delete a Single Link

Source: https://goodlinks.app/api

This example demonstrates how to delete a single link by its ID. The ID is passed as a query parameter.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X DELETE \
  "http://localhost:9428/api/v1/links?id=abc123"

```

--------------------------------

### Get Lists

Source: https://goodlinks.app/api

Retrieve all visible lists in your library. Each list object contains its unique identifier and name.

```APIDOC
## Get Lists

### Description
Retrieve all visible lists in your library.

### Method
GET

### Endpoint
/api/v1/lists

### Response
#### Success Response
Returns an array of list objects. Each object contains:
- **`id`** (string) — Unique identifier for the list.
- **`name`** (string) — The name of the list.

### Response Example
```json
[
  {
    "id": "all",
    "name": "All"
  },
  {
    "id": "starred",
    "name": "Starred"
  }
]
```
```

--------------------------------

### Get All Tags

Source: https://goodlinks.app/api

Retrieves all tags present in the user's library. Only tags associated with at least one link are returned. The response is an array of tag strings.

```bash
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/tags
```

```json
["design", "technology", "technology/programming"]
```

--------------------------------

### Get Article Content

Source: https://goodlinks.app/api

Retrieve the article content of a link in HTML, plaintext, or markdown format. Supports controlling the download behavior.

```APIDOC
## GET /api/v1/links/{id}/content

### Description
Retrieve the article content of a link in HTML, plaintext, or markdown format.

### Method
GET

### Endpoint
/api/v1/links/{id}/content

### Parameters
#### Path Parameters
- **`id`** (string) - Required - The unique identifier of the link.

#### Query Parameters
- **`format`** (string, optional) - The format of the content to return. Valid values: `html` (default), `plaintext`, `markdown`.
- **`autoDownload`** (boolean, optional) - Defaults to `true`. Set to `false` to skip downloading and only return already cached article content.

### Response
#### Success Response
Returns the article content in the requested format. The response content type depends on the format: `text/html` for `html`, `text/plain` for `plaintext`, `text/markdown` for `markdown`.

#### Response Example
(Content type will vary based on the `format` query parameter)
{
  "example": "<html>...</html>" 
}

### Errors
- `404 Not Found` — Link with the specified ID does not exist or the link has no content available.
```

--------------------------------

### Example API Response for Link Search

Source: https://goodlinks.app/api

Illustrates the structure of a successful response from the link search endpoint, including the array of matching link objects and a flag indicating if more results are available.

```json
{
  "data": [
    {
      "id": "abc123",
      "url": "https://example.com/article",
      "title": "Example Article Title",
      "summary": "This is a brief summary of the article.",
      "author": "John Doe",
      "tags": ["technology", "programming"],
      "wordCount": 1250,
      "starred": false,
      "highlighted": false,
      "addedAt": "2025-01-15T10:30:00Z",
      "modifiedAt": "2025-01-15T10:30:00Z",
      "readAt": null
    },
    {
      "id": "def456",
      "url": "https://example.com/another",
      "title": "Another Article",
      "summary": "Another summary.",
      "author": "Jane Smith",
      "tags": ["technology"],
      "wordCount": 800,
      "starred": true,
      "highlighted": true,
      "addedAt": "2025-01-14T08:15:00Z",
      "modifiedAt": "2025-01-14T08:15:00Z",
      "readAt": "2025-01-15T12:00:00Z"
    }
  ],
  "hasMore": true
}
```

--------------------------------

### Get Article Content (HTML Format)

Source: https://goodlinks.app/api

Retrieve article content in HTML format. Ensure you have a valid API token and the correct link ID.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links/abc123/content?format=html"
```

--------------------------------

### Example Success Response Format

Source: https://goodlinks.app/api

Successful API responses return JSON data. Some endpoints include pagination metadata like `hasMore` to indicate if additional items are available.

```json
{
  "data": [...],
  "hasMore": true
}
```

--------------------------------

### Get Tags

Source: https://goodlinks.app/api

Retrieve all tags in your library. Only tags that have at least one link are returned. For hierarchical tags, the full path is included.

```APIDOC
## Get Tags

### Description
Retrieve all tags in your library. Only tags that have at least one link are returned.

### Method
GET

### Endpoint
/api/v1/tags

### Response
#### Success Response
Returns an array of tags (strings). For hierarchical tags, this includes the full path (e.g., `technology/programming`).

### Response Example
```json
["design", "technology", "technology/programming"]
```
```

--------------------------------

### Get Link by URL Request

Source: https://goodlinks.app/api

This cURL command demonstrates how to retrieve a link using its URL. The URL must be URL-encoded. Replace 'your-api-token' with your actual API token.

```bash
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links?url=https%3A%2F%2Fexample.com%2Farticle"
```

--------------------------------

### Add Tags to a Link

Source: https://goodlinks.app/api

Use this example to add new tags to a link's existing tag list. Provide the link ID in the URL and the tags in the request body.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ \
    "addedTags": ["technology", "programming"] \
  }' \
  http://localhost:9428/api/v1/links/abc123

```

--------------------------------

### Get Article Content (Markdown Format)

Source: https://goodlinks.app/api

Retrieve article content in Markdown format. Ensure your request includes a valid authorization token and the correct link identifier.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links/abc123/content?format=markdown"
```

--------------------------------

### Get Article Content (Plaintext Format)

Source: https://goodlinks.app/api

Retrieve article content in plaintext format. This endpoint requires a valid API token and the specific link ID.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links/abc123/content?format=plaintext"
```

--------------------------------

### Get a Link by ID

Source: https://goodlinks.app/api

Retrieve a single link by its unique identifier. This endpoint returns all metadata associated with the specified link.

```APIDOC
## GET /api/v1/links/{id}

### Description
Retrieve a single link by its ID.

### Method
GET

### Endpoint
/api/v1/links/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the link to retrieve.

### Response
#### Success Response (200)
Returns a single link object with all metadata fields.

#### Errors
- 404 Not Found — Link with the specified ID does not exist.

### Request Example
```curl
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/links/abc123
```

### Response Example
```json
{
  "id": "abc123",
  "url": "https://example.com/article",
  "title": "Example Article Title",
  "summary": "This is a brief summary of the article.",
  "author": "John Doe",
  "tags": ["technology", "programming"],
  "wordCount": 1250,
  "starred": false,
  "highlighted": false,
  "addedAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T10:30:00Z",
  "readAt": "2025-01-16T14:20:00Z"
}
```
```

--------------------------------

### Get a Link by URL

Source: https://goodlinks.app/api

Retrieve a single link using its full URL. This is useful when the link ID is unknown but the URL is available. The URL must be URL-encoded.

```APIDOC
## GET /api/v1/links

### Description
Retrieve a single link by its URL. This is useful when you have the URL but not the link ID.

### Method
GET

### Endpoint
/api/v1/links

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the link to retrieve. Must be URL-encoded.

### Response
#### Success Response (200)
Returns a single link object with all metadata fields, identical to the “Get a Link by ID” endpoint.

#### Errors
- 404 Not Found — Link with the specified URL does not exist.

### Request Example
```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links?url=https%3A%2F%2Fexample.com%2Farticle"
```
```

--------------------------------

### Get Links in List

Source: https://goodlinks.app/api

Retrieve links from a specific main list with optional filtering and pagination. Links are sorted by date added (newest first) by default.

```APIDOC
## GET /api/v1/lists/{list}

### Description
Retrieve links from a specific main list with optional filtering and pagination. Links are sorted by date added (newest first) by default.

### Method
GET

### Endpoint
/api/v1/lists/{list}

### Parameters
#### Path Parameters
- **list** (string, required) — The main list to retrieve links from. Valid values:
  * `unread` — Links that haven’t been read.
  * `read` — Links that have been read.
  * `starred` — Links that have been starred.
  * `untagged` — Links that have no tags.
  * `highlighted` — Links that have highlights.
  * `all` — All links in the library.

#### Query Parameters
- **search** (string, optional) — Search text to filter links by title, summary, content, URL, and author.
- **tag** (string, optional) — Tag to filter by. This parameter can be specified multiple times. Only links with at least one of the specified tags will be returned. This parameter is ignored when`list=untagged`.
- **includeRead** (boolean, optional) — Whether to include read links in the results. Only relevant for`starred` , `untagged` and `highlighted` lists. Defaults to `false`.
- **limit** (integer, optional) — Maximum number of links to return per page. Must be between 1 and 1000. Defaults to`20` if not specified.
- **offset** (integer, optional) — Number of items to skip before returning results. Defaults to`0`.

### Response
Response format is identical to “Search Links”.

### Errors
- `404 Not Found` — Invalid list type specified in the path.
```

--------------------------------

### Get Article Content (Disable Auto-Download)

Source: https://goodlinks.app/api

Retrieve article content in HTML format while disabling the automatic download feature. This is useful for fetching only cached content.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links/abc123/content?format=html&autoDownload=false"
```

--------------------------------

### Get Unread Links

Source: https://goodlinks.app/api

Retrieves a paginated list of unread links. Ensure your API token is included in the Authorization header.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/lists/unread?limit=20"
```

--------------------------------

### Get Link by ID Request

Source: https://goodlinks.app/api

Use this cURL command to retrieve a single link by its unique identifier. Ensure you replace 'your-api-token' with your actual API token.

```bash
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/links/abc123
```

--------------------------------

### Get Current Link

Source: https://goodlinks.app/api

Retrieve the link that is currently selected within the Goodlinks application. This endpoint provides quick access to the active link.

```APIDOC
## GET /api/v1/links/current

### Description
Retrieve the link currently selected in GoodLinks.

### Method
GET

### Endpoint
/api/v1/links/current

### Response
#### Success Response (200)
Returns a single link object with all metadata fields, identical to the “Get a Link by ID” endpoint.

#### Errors
- 404 Not Found — No link is currently selected in GoodLinks.

### Request Example
```curl
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/links/current
```
```

--------------------------------

### Get Starred Links with Search and Read Inclusion

Source: https://goodlinks.app/api

Fetches starred links, filtering by a search query and including read items. Requires an API token for authentication.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/lists/starred?search=programming&includeRead=true&limit=10"
```

--------------------------------

### Get Current Link Request

Source: https://goodlinks.app/api

Use this cURL command to fetch the link that is currently selected within the GoodLinks application. Replace 'your-api-token' with your actual API token.

```bash
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/links/current
```

--------------------------------

### Get Tagged Links in Unread List

Source: https://goodlinks.app/api

Retrieves unread links filtered by multiple tags. The 'limit' parameter controls the number of results per page. API token is required.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/lists/unread?tag=technology&tag=programming&limit=50"
```

--------------------------------

### Highlights API

Source: https://goodlinks.app/api

Endpoints for managing highlights.

```APIDOC
## GET /api/v1/highlights

### Description
Retrieves a list of highlights. Supports filtering by tag and pagination.

### Method
GET

### Endpoint
/api/v1/highlights

### Parameters
#### Query Parameters
- **tag** (string) - Optional - Filter highlights by a specific tag.
- **limit** (integer) - Optional - Maximum number of highlights to return.
- **offset** (integer) - Optional - Number of highlights to skip for pagination.

### Response
#### Success Response (200)
- **data** (array) - An array of highlight objects.
  - **id** (string) - The unique identifier of the highlight.
  - **text** (string) - The content of the highlight.
  - **linkId** (string) - The ID of the link associated with the highlight.
  - **addedDate** (string) - The date the highlight was added (ISO-8601 format).
  - **tags** (array) - An array of tags associated with the highlight.
- **hasMore** (boolean) - Indicates if there are more highlights available.

### Response Example
{
  "data": [
    {
      "id": "unique-highlight-id",
      "text": "This is an important quote.",
      "linkId": "unique-link-id",
      "addedDate": "2023-10-27T11:00:00Z",
      "tags": ["important", "quote"]
    }
  ],
  "hasMore": true
}
```

```APIDOC
## POST /api/v1/highlights

### Description
Creates a new highlight.

### Method
POST

### Endpoint
/api/v1/highlights

### Parameters
#### Request Body
- **text** (string) - Required - The content of the highlight.
- **linkId** (string) - Required - The ID of the link this highlight belongs to.
- **tags** (array) - Optional - An array of tags to associate with the highlight.

### Request Example
{
  "text": "A new insight from the article.",
  "linkId": "unique-link-id",
  "tags": ["insight", "api"]
}

### Response
#### Success Response (200)
- **data** (object) - The newly created highlight object.

### Response Example
{
  "data": {
    "id": "new-highlight-id",
    "text": "A new insight from the article.",
    "linkId": "unique-link-id",
    "addedDate": "2023-10-27T11:05:00Z",
    "tags": ["insight", "api"]
  }
}
```

```APIDOC
## DELETE /api/v1/highlights/{id}

### Description
Deletes a highlight by its ID.

### Method
DELETE

### Endpoint
/api/v1/highlights/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the highlight to delete.

### Response
#### Success Response (200)
- **data** (object) - An empty object or a confirmation message upon successful deletion.

### Response Example
{
  "data": {}
}
```

--------------------------------

### Authenticate API Request with Python requests

Source: https://goodlinks.app/api

Set up a headers dictionary with your API token to authenticate requests made with the Python requests library.

```python
import requests

headers = {
    "Authorization": "Bearer your-api-token",
}

requests.get("http://localhost:9428/api/v1/links", headers=headers)

```

--------------------------------

### Export Highlights from Link

Source: https://goodlinks.app/api

Use this endpoint to export highlights associated with a specific link. The export format is determined by the user's GoodLinks settings and uses Mustache templating.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links/abc123/highlights/export"
```

--------------------------------

### Update Link Title and Summary

Source: https://goodlinks.app/api

Use this snippet to update the title and summary of an existing link. Ensure you provide the correct link ID in the URL.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ \
    "title": "Updated Article Title", \
    "summary": "Updated summary of the article." \
  }' \
  http://localhost:9428/api/v1/links/abc123

```

--------------------------------

### Search Highlights by Link ID and Sort Order

Source: https://goodlinks.app/api

Filters highlights by a specific link ID and sorts the results by newest first. This is useful for retrieving all highlights associated with a particular saved link.

```bash
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/highlights?linkID=abc123&sort=newest"
```

--------------------------------

### Authenticate API Request with curl

Source: https://goodlinks.app/api

Use this command to include your API token in the Authorization header for requests made via curl.

```bash
curl -H "Authorization: Bearer your-api-token" \
  http://localhost:9428/api/v1/links

```

--------------------------------

### Search Highlights within a Date Range

Source: https://goodlinks.app/api

Retrieves highlights created within a specified date range, sorted from oldest to newest. This allows for time-based analysis of highlighted content.

```bash
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/highlights?createdAfter=2025-01-01T00:00:00Z&createdBefore=2025-01-31T23:59:59Z&sort=oldest"
```

--------------------------------

### Export Highlights

Source: https://goodlinks.app/api

Exports highlights from a link using the export format template configured in GoodLinks settings.

```APIDOC
## GET /api/v1/links/{id}/highlights/export

### Description
Exports highlights from a link using the export format template configured in GoodLinks settings.

### Method
GET

### Endpoint
/api/v1/links/{id}/highlights/export

### Parameters
#### Path Parameters
- **`id`** (string) - Required - The unique identifier of the link.

### Response
#### Success Response (200)
- **Content-Type**: text/markdown
- The response content is the highlights export content as Markdown, following your configured export template.

#### Response Example
(Response content will be in Markdown format)
```

--------------------------------

### Mark Link as Read and Starred

Source: https://goodlinks.app/api

This snippet demonstrates how to mark a link as both read and starred. The link ID must be specified in the request URL.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ \
    "read": true, \
    "starred": true \
  }' \
  http://localhost:9428/api/v1/links/abc123

```

--------------------------------

### Search Highlights

Source: https://goodlinks.app/api

Search for highlights across your library. This endpoint supports filtering by content, notes, link ID, and date ranges, with options for sorting and pagination.

```APIDOC
## Search Highlights

### Description
Search for highlights across your library. This endpoint searches through highlight content and notes, and supports filtering and sorting options.

### Method
GET

### Endpoint
/api/v1/highlights

### Query Parameters
- **`q`** (string, optional) — Search query text. Searches through highlight content and notes.
- **`linkID`** (string, optional) — Filter highlights by link ID. Only highlights belonging to the specified link will be returned.
- **`content`** (string, optional) — Filter highlights by content containing this text.
- **`note`** (string, optional) — Filter highlights by note containing this text.
- **`createdAfter`** (string, optional) — ISO-8601 timestamp. Only return highlights created after this date.
- **`createdBefore`** (string, optional) — ISO-8601 timestamp. Only return highlights created before this date.
- **`sort`** (string, optional) — Sort order for results. Valid values:
  * `newest` — Newest highlights first (default)
  * `oldest` — Oldest highlights first
  * `linkID` — Sort by link ID
  * `content` — Sort by content alphabetically
  * `note` — Sort by note alphabetically
- **`limit`** (integer, optional) — Maximum number of highlights to return per page. Must be between 1 and 1000. Defaults to`20` if not specified.
- **`offset`** (integer, optional) — Number of items to skip before returning results. Defaults to`0`.

### Response
#### Success Response
Returns an object containing:
  * **`data`** (array) — Array of highlight objects matching the search criteria.
  * **`hasMore`** (boolean) — Whether there are more highlights available beyond the current page.

### Response Example
```json
{
  "data": [
    {
      "id": "highlight123",
      "linkID": "abc123",
      "content": "This is an important quote from the article.",
      "markdownContent": "This is an **important** quote from the article.",
      "note": "Key insight",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "highlight456",
      "linkID": "abc123",
      "content": "Another highlighted section with programming concepts.",
      "markdownContent": "Another highlighted section with `programming` concepts.",
      "note": null,
      "createdAt": "2025-01-14T08:15:00Z"
    }
  ],
  "hasMore": true
}
```
```

--------------------------------

### Edit a Highlight

Source: https://goodlinks.app/api

Updates an existing highlight's metadata. Only the fields provided in the request will be updated; all other fields will remain unchanged.

```APIDOC
## PATCH /api/v1/highlights/{id}

### Description
Updates an existing highlight's metadata. Only the fields provided in the request will be updated; all other fields will remain unchanged.

### Method
PATCH

### Endpoint
/api/v1/highlights/{id}

### Parameters
#### Path Parameters
- **`id`** (string) - Required - The ID of the highlight to update.

#### Request Body
- **`note`** (string) - Optional - The note for the highlight.

### Request Example
```json
{
  "note": "This is an important insight about the highlighted text."
}
```

### Response
#### Success Response (200)
- **`id`** (string) - Description
- **`linkID`** (string) - Description
- **`content`** (string) - Description
- **`markdownContent`** (string) - Description
- **`note`** (string) - Description
- **`createdAt`** (string) - Description

#### Response Example
```json
{
  "id": "highlight123",
  "linkID": "abc123",
  "content": "This is an important quote from the article.",
  "markdownContent": "This is an **important** quote from the article.",
  "note": "This is an important insight about the highlighted text.",
  "createdAt": "2025-01-15T10:30:00Z"
}
```
```

--------------------------------

### Add or Update a Link

Source: https://goodlinks.app/api

Adds a new link to the user's library or updates an existing one if a link with the same URL is found. The API attempts to fetch metadata automatically if not provided.

```APIDOC
## POST /api/v1/links

### Description
Add a new link to your library, or update an existing link if one with the same URL already exists. The link will be created or updated with the provided metadata, or GoodLinks will attempt to fetch metadata automatically if not provided.

### Method
POST

### Endpoint
/api/v1/links

### Parameters
#### Request Body
- **url** (string, required) — The URL of the link to add. Must be a valid HTTP or HTTPS URL. Maximum length is 2000 characters.
- **title** (string, optional) — The title for the link. Maximum length is 200 characters. Newlines will be replaced with spaces and the text will be trimmed.
- **summary** (string, optional) — A summary or description for the link. Maximum length is 400 characters. Newlines will be replaced with spaces and the text will be trimmed.
- **tags** (array of strings, optional) — Tags to associate with the link. Each tag must be a non-empty string with a maximum length of 100 characters.
- **read** (boolean, optional) — Whether to mark the link as read immediately. Defaults to `false`. If `true`, the link’s `readAt` timestamp will be set to the current time.
- **starred** (boolean, optional) — Whether to add the link to the starred list. Defaults to`false`.
- **addedAt** (string, optional) — ISO-8601 timestamp indicating when the link was saved. Only used when creating a new link. If not provided, defaults to the current time. If provided, must not be in the future (will be clamped to current time). When updating an existing link, this field is ignored.

### Response
#### Success Response (200)
Returns the created or updated link object with all metadata fields, including the `id`. If a link with the same URL already exists, it will be updated with the provided fields. Fields not provided in the request will preserve their existing values (except for `addedAt`, which is only set when creating a new link).

#### Response Example
{
  "id": "abc123",
  "url": "https://example.com/article",
  "title": "Example Article Title",
  "summary": "This is a brief summary of the article.",
  "author": "John Doe",
  "tags": ["technology", "programming"],
  "starred": false,
  "highlighted": false,
  "addedAt": "2025-01-15T10:30:00Z",
  "modifiedAt": "2025-01-15T10:30:00Z",
  "readAt": "2025-01-16T14:20:00Z"
}
```

--------------------------------

### Update Highlight Note

Source: https://goodlinks.app/api

Use this endpoint to update the note associated with an existing highlight. Provide the highlight's ID in the path and the new note in the request body. The note can be cleared by sending an empty string.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "note": "This is an important insight about the highlighted text."
  }' \
  http://localhost:9428/api/v1/highlights/highlight123
```

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
    "note": ""
  }' \
  http://localhost:9428/api/v1/highlights/highlight123
```

--------------------------------

### Add or Update Link (With Custom Date)

Source: https://goodlinks.app/api

Use this snippet to specify a custom 'addedAt' timestamp when creating a new link. This field is ignored when updating an existing link.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "title": "Example Article",
    "addedAt": "2025-01-15T10:30:00Z"
  }' \
  http://localhost:9428/api/v1/links

```

--------------------------------

### Highlight Object Structure

Source: https://goodlinks.app/api

Defines the structure of a highlight object returned by the API. It includes fields like ID, link ID, content (plain and markdown), an optional note, and creation timestamp.

```json
{
  "id": "highlight123",
  "linkID": "abc123",
  "content": "This is an important quote from the article.",
  "markdownContent": "This is an **important** quote from the article.",
  "note": "Key insight",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

--------------------------------

### Simple Text Search for Links

Source: https://goodlinks.app/api

Perform a basic search for links containing specific text in their title, summary, content, URL, or author. Specify the maximum number of results to return.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links?search=python&limit=20"
```

--------------------------------

### Search Links within a Date Range

Source: https://goodlinks.app/api

Retrieve links added within a specific date range using ISO-8601 timestamps. This helps in finding recently added or older content.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links?addedAfter=2025-01-01T00:00:00Z&addedBefore=2025-01-31T23:59:59Z&sort=oldestSaved"
```

--------------------------------

### Authenticate API Request with JavaScript fetch

Source: https://goodlinks.app/api

Include your API token in the Authorization header when making requests using the fetch API in JavaScript.

```javascript
fetch("http://localhost:9428/api/v1/links", {
  headers: {
    Authorization: "Bearer your-api-token",
  },
});

```

--------------------------------

### Search Highlights Response Structure

Source: https://goodlinks.app/api

The response structure for highlight searches includes an array of highlight objects ('data') and a boolean indicating if more results are available ('hasMore').

```json
{
  "data": [
    {
      "id": "highlight123",
      "linkID": "abc123",
      "content": "This is an important quote from the article.",
      "markdownContent": "This is an **important** quote from the article.",
      "note": "Key insight",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "highlight456",
      "linkID": "abc123",
      "content": "Another highlighted section with programming concepts.",
      "markdownContent": "Another highlighted section with `programming` concepts.",
      "note": null,
      "createdAt": "2025-01-14T08:15:00Z"
    }
  ],
  "hasMore": true
}
```

--------------------------------

### Advanced Highlight Search

Source: https://goodlinks.app/api

Performs an advanced search for highlights, combining multiple criteria including text query, link ID, note content, sort order, and result limit. This provides granular control over search results.

```bash
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/highlights?q=programming&linkID=abc123&note=insight&sort=newest&limit=10"
```

--------------------------------

### GoodLinks API Base URL

Source: https://goodlinks.app/api

This is the base URL for all API endpoints. Ensure you combine this with the specific endpoint path.

```text
http://localhost:9428/api/v1
```

--------------------------------

### Links API

Source: https://goodlinks.app/api

Endpoints for managing links, including listing, creating, updating, and deleting them.

```APIDOC
## GET /api/v1/links

### Description
Retrieves a list of links. Supports filtering and pagination.

### Method
GET

### Endpoint
/api/v1/links

### Parameters
#### Query Parameters
- **tag** (string) - Optional - Filter links by a specific tag.
- **query** (string) - Optional - Search links by keywords in title or URL.
- **limit** (integer) - Optional - Maximum number of links to return.
- **offset** (integer) - Optional - Number of links to skip for pagination.

### Response
#### Success Response (200)
- **data** (array) - An array of link objects.
  - **url** (string) - The URL of the link.
  - **title** (string) - The title of the link.
  - **addedDate** (string) - The date the link was added (ISO-8601 format).
  - **tags** (array) - An array of tags associated with the link.
- **hasMore** (boolean) - Indicates if there are more links available.

### Response Example
{
  "data": [
    {
      "url": "https://example.com",
      "title": "Example Domain",
      "addedDate": "2023-10-27T10:00:00Z",
      "tags": ["example", "test"]
    }
  ],
  "hasMore": true
}
```

```APIDOC
## POST /api/v1/links

### Description
Creates a new link.

### Method
POST

### Endpoint
/api/v1/links

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the link to add.
- **title** (string) - Optional - The title for the link.
- **tags** (array) - Optional - An array of tags to associate with the link.

### Request Example
{
  "url": "https://new-example.com",
  "title": "New Example",
  "tags": ["new", "api"]
}

### Response
#### Success Response (200)
- **data** (object) - The newly created link object, including its ID and other properties.

### Response Example
{
  "data": {
    "id": "unique-link-id",
    "url": "https://new-example.com",
    "title": "New Example",
    "addedDate": "2023-10-27T10:05:00Z",
    "tags": ["new", "api"]
  }
}
```

```APIDOC
## GET /api/v1/links/{id}

### Description
Retrieves a specific link by its ID.

### Method
GET

### Endpoint
/api/v1/links/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the link.

### Response
#### Success Response (200)
- **data** (object) - The link object with the specified ID.

### Response Example
{
  "data": {
    "id": "unique-link-id",
    "url": "https://example.com",
    "title": "Example Domain",
    "addedDate": "2023-10-27T10:00:00Z",
    "tags": ["example", "test"]
  }
}
```

```APIDOC
## PATCH /api/v1/links/{id}

### Description
Updates an existing link identified by its ID.

### Method
PATCH

### Endpoint
/api/v1/links/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the link to update.
#### Request Body
- **url** (string) - Optional - The new URL for the link.
- **title** (string) - Optional - The new title for the link.
- **tags** (array) - Optional - An array of tags to set for the link (replaces existing tags).

### Request Example
{
  "title": "Updated Example Title",
  "tags": ["updated", "api"]
}

### Response
#### Success Response (200)
- **data** (object) - The updated link object.

### Response Example
{
  "data": {
    "id": "unique-link-id",
    "url": "https://example.com",
    "title": "Updated Example Title",
    "addedDate": "2023-10-27T10:00:00Z",
    "tags": ["updated", "api"]
  }
}
```

```APIDOC
## DELETE /api/v1/links/{id}

### Description
Deletes a link by its ID.

### Method
DELETE

### Endpoint
/api/v1/links/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the link to delete.

### Response
#### Success Response (200)
- **data** (object) - An empty object or a confirmation message upon successful deletion.

### Response Example
{
  "data": {}
}
```

--------------------------------

### Search Links by Multiple Tags

Source: https://goodlinks.app/api

Filter links that belong to any of the specified tags. This is useful for retrieving links related to multiple categories.

```curl
curl -H "Authorization: Bearer your-api-token" \
  "http://localhost:9428/api/v1/links?tag=technology&tag=programming&limit=20"
```

--------------------------------

### Replace All Tags on a Link

Source: https://goodlinks.app/api

Use this to completely replace a link's existing tags with a new set. Provide the link ID and the new list of tags in the request body.

```curl
curl -H "Authorization: Bearer your-api-token" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ \
    "tags": ["design", "ui"] \
  }' \
  http://localhost:9428/api/v1/links/abc123

```
Tokens:
Raw