AgentsWorklog API reference
GitHub★

Activities

Activity Logs are short-lived records of active work in a repository. Create one when an agent starts editing — it auto-archives on PR merge, branch delete, or after 24 hours. Every route is repo-scoped in the path.

BASE URLhttps://<your-instance>/api/v1

The Activity object

Every activity is scoped to one GitHub repository and expires automatically. Access is governed entirely by the caller's GitHub permissions on that repo.

Attributes

ParameterTypeDescription
id
string
Unique identifier, prefixed with act_.
title
string
Short name for the work.
summary
string
One- or two-line description of what is being done.
actor
string
Display name of the human behind the session.
agent
string · nullable
Agent tool in use, e.g. "claude-code"; null for manual work.
status
enum
One of planned, active, paused, blocked, draft-pr-open, ready-for-review, merged, abandoned, archived, expired.
risk
enum
One of low, medium, high, critical.
branch
string · nullable
Branch the work is happening on.
base_branch
string · nullable
Branch it will merge into.
scope
object
{ areas, paths } — area labels and globs being touched.
pr_url
string · nullable
Link to the pull request, if one exists.
draft_pr
boolean
Whether the linked PR is a Draft.
blocking
boolean
Prominent warning flag — never a hard block.
heartbeat_at
timestamp · nullable
Last liveness signal; extends the TTL.
expires_at
timestamp
When the log auto-expires (ISO 8601, UTC).
created_at
timestamp
When the log was created.
THE ACTIVITY OBJECT 
{
  "id": "act_7Hs2Kd9",
  "type": "activity",
  "title": "Refactor auth middleware",
  "summary": "Splitting token validation out of the handler.",
  "actor": "Dana Lee",
  "agent": "claude-code",
  "status": "active",
  "risk": "high",
  "branch": "feat/auth-middleware",
  "scope": { "areas": ["auth"], "paths": ["src/auth/**"] },
  "pr_url": "https://github.com/acme/web/pull/482",
  "draft_pr": true,
  "blocking": false,
  "heartbeat_at": "2026-07-03T11:55:00Z",
  "expires_at": "2026-07-04T12:00:00Z",
  "created_at": "2026-07-03T11:48:00Z"
}
GET /repos/{owner}/{repo}/activity

List activities

Returns active activities for a repository, most recent first. Archived and expired activities are excluded by default. Paginated by next_cursor.

Query parameters

ParameterTypeDescription
status optional
enum
Filter by activity status.
risk optional
enum
Filter by risk level.
actor optional
string
Filter by the human behind the work.
branch optional
string
Filter by branch.
has_pr optional
boolean
Only logs with (or without) a PR link.
draft_pr_only optional
boolean
Restrict to logs whose PR is a Draft.
cursor optional
string
Pagination cursor from a prior next_cursor.
REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/activity \
  -H "Authorization: Bearer $TOKEN" \
  -G -d "status=active"
RESPONSE 200 OK 
{
  "items": [
    {
      "id": "act_7Hs2Kd9",
      "branch": "feat/auth-middleware",
      "risk": "high",
      "status": "active"
    },
    {
      "id": "act_3Ka91Lp",
      "branch": "chore/payments-sdk",
      "risk": "critical",
      "status": "active"
    }
  ],
  "next_cursor": null
}
GET /repos/{owner}/{repo}/activity/{id}

Retrieve an activity

Fetches a single Activity Log by id, including derived fields like pr_reminder_due. Returns 404 if it doesn't exist or the repo isn't visible to your token.

REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/activity/act_7Hs2Kd9 \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "act_7Hs2Kd9",
  "type": "activity",
  "title": "Refactor auth middleware",
  "summary": "Splitting token validation out of the handler.",
  "actor": "Dana Lee",
  "agent": "claude-code",
  "status": "active",
  "risk": "high",
  "branch": "feat/auth-middleware",
  "scope": { "areas": ["auth"], "paths": ["src/auth/**"] },
  "pr_url": "https://github.com/acme/web/pull/482",
  "draft_pr": true,
  "blocking": false,
  "heartbeat_at": "2026-07-03T11:55:00Z",
  "expires_at": "2026-07-04T12:00:00Z",
  "created_at": "2026-07-03T11:48:00Z"
}
POST /repos/{owner}/{repo}/activity

Create an activity

Logs a new unit of active work. title, summary, and actor are required; risk defaults to low. The 201 response wraps the new activity together with an inline overlap result, so a single create call also tells you whether you just collided with active work.

Body parameters

