Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Data Ingestion API

Universal data ingestion engine for importing menus, inventory, staff, and historical data from any source.

Overview

Attribute	Value
Base Path	/api/v1/ingestion
Authentication	Bearer Token
Required Roles	JWT authentication required (no specific role restriction)

Key Features

• Universal File Detection - Auto-detects file type (CSV, JSON, PDF, Images)
• Schema Alignment AI - LangGraph agent maps any format to Olympus schema
• Competitor Migration - Direct import from 25+ POS systems
• Historical Data Import - Sales, labor, and inventory history for ML training

---

Universal Upload

Upload File

POST /api/v1/ingestion/upload

Auto-detects file type and routes to appropriate extractor.

Request

Content-Type: multipart/form-data

file: <binary>

Supported File Types

MIME Type	Detection	Target
image/*	Menu or Floor Plan	Menu items or table layout
application/pdf	Invoice or Roster	Inventory or Staff
text/csv	Competitor export or custom	Auto-detected schema
application/json	Competitor export	Auto-detected schema

Response

{
  "job_id": "ing_abc123",
  "status": "processing",
  "detected_type": "TOAST_EXPORT",
  "target_schema": "menu",
  "progress": 0,
  "estimated_records": 150,
  "created_at": "2026-01-24T20:00:00Z"
}

---

Competitor Migration

Supported POS Systems

Tier	Systems	Format
Tier 1	Toast, Square, Clover	CSV, JSON
Tier 2	Lightspeed, TouchBistro, Revel, SpotOn	CSV
Tier 3	Aloha, MICROS, Shift4	DBF, XML, Fixed-Width
Legacy	Heartland, PAR, Lavu, Rezku, CAKE, Breadcrumb	Various

Detection Signatures

The ingestion router auto-detects POS systems using:

# Content Signatures
"toast" in content     → TOAST_EXPORT
"square" in content    → SQUARE_EXPORT
"clover" in content    → CLOVER_EXPORT
"lightspeed" in content → LIGHTSPEED_EXPORT
"aloha" in content     → ALOHA_EXPORT
"micros" in content    → MICROS_EXPORT

Schema Alignment

The LangGraph agent maps source fields to Olympus schema:

{
  "source_field": "Item Name",
  "target_field": "name",
  "confidence": 0.95,
  "transformation": null
},
{
  "source_field": "Price (cents)",
  "target_field": "price",
  "confidence": 0.92,
  "transformation": "divide_by_100"
}

---

Sales History Import

Import Sales History

POST /api/v1/ingestion/sales-history

Import historical sales data for ML model training.

Request

Content-Type: multipart/form-data

file: <binary>
format: toast|square|clover|aloha|micros|generic
start_date: 2024-01-01 (optional)
end_date: 2026-01-01 (optional)

Supported Formats

Format	Fields Expected
toast	Order ID, Date, Total, Tax, Tip, Items
square	Transaction ID, Created At, Total, Tax
clover	Order ID, Timestamp, Amount, Line Items
aloha	Check Number, Date, Total, Tender
micros	Check ID, Business Date, Total
generic	order_id, date, total_amount, items

Response

{
  "job_id": "sales_import_001",
  "status": "processing",
  "format": "toast",
  "records_found": 45230,
  "date_range": {
    "start": "2024-01-01",
    "end": "2025-12-31"
  },
  "estimated_completion": "2026-01-24T20:15:00Z"
}

List Sales History Formats

GET /api/v1/ingestion/sales-history/formats

Response

{
  "formats": [
    {
      "id": "toast",
      "name": "Toast POS",
      "description": "Toast menu and sales export",
      "file_types": ["csv", "json"],
      "required_fields": ["Order ID", "Date", "Total"],
      "optional_fields": ["Tax", "Tip", "Items"]
    },
    {
      "id": "square",
      "name": "Square POS",
      "description": "Square transactions export",
      "file_types": ["csv"],
      "required_fields": ["Transaction ID", "Created At", "Total"]
    }
  ]
}

---

Labor History Import

Import Labor History

POST /api/v1/ingestion/labor-history

Import historical shift/punch data for labor forecasting.

Request

Content-Type: multipart/form-data

file: <binary>
format: 7shifts|hotschedules|adp|paychex|gusto|generic

Supported Formats

Format	Provider	Fields
7shifts	7shifts	Employee, Shift Start, Shift End, Role
hotschedules	HotSchedules	User, Clock In, Clock Out, Job
adp	ADP	Employee ID, Punch In, Punch Out
paychex	Paychex	Employee, Date, Hours
gusto	Gusto	Employee, Date, Regular Hours, OT Hours
generic	Any	employee_id, clock_in, clock_out

Response

{
  "job_id": "labor_import_001",
  "status": "processing",
  "format": "7shifts",
  "records_found": 12450,
  "employees_detected": 45,
  "date_range": {
    "start": "2024-01-01",
    "end": "2025-12-31"
  }
}

List Labor History Formats

GET /api/v1/ingestion/labor-history/formats

---

Inventory History Import

Import Inventory History

POST /api/v1/ingestion/inventory-history

Import historical inventory transactions for demand forecasting.

Request

Content-Type: multipart/form-data

file: <binary>
format: marketman|bluecart|compeat|restaurant365|xtrachef|generic

Supported Formats

Format	Provider	Fields
marketman	MarketMan	Item, Date, Quantity, Cost
bluecart	BlueCart	Product, Order Date, Qty, Price
compeat	Compeat	Item ID, Date, Units, Cost
restaurant365	Restaurant365	Product, Date, Qty, Amount
xtrachef	xtraCHEF	Item, Invoice Date, Qty, Price
generic	Any	item_id, date, quantity, unit_cost

Response

{
  "job_id": "inv_import_001",
  "status": "processing",
  "format": "marketman",
  "records_found": 28340,
  "items_detected": 450,
  "suppliers_detected": 12,
  "date_range": {
    "start": "2024-01-01",
    "end": "2025-12-31"
  }
}

List Inventory History Formats

GET /api/v1/ingestion/inventory-history/formats

---

Target Schemas

Menu Schema

{
  "categories": [{
    "name": "string",
    "description": "string",
    "sort_order": "integer",
    "items": [{
      "name": "string",
      "description": "string",
      "price": "number",
      "sku": "string",
      "is_available": "boolean",
      "modifiers": [{
        "name": "string",
        "price": "number"
      }]
    }]
  }]
}

Inventory Schema

{
  "items": [{
    "name": "string",
    "sku": "string",
    "barcode": "string",
    "category": "string",
    "quantity_on_hand": "number",
    "unit_cost": "number",
    "supplier": "string",
    "reorder_point": "number"
  }]
}

Staff Schema

{
  "employees": [{
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "phone": "string",
    "role": "string",
    "hourly_rate": "number",
    "pin": "string",
    "start_date": "string (YYYY-MM-DD)"
  }]
}

Floor Plan Schema

{
  "tables": [{
    "id": "string",
    "shape": "rect|round",
    "seats": "integer",
    "x": "number (0-1)",
    "y": "number (0-1)",
    "width": "number (0-1)",
    "height": "number (0-1)",
    "section_name": "string"
  }],
  "walls": [{
    "start_x": "number",
    "start_y": "number",
    "end_x": "number",
    "end_y": "number"
  }]
}

---

Webhooks

Event	Description
ingestion.started	Ingestion job started
ingestion.progress	Progress update (every 10%)
ingestion.completed	Ingestion completed successfully
ingestion.failed	Ingestion failed
ingestion.needs_review	AI found ambiguities requiring user review

---

Error Responses

Status	Code	Description
400	unsupported_format	File format not supported
400	invalid_schema	Data doesn't match expected schema
400	missing_required_fields	Required fields missing
413	file_too_large	File exceeds 100MB limit
422	alignment_failed	Schema alignment AI failed

---

Related Documentation

• Menus API - Menu management
• Inventory API - Inventory management
• Employees API - Employee management
• ML Training API - Model training pipeline