API Docs — MAYA ADMIN

API Base URL

Use the following endpoint path prefix for making consumer query API calls: https://maaya-portal.kallapotti.com

Direct R2 Access Design

MAYA ADMIN uses direct R2 bucket keys for models. Retrieve them directly via the public bucket prefix: https://maaya-assets.kallapotti.com

Consumer Query APIs

GET /api/products

List all products and their aggregated tag/model/variant metadata counts

Response Payload

[
  {
    "id": "2e018d4d-f9e2-4148-be2d-944a1796abcd",
    "name": "Luxury Sofa",
    "description": "Premium leather sofa",
    "price": 10000,
    "cgst": 9,
    "sgst": 9,
    "igst": 18,
    "retail_price": 11800,
    "images": [
      "product-images/1_sofa_front.jpg",
      "product-images/2_sofa_side.jpg"
    ],
    "tag_ids": "[\"9f018d4d-f9e2-4148-be2d-944a17961234\"]",
    "model_ids": "[\"7fa2a884-9fb5-4221-bf96-b63394595ad2\"]",
    "created_at": "2026-08-12T05:08:51",
    "image_count": 2,
    "tag_count": 1,
    "model_count": 1,
    "variant_count": 2
  }
]

curl -X GET https://maaya-portal.kallapotti.com/api/products

GET /api/product/[id]

Fetch full details of a single product including tags, base 3D models, all variant details (with models), and recommended products (with full details). Works with /api/product/[id] or /api/products/[id].

Response Payload

{
  "id": "1",
  "name": "Luxury Sofa",
  "description": "Premium leather sofa",
  "price": 10000,
  "cgst": 9,
  "sgst": 9,
  "igst": 18,
  "retail_price": 11800,
  "pointer_3d": "sofa_pointer",
  "images": [
    "product-images/1_sofa_front.jpg",
    "product-images/2_sofa_side.jpg"
  ],
  "tag_ids": "[\"9f018d4d-f9e2-4148-be2d-944a17961234\"]",
  "model_ids": "[\"7fa2a884-9fb5-4221-bf96-b63394595ad2\"]",
  "recommendation_ids": [
    "2"
  ],
  "tags": [
    {
      "id": "9f018d4d-f9e2-4148-be2d-944a17961234",
      "name": "Furniture"
    }
  ],
  "models": [
    {
      "id": "7fa2a884-9fb5-4221-bf96-b63394595ad2",
      "r2_key": "models/sofa.glb",
      "original_filename": "sofa.glb",
      "file_type": "glb",
      "file_size": 16581665
    }
  ],
  "variants": [
    {
      "id": "5c018d4d-f9e2-4148-be2d-944a1796efgh",
      "product_id": "1",
      "sku": "SOFA-RED-LRG",
      "attributes": [
        {
          "attribute_name": "color",
          "attribute_value": "Red"
        }
      ],
      "model_ids": [
        "7fa2a884-9fb5-4221-bf96-b63394595ad2"
      ],
      "models": [
        {
          "id": "7fa2a884-9fb5-4221-bf96-b63394595ad2",
          "r2_key": "models/sofa.glb",
          "original_filename": "sofa.glb",
          "file_type": "glb",
          "file_size": 16581665
        }
      ]
    }
  ],
  "recommendations": [
    {
      "id": "2",
      "name": "Matching Coffee Table",
      "description": "Oak coffee table",
      "price": 4000,
      "cgst": 9,
      "sgst": 9,
      "igst": 18,
      "retail_price": 4720,
      "pointer_3d": "table_pointer",
      "tags": [
        {
          "id": "9f018d4d-f9e2-4148-be2d-944a17961234",
          "name": "Furniture"
        }
      ],
      "models": [
        {
          "id": "8ab3b995-1234-4567-8901-abcdef123456",
          "r2_key": "models/table.glb",
          "original_filename": "table.glb",
          "file_type": "glb",
          "file_size": 8392100
        }
      ],
      "variants": [
        {
          "id": "6d029e5e-1111-2222-3333-444455556666",
          "product_id": "2",
          "sku": "TBL-OAK-STD",
          "attributes": [
            {
              "attribute_name": "material",
              "attribute_value": "Oak Wood"
            }
          ],
          "model_ids": [
            "8ab3b995-1234-4567-8901-abcdef123456"
          ],
          "models": [
            {
              "id": "8ab3b995-1234-4567-8901-abcdef123456",
              "r2_key": "models/table.glb",
              "original_filename": "table.glb",
              "file_type": "glb",
              "file_size": 8392100
            }
          ]
        }
      ],
      "recommendation_ids": [],
      "recommendations": []
    }
  ]
}

