API Calls

Base: https://api.g3nretailstack.com/visualgrid

Source of truth: /internal-docs/visualgrid-openapi.yaml → /visualgrid/openapi.yaml

Notes: samples are schema-derived placeholders. Replace placeholder values (ORGCODE, SESSION_GUID, etc.) with real values.

Inventory

Method	Path	Summary	Request schema	Response schema
POST	/visualgrid/node/children	Get paginated child nodes	NodeChildrenRequest	NodeChildrenResponse
POST	/visualgrid/node/export	Export a single node as JSON	NodeExportRequest	NodeExportResponse
POST	/visualgrid/node/history	Get temporal history for a node	NodeHistoryRequest	NodeHistoryResponse
POST	/visualgrid/node/load	Load a single node	NodeLoadRequest	NodeLoadResponse
GET	/visualgrid/ping	Health check	None	PingResponse
POST	/visualgrid/root/auth	Authenticate with root secret code	RootAuthRequest	RootAuthResponse
GET	/visualgrid/root/graph	Get top-level entry nodes (all tables)	None	GraphEntryResponse
POST	/visualgrid/root/graph	Get top-level entry nodes (all tables) — POST variant	None	GraphEntryResponse
GET	/visualgrid/schema	Get full schema registry graph	None	SchemaGraphResponse

Call details

POST /visualgrid/node/children

Purpose: Get paginated child nodes

Notes: Fetch paginated children of a node. Children share the same PK and have sort keys matching a given prefix. Uses DDB Query with KeyConditionExpression on PK and optional SK begins_with. Root-only access.

Request schema: NodeChildrenRequest Response schema: NodeChildrenResponse

Sample request (schema-derived)

{
  "table": "uas_main",
  "pk": "USER#u_abc123"
}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "children": [
      {
        "ddb_keys": {
          "PK": "USER#u_abc123",
          "SK": "USER#META"
        },
        "properties": {
          "status": "verified",
          "caption": "John Doe",
          "passcode_hash": "...h8i9j0k1"
        },
        "metadata": {
          "service_code": null,
          "table": null,
          "record_type": null
        }
      }
    ],
    "next_token": "string",
    "count": 0
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /visualgrid/node/children",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /visualgrid/node/export

Purpose: Export a single node as JSON

Notes: Export a single node formatted for clipboard copy or file download. Same data as node/load but wrapped in an export envelope with timestamp. Root-only access.

Request schema: NodeExportRequest Response schema: NodeExportResponse

Sample request (schema-derived)

{
  "table": "scm_main",
  "pk": "ORG#myorg#ORDER",
  "sk": "ORDER#ord_abc123"
}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "export": {
      "table": "scm_main",
      "pk": "ORG#myorg#ORDER",
      "sk": "ORDER#ord_abc123"
    }
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /visualgrid/node/export",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /visualgrid/node/history

Purpose: Get temporal history for a node

Notes: Returns timestamped version history for a DDB item by querying audit/changelog records. Root-only access.

Request schema: NodeHistoryRequest Response schema: NodeHistoryResponse

Sample request (schema-derived)

{
  "table": "uas_main",
  "pk": "USER#u_abc123",
  "sk": "USER#META",
  "limit": 25,
  "next_token": null
}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "items": [
      {
        "timestamp": "2026-02-20T12:00:00Z",
        "action": "update",
        "changes": {}
      }
    ],
    "has_more": false,
    "count": 1
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /visualgrid/node/history",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /visualgrid/node/load

Purpose: Load a single node

Notes: Load a single DynamoDB item by table + PK + SK. Returns the item with separated DDB keys and metadata. Root-only access.

Request schema: NodeLoadRequest Response schema: NodeLoadResponse

Sample request (schema-derived)

{
  "table": "uas_main",
  "pk": "USER#u_abc123",
  "sk": "USER#META"
}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "node": {
      "ddb_keys": {
        "PK": "USER#u_abc123",
        "SK": "USER#META"
      },
      "properties": {
        "status": "verified",
        "caption": "John Doe",
        "passcode_hash": "...h8i9j0k1"
      },
      "metadata": {
        "service_code": "uas",
        "table": "uas_main",
        "record_type": "user_core"
      }
    }
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /visualgrid/node/load",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

GET /visualgrid/ping

Purpose: Health check

Notes: Returns service status and timestamp. No auth required.

Request schema: None Response schema: PingResponse

Sample request (schema-derived)

{}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "status": "healthy",
    "service": "visualgrid",
    "timestamp": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "GET /visualgrid/ping",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /visualgrid/root/auth

Purpose: Authenticate with root secret code

Notes: Verify the root secret code against the scrypt hash stored in DDB. Returns a short-lived token (1h TTL) for subsequent root-mode requests.

Request schema: RootAuthRequest Response schema: RootAuthResponse

Sample request (schema-derived)

{
  "secret_code": "CODE1"
}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "token": "vg_a1b2c3d4e5f6...",
    "expires_at": "2026-02-20T14:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /visualgrid/root/auth",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

GET /visualgrid/root/graph

Purpose: Get top-level entry nodes (all tables)

Notes: Returns entry nodes representing all 21 service DynamoDB tables. Each node includes table name, service code, PK prefix patterns, and links to service documentation.

Request schema: None Response schema: GraphEntryResponse

Sample request (schema-derived)

{}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "nodes": [
      {
        "id": "uas_main",
        "label": "UAS — User Account Service",
        "type": "table"
      }
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "GET /visualgrid/root/graph",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /visualgrid/root/graph

Purpose: Get top-level entry nodes (all tables) — POST variant

Notes: Same handler as GET /root/graph. POST variant for clients that prefer POST.

Request schema: None Response schema: GraphEntryResponse

Sample request (schema-derived)

{}

Sample response (shape-only)

{
  "ok": true,
  "data": {
    "nodes": []
  },
  "stats": {
    "call": "POST /visualgrid/root/graph",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

GET /visualgrid/schema

Purpose: Get full schema registry graph

Notes: Returns the complete service registry with all tables, entity types, edge relationships, and metadata dictionary. Root-only access.

Request schema: None Response schema: SchemaGraphResponse

Sample request (schema-derived)

{}

Sample response (shape-only)

{
  "success": true,
  "data": {
    "services": [
      { "code": "uas", "table": "uas_main", "label": "User Account Service" }
    ],
    "edges": [
      { "from": "uas_main", "to": "usm_main", "label": "sessions" }
    ],
    "entity_types": [
      { "table": "uas_main", "pk_prefix": "USER#", "record_type": "user_core" }
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "GET /visualgrid/schema",
    "service": "visualgrid",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}