API Integration Guide

Overview

The Collections Manager exposes a RESTful API that lets you programmatically create, read, update, and delete collections and their items. Every action available in the web interface can also be performed through the API, making it straightforward to build custom integrations, automate workflows, or connect Collections Manager with third-party tools.

All API communication happens over HTTPS and uses JSON for both request and response payloads. Authentication is handled through Bearer tokens included in the Authorization header.

Authentication

All API requests must be authenticated. The Collections Manager API uses Bearer token authentication. Include your token in the Authorization header of every request.

Obtaining a Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "token_type": "bearer",
    "expires_in": 3600
  }
}

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refreshing a Token

Access tokens expire after 1 hour. Before or after expiration, use the refresh token to obtain a new access token without requiring the user to log in again.

POST /api/auth/refresh
Content-Type: application/json

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

API Base URL & Versioning

All API endpoints are served under a versioned base URL. The current version is v1.

https://your-domain.com/api/v1

When a new API version is released, the previous version will continue to function for at least 12 months. Version deprecation notices will appear in the X-API-Deprecation response header.

Common Endpoints

Below are the most frequently used endpoints. See the full API Reference for all available routes.

Request & Response Format

Request Headers

Every request should include these headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
Accept: application/json

Standard Response Envelope

All responses are wrapped in a consistent envelope. Successful responses include a data field, while errors include an error field.

// Success
{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "pages": 3
  }
}

// Error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required.",
    "details": [ ... ]
  }
}

Error Handling

The API uses standard HTTP status codes to indicate the outcome of each request. Always check the success field and the HTTP status code in your integration logic.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": [
      {
        "field": "name",
        "message": "Name must be between 1 and 255 characters."
      }
    ]
  }
}

Rate Limiting

To ensure fair usage and system stability, API requests are rate-limited per user. The current limits are:

• Standard tier: 100 requests per minute
• Organization tier: 500 requests per minute

Every response includes rate-limit headers so you can monitor your usage:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1708992000

Pagination

All list endpoints support pagination through query parameters. Results are returned in pages with metadata in the meta field.

Query Parameters

Response Metadata

GET /api/collections?page=2&per_page=10

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 42,
    "page": 2,
    "per_page": 10,
    "pages": 5
  }
}

Code Examples

Below are ready-to-use examples for listing collections in three popular languages.

curl -X GET "https://your-domain.com/api/v1/collections?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

const response = await fetch(
  'https://your-domain.com/api/v1/collections?page=1&per_page=20',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Accept': 'application/json'
    }
  }
);

const result = await response.json();

if (result.success) {
  console.log('Collections:', result.data);
  console.log('Total:', result.meta.total);
} else {
  console.error('Error:', result.error.message);
}

import requests

url = "https://your-domain.com/api/v1/collections"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
params = {"page": 1, "per_page": 20}

response = requests.get(url, headers=headers, params=params)
result = response.json()

if result["success"]:
    for collection in result["data"]:
        print(collection["name"])
    print(f"Total: {result['meta']['total']}")
else:
    print(f"Error: {result['error']['message']}")

Creating a Collection

curl -X POST "https://your-domain.com/api/v1/collections" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Collection",
    "description": "A collection created via the API",
    "visibility": "private"
  }'

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Collections Manager, such as collection creation, item updates, or sharing changes.