Eilith Public REST API — Overview

Quick Start

Authorization: Bearer <YOUR_ACCESS_TOKEN>
Base URL (Production):
  https://krjtnboxzkrhejhqtwgm.supabase.co/functions/v1/platform-api/api/v1
Base URL (Staging):
  https://pmjidplmzxohyqsbajvg.supabase.co/functions/v1/platform-api/api/v1

All endpoints return Content-Type: application/json. CORS is enabled for all origins.

Authentication

Every request requires an Authorization: Bearer <api_key> header.

Key format: uk_live_ + 40 hex characters (64 chars total).

Keys are SHA-256 hashed before storage — the plaintext key is only shown once at creation time via the generate_api_key RPC from the Flutter UI.

Key Management (via Flutter UI, not REST)

The full key is only returned at creation. After that, only key_prefix (first 16 chars + ...) is stored.

Plan Gating

API access is tiered by subscription plan:

Exceeding the limit returns 429 with { error, limit, used, resets_at }.

Pagination

All list endpoints use cursor-based pagination with consistent parameters:

Response shape:

{
  "data": [...],
  "pagination": {
    "next_cursor": "uuid-or-null",
    "has_more": true
  }
}

To paginate: pass cursor from pagination.next_cursor of the previous response.

Endpoints

Products (Inventory Items)

List query params: status (active/inactive/archived), item_type (stock/service/consumable/assembly), search (name or SKU).

Create required fields: sku, name, item_type, default_uom.

Update allowed fields: sku, name, item_type, status, default_uom, cost_method, description, reorder_point, reorder_qty, is_stockable, is_purchasable, is_sellable, is_manufacturable, standard_cost, image_url.

Image upload: Content-Type: multipart/form-data with a file field. Accepted types: JPEG, PNG, WebP, GIF. Max 5MB. Returns { image_url } (signed URL, 7-day expiry).

Soft-delete sets deleted_at and status: "archived".

Stock

List query params: location_id, item_id.

Adjust required fields: inventory_item_id, location_id, quantity (positive = add, negative = subtract).

Adjust optional fields: uom (default ea), unit_cost (default 0), notes.

Customers

List query params: search (name, email, or phone).

Create required fields: customer_code, name.

Update allowed fields: customer_code, name, email, phone, address_line1, address_line2, city, state, postal_code, country, is_active.

Orders (Sales Orders)

List query params: status (draft/confirmed/fulfilled/cancelled).

Create required: lines array (min 1 item), each with quantity and unit_price.

Line item fields: inventory_item_id, description, quantity, unit_price, discount_pct (default 0), tax_pct (default 0).

The API auto-calculates subtotal, tax_total, grand_total, and per-line total. Orders are created with source: "integration".

Update allowed fields: customer_name, customer_email, customer_phone, status, currency_code.

Usage

Response:

{
  "plan": "uniledger_plus",
  "month": "2026-08",
  "used": 1234,
  "limit": 10000,
  "active_keys": 2
}

Error Responses

All errors return { "error": "message" } with an appropriate HTTP status:

Architecture

Request → Supabase Edge Function (platform-api)
  → authenticateApiKey() — SHA-256 hash lookup, plan check, usage check
  → handlePublicApi() — route by path + method
  → logApiUsage() — async insert to api_usage_logs (fire-and-forget)
  → Response

Key tables:

Rate Limiting

Rate limits are checked per-tenant (not per-key). Each key on the same tenant shares the same monthly counter. The monthly_limit field on tenant_api_keys overrides the plan default if set.

Usage resets on the 1st of each month (UTC).

Phase 2 (Planned)

• Webhooks:tenant_webhook_endpoints table is ready. Events will include order.created, order.updated, stock.adjusted, etc.
• GraphQL: After REST stabilizes.
• Additional integrations: Shopify, WooCommerce, Square.