{
    "openapi": "3.1.0",
    "info": {
        "title": "TraceLead reporting API",
        "version": "1",
        "description": "Read-only aggregates and attribution columns for an organisation's sites (ADR-034). Authenticate with an organisation token: Authorization: Bearer tlapi_…. Never returns visitor or session ids, contact details or form values."
    },
    "servers": [{ "url": "https://app.tracelead.io/api/v1" }],
    "security": [{ "bearer": [] }],
    "paths": {
        "/sites": {
            "get": {
                "summary": "The organisation's sites",
                "responses": {
                    "200": {
                        "description": "Sites",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SiteList"
                                }
                            }
                        }
                    },
                    "401": { "$ref": "#/components/responses/Unauthenticated" },
                    "429": { "$ref": "#/components/responses/TooManyRequests" }
                }
            }
        },
        "/sites/{public_id}/stats": {
            "get": {
                "summary": "Totals and one breakdown for a period",
                "parameters": [
                    { "$ref": "#/components/parameters/PublicId" },
                    { "$ref": "#/components/parameters/From" },
                    { "$ref": "#/components/parameters/To" },
                    {
                        "name": "group_by",
                        "in": "query",
                        "schema": {
                            "enum": [
                                "channel",
                                "source",
                                "campaign",
                                "term",
                                "content",
                                "landing_page",
                                "referrer_host",
                                "form",
                                "day"
                            ],
                            "default": "channel"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Stats",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Stats"
                                }
                            }
                        }
                    },
                    "401": { "$ref": "#/components/responses/Unauthenticated" },
                    "404": {
                        "description": "No such site in this organisation"
                    },
                    "422": { "description": "Invalid parameters" },
                    "429": { "$ref": "#/components/responses/TooManyRequests" }
                }
            }
        },
        "/sites/{public_id}/leads": {
            "get": {
                "summary": "Lead attribution records, newest first, 100 per page",
                "parameters": [
                    { "$ref": "#/components/parameters/PublicId" },
                    { "$ref": "#/components/parameters/From" },
                    { "$ref": "#/components/parameters/To" },
                    {
                        "name": "channel",
                        "in": "query",
                        "schema": { "type": "string" }
                    },
                    {
                        "name": "form_id",
                        "in": "query",
                        "schema": { "type": "string", "maxLength": 100 }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": { "type": "string" },
                        "description": "next_cursor from the previous page"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Leads",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/LeadPage"
                                }
                            }
                        }
                    },
                    "401": { "$ref": "#/components/responses/Unauthenticated" },
                    "404": {
                        "description": "No such site in this organisation"
                    },
                    "429": { "$ref": "#/components/responses/TooManyRequests" }
                }
            }
        }
    },
    "components": {
        "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } },
        "parameters": {
            "PublicId": {
                "name": "public_id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{1,64}$"
                }
            },
            "From": {
                "name": "from",
                "in": "query",
                "schema": { "type": "string", "format": "date" },
                "description": "First day (UTC), default 29 days before `to`"
            },
            "To": {
                "name": "to",
                "in": "query",
                "schema": { "type": "string", "format": "date" },
                "description": "Last day (UTC), default today; at most 366 days after `from`"
            }
        },
        "responses": {
            "Unauthenticated": {
                "description": "Missing, revoked or invalid token",
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/Message" }
                    }
                }
            },
            "TooManyRequests": {
                "description": "Rate limit per token exceeded",
                "content": {
                    "application/json": {
                        "schema": { "$ref": "#/components/schemas/Message" }
                    }
                }
            }
        },
        "schemas": {
            "Message": {
                "type": "object",
                "required": ["message"],
                "properties": { "message": { "type": "string" } }
            },
            "SiteList": {
                "type": "object",
                "required": ["data"],
                "additionalProperties": false,
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": [
                                "public_id",
                                "name",
                                "status",
                                "domains",
                                "created_at"
                            ],
                            "additionalProperties": false,
                            "properties": {
                                "public_id": { "type": "string" },
                                "name": { "type": "string" },
                                "status": { "enum": ["active", "paused"] },
                                "domains": {
                                    "type": "array",
                                    "items": { "type": "string" }
                                },
                                "created_at": { "type": ["string", "null"] }
                            }
                        }
                    }
                }
            },
            "Stats": {
                "type": "object",
                "required": [
                    "site",
                    "from",
                    "to",
                    "group_by",
                    "totals",
                    "rows"
                ],
                "additionalProperties": false,
                "properties": {
                    "site": { "type": "string" },
                    "from": { "type": "string" },
                    "to": { "type": "string" },
                    "group_by": { "type": "string" },
                    "totals": {
                        "type": "object",
                        "required": [
                            "sessions",
                            "leads",
                            "conversion_rate",
                            "previous"
                        ],
                        "additionalProperties": false,
                        "properties": {
                            "sessions": { "type": "integer" },
                            "leads": { "type": "integer" },
                            "contact_clicks": {
                                "type": "integer",
                                "description": "Phone, email, SMS and WhatsApp link clicks (ADR-041). Not part of leads or conversion_rate."
                            },
                            "conversion_rate": { "type": ["number", "null"] },
                            "previous": {
                                "type": "object",
                                "required": ["sessions", "leads"],
                                "additionalProperties": false,
                                "properties": {
                                    "sessions": { "type": "integer" },
                                    "leads": { "type": "integer" },
                                    "contact_clicks": { "type": "integer" }
                                }
                            }
                        }
                    },
                    "rows": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "required": ["sessions", "leads"],
                            "propertyNames": {
                                "not": {
                                    "enum": [
                                        "visitor_id",
                                        "session_id",
                                        "vid",
                                        "sid"
                                    ]
                                }
                            },
                            "properties": {
                                "sessions": { "type": "integer" },
                                "leads": { "type": "integer" },
                                "contact_clicks": { "type": "integer" },
                                "conversion_rate": {
                                    "type": ["number", "null"]
                                },
                                "previous": { "type": "object" },
                                "date": { "type": "string" }
                            }
                        }
                    }
                }
            },
            "LeadPage": {
                "type": "object",
                "required": ["data", "next_cursor"],
                "additionalProperties": false,
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                                "id",
                                "occurred_at",
                                "channel",
                                "source",
                                "medium",
                                "landing_page",
                                "page_path",
                                "first_touch_at"
                            ],
                            "properties": {
                                "id": { "type": "integer" },
                                "occurred_at": { "type": "string" },
                                "channel": { "type": "string" },
                                "source": { "type": "string" },
                                "medium": { "type": "string" },
                                "utm_campaign": { "type": ["string", "null"] },
                                "utm_term": { "type": ["string", "null"] },
                                "utm_content": { "type": ["string", "null"] },
                                "utm_id": { "type": ["string", "null"] },
                                "click_id_type": { "type": ["string", "null"] },
                                "referrer_host": { "type": ["string", "null"] },
                                "landing_page": { "type": "string" },
                                "page_path": { "type": "string" },
                                "form_id": { "type": ["string", "null"] },
                                "first_touch_at": { "type": "string" }
                            }
                        }
                    },
                    "next_cursor": { "type": ["string", "null"] }
                }
            }
        }
    }
}