paperclip-docs/docs/reference/api/activity.md

---

seo_title: Activity API seo_description: Paperclip's audit trail: what changed, who changed it, which object, and when. Two reads of the same underlying log, for auditing and for debugging.

Activity

Activity is Paperclip's audit trail. Use it when you want to answer: what changed, who changed it, which object changed, and when did it happen?

There are two reads of the same underlying log. The plain company feed (/activity) is a lightweight, newest-first list meant for quick review. The richer audit feed (/audit/agent-actions) is the one the UI's unified Activity page is built on — it adds cursor pagination, a scope toggle, attribution (which agent, which run, on whose behalf), and CSV export. If you need the history for one issue or one heartbeat run, use the issue and run-specific endpoints below.

---

Endpoints

List company activity

GET /api/companies/{companyId}/activity

Returns the company activity feed, newest first.

Query parameters:

Param	Description
agentId	Exact actor agent ID to filter by
entityType	Exact entity type to filter by
entityId	Exact entity ID to filter by

Notes:

• Filters are exact matches. There is no fuzzy search.
• There is no pagination on this endpoint.
• Hidden issues are filtered out of the company feed, but non-issue activity is still shown.
• Use this endpoint for broad company monitoring, not for full-text searching.

Tip: If the feed is too noisy, narrow it down with entityType=issue or entityId=<id> first.

curl "http://localhost:3100/api/companies/company-1/activity?entityType=issue&agentId=agent-1" \
  -H "Authorization: Bearer <your-token>"

const url = new URL("/api/companies/company-1/activity", "http://localhost:3100");
url.searchParams.set("entityType", "issue");
url.searchParams.set("agentId", "agent-1");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const activity = await res.json();

import requests

url = "http://localhost:3100/api/companies/company-1/activity"
params = {
    "entityType": "issue",
    "agentId": "agent-1",
}
headers = {
    "Authorization": f"Bearer {token}",
}

response = requests.get(url, params=params, headers=headers)
activity = response.json()

Audit feed (agent actions)

GET /api/companies/{companyId}/audit/agent-actions

Returns the rich, cursor-paginated audit feed that powers the unified Activity page. Rows come newest first and carry attribution the plain feed does not: the acting agent, the heartbeat run, and the responsible user (resolved from the run when the row itself doesn't name one). Issue, comment, and document rows are enriched with the issue identifier, title, and a short comment excerpt.

Query parameters:

Param	Type	Description
actorScope	agents | all	Which actors to include. agents (the default) returns only rows with an agent attached; all returns every actor kind.
agentId	string (UUID)	Filter to one acting agent.
responsibleUserId	string	Everything done on one person's behalf.
runId	string (UUID)	Filter to one heartbeat run.
entityType	string	Exact entity type, such as issue.
entityId	string	Exact entity ID.
action	string	Action-name prefix match, so issue matches issue.updated, issue.comment_added, and so on.
actorType	agent | user | system | plugin	Exact actor kind.
from	date	Earliest createdAt to include.
to	date	Latest createdAt to include.
cursor	string	Opaque cursor from a previous response's nextCursor.
limit	integer	Page size, 1–200. Defaults to 50.

Each response is { items, nextCursor, accessTier }. Pass nextCursor back as cursor to page; it is null on the last page.

Two-tier access

This endpoint has two levels of access, and the level is reported back as accessTier:

• actorScope=all is open to any company member. They get every actor kind (agent, user, system, plugin), but the sensitive attribution fields — agentId, runId, responsibleUserId, and details — are stripped to null, and the response comes back with accessTier: "basic". Attribution filters (agentId, responsibleUserId, runId, entityType, entityId, action, actorType, from, to) are rejected with 403 for these callers.
• Members holding the audit:view_agent_actions permission get complete rows, may use every filter, and get accessTier: "full". The default scope, actorScope=agents, always requires this permission regardless of tier.

curl "http://localhost:3100/api/companies/company-1/audit/agent-actions?actorScope=all&limit=50" \
  -H "Authorization: Bearer <your-token>"

const url = new URL("/api/companies/company-1/audit/agent-actions", "http://localhost:3100");
url.searchParams.set("actorScope", "all");
url.searchParams.set("limit", "50");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const { items, nextCursor, accessTier } = await res.json();

import requests

url = "http://localhost:3100/api/companies/company-1/audit/agent-actions"
params = {
    "actorScope": "all",
    "limit": 50,
}
headers = {
    "Authorization": f"Bearer {token}",
}

response = requests.get(url, params=params, headers=headers)
feed = response.json()

Export the audit feed as CSV

GET /api/companies/{companyId}/audit/agent-actions.csv

Streams the audit feed as a CSV attachment. It takes the same filter parameters as the feed above (cursor and limit are ignored — the export drives its own pagination). A single export tops out at 10,000 rows, so narrow the date range for long histories.

This endpoint always requires the audit:view_agent_actions permission — there is no basic tier for the export.

The export is itself an auditable act: Paperclip records an audit.exported activity event capturing who exported, the filter set they used, and how many rows left the system.

The columns are, in order: createdAt, action, actorType, actorId, agentId, runId, responsibleUserId, entityType, entityId, issueIdentifier, issueTitle, commentExcerpt, documentKey.

curl "http://localhost:3100/api/companies/company-1/audit/agent-actions.csv?from=2026-01-01" \
  -H "Authorization: Bearer <your-token>" \
  -o agent-audit.csv

const url = new URL("/api/companies/company-1/audit/agent-actions.csv", "http://localhost:3100");
url.searchParams.set("from", "2026-01-01");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const csv = await res.text();

import requests

response = requests.get(
    "http://localhost:3100/api/companies/company-1/audit/agent-actions.csv",
    params={"from": "2026-01-01"},
    headers={"Authorization": f"Bearer {token}"},
)

with open("agent-audit.csv", "wb") as f:
    f.write(response.content)

Create activity event

POST /api/companies/{companyId}/activity

Creates a new activity log entry. This endpoint is board-only.

Most Paperclip routes write activity automatically, so you usually do not call this yourself unless you are building a custom admin integration or recording a system event.

Request body:

Field	Type	Required	Notes
actorType	agent | user | system | plugin	no	Defaults to system
actorId	string	yes	Free-form actor label or ID
action	string	yes	Event name, such as issue.updated
entityType	string	yes	What changed
entityId	string	yes	ID of the affected entity
agentId	string | null	no	Optional agent UUID
details	object | null	no	Additional JSON payload; sanitized before storage

Practical notes:

• actorId is stored as text. It can be a user ID, agent ID, or a system label.
• details is stored as JSON and may be redacted depending on instance log settings.
• Use this for board-side or system-side events, not for a public client API.

curl -X POST "http://localhost:3100/api/companies/company-1/activity" \
  -H "Authorization: Bearer <board-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "actorType": "system",
    "actorId": "nightly-sync",
    "action": "company.report_generated",
    "entityType": "company",
    "entityId": "company-1",
    "details": {
      "source": "scheduled-job",
      "report": "weekly-summary"
    }
  }'

