Envelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hyperaware-live/json-schema/hyperaware-live-envelope-schema.json",
  "title": "Envelope",
  "description": "REST answers HTTP 200 with an envelope: `{\"statusCode\": 400, \"body\": \"…\"}`. Read `statusCode`, then parse `body`. A missing or wrong key is the exception: HTTP 401 (`missing_api_key`) or 403 (`invalid_api_key`), with the error object as the body. Errors carry an `error` code and a `message`. Over MCP, a failed call sets `isError` on the tool result.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hyperaware-live-openapi.json#/components/schemas/Envelope",
  "properties": {
    "body": {
      "contentMediaType": "application/json",
      "contentSchema": {
        "oneOf": [
          {
            "$ref": "#/$defs/TimeSeriesResponse"
          },
          {
            "$ref": "#/$defs/GrowthResponse"
          },
          {
            "$ref": "#/$defs/TopTrendsResponse"
          },
          {
            "$ref": "#/$defs/ContextResponse"
          },
          {
            "$ref": "#/$defs/Error"
          }
        ]
      },
      "description": "JSON text: parse it a second time. On success it matches the tool's response schema; any other statusCode means it parses to Error.",
      "type": "string"
    },
    "statusCode": {
      "description": "The real outcome: 200 on success, otherwise the error status.",
      "type": "integer"
    }
  },
  "required": [
    "statusCode",
    "body"
  ],
  "type": "object",
  "$defs": {
    "ContextResponse": {
      "description": "Per source, the posts, videos, stories and markets about the keyword, best first.",
      "properties": {
        "keyword": {
          "description": "The keyword you asked for.",
          "type": "string"
        },
        "sources": {
          "items": {
            "properties": {
              "error": {
                "description": "Why a source returned nothing, when it failed.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "items": {
                "description": "Each item: kind, url, title, text, author, published, engagement (views, likes, comments, shares, score…), top_comments.",
                "type": "array"
              },
              "source": {
                "description": "The source.",
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "window_days": {
          "description": "How far back it looked.",
          "type": "number"
        }
      },
      "type": "object"
    },
    "Error": {
      "description": "The error object: the parsed envelope body when statusCode is not 2xx, or the response body itself on the HTTP 401 and 403 key errors.",
      "properties": {
        "error": {
          "enum": [
            "missing_parameter",
            "invalid_source",
            "invalid_mode",
            "invalid_request",
            "no_data",
            "source_unavailable",
            "growth_calculation_failed",
            "internal_error",
            "missing_api_key",
            "invalid_api_key",
            "monthly_limit_reached"
          ],
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "request_id": {
          "description": "Present on internal_error; quote it when contacting support.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "GrowthResponse": {
      "properties": {
        "data_source": {
          "type": "string"
        },
        "metadata": {
          "properties": {
            "all_successful": {
              "type": "boolean"
            },
            "calculations_completed": {
              "type": "integer"
            },
            "total_data_points": {
              "type": "integer"
            }
          },
          "type": "object"
        },
        "results": {
          "items": {
            "$ref": "#/$defs/GrowthResult"
          },
          "type": "array"
        },
        "search_term": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "GrowthResult": {
      "properties": {
        "baseline_date": {
          "format": "date",
          "type": "string"
        },
        "baseline_value": {
          "type": "number"
        },
        "baseline_volume": {
          "type": [
            "number",
            "null"
          ]
        },
        "direction": {
          "description": "'increase' or 'decrease'.",
          "type": "string"
        },
        "growth": {
          "description": "Percentage change, e.g. -12.31.",
          "type": "number"
        },
        "period": {
          "type": "string"
        },
        "recent_date": {
          "format": "date",
          "type": "string"
        },
        "recent_value": {
          "type": "number"
        },
        "recent_volume": {
          "type": [
            "number",
            "null"
          ]
        },
        "volume_available": {
          "type": "boolean"
        },
        "volume_growth": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "TimeSeriesPoint": {
      "properties": {
        "date": {
          "format": "date",
          "type": "string"
        },
        "keyword": {
          "type": "string"
        },
        "source": {
          "type": "string"
        },
        "value": {
          "description": "Trend score on a 0-100 index.",
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        "volume": {
          "description": "Absolute volume where available.",
          "type": [
            "number",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "TimeSeriesResponse": {
      "description": "~5 years of weekly data points, oldest to newest.",
      "items": {
        "$ref": "#/$defs/TimeSeriesPoint"
      },
      "type": "array"
    },
    "TopTrendsResponse": {
      "properties": {
        "as_of_ts": {
          "format": "date-time",
          "type": "string"
        },
        "baseline_ts": {
          "description": "Present only when sort is 'rank_change'.",
          "format": "date-time",
          "type": "string"
        },
        "category": {
          "type": "string"
        },
        "count": {
          "type": "integer"
        },
        "data": {
          "items": {
            "oneOf": [
              {
                "description": "[rank, keyword] for sort='rank'.",
                "prefixItems": [
                  {
                    "description": "Current rank.",
                    "type": "integer"
                  },
                  {
                    "description": "Keyword or item name.",
                    "type": "string"
                  }
                ],
                "type": "array"
              },
              {
                "description": "Mover row for sort='rank_change'.",
                "properties": {
                  "category_path": {
                    "type": "string"
                  },
                  "keyword": {
                    "type": "string"
                  },
                  "prev_rank": {
                    "type": "integer"
                  },
                  "rank": {
                    "type": "integer"
                  },
                  "rank_change": {
                    "description": "Positions climbed.",
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            ]
          },
          "type": "array"
        },
        "limit": {
          "type": "integer"
        },
        "note": {
          "description": "Present when count is 0 to explain why and what to do next.",
          "type": "string"
        },
        "sort": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "window": {
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}