PixieBrix Activity API

openapi: 3.2.0
info:
  title: PixieBrix Activity API
  version: 1.0.0
  description: PixieBrix admin and package registry API
  contact:
    name: PixieBrix Support
    email: support@pixiebrix.com
servers:
- url: https://app.pixiebrix.com
tags:
- name: activity
paths:
  /api/activity/policy/:
    get:
      operationId: retrieveEffectivePolicyResponse
      description: Return the caller's merged effective activity policy for an organization (the additive union of all policies assigned to the user's groups). Gated by the activity-tracking organization feature flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization whose effective policy to return.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/EffectivePolicyResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/EffectivePolicyResponse'
          description: ''
      tags:
      - activity
  /api/activity/corpus/:
    get:
      operationId: retrieveProhibitedLanguageCorpus
      description: Return the prohibited-language matching corpus (term / category / severity) for the on-device outbound-text guard. Versioned; conditionally cacheable via an ``ETag`` / ``If-None-Match`` 304. Gated by the activity-tracking organization feature flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization whose feature access to check.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProhibitedLanguageCorpus'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProhibitedLanguageCorpus'
          description: ''
      tags:
      - activity
  /api/activity/custom-language-list/:
    get:
      operationId: listCustomLanguages
      description: Return the organization's Custom Language List (``term`` / ``category`` / ``severity``) for the on-device prohibited-language guard, which merges it into the matching engine alongside the curated corpus. Conditionally cacheable via an ``ETag`` / ``If-None-Match`` 304; an upload that changes the list changes the ETag. Membership + ``activity-tracking`` flag gated; scoped to the caller's organization.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization whose custom language list to return.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomLanguageListEntry'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomLanguageListEntry'
          description: ''
      tags:
      - activity
    put:
      operationId: updateCustomLanguageList
      description: Replace or upsert the caller's organization Custom Language List from a bulk upload. Each ``{term, category, severity}`` row's ``term`` is canonicalized (lowercase + trimmed) and duplicate terms in one batch are collapsed last-wins. Re-uploading a term updates its category/severity in place; when ``replace`` is true, terms absent from the upload are also deleted so the stored list matches the file exactly. ``upserted`` / ``deleted`` count terms. Admin/manager + ``activity-tracking`` flag gated; scoped to the caller's organization.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomLanguageListUpload'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CustomLanguageListUpload'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CustomLanguageListUpload'
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/CustomLanguageListUploadResult'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/CustomLanguageListUploadResult'
          description: ''
      tags:
      - activity
  /api/activity/address-list/match/:
    get:
      operationId: listAddressListMatches
      description: Look up on-device address hashes against the caller's organization known-address list. The caller sends one ``hash`` per match granularity (``exact`` / ``building`` / ``street``, computed on-device); the endpoint returns the **finest** matched level's entry — its ``identifier``, ``entry_type`` (fraud/employee), and matched ``level`` — and 404 on a miss. The raw address never leaves the browser; only the hashes are sent. Gated by the ``activity-tracking`` flag and scoped to the caller's organization; enablement is driven by the org's activity policy (``security.addressFraudRules``).
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization whose known-address list to look up.
        schema:
          type: string
          format: uuid
      - name: hash
        in: query
        required: true
        description: On-device HMAC-SHA256 hashes of the normalized entered address, one per match granularity (exact / building / street), each 64-char hex. Repeated (?hash=a&hash=b); the endpoint returns the finest matched level. The raw address is never sent.
        schema:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{64}$
        style: form
        explode: true
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/AddressListMatch'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/AddressListMatch'
          description: ''
      tags:
      - activity
  /api/activity/address-list/count/:
    get:
      operationId: listAddressListSummaries
      description: Return a summary of the caller's organization known-address list — currently just ``count``, the number of uploaded entries (distinct identifiers). Admin/manager + ``activity-tracking`` flag gated; scoped to the caller's organization. Used by the Admin Console to show how many addresses are on the list.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization whose known-address list to summarize.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/AddressListSummary'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/AddressListSummary'
          description: ''
      tags:
      - activity
  /api/activity/policies/:
    get:
      operationId: listActivityPolicies
      description: Return the activity policies for an organization (``organization`` query parameter). Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: q
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope results to.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=2.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivityPolicy'
            application/vnd.pixiebrix.api+json; version=2.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ActivityPolicy'
          description: ''
          headers:
            Link:
              schema:
                type: string
              example: '<https://app.pixiebrix.com/activity/policies/>; rel="first", <https://app.pixiebrix.com/activity/policies/?page=3>; rel="prev", <https://app.pixiebrix.com/activity/policies/?page=5>; rel="next", <https://app.pixiebrix.com/activity/policies/?page=11>; rel="last"'
              description: See https://datatracker.ietf.org/doc/html/rfc8288 for more information.
      tags:
      - activity
    post:
      operationId: createActivityPolicy
      description: Create an activity policy for an organization. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
      responses:
        '201':
          content:
            application/json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
            application/vnd.pixiebrix.api+json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
          description: ''
      tags:
      - activity
  /api/activity/policies/{id}/:
    get:
      operationId: retrieveActivityPolicy
      description: Return a single activity policy. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: id
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        '200':
          content:
            application/json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
            application/vnd.pixiebrix.api+json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
          description: ''
      tags:
      - activity
    patch:
      operationId: partialUpdateActivityPolicy
      description: Update an activity policy's name, assigned groups, or config. Changing the config bumps the policy version. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: id
        in: path
        required: true
        description: ''
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ActivityPolicy'
      responses:
        '200':
          content:
            application/json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
            application/vnd.pixiebrix.api+json; version=2.0:
              schema:
                $ref: '#/components/schemas/ActivityPolicy'
          description: ''
      tags:
      - activity
    delete:
      operationId: destroyActivityPolicy
      description: Delete an activity policy. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: id
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - activity
  /api/activity/member-policies/:
    get:
      operationId: listMemberPolicies
      description: Return the activity policies that apply to a specific team member (those assigned to any of the member's groups), each with the group(s) the member belongs to that make it apply. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: true
        description: Member UUID whose applicable policies to return (required).
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemberPolicy'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemberPolicy'
          description: ''
      tags:
      - activity
  /api/activity/reports/member-timeline/:
    get:
      operationId: listMemberTimelines
      description: Return a member's activity spans and events over the reporting window (``start``/``end``, default the last 7 days). When no window is given, a single ``date`` is honored instead (day boundaries in the optional ``tz``, else UTC). Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: true
        description: Member UUID whose timeline to return (required).
        schema:
          type: string
          format: uuid
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: date
        in: query
        required: false
        description: Optional single day (YYYY-MM-DD) to scope the timeline to, in `tz`. Ignored when start/end is given.
        schema:
          type: string
          format: date
      - name: tz
        in: query
        required: false
        description: Optional IANA timezone for day boundaries (e.g. America/New_York); defaults to UTC.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/MemberTimelineResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/MemberTimelineResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/top-sites/:
    get:
      operationId: listTopSites
      description: Return page-session domains ranked by focused time for a member (``user``) or across one or more groups (``groups``), else the whole organization. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        description: Optional maximum number of rows to return.
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/TopSitesResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/TopSitesResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/productivity/:
    get:
      operationId: listProductivitySummaries
      description: Return the productivity score (share of focused-active time on productive sites) and the focused-time breakdown by class (productive/unproductive/neutral/unrated/mixed), for a member (``user``) or across one or more groups (``groups``), else the whole organization. Domains are classified at report time from each member's effective policy (default catalog + per-campaign overrides). Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProductivitySummaryResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProductivitySummaryResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/trends/:
    get:
      operationId: listProductivityTrends
      description: Return period-over-period trend series for the productivity score, focused time, in-tab activity level, and the productivity-class focused-time mix, bucketed by ``day`` (default) or ``week`` in the optional ``tz`` (else UTC), for a member (``user``) or across one or more groups (``groups``), else the whole organization. Also returns totals for the selected window and the immediately-preceding equal-length window for period-over-period deltas. Re-aggregates existing page-session spans (no new capture). Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: granularity
        in: query
        required: false
        description: 'Bucket granularity for the trend series: `day` (default) or `week`.'
        schema:
          type: string
          enum:
          - day
          - week
      - name: tz
        in: query
        required: false
        description: Optional IANA timezone for day boundaries (e.g. America/New_York); defaults to UTC.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProductivityTrendsResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/ProductivityTrendsResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/knowledge/:
    get:
      operationId: listKnowledgeReferenceds
      description: Return knowledge-base articles/videos referenced (the default Knowledge Referenced report), ranked by reference count, for a member (``user``) or across one or more groups (``groups``), else the whole organization. Each row reports the source, title, reference count, distinct agents, and the page dwell time (focused/visible) on the resource. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        description: Optional maximum number of rows to return.
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/KnowledgeReferencedResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/KnowledgeReferencedResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/handle-time/:
    get:
      operationId: listHandleTimes
      description: Return handle time per task span and aggregated per agent, for a member (``user``) or across one or more groups (``groups``), else the whole organization. Handle time is a task span's wall-clock duration. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        description: Optional maximum number of rows to return.
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/HandleTimeResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/HandleTimeResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/security/:
    get:
      operationId: listSecurityEvents
      description: Return security events (recorded by the Record Security Event brick and the policy-driven clipboard/URL-block/file-upload/protected-field enforcers) over the reporting window, newest first, for a member (``user``) or across one or more groups (``groups``), else the whole organization. Optional ``category`` / ``severity`` / ``action`` / ``destination`` query params filter the list; the response also includes per-category, per-severity, per-action, and top-destination (file-upload report) counts over the full window. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        required: false
        description: Optional member UUID to scope the report to one user.
        schema:
          type: string
          format: uuid
      - name: groups
        in: query
        required: false
        description: Optional group UUIDs to scope the report; repeated (?groups=a&groups=b) or comma-separated (?groups=a,b).
        schema:
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: start
        in: query
        required: false
        description: Optional ISO-8601 start of the report window (inclusive).
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        required: false
        description: Optional ISO-8601 end of the report window (exclusive).
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        description: Optional maximum number of rows to return.
        schema:
          type: integer
      - name: category
        in: query
        required: false
        description: Optional security-event category to filter the list by.
        schema:
          type: string
      - name: severity
        in: query
        required: false
        description: Optional security-event severity to filter the list by.
        schema:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
      - name: action
        in: query
        required: false
        description: Optional graduated-action (monitor/warn/block/softBlock) to filter the list by.
        schema:
          type: string
      - name: destination
        in: query
        required: false
        description: Optional file-upload destination to filter the list by.
        schema:
          type: string
      - name: precision
        in: query
        required: false
        description: Optional Interaction-Matching precision (L0/L1/L2) to filter the list by.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/SecurityEventsResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/SecurityEventsResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/security-event-context/:
    get:
      operationId: listSecurityEventContexts
      description: Return the activity context surrounding a single security event (``event``) — the enclosing trace's references and security events, plus other same-agent security events within a few minutes (any trace), each carrying its full detail — for the before/after timeline on the event detail. Resolution is by event id within the organization, with no date-range / group filter, so a shared link always resolves the anchor within the recipient's permission scope. Restricted to organization admins/managers and gated by the activity-tracking flag.
      parameters:
      - name: organization
        in: query
        required: true
        description: UUID of the organization to scope the report to.
        schema:
          type: string
          format: uuid
      - name: event
        in: query
        required: true
        description: UUID of the security event to build surrounding context around.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json; version=1.0:
              schema:
                $ref: '#/components/schemas/SecurityEventContextResponse'
            application/vnd.pixiebrix.api+json; version=1.0:
              schema:
                $ref: '#/components/schemas/SecurityEventContextResponse'
          description: ''
      tags:
      - activity
  /api/activity/reports/shadow-ai/:
    get:
      operationId: listShadowAis
      description: Return shadow-AI usage rolled up per AI too

# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pixiebrix/refs/heads/main/openapi/pixiebrix-activity-api-openapi.yml