Data Composer Demo API

Unified API Base URL
https://api.mapmydata.app/v1
Auth Token URL
https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token

Overview

This is a demo endpoint created to validate orchestration flows in Data Composer. A common pattern is to authenticate once, fetch products filtered by category, extract a product ID from the list response, request the product details from /products/[id], and then request the related review data from /products/[id]/reviews.

Authentication

The API uses the OAuth 2.0 Client Credentials flow. Clients exchange a client_id and client_secret for a bearer access token, then include that token on subsequent API requests.

Token endpoint

POST https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token

Use this endpoint to request an access token for the https://api.mapmydata.app/ audience.

Required request fields

Field Description
client_id OAuth client identifier
client_secret OAuth client secret
audience https://api.mapmydata.app/
grant_type client_credentials
Request access tokencurl
curl --request POST \
  --url https://dev-ij8d8xnp6zjae8hn.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id":"YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "audience":"https://api.mapmydata.app/",
    "grant_type":"client_credentials"
  }'
Successful token responsejson
{
  "access_token": "eyJ...",
  "expires_in": 86400,
  "token_type": "Bearer"
}
Use token on API requestshttp
Authorization: Bearer YOUR_ACCESS_TOKEN

List products (with optional filters)

GET /products

Returns a paginated collection of products. Supports filtering, sorting, and keyword search spanning multiple connected systems to support browsing, incremental retrieval, and operational workflows.

Supported query parameters