curl -X GET https://maaya-portal.kallapotti.com/api/product/1

GET /api/variants

List variants, optionally filtered by a specific product (?product_id=uuid)

Parameters

Optional query filters:

Parameter	Type	Required	Description
`product_id`	String (UUID)	No	Filters variants that belong to this specific product.

Response Payload

[
  {
    "id": "5c018d4d-f9e2-4148-be2d-944a1796efgh",
    "product_id": "2e018d4d-f9e2-4148-be2d-944a1796abcd",
    "sku": "SOFA-RED-LRG",
    "attributes": [
      {
        "attribute_name": "color",
        "attribute_value": "Red"
      },
      {
        "attribute_name": "size",
        "attribute_value": "Large"
      }
    ],
    "model_ids": [
      "7fa2a884-9fb5-4221-bf96-b63394595ad2"
    ],
    "created_at": "2026-08-12T05:09:46"
  }
]

curl -X GET https://maaya-portal.kallapotti.com/api/variants?product_id=2e018d4d-f9e2-4148-be2d-944a1796abcd

3D Models APIs

GET /api/models

List all 3D assets, optionally filtering by search string (?q=search)

Parameters

Optional filters:

Parameter	Type	Required	Description
`q`	String	No	Search queries matching original filenames or extension types.

Response Payload

[
  {
    "id": "1",
    "r2_key": "models/1_IronMan.obj",
    "original_filename": "IronMan.obj",
    "file_type": "obj",
    "file_size": 16581665,
    "thumbnail_r2_key": null,
    "tag_ids": [
      "b74d46ce-77b1-4378-bb4a-5726c303f820"
    ],
    "created_at": "2026-08-12T06:34:12",
    "tags": [
      {
        "id": "b74d46ce-77b1-4378-bb4a-5726c303f820",
        "name": "Avengers"
      }
    ]
  }
]

curl -X GET https://maaya-portal.kallapotti.com/api/models?q=IronMan

GET /api/model/[id]

Fetch full details of a single 3D model by numeric ID. Works with /api/model/[id], /api/models/[id], or /api/models?id=1.

Response Payload

{
  "id": "1",
  "r2_key": "models/1_IronMan.obj",
  "original_filename": "IronMan.obj",
  "file_type": "obj",
  "file_size": 16581665,
  "thumbnail_r2_key": null,
  "tag_ids": [
    "b74d46ce-77b1-4378-bb4a-5726c303f820"
  ],
  "created_at": "2026-08-12T06:34:12",
  "tags": [
    {
      "id": "b74d46ce-77b1-4378-bb4a-5726c303f820",
      "name": "Avengers"
    }
  ]
}

curl -X GET https://maaya-portal.kallapotti.com/api/model/1

Model Categories APIs

GET /api/model-categories

List all 3D model categories. Works with /api/model-categories, /api/model-categories/[id], or /api/model-category/[id].

Response Payload

[
  {
    "id": "e058d8df-3391-4123-987e-156377f25339",
    "number": "1",
    "name": "character",
    "created_at": "2026-08-12T18:07:35"
  },
  {
    "id": "ddc0c529-cd8b-4b3a-b99e-d26e7d7142ae",
    "number": "2",
    "name": "home",
    "created_at": "2026-08-12T18:07:45"
  }
]

curl -X GET https://maaya-portal.kallapotti.com/api/model-categories

Tags APIs

GET /api/tags

List all category classification tags

Response Payload

[
  {
    "id": "9f018d4d-f9e2-4148-be2d-944a17961234",
    "name": "Furniture",
    "created_at": "2026-08-12T04:58:38"
  },
  {
    "id": "b6a45e5d-51ae-4034-b90b-f8047de16eef",
    "name": "Featured",
    "created_at": "2026-08-12T05:08:51"
  }
]

