API Documentation

Integrate with HostStock programmatically. Access properties, inventory, stock health, transactions, bookings, and suppliers via the read-only v1 REST API.

Overview

The HostStock API provides read-only RESTful endpoints for accessing your inventory data programmatically. All API responses follow a consistent JSON format, and authenticated endpoints require a valid Bearer token. The API is designed for server-to-server integrations, dashboards, and reporting tools.

Base URL: https://hoststock.app

Authentication

Authenticated endpoints require a Bearer token in the Authorization header. Tokens are prefixed with hs_live_. You can generate API keys from the Settings → API tab in your dashboard.

The v1 API endpoints require an Analytics Pro plan with the API add-on enabled.

curl -X GET https://hoststock.app/api/v1/properties \
  -H "Authorization: Bearer hs_live_abc123..."

Rate Limiting

All API endpoints are rate-limited to 60 requests per minute per IP. Exceeding this limit returns a 429 Too Many Requests response. Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709035200

Error Format

All error responses follow a consistent format. The HTTP status code indicates the type of error, and the body includes a human-readable message.

{
  "success": false,
  "error": "Unauthorized: invalid or expired API key"
}

Status Code	Description
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — insufficient permissions
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

Pagination

List endpoints in the v1 API support cursor-based pagination via query parameters. Every paginated response includes a meta object with the current page, page size, and total count.

Parameter	Default	Description
`page`	1	Page number (1-indexed)
`pageSize`	50	Items per page (max 100)

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 127
  }
}

Public Endpoints

GET/api/healthPublic

Returns the current health status of the HostStock API, including database connectivity and version information. This endpoint is public and does not require authentication.

Example Response

{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2026-02-26T12:00:00.000Z",
  "database": "connected"
}

v1 API Endpoints

The v1 REST API provides read-only access to your HostStock data. All v1 endpoints require authentication and an Analytics Pro plan with the API add-on.

GET/api/v1/propertiesAuth required

List all active properties in your organisation with pagination. Includes room and inventory item counts.

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default 1).
`pageSize`	number	No	Items per page (default 50, max 100).

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx1abc...",
      "name": "Seaside Villa",
      "address": "123 Beach Road",
      "bedroomCount": 3,
      "bathroomCount": 2,
      "maxGuests": 6,
      "roomCount": 5,
      "inventoryItemCount": 42,
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 50, "total": 3 }
}

GET/api/v1/properties/:idAuth required

Retrieve a single property by ID, including its full list of rooms and aggregate counts for rooms, inventory items, and bookings.

Example Response

{
  "success": true,
  "data": {
    "id": "clx1abc...",
    "name": "Seaside Villa",
    "address": "123 Beach Road",
    "bedroomCount": 3,
    "bathroomCount": 2,
    "maxGuests": 6,
    "roomCount": 5,
    "inventoryItemCount": 42,
    "bookingCount": 12,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "rooms": [
      {
        "id": "clx2def...",
        "name": "Master Bedroom",
        "roomType": "BEDROOM",
        "maxOccupancy": 2,
        "sortOrder": 1,
        "createdAt": "2026-01-15T10:05:00.000Z"
      }
    ]
  }
}

GET/api/v1/properties/:id/roomsAuth required

List all rooms for a specific property, ordered by sort position. Useful for building room-level inventory views.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx2def...",
      "name": "Master Bedroom",
      "roomType": "BEDROOM",
      "maxOccupancy": 2,
      "sortOrder": 1,
      "createdAt": "2026-01-15T10:05:00.000Z"
    },
    {
      "id": "clx3ghi...",
      "name": "Kitchen",
      "roomType": "KITCHEN",
      "maxOccupancy": null,
      "sortOrder": 2,
      "createdAt": "2026-01-15T10:06:00.000Z"
    }
  ]
}

GET/api/v1/inventoryAuth required

List inventory items across your organisation with pagination. Each item includes its current stock level, par level, computed status (OK, LOW, CRITICAL, or OUT_OF_STOCK), and linked supplier.

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default 1).
`pageSize`	number	No	Items per page (default 50, max 100).
`propertyId`	string	No	Filter items by property ID.
`category`	string	No	Filter by category. Built-in: TOILETRIES, LINENS, CLEANING, KITCHEN, AMENITIES, MAINTENANCE, PETTY_CASH, OTHER. Custom categories: use "custom:<id>" format.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx4jkl...",
      "name": "Bath Towels",
      "category": "LINENS",
      "customCategory": null,
      "unit": "each",
      "currentStock": 12,
      "parLevel": 20,
      "reorderPoint": 5,
      "costPerUnit": 8.50,
      "propertyId": "clx1abc...",
      "propertyName": "Seaside Villa",
      "supplier": { "id": "clx5mno...", "name": "Linen Co" },
      "status": "LOW"
    }
  ],
  "meta": { "page": 1, "pageSize": 50, "total": 42 }
}

