Management API Reference

The current REST API is the authenticated management API. It lets trusted clients read and manage Inventory data programmatically. All endpoints require authentication via a Sanctum bearer token, except for health and version checks.

The future read-only API is a separate design area. It should optimize public content delivery and should not be confused with this management API.

Quick Access

• Interactive API Explorer (Swagger UI) - Browse and test endpoints directly
• OpenAPI Specification - Download the full specification (JSON)
• TypeScript Client Documentation - Auto-generated client reference

Interactive Documentation

What the API Offers

• Full CRUD on all inventory entities (items, partners, collections, projects, etc.)
• Multi-language translations - create and retrieve content in any language and audience context
• Image management - upload, process, and attach images to items, collections, and partners
• Hierarchical collections - organise items into exhibitions, galleries, thematic trails, and more
• Tags - flexible, ad-hoc categorisation of items
• Search and pagination - filter and page through large result sets

System Endpoints

• GET /api/info - Application information
• GET /api/health - Health check (no auth required)
• GET /api/version - Current application version (no auth required)

Image Workflow

Images flow through a three-stage pipeline:

1. Upload - POST /api/image-upload uploads a file for processing.
2. Processing - the system resizes and optimises the image in the background.
3. Attachment - attach the processed image to an item, collection, or partner.

See Core Model for the business meaning of images and picture Items.

TypeScript API Client

An auto-generated TypeScript client is available as an npm package. It provides type-safe access to every API endpoint.

Installation

npm install @metanull/inventory-app-api-client@latest

The package is published to GitHub Packages. You need a GitHub PAT with read:packages scope and an .npmrc pointing to the GitHub registry. See the README for setup details.

Quick Example

import { Configuration, DefaultApi } from "@metanull/inventory-app-api-client";

const api = new DefaultApi(
  new Configuration({ basePath: "https://your.api.url" }),
);
const items = await api.itemIndex();
console.log(items.data);

Client Documentation

• TypeScript API Client Reference - Auto-generated documentation for all client methods, parameters, and response types

For Maintainers

The client is auto-generated from the OpenAPI specification using openapi-generator-cli. Generation and publishing scripts are documented in Development / Scripts.