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 tool and per member from the on-device AI-prompt security events, for a member (``user``) or across one or more groups (``groups``), else the whole organization. Each tool reports how many PII-bearing prompts were seen, how many were intervened (block/softBlock/redact), and how many distinct members used it; each member reports the same counts and the tools they used. Tools are attributed at report time from the shipped AI-tool catalog. 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/ShadowAiResponse' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/ShadowAiResponse' description: '' tags: - activity /api/activity/reports/trace/: get: operationId: listTraces description: Return all spans and events for a single trace (``trace``), scoped to the organization, for the trace-waterfall view. 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: trace in: query required: true description: UUID of the trace whose spans and events to return. schema: type: string format: uuid responses: '200': content: application/json; version=1.0: schema: $ref: '#/components/schemas/TraceResponse' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/TraceResponse' description: '' tags: - activity /api/activity/exports/{id}/: get: operationId: retrieveActivityExportJob description: Return the status and result of an activity-data export job, including the signed download URL (``data``) once the job succeeds or the error message if it failed. Scoped to the user that requested the export, who must still be an admin/manager of the organization. parameters: - name: id in: path required: true description: A UUID string identifying this activity export job. schema: type: string responses: '200': content: application/json; version=1.0: schema: $ref: '#/components/schemas/ActivityExportJob' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/ActivityExportJob' description: '' tags: - activity /api/activity/ingest/: post: operationId: createActivityIngest description: Ingest a batch of activity spans and span events for an organization. Records are attributed to the authenticated user and stamped with the organization's resolved policy. Returns 202 Accepted with the number of spans and events written. Gated by the activity-tracking organization feature flag. parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ActivityIngest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ActivityIngest' multipart/form-data: schema: $ref: '#/components/schemas/ActivityIngest' responses: '202': content: application/json; version=1.0: schema: $ref: '#/components/schemas/ActivityIngestResult' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/ActivityIngestResult' description: '' tags: - activity /api/activity/exports/: post: operationId: createActivityExportJob description: Start an asynchronous job that exports an organization's collected activity data (``spans`` or ``events``) to a downloadable CSV, returning the new job's id and initial status. Optionally scoped to a member, groups, and a date window. Restricted to organization admins/managers and gated by the activity-tracking flag. parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ActivityExportRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ActivityExportRequest' multipart/form-data: schema: $ref: '#/components/schemas/ActivityExportRequest' responses: '201': content: application/json; version=1.0: schema: $ref: '#/components/schemas/ActivityExportJobStarted' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/ActivityExportJobStarted' description: '' tags: - activity /api/activity/address-list/: put: operationId: updateAddressListUpload description: Replace or upsert the caller's organization known-address list from a self-service upload. The uploader hashes each address on-device (see ``libs/data-access-base/src/addressHashUtils.ts``) and sends only ``{identifier, entry_type, level, hash}`` rows — raw addresses never leave the browser. Each address expands into one row per match level (exact / building / street) sharing an ``identifier``. Re-uploading an identifier replaces its whole level set (a changed address that now yields fewer levels leaves no stale level row); when ``replace`` is true, addresses whose identifier is absent from the upload are also deleted so the stored list matches the file exactly. ``upserted`` / ``deleted`` count distinct addresses (identifiers), not the larger per-level row count. Admin/manager + ``activity-tracking`` flag gated; scoped to the caller's organization. parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/AddressListUpload' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AddressListUpload' multipart/form-data: schema: $ref: '#/components/schemas/AddressListUpload' responses: '200': content: application/json; version=1.0: schema: $ref: '#/components/schemas/AddressListUploadResult' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/AddressListUploadResult' description: '' tags: - activity delete: operationId: destroyAddressListUpload description: Clear the caller's organization known-address list, removing every address. Returns the number of addresses deleted. Admin/manager + ``activity-tracking`` flag gated; scoped to the caller's organization. parameters: - name: organization in: query required: true description: UUID of the organization whose known-address list to clear. schema: type: string format: uuid responses: '200': content: application/json; version=1.0: schema: $ref: '#/components/schemas/AddressListClearResult' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/AddressListClearResult' description: '' tags: - activity /api/activity/data/: delete: operationId: destroyPurgeActivityData description: Delete all collected activity data (spans and events) for an organization (``organization`` query parameter), leaving its activity policies intact. A development affordance for clearing prototype data; the deletion cannot be undone. Restricted to organization admins/managers and gated by the activity-tracking flag. parameters: - name: organization in: query required: true description: UUID of the organization whose collected activity data to purge. schema: type: string format: uuid responses: '200': content: application/json; version=1.0: schema: $ref: '#/components/schemas/PurgeActivityDataResponse' application/vnd.pixiebrix.api+json; version=1.0: schema: $ref: '#/components/schemas/PurgeActivityDataResponse' description: '' tags: - activity components: schemas: SecurityEventsResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time events: type: array items: type: object properties: id: type: string format: uuid occurred_at: type: string format: date-time user: type: string format: uuid email: type: - string - 'null' category: type: - string - 'null' severity: type: - string - 'null' message: type: - string - 'null' action: type: - string - 'null' outcome: type: - string - 'null' intervention_response: type: - string - 'null' justification: type: - string - 'null' reason_code: type: - string - 'null' destination: type: - string - 'null' files: type: - array - 'null' items: type: object properties: name: type: - string - 'null' size: type: - integer - 'null' type: type: - string - 'null' required: - name - size - type categories: type: - array - 'null' items: type: string terms: type: - array - 'null' items: type: string kind: type: - string - 'null' identifier: type: - string - 'null' entry_type: type: - string - 'null' match_level: type: - string - 'null' record_id: type: - string - 'null' precision: type: - string - 'null' url: type: string domain: type: string trace_id: type: string format: uuid span_id: type: - string - 'null' format: uuid required: - id - occurred_at - user - email - category - severity - message - action - outcome - intervention_response - justification - reason_code - destination - files - categories - terms - kind - identifier - entry_type - match_level - record_id - precision - url - domain - trace_id - span_id events_truncated: type: boolean by_category: type: array items: type: object properties: category: type: - string - 'null' count: type: integer required: - category - count by_severity: type: array items: type: object properties: severity: type: - string - 'null' count: type: integer required: - severity - count by_action: type: array items: type: object properties: action: type: - string - 'null' count: type: integer required: - action - count by_destination: type: array items: type: object properties: destination: type: string count: type: integer required: - destination - count required: - organization - start - end - events - events_truncated - by_category - by_severity - by_action - by_destination AddressListUpload: type: object properties: organization: type: string format: uuid replace: type: boolean default: false entries: type: array items: type: object properties: identifier: type: string maxLength: 255 entry_type: enum: - fraud - employee type: string level: enum: - exact - building - street type: string hash: type: string pattern: ^[0-9a-fA-F]{64}$ required: - identifier - entry_type - level - hash required: - organization - entries ShadowAiResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time by_tool: type: array items: type: object properties: tool: type: string event_count: type: integer intervention_count: type: integer member_count: type: integer required: - tool - event_count - intervention_count - member_count by_member: type: array items: type: object properties: user_id: type: string format: uuid email: type: - string - 'null' event_count: type: integer intervention_count: type: integer tools: type: array items: type: string required: - user_id - email - event_count - intervention_count - tools truncated: type: boolean required: - organization - start - end - by_tool - by_member - truncated CustomLanguageListUpload: type: object properties: organization: type: string format: uuid replace: type: boolean default: false entries: type: array items: type: object properties: term: type: string maxLength: 255 category: enum: - profanity - slurs_hate - sexual - threats - custom type: string default: custom severity: enum: - low - medium - high type: string default: medium required: - term required: - organization - entries CustomLanguageListUploadResult: type: object properties: upserted: type: integer minimum: 0 deleted: type: integer minimum: 0 required: - upserted - deleted CustomLanguageListEntry: type: object properties: term: type: string category: enum: - profanity - slurs_hate - sexual - threats - custom type: string severity: enum: - low - medium - high type: string required: - term - category - severity AddressListMatch: type: object properties: identifier: type: string description: Human reference surfaced in the risk report in place of the raw address (e.g. a fraud-case id or an employee id). maxLength: 255 entry_type: enum: - fraud - employee type: string description: Whether the address is a known-fraud address or an employee's own. level: enum: - exact - building - street type: string description: Granularity this hash row represents (exact / building / street). Set on-device at seed/upload time — the server never normalizes, so it cannot derive closeness itself. One seeded address expands into one row per level, sharing an identifier; the match endpoint returns the finest level that hits. required: - identifier - entry_type ActivityExportJob: type: object properties: id: type: string format: uuid status: enum: - UNKNOWN - PENDING - STARTED - SUCCESS - FAILURE type: string dataset: enum: - spans - events type: string created_at: type: string format: date-time readOnly: true data: type: - string - 'null' format: binary error_message: type: - string - 'null' required: - id - dataset KnowledgeReferencedResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time articles: type: array items: type: object properties: source: type: - string - 'null' title: type: - string - 'null' record_id: type: - string - 'null' url: type: string reference_count: type: integer distinct_agents: type: integer last_referenced_at: type: string format: date-time total_focused_ms: type: integer total_visible_ms: type: integer required: - source - title - record_id - url - reference_count - distinct_agents - last_referenced_at - total_focused_ms - total_visible_ms required: - organization - start - end - articles TraceResponse: type: object properties: organization: type: string format: uuid trace_id: type: string format: uuid spans: type: array items: type: object properties: trace_id: type: string format: uuid span_id: type: string format: uuid parent_span_id: type: - string - 'null' format: uuid user: type: string format: uuid email: type: - string - 'null' kind: enum: - task - page_session - subtask - custom - interaction type: string name: type: string started_at: type: string format: date-time ended_at: type: string format: date-time focused_ms: type: integer idle_ms: type: integer visible_ms: type: integer background_ms: type: integer active_input_ms: type: integer active_input_samples: type: integer attributes: type: object additionalProperties: true classification: type: - string - 'null' required: - trace_id - span_id - parent_span_id - user - email - kind - name - started_at - ended_at - focused_ms - idle_ms - visible_ms - background_ms - active_input_ms - active_input_samples - attributes - classification events: type: array items: type: object properties: id: type: string format: uuid trace_id: type: string format: uuid span_id: type: - string - 'null' format: uuid user: type: string format: uuid email: type: - string - 'null' event_type: type: string occurred_at: type: string format: date-time url: type: string domain: type: string data: type: object additionalProperties: true required: - id - trace_id - span_id - user - email - event_type - occurred_at - url - domain - data spans_truncated: type: boolean events_truncated: type: boolean required: - organization - trace_id - spans - events - spans_truncated - events_truncated ProhibitedLanguageCorpus: type: object properties: version: type: integer terms: type: array items: type: object properties: term: type: string category: enum: - profanity - sexual - slurs_hate type: string severity: enum: - low - medium - high type: string required: - term - category - severity required: - version - terms MemberPolicy: type: object properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true version: type: integer readOnly: true assigned_groups: type: array items: type: object properties: id: type: string format: uuid name: type: string required: - id - name readOnly: true matching_groups: type: array items: type: object properties: id: type: string format: uuid name: type: string required: - id - name readOnly: true HandleTimeResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time tasks: type: array items: type: object properties: trace_id: type: string format: uuid span_id: type: string format: uuid name: type: string user_id: type: string format: uuid email: type: - string - 'null' started_at: type: string format: date-time ended_at: type: string format: date-time handle_ms: type: integer required: - trace_id - span_id - name - user_id - email - started_at - ended_at - handle_ms by_agent: type: array items: type: object properties: user_id: type: string format: uuid email: type: - string - 'null' task_count: type: integer total_handle_ms: type: integer avg_handle_ms: type: integer required: - user_id - email - task_count - total_handle_ms - avg_handle_ms required: - organization - start - end - tasks - by_agent ActivityExportRequest: type: object properties: organization: type: string format: uuid dataset: enum: - spans - events type: string default: spans user: type: - string - 'null' format: uuid groups: type: array items: type: string format: uuid start: type: - string - 'null' format: date-time end: type: - string - 'null' format: date-time required: - organization MemberTimelineResponse: type: object properties: organization: type: string format: uuid user: type: string format: uuid start: type: string format: date-time end: type: string format: date-time tz: type: string spans: type: array items: type: object properties: trace_id: type: string format: uuid span_id: type: string format: uuid parent_span_id: type: - string - 'null' format: uuid user: type: string format: uuid email: type: - string - 'null' kind: enum: - task - page_session - subtask - custom - interaction type: string name: type: string started_at: type: string format: date-time ended_at: type: string format: date-time focused_ms: type: integer idle_ms: type: integer visible_ms: type: integer background_ms: type: integer active_input_ms: type: integer active_input_samples: type: integer attributes: type: object additionalProperties: true classification: type: - string - 'null' required: - trace_id - span_id - parent_span_id - user - email - kind - name - started_at - ended_at - focused_ms - idle_ms - visible_ms - background_ms - active_input_ms - active_input_samples - attributes - classification events: type: array items: type: object properties: id: type: string format: uuid trace_id: type: string format: uuid span_id: type: - string - 'null' format: uuid user: type: string format: uuid email: type: - string - 'null' event_type: type: string occurred_at: type: string format: date-time url: type: string domain: type: string data: type: object additionalProperties: true required: - id - trace_id - span_id - user - email - event_type - occurred_at - url - domain - data spans_truncated: type: boolean events_truncated: type: boolean required: - organization - user - start - end - tz - spans - events - spans_truncated - events_truncated AddressListSummary: type: object properties: count: type: integer minimum: 0 required: - count AddressListClearResult: type: object properties: deleted: type: integer minimum: 0 required: - deleted EffectivePolicyResponse: type: object properties: organization: type: string format: uuid schemaVersion: type: integer config: type: object additionalProperties: true policies: type: array items: type: object properties: id: type: string format: uuid version: type: integer required: - id - version required: - organization - schemaVersion - config - policies ActivityIngestResult: type: object properties: spans: type: integer minimum: 0 events: type: integer minimum: 0 required: - spans - events AddressListUploadResult: type: object properties: upserted: type: integer minimum: 0 deleted: type: integer minimum: 0 required: - upserted - deleted ProductivityTrendsResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time tz: type: string granularity: enum: - day - week type: string buckets: type: array items: type: object properties: focused_ms: type: integer active_input_ms: type: integer active_input_samples: type: integer productive_focused_ms: type: integer unproductive_focused_ms: type: integer neutral_focused_ms: type: integer unrated_focused_ms: type: integer mixed_focused_ms: type: integer score: type: - number - 'null' bucket_start: type: string format: date-time required: - focused_ms - active_input_ms - active_input_samples - productive_focused_ms - unproductive_focused_ms - neutral_focused_ms - unrated_focused_ms - mixed_focused_ms - score - bucket_start buckets_truncated: type: boolean summary: type: object properties: focused_ms: type: integer active_input_ms: type: integer active_input_samples: type: integer productive_focused_ms: type: integer unproductive_focused_ms: type: integer neutral_focused_ms: type: integer unrated_focused_ms: type: integer mixed_focused_ms: type: integer score: type: - number - 'null' required: - focused_ms - active_input_ms - active_input_samples - productive_focused_ms - unproductive_focused_ms - neutral_focused_ms - unrated_focused_ms - mixed_focused_ms - score previous_summary: type: object properties: focused_ms: type: integer active_input_ms: type: integer active_input_samples: type: integer productive_focused_ms: type: integer unproductive_focused_ms: type: integer neutral_focused_ms: type: integer unrated_focused_ms: type: integer mixed_focused_ms: type: integer score: type: - number - 'null' required: - focused_ms - active_input_ms - active_input_samples - productive_focused_ms - unproductive_focused_ms - neutral_focused_ms - unrated_focused_ms - mixed_focused_ms - score required: - organization - start - end - tz - granularity - buckets - buckets_truncated - summary - previous_summary TopSitesResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time sites: type: array items: type: object properties: domain: type: string hostname: type: string total_focused_ms: type: integer total_visible_ms: type: integer total_idle_ms: type: integer span_count: type: integer classification: type: - string - 'null' required: - domain - hostname - total_focused_ms - total_visible_ms - total_idle_ms - span_count - classification required: - organization - start - end - sites ProductivitySummaryResponse: type: object properties: organization: type: string format: uuid start: type: string format: date-time end: type: string format: date-time score: type: - number - 'null' total_focused_ms: type: integer productive_focused_ms: type: integer unproductive_focused_ms: type: integer neutral_focused_ms: type: integer unrated_focused_ms: type: integer mixed_focused_ms: type: integer required: - organization - start - end - score - total_focused_ms - productive_focused_ms - unproductive_focused_ms - neutral_focused_ms - unrated_focused_ms - mixed_focused_ms ActivityIngest: type: object properties: organization: type: string format: uuid spans: type: array items: type: object properties: span_id: type: string format: uuid parent_span_id: type: - string - 'null' format: uuid trace_id: type: string format: uuid deployment: type: - string - 'null' format: uuid kind: enum: - task - page_session - subtask - custom - interaction type: string name: type: string default: '' maxLength: 512 policy_version: type: - integer - 'null' minimum: 1 started_at: type: string format: date-time ended_at: type: string format: date-time focused_ms: type: integer default: 0 minimum: 0 idle_ms: type: integer default: 0 minimum: 0 visible_ms: type: integer default: 0 minimum: 0 background_ms: type: integer default: 0 minimum: 0 active_input_ms: type: integer default: 0 minimum: 0 active_input_samples: type: integer default: 0 minimum: 0 attributes: type: object additionalProperties: true required: - span_id - trace_id - kind - started_at - ended_at events: type: array items: type: object properties: event_id: type: string format: uuid trace_id: type: string format: uuid span_id: type: - string - 'null' format: uuid deployment: type: - string - 'null' format: uuid event_type: type: string maxLength: 64 policy_version: type: - integer - 'null' minimum: 1 occurred_at: type: string format: date-time url: type: string default: '' domain: type: string default: '' maxLength: 255 data: type: object additionalProperties: true required: - event_id - trace_id - event_type - occurred_at required: - organization ActivityExportJobStarted: type: object properties: id: type: string format: uuid description: The export job id to poll for status. status: enum: - UNKNOWN - PENDING - STARTED - SUCCESS - FAILURE type: string required: - id - status PurgeActivityDataResponse: type: object properties: organization: type: string format: uuid spans_deleted: type: integer events_deleted: type: integer required: - organization - spans_deleted - events_deleted ActivityPolicy: type: object properties: id: type: string format: uuid readOnly: true organization: type: string name: type: string maxLength: 256 config: type: object additionalProperties: true description: Policy configuration (signals, PII knobs, task definitions, URL rules); validated against the versioned activity policy JSON Schema. version: type: integer readOnly: true groups: type: array items: type: string description: Organization groups this policy applies to. assigned_groups: type: array items: type: object properties: id: type: string format: uuid name: type: string required: - id - name readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - organization - name SecurityEventContextResponse: type: object properties: organization: type: string format: uuid anchor: type: object properties: id: type: string format: uuid occurred_at: type: string format: date-time user: type: string format: uuid email: type: - string - 'null' category: type: - string - 'null' severity: type: - string - 'null' message: type: - string - 'null' action: type: - string - 'null' outcome: type: - string - 'null' intervention_response: type: - string - 'null' justification: type: - string - 'null' reason_code: type: - string - 'null' destination: type: - string - 'null' files: type: - array - 'null' items: type: object properties: name: type: - string - 'null' size: type: - integer - 'null' type: type: - string - 'null' required: - name - size - type categories: type: - array - 'null' items: type: string terms: type: - array - 'null' items: type: string kind: type: - string - 'null' identifier: type: - string - 'null' entry_type: type: - string - 'null' match_level: type: - string - 'null' record_id: type: - string - 'null' precision: type: - string - 'null' url: type: string domain: type: string trace_id: type: string format: uuid span_id: type: - string - 'null' format: uuid required: - id - occurred_at - user - email - category - severity - message - action - outcome - intervention_response - justification - reason_code - destination - files - categories - terms - kind - identifier - entry_type - match_level - record_id - precision - url - domain - trace_id - span_id events: type: array items: type: object properties: id: type: string format: uuid occurred_at: type: string format: date-time event_type: type: string url: type: string domain: type: string data: type: object additionalProperties: true required: - id - occurred_at - event_type - url - domain - data truncated: type: boolean required: - organization - anchor - events - truncated