Ciphera API

openapi: 3.1.0
info:
  title: Ciphera API
  version: '2026-11-03'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-03: 13 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Ciphera has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 10
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-03'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.ciphera.net/pulse/api
servers:
- url: https://pulse-api.ciphera.net
paths:
  /api/public/v1/me:
    get:
      operationId: get_api_public_v1_me
      tags:
      - Api
      summary: GET /api/public/v1/me
      x-source: https://docs.ciphera.net/pulse/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H \"Authorization: Bearer $PULSE_API_KEY \"  \"https://pulse-api.ciphera.net/api/public/v1/me\" \n { \n \"data\" : { \n\
          \ \"organization\" : { \"id\" : \"2c1f74ec-...\" , \"name\" : null }, \n \"key\" : { \n \"name\" : \"Grafana dashboard\" , \n \"last4\"\
          \ : \"chju\" , \n \"expires_at\" : \"2026-11-05T00:00:00Z\" , \n \"scope_all_sites\" : true , \n \"site_ids\" : [], \n \"last_used_at\"\
          \ : \"2026-08-07T09:12:44Z\" \n } \n }, \n \"meta\" : { \"su"
  /api/public/v1/sites:
    get:
      operationId: get_api_public_v1_sites
      tags:
      - Api
      summary: GET /api/public/v1/sites
      x-source: https://docs.ciphera.net/pulse/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H \"Authorization: Bearer $PULSE_API_KEY \"  \"https://pulse-api.ciphera.net/api/public/v1/sites/ $SITE /stats?period=7d\"\
          \ \n { \n \"data\" : { \n \"visitors\" : 1284 , \n \"pageviews\" : 3401 , \n \"bounce_rate\" : 62.4 , \n \"avg_duration\" : 107.2 ,\
          \ \n \"avg_scroll_depth\" : 51.8 , \n \"avg_visible_duration\" : 44.1 \n }, \n \"meta\" : { \n \"range\" : { \"from\" : \"2026-08-01\"\
          \ , \"to\" : \"2026-08-07\" , \"timezone\" : \"Europe/"
  /api/public/v1/sites/{siteId}/breakdown:
    get:
      operationId: get_api_public_v1_sites_siteId_breakdown
      tags:
      - Api
      summary: Ranks a site's traffic by one dimension over a date range
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      - name: dimension
        in: query
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      - name: filter
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiPublicV1SitesSiteidBreakdownResponse'
      x-evidence:
        kind: documentation
  /api/public/v1/sites/{siteId}/export/pages:
    get:
      operationId: get_api_public_v1_sites_siteId_export_pages
      tags:
      - Api
      summary: Top pages export returns path and pageviews as CSV or JSON
      description: Returns raw CSV (default) or a JSON array of page rows. Includes headers X-Pulse-Min-Cell-Size, X-Pulse-Suppressed-Rows, and
        X-Pulse-Suppressed-Pageviews (all always 0).
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        required: true
        schema:
          type: string
        description: Start date (YYYY‑MM‑DD, inclusive)
      - name: to
        in: query
        required: true
        schema:
          type: string
        description: End date (YYYY‑MM‑DD, inclusive)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Maximum rows to return (default 100, max 1000)
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Repeatable filter expression, e.g. filter=country==BE
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: Response format, csv (default) or json
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiPublicV1SitesSiteidExportPagesResponse'
      x-evidence:
        kind: documentation
  /api/public/v1/sites/{siteId}/realtime:
    get:
      operationId: get_api_public_v1_sites_siteId_realtime
      tags:
      - Api
      summary: Sessions active in the last five minutes, and the pages they are on
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiPublicV1SitesSiteidRealtimeResponse'
      x-evidence:
        kind: documentation
  /api/public/v1/sites/{siteId}/stats:
    get:
      operationId: get_api_public_v1_sites_siteId_stats
      tags:
      - Api
      summary: Totals over a date range
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: siteId
        in: path
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      - name: filter
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiPublicV1SitesSiteidStatsResponse'
      x-evidence:
        kind: documentation
  /me:
    get:
      operationId: get_me
      tags:
      - Me
      summary: What this key is and when it expires
      x-source: https://docs.ciphera.net/pulse/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMeResponse'
      x-evidence:
        kind: documentation
  /sites:
    get:
      operationId: get_sites
      tags:
      - Sites
      summary: The sites this key can read
      x-source: https://docs.ciphera.net/pulse/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesResponse'
      x-evidence:
        kind: documentation
  /sites/{id}/breakdown:
    get:
      operationId: get_sites_id_breakdown
      tags:
      - Sites
      summary: Traffic ranked by one dimension — pages, referrers, countries, and more
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: dimension
        in: query
        required: true
        schema:
          type: string
        description: One of page, entry_page, exit_page, referrer, channel, country, region, browser, os, device, language, utm_source, utm_medium,
          utm_campaign
      - name: period
        in: query
        required: false
        schema:
          type: string
        description: One of 7d, 30d, month, year (default 7d)
      - name: from
        in: query
        required: false
        schema:
          type: string
      - name: to
        in: query
        required: false
        schema:
          type: string
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Repeatable filter expression
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Default 20, max 100
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesIdBreakdownResponse'
      x-evidence:
        kind: documentation
  /sites/{id}/export/daily:
    get:
      operationId: get_sites_id_export_daily
      tags:
      - Sites
      summary: One row per day, as CSV
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        required: true
        schema:
          type: string
        description: Start date YYYY‑MM‑DD
      - name: to
        in: query
        required: true
        schema:
          type: string
        description: End date YYYY‑MM‑DD
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: csv (default) or json
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesIdExportDailyResponse'
      x-evidence:
        kind: documentation
  /sites/{id}/export/pages:
    get:
      operationId: get_sites_id_export_pages
      tags:
      - Sites
      summary: Top pages, as CSV
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        required: true
        schema:
          type: string
      - name: to
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Default 100, max 1000
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Repeatable filter expression
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesIdExportPagesResponse'
      x-evidence:
        kind: documentation
  /sites/{id}/realtime:
    get:
      operationId: get_sites_id_realtime
      tags:
      - Sites
      summary: Who is on the site right now
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Default 20, max 100
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesIdRealtimeResponse'
      x-evidence:
        kind: documentation
  /sites/{id}/stats:
    get:
      operationId: get_sites_id_stats
      tags:
      - Sites
      summary: Totals over a date range, filterable
      x-source: https://docs.ciphera.net/pulse/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
        description: One of 7d, 30d, month, year (default 7d)
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: Start date YYYY‑MM‑DD
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: End date YYYY‑MM‑DD
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Repeatable filter expression
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSitesIdStatsResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiPublicV1SitesSiteidBreakdownResponse:
      type: object
      properties:
        data:
          type: object
          description: Dimension and rows
        meta:
          type: object
          description: Range and suppressed flag
    GetApiPublicV1SitesSiteidExportPagesResponse:
      type: object
      properties:
        path:
          type: string
          description: Page path
        pageviews:
          type: integer
          description: Pageviews for the path
    GetApiPublicV1SitesSiteidRealtimeResponse:
      type: object
      properties:
        data:
          type: object
          description: Visitors count and top_paths array
        meta:
          type: object
          description: Envelope meta
    GetApiPublicV1SitesSiteidStatsResponse:
      type: object
      properties:
        data:
          type: object
          description: Metrics such as visitors, pageviews, bounce_rate, avg_duration, avg_scroll_depth, avg_visible_duration
        meta:
          type: object
          description: Range and suppressed flag
    GetMeResponse:
      type: object
      properties:
        data:
          type: object
          description: Contains organization and key information
        meta:
          type: object
          description: Envelope meta, always present
    GetSitesResponse:
      type: object
      properties:
        data:
          type: array
          description: List of site objects
        meta:
          type: object
          description: Envelope meta
    GetSitesIdBreakdownResponse:
      type: object
      properties:
        data:
          type: object
          description: Contains dimension and rows
        meta:
          type: object
          description: Contains range and suppressed flag
    GetSitesIdExportDailyResponse:
      type: object
      properties:
        CSV rows:
          type: string
          description: date, pageviews, visitors, bounce_rate, avg_duration, avg_scroll_depth, avg_visible_duration
    GetSitesIdExportPagesResponse:
      type: object
      properties:
        CSV rows:
          type: string
          description: path, pageviews
    GetSitesIdRealtimeResponse:
      type: object
      properties:
        data:
          type: object
          description: Contains visitors count and top_paths array
        meta:
          type: object
          description: Envelope meta
    GetSitesIdStatsResponse:
      type: object
      properties:
        data:
          type: object
          description: Metrics such as visitors, pageviews, bounce_rate, avg_duration, avg_scroll_depth, avg_visible_duration
        meta:
          type: object
          description: Contains range and suppressed flag
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Me
- name: Sites