Skip to Content
v2DeveloperApi Reference

Last Updated: 3/11/2026

API Reference

LinkAce provides a comprehensive REST API that allows you to interact with all features programmatically. The API uses Laravel Sanctum for authentication and supports rate limiting.

Base URL

All API requests should be made to:

https://your-linkace-instance.com/api/v2

Authentication

The API uses token-based authentication via Laravel Sanctum. You need to:

  1. Generate an API token from your user settings or system settings
  2. Include the token in the Authorization header of each request:
Authorization: Bearer YOUR_API_TOKEN

Rate Limiting

API requests are rate-limited according to the app.api_rate_limit configuration setting. When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Endpoints

GET /api/v2/links

Retrieve a paginated list of links.

Query Parameters:

  • page - Page number for pagination
  • per_page - Items per page (default: 25)
  • order_by - Field to order by (id, url, title, description, visibility, status, check_disabled, created_at, updated_at, random)
  • order_dir - Order direction (asc, desc)
GET /api/v2/links/{id}

Retrieve a specific link by ID.

POST /api/v2/links

Request Body:

{
  "url": "https://example.com",
  "title": "Example Site",
  "description": "Optional description",
  "visibility": 1,
  "tags": [1, 2, 3],
  "lists": [1, 2]
}

Fields:

  • url (required) - The URL to bookmark
  • title (optional) - Link title (auto-generated if not provided)
  • description (optional) - Link description
  • icon (optional) - Icon identifier
  • visibility (optional) - 1=Private, 2=Internal, 3=Public (default: 1)
  • check_disabled (optional) - Disable link checking (boolean)
  • tags (optional) - Array of tag IDs
  • lists (optional) - Array of list IDs
PATCH /api/v2/links/{id}

Update an existing link. Accepts the same fields as create.

DELETE /api/v2/links/{id}

Soft delete a link (moves to trash).

GET /api/v2/links/check?url={url}

Check if a URL already exists in your bookmarks.

Query Parameters:

  • url (required) - The URL to check
GET /api/v2/links/{id}/notes

Retrieve all notes associated with a link.

Lists

List Lists

GET /api/v2/lists

Retrieve a paginated list of all lists.

Get List

GET /api/v2/lists/{id}

Retrieve a specific list by ID.

Create List

POST /api/v2/lists

Request Body:

{
  "name": "Reading List",
  "description": "Articles to read later",
  "visibility": 1
}

Update List

PATCH /api/v2/lists/{id}

Update an existing list.

Delete List

DELETE /api/v2/lists/{id}

Soft delete a list.

GET /api/v2/lists/{id}/links

Retrieve all links in a specific list.

Tags

List Tags

GET /api/v2/tags

Retrieve a paginated list of all tags.

Get Tag

GET /api/v2/tags/{id}

Retrieve a specific tag by ID.

Create Tag

POST /api/v2/tags

Request Body:

{
  "name": "Technology",
  "visibility": 1
}

Update Tag

PATCH /api/v2/tags/{id}

Update an existing tag.

Delete Tag

DELETE /api/v2/tags/{id}

Soft delete a tag.

GET /api/v2/tags/{id}/links

Retrieve all links with a specific tag.

Notes

Create Note

POST /api/v2/notes

Request Body:

{
  "link_id": 123,
  "note": "This is a note about the link",
  "visibility": 1
}

Update Note

PATCH /api/v2/notes/{id}

Update an existing note.

Delete Note

DELETE /api/v2/notes/{id}

Delete a note permanently.

Bulk Operations

POST /api/v2/bulk/links

Create multiple links in a single request.

Bulk Create Lists

POST /api/v2/bulk/lists

Create multiple lists in a single request.

Bulk Create Tags

POST /api/v2/bulk/tags

Create multiple tags in a single request.

PATCH /api/v2/bulk/links

Update multiple links in a single request.

Bulk Update Lists

PATCH /api/v2/bulk/lists

Update multiple lists in a single request.

Bulk Update Tags

PATCH /api/v2/bulk/tags

Update multiple tags in a single request.

Bulk Delete

DELETE /api/v2/bulk/delete

Delete multiple items (links, lists, tags, or notes) in a single request.

GET /api/v2/search/links

Search for links using various filters.

Query Parameters:

  • query - Search term
  • tags - Filter by tag IDs (comma-separated)
  • lists - Filter by list IDs (comma-separated)
  • visibility - Filter by visibility (1, 2, or 3)
  • status - Filter by link status (1=OK, 2=Moved, 3=Broken)
  • order_by - Field to order by
  • order_dir - Order direction

Search by Tags

GET /api/v2/search/tags

Search for links by tag criteria.

Search by Lists

GET /api/v2/search/lists

Search for links by list criteria.

Trash

GET /api/v2/trash/links

Retrieve all soft-deleted links.

Get Trashed Lists

GET /api/v2/trash/lists

Retrieve all soft-deleted lists.

Get Trashed Tags

GET /api/v2/trash/tags

Retrieve all soft-deleted tags.

Get Trashed Notes

GET /api/v2/trash/notes

Retrieve all deleted notes.

Clear Trash

DELETE /api/v2/trash/clear

Permanently delete all items in trash.

Restore from Trash

PATCH /api/v2/trash/restore

Restore items from trash.

Request Body:

{
  "links": [1, 2, 3],
  "lists": [1, 2],
  "tags": [1],
  "notes": [1]
}

Response Format

All API responses follow a consistent JSON format:

Success Response:

{
  "data": { ... },
  "message": "Success message"
}

Error Response:

{
  "error": "Error message",
  "errors": {
    "field": ["Validation error message"]
  }
}

Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded with no response body
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation errors
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Links have a status field indicating their health:

  • 1 - OK (link is accessible)
  • 2 - Moved (link redirects to a new location)
  • 3 - Broken (link is inaccessible)

Visibility Values

All resources (links, lists, tags) support visibility settings:

  • 1 - Private (only visible to the owner)
  • 2 - Internal (visible to all authenticated users)
  • 3 - Public (visible to everyone, including guests)

Example Usage

curl -X POST https://your-linkace-instance.com/api/v2/links \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/Kovah/LinkAce",
    "title": "LinkAce GitHub Repository",
    "description": "Self-hosted bookmark manager",
    "visibility": 1
  }'
import requests
 
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
 
params = {
    "query": "github",
    "order_by": "created_at",
    "order_dir": "desc"
}
 
response = requests.get(
    "https://your-linkace-instance.com/api/v2/search/links",
    headers=headers,
    params=params
)
 
links = response.json()["data"]
for link in links:
    print(f"{link['title']}: {link['url']}")

Third-Party Integrations

LinkAce is available on Zapier, enabling integration with over 2500+ applications. Visit zapier.com/apps/linkace  to explore available integrations.

  • User API Tokens - Generate and manage user-level API tokens
  • System API Tokens - Generate and manage system-level API tokens
AuthenticationArchitecture