Parameter Description Example
page Page number 1
limit Page size 25
sort Sort by name, price, brand, category, inventory, updated_at, or sku price
order asc or desc asc
brand Filter by brand Acme
category Filter by category Footwear
department Filter by department Women
active Filter by active status true
min_price Minimum price filter 20
max_price Maximum price filter 100
q Keyword search across selected fields trail
inventory Exact inventory quantity match 47
min_inventory Minimum inventory quantity filter 10
max_inventory Maximum inventory quantity filter 100
Example requestcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products?page=1&limit=25&brand=Acme&sort=price&order=asc' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Example responsejson
{
  "data": [
    {
      "id": "prod_nrt3e91199",
      "external_id": "ext_catalog_nrt_1001",
      "sku": "NRT-TRN-SLP-OCN",
      "name": "Trail Terrain Slip-On",
      "display_name": "Northstar Trail Terrain Slip-On - Ocean",
      "brand": "Northstar",
      "category": "Apparel",
      "department": "Women",
      "price": 23.49,
      "currency": "USD",
      "inventory": 47,
      "active": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1000,
    "has_next": true,
    "has_prev": false
  },
  "sort": {
    "field": "price",
    "order": "asc"
  },
  "applied_filters": {
    "brand": "Acme",
    "category": null,
    "department": null,
    "active": null,
    "min_price": null,
    "max_price": null,
    "inventory": null,
    "min_inventory": null,
    "max_inventory": null,
    "q": null
  }
}

Get product by ID

GET /products/[id]

Returns the complete product object for a specific internal identifier. Reviews are not returned in this response and must be requested separately from /products/[id]/reviews.

Example requestcurl
curl --request GET \
  --url https://api.mapmydata.app/products/prod_nrt3e91199 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Example responsejson
{
  "data": {
    "id": "prod_nrt3e91199",
    "external_id": "ext_catalog_nrt_1001",
    "sku": "NRT-TRN-SLP-OCN",
    "name": "Trail Terrain Slip-On",
    "display_name": "Northstar Trail Terrain Slip-On - Ocean",
    "brand": "Northstar",
    "category": "Apparel",
    "department": "Women",
    "price": 23.49,
    "currency": "USD",
    "inventory": 47,
    "active": true,
    "tags": ["northstar", "apparel", "summer", "blue"],
    "image_url": "https://images.nexusdemo.app/products/prod_nrt3e91199/primary.jpg",
    "attributes": {
      "color": "blue",
      "color_label": "Ocean",
      "size": "M",
      "material": "mesh",
      "season": "Summer",
      "dimensions": {
        "width_in": 8.5,
        "height_in": 10.4,
        "depth_in": 2.25
      },
      "care": {
        "washable": true,
        "wash_method": "machine_wash",
        "dryer_safe": false
      },
      "rating": {
        "average": 4.2,
        "count": 1011
      }
    },
    "pricing": {
      "list": 33.99,
      "sale": 23.49,
      "markdown": true,
      "promotions": [
        {
          "code": "PROMO1",
          "description": "Seasonal markdown",
          "amount_off": 7,
          "stackable": false
        }
      ]
    },
    "availability": {
      "online": true,
      "store_pickup": true,
      "backorderable": false,
      "inventory_by_location": [
        { "location_id": "store_dallas", "location_type": "store", "quantity": 6 },
        { "location_id": "store_chicago", "location_type": "store", "quantity": 9 },
        { "location_id": "wh_tx_01", "location_type": "warehouse", "quantity": 45 }
      ]
    },
    "media": {
      "primary_image": {
        "url": "https://images.nexusdemo.app/products/prod_nrt3e91199/primary.jpg",
        "alt_text": "Northstar Trail Terrain Slip-On - Ocean primary image"
      },
      "gallery": [
        {
          "type": "image",
          "url": "https://images.nexusdemo.app/products/prod_nrt3e91199/1.jpg",
          "sort_order": 1,
          "metadata": { "angle": "front", "background": "white" }
        },
        {
          "type": "image",
          "url": "https://images.nexusdemo.app/products/prod_nrt3e91199/2.jpg",
          "sort_order": 2,
          "metadata": { "angle": "side", "background": "white" }
        }
      ],
      "videos": [
        {
          "url": "https://videos.nexusdemo.app/products/prod_nrt3e91199/overview.mp4",
          "duration_seconds": 30,
          "captions": { "en": true, "es": true }
        }
      ]
    },
    "variants": [
      {
        "variant_id": "var_nrt3e9a",
        "sku": "NRT-TRN-SLP-OCN-M",
        "color": "blue",
        "size": "M",
        "inventory": 6,
        "pricing": { "list": 33.99, "sale": 23.49 },
        "identifiers": { "upc": "000100101", "ean": "1000000100101" }
      }
    ],
    "related_products": [
      { "relationship_type": "cross_sell", "product_id": "prod_nrt3ea7ba", "score": 0.9 },
      { "relationship_type": "upsell", "product_id": "prod_nrt3eb8cb", "score": 0.8 }
    ],
    "seo": {
      "slug": "northstar-trail-terrain-slip-on-blue",
      "meta": {
        "title": "Northstar Trail Terrain Slip-On - Ocean | Northstar",
        "description": "Shop Northstar Trail Terrain Slip-On - Ocean from Northstar in Apparel."
      }
    },
    "compliance": {
      "country_of_origin": "VN",
      "restricted_states": [],
      "hazardous_material": false
    },
    "audit": {
      "created_at": "2025-01-22T00:00:00.000Z",
      "updated_at": "2026-01-22T00:00:00.000Z",
      "source": {
        "system": "nexusgraph-orchestrator",
        "version": "1.0.0",
        "batch": "seed_batch_40"
      }
    }
  }
}

Get product reviews

GET /products/[id]/reviews

Returns reviews for a specific product. This is the only endpoint that returns review data. Use the same product ID returned from /products or /products/[id].

Parameter Description Example
page Page number 1
limit Number of reviews per page 10
sort Sort by created_at, rating, or helpfulness helpfulness
order asc or desc desc
min_rating Minimum rating filter 4
max_rating Maximum rating filter 5
verified_buyer Filter by verified buyer status true
Example requestcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products/prod_nrt3e94279/reviews?min_rating=4&sort=helpfulness&order=desc&limit=5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Example responsejson
{
  "data": [
    {
      "review_id": "rev_1001_1",
      "product_id": "prod_nrt3e94279",
      "rating": 5,
      "title": "Great fit and quality",
      "created_at": "2026-06-25T00:00:00.000Z",
      "verified_buyer": true,
      "author": {
        "id": "user_1001_1",
        "name": "Demo User 1001A",
        "badges": ["verified_buyer", "top_reviewer"]
      },
      "content": {
        "summary": "Really liked the fit and finish.",
        "pros": ["Comfortable", "Stylish", "Good value"],
        "cons": ["Runs slightly small"]
      },
      "media": [
        {
          "type": "image",
          "url": "https://images.mapmydata.app/reviews/rev_1001_1/1.jpg"
        }
      ],
      "helpfulness": {
        "upvotes": 11,
        "downvotes": 1
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 2,
    "has_next": false,
    "has_prev": false
  },
  "sort": {
    "field": "helpfulness",
    "order": "desc"
  },
  "applied_filters": {
    "min_rating": "4",
    "max_rating": null,
    "verified_buyer": null
  },
  "product": {
    "id": "prod_nrt3e94279",
    "sku": "NRT-TRN-JOG-OCN",
    "name": "Atlas Terrain Jogger"
  }
}

Bulk fetch products

GET /products/bulk?ids=...

Retrieves multiple products in a single request using a comma-separated list of product IDs. This endpoint is useful for cart hydration, recommendation retrieval, and multi-record data ingestion workflows. Maximum 100 product IDs per request.

Example requestcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products/bulk?ids=prod_nrt3e91199,prod_smt3eb11aa,prod_evr3ec11bb' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Example responsejson
{
  "data": [
    {
      "id": "prod_nrt3e91199",
      "sku": "NRT-TRN-SLP-OCN",
      "name": "Trail Terrain Slip-On"
    },
    {
      "id": "prod_smt3eb11aa",
      "sku": "SMT-TRN-RUN-CRM",
      "name": "Horizon Terrain Runner"
    }
  ],
  "missing_ids": ["prod_missing123"],
  "requested_count": 3,
  "returned_count": 2
}
Error response — too many IDsjson
{
  "error": "too_many_ids",
  "max": 100
}

Data model

The product payload is intentionally structured to support modern downstream uses including storefront rendering, synchronization pipelines, and schema-aware integrations. Review data is modeled as a separate resource and returned only from /products/[id]/reviews.

Field Type Description
id string Internal product identifier
external_id string External source-system identifier
sku string Merchant-facing SKU
name string Product name
display_name string Display-ready product name
brand string Brand name
category string Product category
department string Department (Men, Women, Kids, Unisex)
price number Current sale price
currency string ISO 4217 currency code (e.g. USD)
inventory integer Total inventory quantity
active boolean Whether the product is active
tags string[] Keyword tags for search and filtering
image_url string Top-level primary image URL shortcut
attributes object Color, size, material, season, dimensions, care instructions, and rating summary
attributes.care object Wash and care instructions (washable, wash_method, dryer_safe)
attributes.rating object Aggregate rating (average, count)
pricing object List price, sale price, markdown flag, and promotions array
availability object Online, store pickup, backorder availability, and per-location inventory
availability.store_pickup boolean Whether in-store pickup is available
availability.backorderable boolean Whether the product can be backordered
availability.inventory_by_location array Per-location inventory with location_id, location_type, and quantity
media object Primary image object, gallery array, and videos array
media.primary_image object Primary image url and alt_text
media.gallery array Gallery items with type, url, sort_order, and metadata
media.videos array Video items with url, duration_seconds, and captions
variants array Variant records with size, color, inventory, per-variant pricing, and UPC/EAN identifiers
related_products array Cross-sell and upsell references with relationship type and relevance score
seo object URL slug and meta title/description for SEO
compliance object Country of origin, restricted states, and hazardous material flag
audit object Creation and update timestamps, and source system metadata

Example nested paths

attributes.dimensions.width_in attributes.care.wash_method attributes.rating.average pricing.promotions[0].code availability.inventory_by_location[0].location_type media.primary_image.url media.gallery[0].metadata.angle media.videos[0].duration_seconds variants[0].identifiers.upc variants[0].pricing.sale related_products[0].product_id reviews[0].content.pros seo.meta.title compliance.country_of_origin audit.source.batch

JSON schema

JSON Schema for the product response object returned by /products, /products/bulk, and /products/[id]. Review data is excluded from this schema and is returned separately by /products/[id]/reviews.

Aggregated schemajson
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "type": "object",
  "properties": {
    "id":           { "type": "string",  "description": "Internal product identifier" },
    "external_id":  { "type": "string",  "description": "Source system identifier" },
    "sku":          { "type": "string",  "description": "Merchant-facing SKU" },
    "name":         { "type": "string",  "description": "Product name" },
    "display_name": { "type": "string",  "description": "Display-ready product name" },
    "brand":        { "type": "string" },
    "category":     { "type": "string" },
    "department":   { "type": "string" },
    "price":        { "type": "number" },
    "currency":     { "type": "string",  "example": "USD" },
    "inventory":    { "type": "integer" },
    "active":       { "type": "boolean" },
    "tags":         { "type": "array", "items": { "type": "string" } },
    "image_url":    { "type": "string", "format": "uri", "description": "Top-level primary image URL" },

    "attributes": {
      "type": "object",
      "properties": {
        "color":       { "type": "string" },
        "color_label": { "type": "string" },
        "size":        { "type": "string" },
        "material":    { "type": "string" },
        "season":      { "type": "string" },
        "dimensions": {
          "type": "object",
          "properties": {
            "width_in":  { "type": "number" },
            "height_in": { "type": "number" },
            "depth_in":  { "type": "number" }
          }
        },
        "care": {
          "type": "object",
          "properties": {
            "washable":    { "type": "boolean" },
            "wash_method": { "type": "string", "enum": ["machine_wash", "hand_wash"] },
            "dryer_safe":  { "type": "boolean" }
          }
        },
        "rating": {
          "type": "object",
          "properties": {
            "average": { "type": "number", "minimum": 1, "maximum": 5 },
            "count":   { "type": "integer" }
          }
        }
      }
    },

    "pricing": {
      "type": "object",
      "properties": {
        "list":     { "type": "number" },
        "sale":     { "type": "number" },
        "markdown": { "type": "boolean" },
        "promotions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code":        { "type": "string" },
              "description": { "type": "string" },
              "amount_off":  { "type": "number" },
              "stackable":   { "type": "boolean" }
            }
          }
        }
      }
    },

    "availability": {
      "type": "object",
      "properties": {
        "online":        { "type": "boolean" },
        "store_pickup":  { "type": "boolean" },
        "backorderable": { "type": "boolean" },
        "inventory_by_location": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "location_id":   { "type": "string" },
              "location_type": { "type": "string", "enum": ["store", "warehouse"] },
              "quantity":      { "type": "integer" }
            }
          }
        }
      }
    },

    "media": {
      "type": "object",
      "properties": {
        "primary_image": {
          "type": "object",
          "properties": {
            "url":      { "type": "string", "format": "uri" },
            "alt_text": { "type": "string" }
          }
        },
        "gallery": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type":       { "type": "string", "enum": ["image"] },
              "url":        { "type": "string", "format": "uri" },
              "sort_order": { "type": "integer" },
              "metadata": {
                "type": "object",
                "properties": {
                  "angle":      { "type": "string" },
                  "background": { "type": "string" }
                }
              }
            }
          }
        },
        "videos": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url":              { "type": "string", "format": "uri" },
              "duration_seconds": { "type": "integer" },
              "captions": {
                "type": "object",
                "additionalProperties": { "type": "boolean" }
              }
            }
          }
        }
      }
    },

    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "variant_id": { "type": "string" },
          "sku":        { "type": "string" },
          "color":      { "type": "string" },
          "size":       { "type": "string" },
          "inventory":  { "type": "integer" },
          "pricing": {
            "type": "object",
            "properties": {
              "list": { "type": "number" },
              "sale": { "type": "number" }
            }
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "upc": { "type": "string" },
              "ean": { "type": "string" }
            }
          }
        }
      }
    },

    "related_products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "relationship_type": { "type": "string", "enum": ["cross_sell", "upsell"] },
          "product_id":        { "type": "string" },
          "score":             { "type": "number", "minimum": 0, "maximum": 1 }
        }
      }
    },

    "seo": {
      "type": "object",
      "properties": {
        "slug": { "type": "string" },
        "meta": {
          "type": "object",
          "properties": {
            "title":       { "type": "string" },
            "description": { "type": "string" }
          }
        }
      }
    },

    "compliance": {
      "type": "object",
      "properties": {
        "country_of_origin":  { "type": "string" },
        "restricted_states":  { "type": "array", "items": { "type": "string" } },
        "hazardous_material": { "type": "boolean" }
      }
    },

    "audit": {
      "type": "object",
      "properties": {
        "created_at": { "type": "string", "format": "date-time" },
        "updated_at": { "type": "string", "format": "date-time" },
        "source": {
          "type": "object",
          "properties": {
            "system":  { "type": "string" },
            "version": { "type": "string" },
            "batch":   { "type": "string" }
          }
        }
      }
    }
  }
}