GET/api/v1/inventory/:idAuth required

Retrieve a single inventory item by ID with its current stock status, property and supplier details, and the 20 most recent transactions.

Example Response

{
  "success": true,
  "data": {
    "id": "clx4jkl...",
    "name": "Bath Towels",
    "category": "LINENS",
    "customCategory": null,
    "unit": "each",
    "currentStock": 12,
    "parLevel": 20,
    "reorderPoint": 5,
    "costPerUnit": 8.50,
    "propertyId": "clx1abc...",
    "property": { "id": "clx1abc...", "name": "Seaside Villa" },
    "supplier": { "id": "clx5mno...", "name": "Linen Co" },
    "status": "LOW",
    "recentTransactions": [
      {
        "id": "clx6pqr...",
        "type": "STOCK_OUT",
        "quantity": -3,
        "note": "Guest checkout",
        "createdAt": "2026-03-01T09:30:00.000Z",
        "userName": "Jane Host"
      }
    ]
  }
}

GET/api/v1/stock-healthAuth required

Aggregate stock health report across all properties. Returns overall totals and per-property breakdowns showing how many items are OK, LOW, or CRITICAL, plus a health percentage.

Example Response

{
  "success": true,
  "data": {
    "overall": {
      "totalItems": 120,
      "ok": 95,
      "low": 18,
      "critical": 7,
      "healthPercent": 79
    },
    "byProperty": [
      {
        "propertyId": "clx1abc...",
        "propertyName": "Seaside Villa",
        "totalItems": 42,
        "ok": 35,
        "low": 5,
        "critical": 2,
        "healthPercent": 83
      }
    ]
  }
}

GET/api/v1/transactionsAuth required

List stock transactions (stock-in, stock-out, adjustments, deliveries) with pagination. Filterable by property, transaction type, and date range.

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default 1).
`pageSize`	number	No	Items per page (default 50, max 100).
`propertyId`	string	No	Filter transactions by property ID.
`type`	string	No	Filter by transaction type: STOCK_IN, STOCK_OUT, ADJUSTMENT, DELIVERY.
`from`	string (ISO 8601)	No	Start date for the date range filter.
`to`	string (ISO 8601)	No	End date for the date range filter.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx6pqr...",
      "type": "STOCK_OUT",
      "quantity": -3,
      "costPerUnit": 8.50,
      "note": "Guest checkout",
      "itemId": "clx4jkl...",
      "itemName": "Bath Towels",
      "propertyId": "clx1abc...",
      "propertyName": "Seaside Villa",
      "userName": "Jane Host",
      "createdAt": "2026-03-01T09:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 50, "total": 256 }
}

GET/api/v1/bookingsAuth required

List upcoming bookings (where checkout is in the future) with pagination. Includes guest name, dates, guest count, status, and booking source.

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default 1).
`pageSize`	number	No	Items per page (default 50, max 100).
`propertyId`	string	No	Filter bookings by property ID.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx7stu...",
      "guestName": "John Smith",
      "checkIn": "2026-03-10T14:00:00.000Z",
      "checkOut": "2026-03-14T10:00:00.000Z",
      "guestCount": 4,
      "status": "CONFIRMED",
      "source": "ical",
      "propertyId": "clx1abc...",
      "propertyName": "Seaside Villa"
    }
  ],
  "meta": { "page": 1, "pageSize": 50, "total": 8 }
}

GET/api/v1/suppliersAuth required

List all suppliers for your organisation. Includes contact details and a count of linked inventory items.

Example Response

{
  "success": true,
  "data": [
    {
      "id": "clx5mno...",
      "name": "Linen Co",
      "contactEmail": "orders@linenco.com",
      "contactPhone": "+44 20 1234 5678",
      "website": "https://linenco.com",
      "notes": null,
      "itemCount": 15,
      "createdAt": "2026-01-20T08:00:00.000Z"
    }
  ]
}

Need help integrating? Contact us at support@hoststock.app

Back to HostStock