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:

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:

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:

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:

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