Testing & sample values

Use the values below to explore the unified endpoints. All IDs and parameter values reference real records resolving across the connected underlying graph.

Sample product IDs

Pass any of these to /products/[id], /products/[id]/reviews, or combine them for a /products/bulk request.

prod_nrt3e94279 prod_acm3e97a9 prod_smt3eb11aa prod_evr3ec22bb

Query parameters — GET /products

Category

Footwear Apparel Accessories Outerwear

Brand

Acme Northstar Summit Evertrail

Department

Men Women Kids Unisex

Price filters

min_price=20 max_price=100

Inventory filters

min_inventory=10 max_inventory=50 inventory=0

Search keywords

runner trail acme midnight cotton

Query parameters — GET /products/[id]/reviews

Ratings

min_rating=4 max_rating=5

Verified buyer

verified_buyer=true verified_buyer=false

Review sorting

sort=created_at&order=desc sort=rating&order=desc sort=helpfulness&order=desc

Sort options

sort=price&order=asc sort=price&order=desc sort=inventory&order=desc sort=updated_at&order=desc sort=name&order=asc

Example requests

Filtered + sorted listcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products?category=Footwear&brand=Northstar&min_inventory=10&sort=price&order=desc&limit=5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Keyword searchcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products?q=trail&limit=5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Bulk fetchcurl
curl --request GET \
  --url 'https://api.mapmydata.app/products/bulk?ids=prod_nrt3e94279,prod_acm3e97a9,prod_smt3eb11aa' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Data Composer flows