curl -X GET https://maaya-portal.kallapotti.com/api/tags

Cart & Shopping APIs

GET /api/cart

Fetch the user's cart (1 row per user) with populated product details, 3D model links, pricing subtotals, tax breakdown, and grand total.

Parameters

Required authentication / identification:

Parameter	Type	Required	Description
`user_id`	String	Yes	User ID (e.g. `?user_id=usr_demo_01` or header `x-user-id`).

Response Payload

{
  "id": "crt_demo_01",
  "user_id": "usr_demo_01",
  "items": [
    {
      "id": "it_demo_01",
      "product_id": "2",
      "name": "Garden Urn",
      "qty": 2,
      "variant_id": null,
      "sku": "",
      "price": 1200,
      "retail_price": 1416,
      "cgst": 9,
      "sgst": 9,
      "igst": 18,
      "item_subtotal": 2400,
      "item_retail_total": 2832,
      "thumbnail_url": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
      "models": [
        {
          "id": "3",
          "r2_key": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
          "original_filename": "garden-urn.glb",
          "file_type": "glb",
          "file_size": 38420
        }
      ],
      "added_at": "2026-08-18T13:10:00.000Z",
      "updated_at": "2026-08-18T13:10:50.000Z"
    }
  ],
  "summary": {
    "total_items": 2,
    "total_unique_items": 1,
    "subtotal": 2400,
    "total_cgst": 216,
    "total_sgst": 216,
    "total_igst": 432,
    "total_tax": 864,
    "grand_total": 2832
  },
  "created_at": "2026-08-18T13:05:07",
  "updated_at": "2026-08-18T13:10:50"
}

curl -X GET "https://maaya-portal.kallapotti.com/api/cart?user_id=usr_demo_01"

POST /api/cart

Add a new product to the cart or automatically increment the quantity if the product/variant is already present.

JSON Body Parameters

Field	Type	Required	Description
`user_id`	String	Yes	Target user ID (e.g. `usr_demo_01`).
`product_id`	String	Yes	Numeric or UUID product ID (e.g. `"2"`).
`variant_id`	String	No	Optional variant ID for products with multiple SKUs.
`qty`	Number	No	Quantity to add (defaults to `1`).

Response Payload

{
  "success": true,
  "message": "Item added to cart",
  "cart": {
    "id": "crt_demo_01",
    "user_id": "usr_demo_01",
    "items": [
      {
        "id": "it_demo_01",
        "product_id": "2",
        "name": "Garden Urn",
        "qty": 2,
        "variant_id": null,
        "sku": "",
        "price": 1200,
        "retail_price": 1416,
        "cgst": 9,
        "sgst": 9,
        "igst": 18,
        "item_subtotal": 2400,
        "item_retail_total": 2832,
        "thumbnail_url": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
        "models": [
          {
            "id": "3",
            "r2_key": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
            "original_filename": "garden-urn.glb",
            "file_type": "glb",
            "file_size": 38420
          }
        ],
        "added_at": "2026-08-18T13:10:00.000Z",
        "updated_at": "2026-08-18T13:10:50.000Z"
      }
    ],
    "summary": {
      "total_items": 2,
      "total_unique_items": 1,
      "subtotal": 2400,
      "total_cgst": 216,
      "total_sgst": 216,
      "total_igst": 432,
      "total_tax": 864,
      "grand_total": 2832
    },
    "created_at": "2026-08-18T13:05:07",
    "updated_at": "2026-08-18T13:10:50"
  }
}

curl -X POST https://maaya-portal.kallapotti.com/api/cart \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_demo_01", "product_id": "2", "qty": 1}'

PATCH /api/cart

Update the quantity of a product in the cart, or increment/decrement with delta (+1, -1). Setting quantity to 0 removes the item.

JSON Body Parameters

Field	Type	Required	Description
`user_id`	String	Yes	Target user ID.
`product_id`	String	Yes*	Product ID (*or provide `item_id`).
`qty`	Number	No	Sets exact new quantity.
`delta`	Number	No	Relative change (+1 to increment, -1 to decrement).