ParameterTypeDescription
title required
string
Short name for the work.
summary required
string
What you are about to do.
actor required
string
Display name of the human behind the session.
agent optional
string
Agent tool in use, e.g. "claude-code".
branch optional
string
Branch you're about to work on.
base_branch optional
string
Branch it will merge into.
scope optional
object
{ areas, paths } — area labels and globs. Defaults to empty.
risk optional
enum
Defaults to low.
pr_url optional
string
A https://github.com/ pull-request URL.
draft_pr optional
boolean
Whether the linked PR is a Draft. Defaults to false.
REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/activity \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refresh auth tokens",
    "summary": "Rotate refresh-token handling.",
    "actor": "Dana Lee",
    "branch": "feat/auth-refresh",
    "scope": { "paths": ["src/auth/**"] },
    "risk": "high"
  }'
RESPONSE 201 Created 
{
  "activity": {
    "id": "act_9Fq0Zt4",
    "status": "active",
    "risk": "high",
    "branch": "feat/auth-refresh",
    "expires_at": "2026-07-04T12:00:00Z"
  },
  "overlap": {
    "overlap_detected": false,
    "severity": null,
    "related_activity_ids": []
  }
}
POST /repos/{owner}/{repo}/activity/check

Check for overlap

Compares a proposed branch and scope against all active work in the repo without creating anything. It always returns 200 — overlap is advisory data, never a block. overlap_detected is true only for a genuine collision or a matching Notable; your own or stacked work is surfaced under expected_activity_ids instead. severity is one of low, medium, high (or null).

Body parameters

ParameterTypeDescription
scope optional
object
{ areas, paths } the caller intends to touch.
branch optional
string
Branch the caller intends to work on.
base_branch optional
string
Branch it will merge into.
tags optional
string[]
Extra labels to widen the match.
REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/activity/check \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "branch": "feat/auth-refresh",
       "scope": { "paths": ["src/auth/**"] } }'
RESPONSE 200 OK 
{
  "overlap_detected": true,
  "severity": "high",
  "reason": "Overlaps active work in src/auth/**",
  "related_activity_ids": ["act_7Hs2Kd9"],
  "related_notable_ids": [],
  "expected_activity_ids": [],
  "relationships": { "act_7Hs2Kd9": "collision" },
  "recommended_action": "Inspect Draft PR #482 before you start.",
  "reuse_opportunities": []
}
PATCH /repos/{owner}/{repo}/activity/{id}

Update an activity

Keeps a log current as scope grows or the PR opens. Only the fields you send change. Advance the lifecycle with status (illegal transitions return 409 invalid_transition), or pass heartbeat: true to extend the TTL.

Body parameters

ParameterTypeDescription
scope optional
object
Replacement { areas, paths } as scope changes.
risk optional
enum
New risk level.
pr_url optional
string
Attach or change the PR link.
draft_pr optional
boolean
Whether the PR is a Draft.
status optional
enum
Advance the lifecycle (transitions are validated).
heartbeat optional
boolean
Set true to bump heartbeat_at and extend the TTL.
REQUEST 
curl -X PATCH https://your-instance.example.com/api/v1/repos/acme/web/activity/act_9Fq0Zt4 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "paths": ["src/auth/**", "src/auth/tokens.ts"] },
    "risk": "critical"
  }'
RESPONSE 200 OK 
{
  "id": "act_9Fq0Zt4",
  "scope": { "areas": [], "paths": ["src/auth/**", "src/auth/tokens.ts"] },
  "risk": "critical",
  "status": "active"
}
POST /repos/{owner}/{repo}/activity/{id}/heartbeat

Heartbeat an activity

Signals the work is still live: bumps heartbeat_at and pushes expires_at out by the repo's activity TTL (capped by max_activity_ttl_ms when set). The plugin sends these automatically while you work.

REQUEST 
curl -X POST https://your-instance.example.com/api/v1/repos/acme/web/activity/act_9Fq0Zt4/heartbeat \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "act_9Fq0Zt4",
  "heartbeat_at": "2026-07-03T13:10:00Z",
  "expires_at": "2026-07-04T13:10:00Z"
}
POST /repos/{owner}/{repo}/activity/{id}/archive

Archive an activity

Archives a log immediately rather than waiting for expiry or an auto-archive trigger. The activity moves to status archived and drops out of the live feed, but remains retrievable until it is purged. Archiving is idempotent — re-archiving an already-archived log returns 200 with the record, not a conflict.

REQUEST 
curl -X POST https://your-instance.example.com/api/v1/repos/acme/web/activity/act_9Fq0Zt4/archive \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "act_9Fq0Zt4",
  "status": "archived",
  "archived_at": "2026-07-03T15:20:00Z"
}