{
  "openapi": "3.1.0",
  "info": {
    "title": "TrueMetriks API",
    "version": "1.0.0",
    "description": "TrueMetriks v1 REST API. Hand this URL to an AI along with your API key to query your analytics in plain English."
  },
  "servers": [
    {
      "url": "https://app.truemetriks.com"
    }
  ],
  "components": {
    "schemas": {},
    "parameters": {}
  },
  "paths": {
    "/v1/overview": {
      "get": {
        "summary": "Top-level KPIs (sessions, users, revenue, leads) for a date range, with source breakdown.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "sessions": {
                          "type": "number"
                        },
                        "unique_visitors": {
                          "type": "number"
                        },
                        "pageviews": {
                          "type": "number"
                        },
                        "revenue": {
                          "type": "number"
                        },
                        "leads": {
                          "type": "number"
                        },
                        "purchases": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "sessions",
                        "unique_visitors",
                        "pageviews",
                        "revenue",
                        "leads",
                        "purchases"
                      ]
                    },
                    "by_source": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "sessions": {
                            "type": "number"
                          },
                          "revenue": {
                            "type": "number"
                          },
                          "leads": {
                            "type": "number"
                          },
                          "purchases": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "source",
                          "channel",
                          "sessions",
                          "revenue",
                          "leads",
                          "purchases"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "totals",
                    "by_source"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/revenue": {
      "get": {
        "summary": "Revenue totals + breakdowns by source, product, and day. Use this for any 'how much money' question.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "revenue": {
                          "type": "number"
                        },
                        "purchases": {
                          "type": "number"
                        },
                        "average_order_value": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "revenue",
                        "purchases",
                        "average_order_value"
                      ]
                    },
                    "by_source": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "revenue": {
                            "type": "number"
                          },
                          "purchases": {
                            "type": "number"
                          },
                          "conversion_rate_pct": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "source",
                          "channel",
                          "revenue",
                          "purchases",
                          "conversion_rate_pct"
                        ]
                      }
                    },
                    "by_product": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sku": {
                            "type": "string"
                          },
                          "product_name": {
                            "type": "string"
                          },
                          "revenue": {
                            "type": "number"
                          },
                          "units": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "sku",
                          "product_name",
                          "revenue",
                          "units"
                        ]
                      }
                    },
                    "by_day": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string"
                          },
                          "revenue": {
                            "type": "number"
                          },
                          "purchases": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "date",
                          "revenue",
                          "purchases"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "totals",
                    "by_source",
                    "by_product",
                    "by_day"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/leads": {
      "get": {
        "summary": "Lead counts with source attribution.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "leads": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "leads"
                      ]
                    },
                    "by_source": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "leads": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "source",
                          "channel",
                          "leads"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "totals",
                    "by_source"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/pages": {
      "get": {
        "summary": "Top pages by pageviews. Optional ?limit=N (default 25, max 100). No source breakdown by design.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "pages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "path": {
                            "type": "string"
                          },
                          "pageviews": {
                            "type": "number"
                          },
                          "unique_visitors": {
                            "type": "number"
                          },
                          "avg_time_on_page_seconds": {
                            "type": "number"
                          },
                          "bounce_rate_pct": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "path",
                          "pageviews",
                          "unique_visitors",
                          "avg_time_on_page_seconds",
                          "bounce_rate_pct"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "pages"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/products": {
      "get": {
        "summary": "Per-product revenue and units.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sku": {
                            "type": "string"
                          },
                          "product_name": {
                            "type": "string"
                          },
                          "units_sold": {
                            "type": "number"
                          },
                          "revenue": {
                            "type": "number"
                          },
                          "average_price": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "sku",
                          "product_name",
                          "units_sold",
                          "revenue",
                          "average_price"
                        ]
                      }
                    },
                    "by_source": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "top_product_sku": {
                            "type": "string"
                          },
                          "top_product_name": {
                            "type": "string"
                          },
                          "revenue": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "source",
                          "channel",
                          "top_product_sku",
                          "top_product_name",
                          "revenue"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "products",
                    "by_source"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/users": {
      "get": {
        "summary": "Unique visitor counts and segmentation (new vs returning, by source, by country).",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "totals": {
                      "type": "object",
                      "properties": {
                        "unique_visitors": {
                          "type": "number"
                        },
                        "returning_visitors": {
                          "type": "number"
                        },
                        "new_visitors": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "unique_visitors",
                        "returning_visitors",
                        "new_visitors"
                      ]
                    },
                    "by_source": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string"
                          },
                          "channel": {
                            "type": "string"
                          },
                          "visitors": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "source",
                          "channel",
                          "visitors"
                        ]
                      }
                    },
                    "by_country": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "country": {
                            "type": "string"
                          },
                          "visitors": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "country",
                          "visitors"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "totals",
                    "by_source",
                    "by_country"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    },
    "/v1/funnels": {
      "get": {
        "summary": "All defined funnels for the site, with per-step counts and conversion rates. Returns empty array if no funnels defined.",
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": 0
            },
            "required": true,
            "name": "site_id",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "yesterday",
                "last_7d",
                "last_30d",
                "last_90d",
                "last_365d"
              ]
            },
            "required": false,
            "name": "period",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "timezone",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "timezone"
                      ]
                    },
                    "note": {
                      "type": "string"
                    },
                    "funnels": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "name": {
                            "type": "string"
                          },
                          "steps": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "step_name": {
                                  "type": "string"
                                },
                                "visitors": {
                                  "type": "number"
                                },
                                "conversion_from_previous_pct": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "step_name",
                                "visitors",
                                "conversion_from_previous_pct"
                              ]
                            }
                          },
                          "overall_conversion_pct": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "steps",
                          "overall_conversion_pct"
                        ]
                      }
                    }
                  },
                  "required": [
                    "period",
                    "funnels"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request (e.g. range too wide)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "API key lacks access to this site"
          },
          "504": {
            "description": "Query timeout (>10s)"
          }
        }
      }
    }
  },
  "webhooks": {}
}