---
title: "Add activity log event"
method: POST
path: "/v1/audit"
tags: ["audit"]
---

# Add activity log event

`POST /v1/audit`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/audit`
- Auth: HTTP bearer

Appends one client event to the workspace's activity log, for example that a help panel was opened. The `action` must be in the `cms.` namespace, so only events of that kind can be added this way. The actor is always the caller, never taken from the request body. The activity log is append-only: events can be added but never updated or deleted. Limited to 120 events a minute.

**Notes.**
- Needs only `audit-log.view`. The actor is always the caller; `ipAddress` and `userAgent` come from the request.

## Request body

- object
  - `action` string, required: Must be in the `cms.` namespace: `cms.` then lower-case letters, digits, `.`, `_` or `-` (up to 122 more characters).
  - `target` string
  - `detail` string
  - `nodeId` string, nullable: A location you can see.

## Response `201`

Success.

- object
  - `data` AuditEvent, required: One activity log event, with the actor resolved to a name.
    - `id` string, required
    - `at` string, required: ISO-8601 timestamp (UTC).
    - `workspaceId` string, required
    - `actor` string, required: `user:<id>`, `apikey:<id>`, `system`, or another internal actor.
    - `actorKind` 'user' | 'api-key' | 'system', required
    - `actorName` string, required: The person's or key's name; `System` for the system.
    - `actorEmail` string, required: The person's email; `n/a` for a key; `system@brix` for the system.
    - `action` string, required: What happened, e.g. `screen.renamed`.
    - `target` string, nullable, required: The id of the thing acted on.
    - `detail` string, nullable, required
    - `nodeId` string, nullable, required: The location the event belongs to; null for the workspace.
    - `nodeName` string, nullable, required
    - `ipAddress` string, nullable, required
    - `userAgent` string, nullable, required
    - `via` 'mcp' | 'api', nullable, required: How it arrived: `mcp` (an MCP tool such as Claude or ChatGPT), `api` (an API key on REST), null (in the Brix app).
    - `viaApp` string, nullable, required: The connector or API key behind an `mcp`/`api` event; null for the app.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `422`: `action` is missing or outside the `cms.` namespace, or `nodeId` is not a location you can see.
- `429`: More than 120 events a minute.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/7c2741bcdb16?raw)