Response Payload

{
  "success": true,
  "message": "Cart updated",
  "cart": {
    "id": "crt_demo_01",
    "user_id": "usr_demo_01",
    "items": [
      {
        "id": "it_demo_01",
        "product_id": "2",
        "name": "Garden Urn",
        "qty": 2,
        "variant_id": null,
        "sku": "",
        "price": 1200,
        "retail_price": 1416,
        "cgst": 9,
        "sgst": 9,
        "igst": 18,
        "item_subtotal": 2400,
        "item_retail_total": 2832,
        "thumbnail_url": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
        "models": [
          {
            "id": "3",
            "r2_key": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
            "original_filename": "garden-urn.glb",
            "file_type": "glb",
            "file_size": 38420
          }
        ],
        "added_at": "2026-08-18T13:10:00.000Z",
        "updated_at": "2026-08-18T13:10:50.000Z"
      }
    ],
    "summary": {
      "total_items": 2,
      "total_unique_items": 1,
      "subtotal": 2400,
      "total_cgst": 216,
      "total_sgst": 216,
      "total_igst": 432,
      "total_tax": 864,
      "grand_total": 2832
    },
    "created_at": "2026-08-18T13:05:07",
    "updated_at": "2026-08-18T13:10:50"
  }
}

curl -X PATCH https://maaya-portal.kallapotti.com/api/cart \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_demo_01", "product_id": "2", "delta": 1}'

DELETE /api/cart

Remove a product from the cart by product ID / item ID, or clear the entire cart with clear=true.

Query Parameters / Body

Field	Type	Required	Description
`user_id`	String	Yes	Target user ID.
`product_id`	String	No	Product to remove.
`item_id`	String	No	Cart item unique ID to remove.
`clear`	Boolean	No	Pass `true` to wipe all items from cart.

Response Payload

{
  "success": true,
  "message": "Item removed from cart",
  "cart": {
    "id": "crt_demo_01",
    "user_id": "usr_demo_01",
    "items": [],
    "summary": {
      "total_items": 2,
      "total_unique_items": 1,
      "subtotal": 2400,
      "total_cgst": 216,
      "total_sgst": 216,
      "total_igst": 432,
      "total_tax": 864,
      "grand_total": 2832
    },
    "created_at": "2026-08-18T13:05:07",
    "updated_at": "2026-08-18T13:10:50"
  }
}

curl -X DELETE "https://maaya-portal.kallapotti.com/api/cart?user_id=usr_demo_01&product_id=2"

Wishlist APIs

D1 Table: wishlist 1 Row Per User · Cascade Delete on Users · Auto-Enriched Products

The Wishlist system maintains persistent saved items per customer. All queries are strictly isolated to the specified user_id (sent as a query param or x-user-id header). When fetching a wishlist, item entries are automatically populated with real-time product prices, tax rates (CGST/SGST/IGST), variant details, and 3D model links.

GET /api/wishlist

Fetch the particular user's wishlist (1 row per user) with populated product details, 3D models, variants, and notes.

Parameters

User identification:

Parameter	Type	Required	Description
`user_id`	String	Yes	Target user ID (e.g. `?user_id=usr_demo_01` or header `x-user-id`).

Response Payload

{
  "id": "wsh_e158d8df-1111-4223-987e-156377f25339",
  "user_id": "usr_demo_01",
  "total_items": 1,
  "items": [
    {
      "id": "witem_9fa2a884-9fb5-4221-bf96-b63394595ad2",
      "product_id": "2",
      "name": "Garden Urn",
      "variant_id": null,
      "variant": null,
      "sku": "",
      "attributes": [],
      "price": 1200,
      "retail_price": 1416,
      "cgst": 9,
      "sgst": 9,
      "igst": 18,
      "thumbnail_url": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
      "models": [
        {
          "id": "3",
          "r2_key": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
          "original_filename": "garden-urn.glb",
          "file_type": "glb",
          "file_size": 38420
        }
      ],
      "images": [],
      "tags": [
        {
          "id": "9f018d4d-f9e2-4148-be2d-944a17961234",
          "name": "Decor"
        }
      ],
      "notes": "Saved for patio renovation",
      "added_at": "2026-08-28T22:15:00.000Z",
      "updated_at": "2026-08-28T22:15:00.000Z"
    }
  ],
  "created_at": "2026-08-28T22:10:00",
  "updated_at": "2026-08-28T22:15:00"
}

