Skip to Content
Api Reference

Last Updated: 3/17/2026

API Reference

LinkAce provides a comprehensive REST API for managing your bookmarks programmatically. All API endpoints are versioned under /api/v2 and require authentication using Laravel Sanctum tokens.

Authentication

All API requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

API tokens can be created in the User Settings or System Settings sections of LinkAce. See User API Tokens and System API Tokens for more details.

Token Abilities

System API tokens support special abilities:

  • ABILITY_SYSTEM_ACCESS_PRIVATE: Grants access to private resources across all users

Rate Limiting

All API endpoints are rate-limited according to your configuration. The default rate limit is configurable via the app.api_rate_limit setting.

Base URL

All endpoints are prefixed with /api/v2:

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

Common Parameters

Many list endpoints support these query parameters:

  • order_by: Field to sort by (e.g., created_at, title, name)
  • order_dir: Sort direction (asc or desc)
  • page: Page number for pagination
  • per_page: Number of items per page
GET /api/v2/links

Query Parameters:

  • order_by: id, url, title, description, visibility, status, check_disabled, created_at, updated_at, random
  • order_dir: asc or desc (default: desc)

Response:

{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "url": "https://example.com",
      "title": "Example Site",
      "description": "An example website",
      "icon": "globe",
      "visibility": 1,
      "status": 1,
      "check_disabled": false,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": {...},
  "meta": {...}
}
GET /api/v2/links/{id}

Returns a single link with its associated lists and tags.

POST /api/v2/links

Request Body:

{
  "url": "https://example.com",
  "title": "Example Site",
  "description": "An example website",
  "visibility": 1,
  "lists": [1, 2],
  "tags": [3, 4],
  "check_disabled": false
}
PATCH /api/v2/links/{id}

Same request body format as Create Link.

DELETE /api/v2/links/{id}

Moves the link to trash (soft delete).

GET /api/v2/links/check?url=https://example.com

Checks if a URL already exists in your LinkAce instance.

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

Returns all notes associated with a specific link.

Lists API

List All Lists

GET /api/v2/lists

Query Parameters:

  • order_by: id, name, description, visibility, created_at, updated_at, random, links_count
  • order_dir: asc or desc

Get List

GET /api/v2/lists/{id}

Create List

POST /api/v2/lists

Request Body:

{
  "name": "My List",
  "description": "A collection of useful links",
  "visibility": 1
}

Update List

PATCH /api/v2/lists/{id}

Delete List

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

Returns all links associated with a specific list.

Tags API

List All Tags

GET /api/v2/tags

Query Parameters:

  • order_by: id, name, visibility, created_at, updated_at, random, links_count
  • order_dir: asc or desc

Get Tag

GET /api/v2/tags/{id}

Create Tag

POST /api/v2/tags

Request Body:

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

Update Tag

PATCH /api/v2/tags/{id}

Delete Tag

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

Returns all links associated with a specific tag.

Notes API

Create Note

POST /api/v2/notes

Request Body:

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

Update Note

PATCH /api/v2/notes/{id}

Delete Note

DELETE /api/v2/notes/{id}

Bulk Operations API

POST /api/v2/bulk/links

Create multiple links in one request.

Bulk Create Lists

POST /api/v2/bulk/lists

Bulk Create Tags

POST /api/v2/bulk/tags
PATCH /api/v2/bulk/links

Update multiple links in one request.

Bulk Update Lists

PATCH /api/v2/bulk/lists

Bulk Update Tags

PATCH /api/v2/bulk/tags

Bulk Delete

DELETE /api/v2/bulk/delete

Delete multiple resources (links, lists, tags, or notes) in one request.

Search API

GET /api/v2/search/links?query=example

Search for links by title, description, or URL.

Search by Tags

GET /api/v2/search/tags?tags=tutorial,howto

Find links tagged with specific tags.

Search by Lists

GET /api/v2/search/lists?lists=1,2

Find links in specific lists.

Trash API

GET /api/v2/trash/links

Get Trashed Lists

GET /api/v2/trash/lists

Get Trashed Tags

GET /api/v2/trash/tags

Get Trashed Notes

GET /api/v2/trash/notes

Restore from Trash

PATCH /api/v2/trash/restore

Request Body:

{
  "type": "link",
  "ids": [1, 2, 3]
}

Clear Trash

DELETE /api/v2/trash/clear

Permanently delete all trashed items.

Visibility Levels

The visibility field determines who can see a resource:

  • 1 (PRIVATE): Only visible to the owner
  • 2 (INTERNAL): Visible to all authenticated users
  • 3 (PUBLIC): Visible to everyone, including guests

The status field on links indicates the health check result:

  • 1 (STATUS_OK): Link is accessible
  • 2 (STATUS_MOVED): Link was moved (redirect detected)
  • 3 (STATUS_BROKEN): Link is broken or inaccessible

Error Responses

All error responses follow a standard format:

{
  "message": "Error description",
  "errors": {
    "field": ["Error detail"]
  }
}

Common HTTP status codes:

  • 200 OK: Success
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 422 Unprocessable Entity: Validation failed
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
V2