Hostingsurge Analytics API

openapi: 3.2.0
info:
  title: Hostingsurge Platform Analytics API
  version: 1.0.0
  description: 'Deploy and operate projects on Hostingsurge: Git/upload/Docker/WordPress projects, deployments, logs, environment variables, domains and databases. Errors are {"error":{"code","message","details?"}}.'
servers:
- url: /api/v1
  description: Same origin as the dashboard, e.g. https://hostingsurge.com/api/v1
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: Analytics
paths:
  /projects/{projectId}/analytics:
    get:
      tags:
      - Analytics
      summary: 'Visitor analytics of a project: pageviews, unique visitors, top pages…'
      description: 'Cookieless and server-side: counted from the platform proxy''s access log for the project''s platform hostname and verified custom domains, without any script in the site. Bots, assets and non-page responses are left out; unique visitors are a daily salted hash of address and browser (never stored as such). range=24h gives hourly buckets of the rolling 24 hours, 7d and 30d daily UTC buckets. `collector.active` is false until the platform operator has switched the proxy''s access log on.'
      parameters:
      - schema:
          type: string
          maxLength: 64
          format: uuid
        required: true
        name: projectId
        in: path
      - schema:
          type: string
          enum:
          - 24h
          - 7d
          - 30d
          default: 24h
        required: false
        name: range
        in: query
      responses:
        '200':
          description: Analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectId:
                    type: string
                    format: uuid
                  range:
                    type: string
                    enum:
                    - 24h
                    - 7d
                    - 30d
                  granularity:
                    type: string
                    enum:
                    - hour
                    - day
                  from:
                    type: string
                    description: Start of the first bucket (inclusive)
                  to:
                    type: string
                    description: End of the window (now)
                  collector:
                    type: object
                    properties:
                      active:
                        type: boolean
                        description: The access-log collector reported within the last 15 minutes (analytics is switched on)
                      lastSeenAt:
                        type:
                        - string
                        - 'null'
                        description: ISO-8601 timestamp
                      countries:
                        type: boolean
                        description: The collector resolves countries (its IP-to-country database is present)
                    required:
                    - active
                    - lastSeenAt
                    - countries
                  totals:
                    type: object
                    properties:
                      pageviews:
                        type: integer
                        minimum: 0
                      visitors:
                        type: integer
                        minimum: 0
                        description: '24h: unique visitors in the rolling 24 hours; 7d/30d: the sum of each day''s unique visitors'
                    required:
                    - pageviews
                    - visitors
                  series:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: string
                          description: Start of the hour (range 24h) or UTC day (7d/30d)
                        pageviews:
                          type: integer
                          minimum: 0
                        visitors:
                          type: integer
                          minimum: 0
                          description: Unique visitors in this hour or day
                      required:
                      - start
                      - pageviews
                      - visitors
                    description: Every bucket of the window, zero-filled, oldest first
                  pages:
                    type: object
                    properties:
                      metric:
                        type: string
                        enum:
                        - pageviews
                        - visitors
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              description: Path, referrer host, ISO country code, device class or browser family; "(other)" collects values past the cap
                            count:
                              type: integer
                              minimum: 0
                          required:
                          - value
                          - count
                        description: At most 10, largest first
                    required:
                    - metric
                    - items
                  referrers:
                    type: object
                    properties:
                      metric:
                        type: string
                        enum:
                        - pageviews
                        - visitors
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              description: Path, referrer host, ISO country code, device class or browser family; "(other)" collects values past the cap
                            count:
                              type: integer
                              minimum: 0
                          required:
                          - value
                          - count
                        description: At most 10, largest first
                    required:
                    - metric
                    - items
                  countries:
                    type: object
                    properties:
                      metric:
                        type: string
                        enum:
                        - pageviews
                        - visitors
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              description: Path, referrer host, ISO country code, device class or browser family; "(other)" collects values past the cap
                            count:
                              type: integer
                              minimum: 0
                          required:
                          - value
                          - count
                        description: At most 10, largest first
                    required:
                    - metric
                    - items
                  devices:
                    type: object
                    properties:
                      metric:
                        type: string
                        enum:
                        - pageviews
                        - visitors
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              description: Path, referrer host, ISO country code, device class or browser family; "(other)" collects values past the cap
                            count:
                              type: integer
                              minimum: 0
                          required:
                          - value
                          - count
                        description: At most 10, largest first
                    required:
                    - metric
                    - items
                  browsers:
                    type: object
                    properties:
                      metric:
                        type: string
                        enum:
                        - pageviews
                        - visitors
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              description: Path, referrer host, ISO country code, device class or browser family; "(other)" collects values past the cap
                            count:
                              type: integer
                              minimum: 0
                          required:
                          - value
                          - count
                        description: At most 10, largest first
                    required:
                    - metric
                    - items
                required:
                - projectId
                - range
                - granularity
                - from
                - to
                - collector
                - totals
                - series
                - pages
                - referrers
                - countries
                - devices
                - browsers
        '400':
          description: Invalid request (code invalid_request)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing or invalid session/token (code unauthorized)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '403':
          description: Authenticated but not permitted (code forbidden)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: Not found or not visible to the caller (code not_found)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Too many requests (code rate_limited); see Retry-After
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '501':
          description: Visitor analytics is not available on this server yet (code not_configured)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
      operationId: getProjectsByProjectIdAnalytics
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API or MCP key created in the dashboard (Account → API & MCP keys). Keys carry scopes and project grants.
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-hs_session
      description: Dashboard session (same origin only; changes require a matching Origin header)