{
  "openapi": "3.0.3",
  "info": {
    "title": "DevDome Stats API",
    "version": "v1",
    "description": "Every report the DevDome dashboard shows, over plain JSON, plus site management. Authenticate with a Bearer API key (ddk_...) created under Account > API. Rate limit: 60 requests per minute per key. Human-readable reference: https://devdome.com/docs/api/",
    "termsOfService": "https://devdome.com/terms-of-service/",
    "contact": {
      "url": "https://devdome.com/contact/"
    }
  },
  "externalDocs": {
    "description": "Reference with captured samples",
    "url": "https://devdome.com/docs/api/"
  },
  "servers": [
    {
      "url": "https://analytics.devdome.com"
    }
  ],
  "tags": [
    {
      "name": "Account and sites",
      "description": "Who you are and what you track. Adding and verifying sites works exactly like the dashboard wizard."
    },
    {
      "name": "Traffic",
      "description": "The headline numbers and the per-page detail. Every count comes with its bot twin, so human numbers are never inflated. Every windowed report takes the dashboard filters as filter_page, filter_referrer, filter_browser, filter_os, filter_device, filter_country, filter_campaign (source|medium|campaign), filter_event and filter_goal (a goal id); each narrows the report to the visits that match, inside the same window. countries, regions and cities ignore the page, referrer, campaign, event and goal filters."
    },
    {
      "name": "Audience",
      "description": "Where visitors are and what they browse with. Rows in these tables use short keys, decoded below."
    },
    {
      "name": "Visitors and realtime",
      "description": "Individual anonymous visits with their full paths, and who is on the site right now."
    },
    {
      "name": "Bots",
      "description": "The report nobody else gives you over an API: every detected bot with the receipt for WHY it was flagged."
    },
    {
      "name": "Site health",
      "description": "The uptime and health monitoring that rides on the same key."
    },
    {
      "name": "Export",
      "description": "Everything, raw."
    }
  ],
  "paths": {
    "/api/v1/account": {
      "get": {
        "tags": [
          "Account and sites"
        ],
        "summary": "Who am I: account id and plan.",
        "description": "Who am I: account id and plan.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "account_id": "DD12345678",
                  "plan": "pro"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/sites": {
      "get": {
        "tags": [
          "Account and sites"
        ],
        "summary": "Every site on the account.",
        "description": "Every site on the account.\n\nverified = ownership proven. pending_verification = added but not verified yet; no data access until it is.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "sites": [
                    {
                      "domain": "example.com",
                      "verified": true,
                      "pending_verification": false,
                      "category": null
                    },
                    {
                      "domain": "newsite.com",
                      "verified": false,
                      "pending_verification": true,
                      "category": null
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": [
          "Account and sites"
        ],
        "summary": "Add a site.",
        "description": "Add a site. Creates a pending claim and returns the verification file to upload: verify_file_path (/.well-known/devdome-analytics.txt) and verify_content. The tracking snippet itself is in the dashboard and the WordPress plugin.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/sites/{domain}/verify": {
      "post": {
        "tags": [
          "Account and sites"
        ],
        "summary": "Verify ownership: passes when the live homepage carries your snippet, or a DNS TXT record devdome-verify=DD...",
        "description": "Verify ownership: passes when the live homepage carries your snippet, or a DNS TXT record devdome-verify=DD... exists.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The site domain, exactly as stored."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/sites/{domain}": {
      "delete": {
        "tags": [
          "Account and sites"
        ],
        "summary": "Remove the site from the account.",
        "description": "Remove the site from the account. A site that still has analytics data answers 409 until you add ?purge=1, which removes the site and deletes its data for good.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The site domain, exactly as stored."
          },
          {
            "name": "purge",
            "in": "query",
            "required": false,
            "description": "Set to 1 to delete the site together with its analytics data.",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Headline KPIs for the window plus the previous window (period \"current\" / \"previous\") so you can compute changes.",
        "description": "Headline KPIs for the window plus the previous window (period \"current\" / \"previous\") so you can compute changes.\n\nHow the numbers are counted. visits = sessions with the 30-minute gap rule. session_seconds / visits = average visit duration (every visit counts, a bounce as 0 seconds; dur_sessions, the visits with a measured dwell, stays in the answer for older integrations). bounces = one-page visits without an outbound click; bounces / visits = bounce rate. visitors = distinct identities that loaded a page in the window; people who only passed through a tracked redirect link and never loaded a page are reported apart as hop_only_visitors. Counting changes on 19 October 2026: a click or a redirect-hop landing no longer starts a visit (visits and bounce rate drop on redirect-heavy sites), a one-page visit with an outbound click is no longer a bounce, the average runs over every visit, and visitors counts page loaders only. new_visitors = identities seen for the first time in the window; it is only meaningful when the site recognises returning visitors. Cookieless tracking rotates the visitor id every day, so every return visit looks new. Two switches decide this and must agree: the tracker (hosted snippet: data-cookieless=\"true\" on the script tag; WordPress plugin: Track Returning Visitors off) and the dashboard (Website Settings > Cookieless tracking). With the dashboard switch on, new_visitors is null and returning_visitors is 0: do not report them. If new_visitors is almost equal to visitors, the tracker runs in cookieless mode but the dashboard switch is off: turn Cookieless tracking on for that site, or turn returning-visitor tracking on in the tracker, so the two agree.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/timeseries": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "One row per day, zero-filled, bucketed in the site timezone.",
        "description": "One row per day, zero-filled, bucketed in the site timezone.\n\nctr = human clicks / visits in percent, the same formula as the dashboard CTR tile. ppv = pageviews / visits. hop_only_visitors = identities that only passed through a redirect link that day and never loaded a page (not in visitors).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/hourly": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "The last 24 hours by hour (UTC timestamps).",
        "description": "The last 24 hours by hour (UTC timestamps).\n\nFixed window: the header says fixed=24h.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/pages": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Per-page traffic with page health.",
        "description": "Per-page traffic with page health.\n\nstatus / checked_at come from the page health prober (404 detection). With limit=N, row 0 carries _total (all pages) and _t404 (broken count).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": [
                  {
                    "page_path": "/pricing",
                    "traffic": 302,
                    "visitors": 287,
                    "bots": 44,
                    "clicks": 21,
                    "status": 200,
                    "checked_at": "2026-08-22T18:20:29.149+00:00",
                    "_total": 214,
                    "_t404": 3
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/referrers": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Traffic sources, one row per referrer.",
        "description": "Traffic sources, one row per referrer.\n\nvisits = visits whose first pageview arrived from that source (30-minute gap rule); the rows add up to the Visits KPI. clicks = outbound clicks made during those visits.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": [
                  {
                    "referrer": "google.com",
                    "visits": 1211,
                    "clicks": 84
                  },
                  {
                    "referrer": "direct",
                    "visits": 903,
                    "clicks": 61
                  },
                  {
                    "referrer": "reddit.com",
                    "visits": 88,
                    "clicks": 9
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/redirects": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Redirect slugs served, with clicks through them.",
        "description": "Redirect slugs served, with clicks through them.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/keywords": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Search keywords, where engines disclose them.",
        "description": "Search keywords, where engines disclose them.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Amazon product clicks (Amazon Importer sites).",
        "description": "Amazon product clicks (Amazon Importer sites).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/campaigns": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "UTM campaigns: one row per utm_source / utm_medium / utm_campaign on the links visitors landed from, with visits, people and bot landings.",
        "description": "UTM campaigns: one row per utm_source / utm_medium / utm_campaign on the links visitors landed from, with visits, people and bot landings. Tags are stored from 10 Oct 2026 on.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/goals": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "The saved goals of the site (Website Settings > Goals) with the human and bot visits that completed each one in the window.",
        "description": "The saved goals of the site (Website Settings > Goals) with the human and bot visits that completed each one in the window. Each row carries the goal id used by filter_goal.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/events": {
      "get": {
        "tags": [
          "Traffic"
        ],
        "summary": "Custom events the site sends, one row per event name with counts for the window.",
        "description": "Custom events the site sends, one row per event name with counts for the window. Names feed filter_event.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/countries": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Traffic by country (ISO 3166-1 alpha-2).",
        "description": "Traffic by country (ISO 3166-1 alpha-2).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": [
                  {
                    "country": "US",
                    "visitors": 5,
                    "bots": 2,
                    "clicks": 0,
                    "pageviews": 5,
                    "visits": 5
                  },
                  {
                    "country": "IE",
                    "visitors": 2,
                    "bots": 0,
                    "clicks": 0,
                    "pageviews": 2,
                    "visits": 2
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/regions": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Regions inside one country.",
        "description": "Regions inside one country.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/cities": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Cities inside one region.",
        "description": "Cities inside one region.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "description": "Region name inside the country, as returned by /api/v1/regions.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/devices": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Device split with sub-breakdowns.",
        "description": "Device split with sub-breakdowns.\n\nShort keys: k = dimension value, t = visits, b = bot visits, c = clicks, cb = bot clicks, uv = unique visitors, pv = pageviews. subs = the same value split by a second dimension.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "rows": [
                    {
                      "k": "desktop",
                      "t": 9,
                      "b": 2,
                      "c": 0,
                      "cb": 0,
                      "uv": 9,
                      "pv": 9
                    }
                  ],
                  "subs": [
                    {
                      "k": "desktop",
                      "dim": "browser",
                      "skey": "chrome",
                      "t": 9,
                      "c": 0
                    },
                    {
                      "k": "desktop",
                      "dim": "country",
                      "skey": "US",
                      "t": 5,
                      "c": 0
                    }
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/browsers": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Browser split.",
        "description": "Browser split. Same shape as devices.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/os": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Operating system split.",
        "description": "Operating system split. Same shape as devices.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/dates": {
      "get": {
        "tags": [
          "Audience"
        ],
        "summary": "Per-date table.",
        "description": "Per-date table. Same shape as devices, keyed by date.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/visitors": {
      "get": {
        "tags": [
          "Visitors and realtime"
        ],
        "summary": "Recent visits, each with its step-by-step path.",
        "description": "Recent visits, each with its step-by-step path.\n\nvisitor_id is a daily-rotating anonymous hash, never a person. steps carry pageviews and outbound clicks with per-page dwell seconds. Newest first; the window holds at most the plan row cap (500 on Free, 5,000 on paid plans) and row 0 carries that count as _total. Page with limit plus before = the last_seen of the last row you got; a page shorter than limit is the end. Narrow the window with from+to to reach visits past the cap.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Page further back: incidents = the started_at of the last row of the previous page, visitors = its last_seen.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/paths": {
      "get": {
        "tags": [
          "Visitors and realtime"
        ],
        "summary": "The visitors who entered on one page, each with their step-by-step path.",
        "description": "The visitors who entered on one page, each with their step-by-step path.\n\npage is required (the entry page path, e.g. /pricing); without it the call is a 400.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": true,
            "description": "Entry page path, e.g. /pricing. Required for /paths.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/realtime": {
      "get": {
        "tags": [
          "Visitors and realtime"
        ],
        "summary": "Visitors active in the last 5 minutes with their current page.",
        "description": "Visitors active in the last 5 minutes with their current page.\n\nFixed window: the header says fixed=5m.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/bots": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "Every detected bot: user agent, reason, hits, IPs, networks, pages.",
        "description": "Every detected bot: user agent, reason, hits, IPs, networks, pages.\n\nlimit takes 1 to 1000. No limit returns up to the plan cap (500 rows Free, 5000 paid).",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/bot-threats": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "Detection-category totals for the window.",
        "description": "Detection-category totals for the window.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": [
                  {
                    "bots": 2,
                    "ua_bots": 0,
                    "datacenter": 2,
                    "scanner": 0,
                    "automation": 2,
                    "no_profile": 0,
                    "session_bot": 0,
                    "fleet": 0
                  }
                ]
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "tags": [
          "Site health"
        ],
        "summary": "Full health report: uptime, response times, TLS, DNS, page checks.",
        "description": "Full health report: uptime, response times, TLS, DNS, page checks.\n\nNo days = the full history your plan retains; larger values are clamped to the plan.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "domain": "example.com",
                  "meta": {
                    "monitor_state": "up",
                    "cadence_s": 3600,
                    "plan": "pro",
                    "effective_days": 30,
                    "data_state": "ready",
                    "coverage_24h": 0.98,
                    "latency_metric": "ttfb_ms"
                  },
                  "sections": {
                    "last_check": true,
                    "incidents": true,
                    "audit": true
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/incidents": {
      "get": {
        "tags": [
          "Site health"
        ],
        "summary": "Downtime incidents, newest first.",
        "description": "Downtime incidents, newest first.\n\nlimit is 25 by default, 100 at most. When has_more is true, pass the started_at of the last row as before to page further back.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Page further back: incidents = the started_at of the last row of the previous page, visitors = its last_seen.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {},
                "example": {
                  "incidents": [],
                  "limit": 25,
                  "has_more": false
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/alerts": {
      "get": {
        "tags": [
          "Site health"
        ],
        "summary": "Alert history for the site.",
        "description": "Alert history for the site.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/v1/export": {
      "get": {
        "tags": [
          "Export"
        ],
        "summary": "Full CSV export of the raw analytics for the window.",
        "description": "Full CSV export of the raw analytics for the window. Returns text/csv, not JSON.\n\nOne response, no paging: with no window it streams the whole history your plan retains, which can be tens of megabytes. Export month by month with from+to for anything large.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "site",
            "in": "query",
            "required": true,
            "description": "The site domain, exactly as stored (punycode for international names).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Window length in days, counted back from now. No window parameter means the full history the plan retains.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Window start, YYYY-MM-DD (use with to).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Window end, YYYY-MM-DD, inclusive (use with from).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "ddk_ API key from Account > API, sent as Authorization: Bearer ddk_..."
      }
    },
    "responses": {
      "Error": {
        "description": "400 - missing or malformed parameter; the message names it. days must be a whole number from 1 up; days=0 or days=abc is a 400, never a silent 30-day answer. Above the ceiling (1095) it clamps and the header says clamped=1. 401 - missing or invalid API key. 403 - the key is read-only: creating, verifying or removing a site needs a key with the \"read and manage sites\" scope (Account, API access). Reads work with every key. 403 - the site does not belong to this account. 404 - unknown endpoint. 423 - the account is over its plan limit and dashboards are locked. 429 - rate limited (60 requests/minute per key, plus 60 requests/minute per IP address for calls that need a fresh key lookup); comes with a retry-after: 60 header.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}