Files
PaperClipAI/docs/api/activity.md
T
sentry[bot] ac02de7732 fix(server): validate agentId query parameter on company activity endpoint (#22516)
<!-- Write all pull request text in Simplified Technical English
(ASD-STE100): short sentences, one instruction per sentence, simple
approved vocabulary, and the active voice. -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - This change is in the activity log API, `GET
/companies/:companyId/activity`.
> - The route sends the `agentId` query value directly to the database.
The `activity_log.agent_id` column is a UUID column.
> - A malformed value makes PostgreSQL fail, and the client gets a 500
response for a client mistake.
> - This pull request validates the `agentId` query value as a UUID and
returns HTTP 400 for a malformed value.
> - The benefit is that clients get a clear 400 error, and the server
does not report a false server error.

## Linked Issues or Issue Description

No public GitHub issue exists. This is the bug description.

**What happened?**

A client sent `GET /companies/:companyId/activity?agentId=dc04285a-`.
The route sent the truncated value to an `eq(activityLog.agentId, ...)`
condition. PostgreSQL failed with `invalid input syntax for type uuid:
"dc04285a-"`, and the server returned 500.

**Expected behavior**

A malformed `agentId` returns HTTP 400 with validation issues. A valid
UUID returns HTTP 200. An empty `agentId` applies no filter.

**Steps to reproduce**

1. Start the server.
2. Send `GET /api/companies/<company-id>/activity?agentId=dc04285a-` as
a board user.
3. Look at the response status. Before this change it is 500.

**Paperclip version or commit**

`master` at `68f641ba0bb7e8e8740bf62cca1cbfab45da8264` and later.

**Deployment mode**

Not specific to one deployment mode. The route is in the core server.

## What Changed

- Validate the `agentId` query on `GET /companies/:companyId/activity`
with `z.string().guid().optional()`.
- Convert an empty `agentId` value to `undefined`. This matches the
service behavior for an omitted filter.
- Throw a standard `badRequest` (HTTP 400) with validation issues for a
malformed `agentId`.
- Update `docs/api/activity.md` with the UUID requirement, the
empty-value behavior, and the 400 response.
- Add regression tests: a malformed `agentId` returns 400 and does not
call the service, and a valid UUID returns 200 and passes the filter.

## Verification

- `pnpm vitest run server/src/__tests__/activity-routes.test.ts` runs
the new validation tests.
- CI on head `ed3078339894bdd68f2093ddaf921fdb297623aa` is green,
including `ci / verify`, `ci / e2e`, and all server test shards.

## Risks

- Low risk. The change is one route and one query parameter.
- A client that sends a malformed `agentId` now gets HTTP 400 instead of
HTTP 500.
- A client that sends an empty `agentId` now gets the same result as an
omitted filter.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Code: Sentry Seer Autofix (Claude 3.5 Sonnet, as reported by Seer),
with tool use.
- PR description update: Claude Opus 5.5 (`claude-opus-5-5`), with tool
use.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

<!-- SEER_FIXES_SENTRY_ISSUE -->
Fixes
[PAPERCLIP-BACKEND-4E](https://paperclip-e0.sentry.io/issues/7805680817/?seerDrawer=true)
<!-- /SEER_FIXES_SENTRY_ISSUE -->

<sub>`@sentry <feedback>`: Autofix iterates on these changes</sub>
<sub>`@sentry stop iterating`: Autofix stops iterating on this run</sub>

<sub>This PR was automatically generated by Sentry at no cost. You can
[adjust this
setting](https://paperclip-e0.sentry.io/settings/projects/paperclip-backend/seer/)
at any time.</sub>

---------

Co-authored-by: sentry[bot] <39604003+sentry[bot]@users.noreply.github.com>
2026-11-21 19:20:02 -08:00

1.2 KiB

title, summary
title summary
Activity Activity log queries

Query the audit trail of all mutations across the company.

List Activity

GET /api/companies/{companyId}/activity

Query parameters:

Param Description
agentId Filter by actor agent. Must be a UUID; an empty value applies no filter. A malformed value returns 400 with validation details.
entityType Filter by entity type (issue, agent, approval)
entityId Filter by specific entity

Activity Record

Each entry includes:

Field Description
actor Agent or user who performed the action
action What was done (created, updated, commented, etc.)
entityType What type of entity was affected
entityId ID of the affected entity
details Specifics of the change
createdAt When the action occurred

What Gets Logged

All mutations are recorded:

  • Issue creation, updates, status transitions, assignments
  • Agent creation, configuration changes, pausing, resuming, termination
  • Approval creation, approval/rejection decisions
  • Comment creation
  • Budget changes
  • Company configuration changes

The activity log is append-only and immutable.