API Reference

Integrate with the Collections Manager API

Docs Swagger UI
Authentication
Bearer token required for all requests

All API requests require a valid Bearer token in the Authorization header. Obtain a token by calling the login endpoint.

Example Request 
curl -X GET https://collections.local/api/collections \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
Base URL
All endpoints are relative to this URL

All API endpoints listed below are prefixed with this base URL. Ensure your requests target the correct environment.

https://collections.local/api
HTTPS All requests must use HTTPS
Collections
Create, read, update, and delete collections
5 endpoints
GET /api/collections

Returns a paginated list of collections accessible to the authenticated user. Supports query parameters for filtering, sorting, and pagination.

?page=1 ?per_page=20 ?search=term ?sort=date-desc
POST /api/collections

Creates a new collection. Requires a JSON body with name (required), description, and type fields. Returns the newly created collection object.

GET /api/collections/{id}

Returns the full details of a single collection by its ID, including metadata, item count, member count, and hierarchy information.

PUT /api/collections/{id}

Updates an existing collection. Send a JSON body with the fields to update. Only the fields provided will be modified (partial update supported).

DELETE /api/collections/{id}

Permanently deletes a collection and all its associated data. This action cannot be undone. Requires Admin role on the collection.

Collection Items
Manage items within collections
3 endpoints
GET /api/collections/{id}/items

Returns a paginated list of all items in the specified collection. Supports search, filtering, and sorting parameters.

POST /api/collections/{id}/items

Adds a new item to the specified collection. Requires a JSON body with item details including name and optional metadata fields.

DELETE /api/collections/{id}/items/{item_id}

Removes an item from the specified collection. The item itself is not deleted if it belongs to other collections.

Members
Manage collection membership and roles
4 endpoints
GET /api/collections/{id}/members

Returns all members of the specified collection, including their roles and join dates.

POST /api/collections/{id}/members

Invites a user to the collection. Requires user_id and role (viewer, editor, or admin) in the request body.

PUT /api/collections/{id}/members/{member_id}

Updates a member's role within the collection. Send a JSON body with the new role value. Requires Admin permissions.

DELETE /api/collections/{id}/members/{member_id}

Removes a member from the collection. The user loses all access to the collection immediately. Requires Admin permissions.

Bulk Operations
Import and export collections in bulk
2 endpoints
POST /api/bulk/upload

Upload an Excel file to create or update collections and items in bulk. Send the file as multipart/form-data. Returns a job ID for tracking progress.

GET /api/bulk/template

Downloads an Excel template file pre-formatted with the correct headers and example data for bulk uploads.

Auth
Authentication and session management
3 endpoints
POST /api/auth/login

Authenticates a user with email and password. Returns a Bearer token and user profile on success.

POST /api/auth/logout

Invalidates the current session and Bearer token. The token can no longer be used for authenticated requests after logout.

GET /api/auth/me

Returns the profile of the currently authenticated user, including display name, email, role, and account metadata.

Try the Interactive Swagger UI
Explore and test all API endpoints directly in your browser with the auto-generated OpenAPI documentation.