Basic chain

  1. GET /products?category=Footwear&limit=3
  2. Extract product ID
  3. GET /products/[id]
  4. GET /products/[id]/reviews

Filtered + enriched

  1. GET /products?brand=Acme&min_inventory=20&limit=5
  2. Extract IDs
  3. GET /products/bulk?ids=...
  4. GET /products/[id]/reviews?min_rating=4

Search driven

  1. GET /products?q=trail&limit=5
  2. Extract product ID
  3. GET /products/[id]
  4. GET /products/[id]/reviews?sort=helpfulness

Health endpoint

GET /health

Returns a lightweight operational status response for platform and integration monitoring. Does not require authentication.

Example responsejson

{
"ok":true,
"message":"Demo product API is running"
}

Error responses

401 Unauthorized

Returned when the Authorization header is absent, or when the bearer token is malformed, expired, or has an invalid audience.

Missing tokenjson
{
  "error": "missing_bearer_token"
}
Invalid tokenjson
{
  "error": "unauthorized"
}

404 Not Found

Returned when a requested product ID does not exist in the catalog.

Examplejson
{
  "error": "product_not_found",
  "id": "prod_unknown"
}

400 Bad Request

Returned when required request parameters are missing, malformed, or exceed endpoint limits.

Examplejson
{
  "error": "missing_ids",
  "message": "Provide ids as a comma-separated query param."
}

{
  "error": "too_many_ids",
  "max": 100
}

{
  "error": "invalid_numeric_filter"
}