const res = await fetch("/api/companies/company-1/activity", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${boardToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    actorType: "system",
    actorId: "nightly-sync",
    action: "company.report_generated",
    entityType: "company",
    entityId: "company-1",
    details: {
      source: "scheduled-job",
      report: "weekly-summary",
    },
  }),
});

const created = await res.json();

import requests

response = requests.post(
    "http://localhost:3100/api/companies/company-1/activity",
    headers={
        "Authorization": f"Bearer {board_token}",
        "Content-Type": "application/json",
    },
    json={
        "actorType": "system",
        "actorId": "nightly-sync",
        "action": "company.report_generated",
        "entityType": "company",
        "entityId": "company-1",
        "details": {
            "source": "scheduled-job",
            "report": "weekly-summary",
        },
    },
)

created = response.json()

Issue activity

GET /api/issues/{issueId}/activity

Returns the activity history for one issue, newest first.

You can pass either:

• the raw issue UUID
• the human identifier shown in the UI, such as PAP-475

The route resolves the identifier before loading activity, so this is the best endpoint when you are investigating one task and want the full history in order.

curl "http://localhost:3100/api/issues/PAP-475/activity" \
  -H "Authorization: Bearer <your-token>"

const res = await fetch("/api/issues/PAP-475/activity", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const issueActivity = await res.json();

import requests

response = requests.get(
    "http://localhost:3100/api/issues/PAP-475/activity",
    headers={
        "Authorization": f"Bearer {token}",
    },
)

issue_activity = response.json()

Runs for an issue

GET /api/issues/{issueId}/runs

Returns the heartbeat runs that touched an issue.

Why this is useful:

• activity answers "what happened"
• runs answers "which heartbeat runs were involved"

The server links runs to issues using the run context snapshot and the issue activity log, so this endpoint can still find a run even when the activity trail is incomplete.

The response includes run metadata such as:

• runId
• status
• agentId
• adapterType
• startedAt
• finishedAt
• createdAt
• invocationSource
• usageJson
• resultJson
• logBytes

Issues for a run

GET /api/heartbeat-runs/{runId}/issues

Returns the issues associated with a heartbeat run.

Notes:

• If the run does not exist, the endpoint returns an empty array.
• The route checks company access before returning anything.
• The response is a compact issue summary, not the full issue record.

Activity record

Each activity row stores:

Field	Meaning
companyId	Which company the event belongs to
actorType	agent, user, system, or plugin
actorId	Text label or ID for the actor
action	Event name
entityType	What was changed
entityId	Which entity changed
agentId	Optional actor agent UUID
runId	Optional heartbeat run UUID
details	Optional JSON payload with extra context
createdAt	When the event was recorded

Note: The company feed is append-only. Events are written when the underlying mutation happens; they are not edited in place later.