curl -X GET "https://maaya-portal.kallapotti.com/api/wishlist?user_id=usr_demo_01"

POST /api/wishlist

Add a product to the user's wishlist or toggle its presence with toggle: true.

JSON Body Parameters

Field	Type	Required	Description
`user_id`	String	Yes	Target user ID (e.g. `usr_demo_01`).
`product_id`	String	Yes	Product ID to save to wishlist (e.g. `"2"`).
`variant_id`	String	No	Optional variant ID if wishlisting a specific variant.
`notes`	String	No	Optional customer note or memo for this item.
`toggle`	Boolean	No	If `true`, removes the item if already in wishlist, or adds it if absent.

Response Payload

{
  "success": true,
  "message": "Item added to wishlist",
  "wishlist": {
    "id": "wsh_e158d8df-1111-4223-987e-156377f25339",
    "user_id": "usr_demo_01",
    "total_items": 1,
    "items": [
      {
        "id": "witem_9fa2a884-9fb5-4221-bf96-b63394595ad2",
        "product_id": "2",
        "name": "Garden Urn",
        "variant_id": null,
        "variant": null,
        "sku": "",
        "attributes": [],
        "price": 1200,
        "retail_price": 1416,
        "cgst": 9,
        "sgst": 9,
        "igst": 18,
        "thumbnail_url": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
        "models": [
          {
            "id": "3",
            "r2_key": "models/46059f3f-f7f9-44fd-adc3-9b623b4c4025_garden-urn.glb",
            "original_filename": "garden-urn.glb",
            "file_type": "glb",
            "file_size": 38420
          }
        ],
        "images": [],
        "tags": [
          {
            "id": "9f018d4d-f9e2-4148-be2d-944a17961234",
            "name": "Decor"
          }
        ],
        "notes": "Saved for patio renovation",
        "added_at": "2026-08-28T22:15:00.000Z",
        "updated_at": "2026-08-28T22:15:00.000Z"
      }
    ],
    "created_at": "2026-08-28T22:10:00",
    "updated_at": "2026-08-28T22:15:00"
  }
}

curl -X POST https://maaya-portal.kallapotti.com/api/wishlist \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_demo_01", "product_id": "2", "notes": "Saved for patio renovation"}'

DELETE /api/wishlist

Remove an item from the user's wishlist by product ID or item ID, or clear the entire wishlist with clear=true.

Query Parameters / Body

Field	Type	Required	Description
`user_id`	String	Yes	Target user ID.
`product_id`	String	No	Product to remove from wishlist.
`item_id`	String	No	Wishlist item unique ID to remove.
`clear`	Boolean	No	Pass `true` to clear all items in wishlist.

Response Payload

{
  "success": true,
  "message": "Item removed from wishlist",
  "wishlist": {
    "id": "wsh_e158d8df-1111-4223-987e-156377f25339",
    "user_id": "usr_demo_01",
    "total_items": 0,
    "items": [],
    "created_at": "2026-08-28T22:10:00",
    "updated_at": "2026-08-28T22:15:00"
  }
}

curl -X DELETE "https://maaya-portal.kallapotti.com/api/wishlist?user_id=usr_demo_01&product_id=2"

API Documentation

API Documentation

API Base URL

Direct R2 Access Design

Consumer Query APIs

Response Payload

Response Payload

Parameters

Response Payload

3D Models APIs

Parameters

Response Payload

Response Payload

Model Categories APIs

Response Payload

Tags APIs

Response Payload

Cart & Shopping APIs

Parameters

Response Payload

JSON Body Parameters

Response Payload

JSON Body Parameters

Response Payload

Query Parameters / Body

Response Payload

Wishlist APIs

Parameters

Response Payload

JSON Body Parameters

Response Payload

Query Parameters / Body

Response Payload