Skip to Content
architectureApi Reference

Last Updated: 3/8/2026

API Reference

Overview

LinkAce provides a comprehensive REST API that allows programmatic access to all core functionality. The API uses token-based authentication and returns JSON responses.

Authentication

All API requests require authentication via API tokens.

Generating API Tokens

  1. Log in to your LinkAce instance
  2. Navigate to Settings → API Tokens
  3. Click Create New Token
  4. Provide a descriptive name
  5. Copy the generated token (shown only once)

Using API Tokens

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Base URL

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

Rate Limiting

  • Default: 60 requests per minute per token
  • Configurable via environment settings
  • Rate limit headers included in responses:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

Endpoints

Retrieve a paginated list of links.

Query Parameters:

  • page (integer): Page number (default: 1)
  • per_page (integer): Items per page (default: 25, max: 100)
  • order_by (string): Sort field (created_at, title, url)
  • order_dir (string): Sort direction (asc, desc)
  • query (string): Search query
  • tags (array): Filter by tag IDs
  • lists (array): Filter by list IDs
  • is_private (boolean): Filter by privacy status

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-instance.com/api/v1/links?per_page=50&order_by=created_at&order_dir=desc"

Example Response:

{
  "data": [
    {
      "id": 1,
      "url": "https://example.com",
      "title": "Example Website",
      "description": "An example website",
      "is_private": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "tags": [...],
      "lists": [...]
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 150
  }
}

GET /links/{id}

Retrieve a specific link by ID.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-instance.com/api/v1/links/1"

POST /links

Create a new link.

Request Body:

{
  "url": "https://example.com",
  "title": "Example Website",
  "description": "Optional description",
  "is_private": false,
  "tags": [1, 2, 3],
  "lists": [1],
  "check_disabled": false
}

Required Fields:

  • url (string): Valid URL

Optional Fields:

  • title (string): Auto-generated if omitted
  • description (string): Auto-generated if omitted
  • is_private (boolean): Default from user settings
  • tags (array): Tag IDs to associate
  • lists (array): List IDs to associate
  • check_disabled (boolean): Disable link checking

PATCH /links/{id}

Update an existing link.

Request Body:

{
  "title": "Updated Title",
  "description": "Updated description",
  "is_private": true
}

DELETE /links/{id}

Delete a link (moves to trash if enabled).

Tags

GET /tags

Retrieve all tags.

Query Parameters:

  • page (integer): Page number
  • per_page (integer): Items per page
  • order_by (string): Sort field (name, created_at)
  • order_dir (string): Sort direction

GET /tags/{id}

Retrieve a specific tag.

POST /tags

Create a new tag.

Request Body:

{
  "name": "Technology",
  "is_private": false
}

PATCH /tags/{id}

Update a tag.

DELETE /tags/{id}

Delete a tag.

Lists

GET /lists

Retrieve all lists.

GET /lists/{id}

Retrieve a specific list with its links.

POST /lists

Create a new list.

Request Body:

{
  "name": "Reading List",
  "description": "Articles to read",
  "is_private": false
}

PATCH /lists/{id}

Update a list.

DELETE /lists/{id}

Delete a list.

Advanced search across links.

Query Parameters:

  • query (string): Search terms
  • search_title (boolean): Search in titles
  • search_description (boolean): Search in descriptions
  • tags (array): Filter by tags
  • lists (array): Filter by lists
  • is_private (boolean): Filter by privacy
  • order_by (string): Sort field
  • order_dir (string): Sort direction

Import/Export

POST /import

Import bookmarks from HTML file.

Request:

  • Content-Type: multipart/form-data
  • Field: file (HTML bookmark file)

GET /export

Export all links as HTML.

Query Parameters:

  • format (string): Export format (html)

Error Handling

Error Response Format

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

HTTP Status Codes

  • 200 OK: Successful request
  • 201 Created: Resource created successfully
  • 204 No Content: Successful deletion
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Missing or invalid API 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

Pagination

All list endpoints support pagination.

Response Structure:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  },
  "links": {
    "first": "https://...",
    "last": "https://...",
    "prev": null,
    "next": "https://..."
  }
}

Zapier Integration

LinkAce is available on Zapier with pre-built triggers and actions:

Triggers:

  • New Link Created
  • Link Updated
  • Tag Created

Actions:

  • Create Link
  • Update Link
  • Create Tag
  • Add Link to List

Connect LinkAce on Zapier 

Best Practices

  1. Store tokens securely: Never commit tokens to version control
  2. Use pagination: Limit response sizes for better performance
  3. Handle rate limits: Implement exponential backoff
  4. Validate input: Check data before sending requests
  5. Monitor usage: Track API calls and errors
OverviewDatabase Schema