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.

BASE URLhttps://api.agentsworklog.dev/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_.
repo
string
Repository the activity belongs to (owner/name).
branch
string
Branch the work is happening on.
paths
string[]
Globs for the files or areas being touched.
risk
enum
One of low, medium, high, critical.
status
enum
active or archived.
draft_pr_url nullable
string
Link to the Draft PR, if one exists.
expires_at
timestamp
When the log auto-expires (ISO 8601).
THE ACTIVITY OBJECT 
{
  "id": "act_7Hs2Kd9",
  "repo": "acme/web",
  "branch": "feat/auth-middleware",
  "paths": ["src/auth/**"],
  "risk": "high",
  "status": "active",
  "draft_pr_url": "https://github.com/acme/web/pull/482",
  "expires_at": "2026-07-04T12:00:00Z",
  "created_at": "2026-07-03T11:48:00Z"
}
GET /v1/activities

List activities

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

Query parameters

ParameterTypeDescription
repo required
string
Repository to list, as owner/name.
status optional
enum
Filter by active or archived.
risk optional
enum
Filter by risk level.
REQUEST 
curl https://api.agentsworklog.dev/v1/activities \
  -H "Authorization: Bearer $TOKEN" \
  -G -d "repo=acme/web" -d "status=active"
RESPONSE 200 OK 
{
  "object": "list",
  "data": [
    {
      "id": "act_7Hs2Kd9",
      "branch": "feat/auth-middleware",
      "risk": "high",
      "status": "active"
    },
    {
      "id": "act_3Ka91Lp",
      "branch": "chore/payments-sdk",
      "risk": "critical",
      "status": "active"
    }
  ],
  "has_more": false
}
POST /v1/activities

Create an activity

Logs a new unit of active work. The activity starts in status active and expires after 24 hours unless it is archived first.

Body parameters

ParameterTypeDescription
branch required
string
Branch you're about to work on.
paths required
string[]
Globs for the files or areas you'll touch.
risk optional
enum
Defaults to medium.
draft_pr_url optional
string
Link to the Draft PR, if open.
task optional
string
Short human-readable summary.
REQUEST 
curl https://api.agentsworklog.dev/v1/activities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "feat/auth-refresh",
    "paths": ["src/auth/**"],
    "risk": "high"
  }'
RESPONSE 201 Created 
{
  "id": "act_9Fq0Zt4",
  "branch": "feat/auth-refresh",
  "risk": "high",
  "status": "active",
  "expires_at": "2026-07-04T12:00:00Z"
}
POST /v1/activities/check

Check for overlap

Compares a proposed branch and paths against all active work in the repo without creating anything. Returns any matches with a severity so an agent can decide whether to proceed.

Body parameters

ParameterTypeDescription
branch required
string
Branch the caller intends to work on.
paths required
string[]
Globs the caller intends to touch.
tags optional
string[]
Extra labels to widen the match.
REQUEST 
curl https://api.agentsworklog.dev/v1/activities/check \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "branch": "feat/auth-refresh",
       "paths": ["src/auth/**"] }'
RESPONSE 200 OK 
{
  "overlap": true,
  "matches": [
    {
      "activity": "act_7Hs2Kd9",
      "title": "Refactor auth middleware",
      "severity": "high",
      "draft_pr_url": "https://github.com/acme/web/pull/482"
    }
  ]
}
PATCH /v1/activities/:id

Update an activity

Keeps a log current as scope grows or the Draft PR opens. Only the fields you send change; the rest are left as they are. Setting status to archived is the explicit "mark done" path.

Body parameters

ParameterTypeDescription
paths optional
string[]
Replacement globs as scope changes.
risk optional
enum
New risk level.
draft_pr_url optional
string
Attach or change the Draft PR.
task optional
string
Update the summary.
status optional
enum
Set to archived to mark the work done.
REQUEST 
curl -X PATCH https://api.agentsworklog.dev/v1/activities/act_9Fq0Zt4 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["src/auth/**", "src/auth/tokens.ts"],
    "risk": "critical"
  }'
RESPONSE 200 OK 
{
  "id": "act_9Fq0Zt4",
  "paths": ["src/auth/**", "src/auth/tokens.ts"],
  "risk": "critical",
  "status": "active"
}
DELETE /v1/activities/:id

Archive an activity

Archives a log immediately rather than waiting for expiry or an auto-archive trigger. This is a soft delete — the activity moves to status archived and drops out of the live feed, but remains retrievable. Archiving an already-archived activity returns 409 Conflict.

REQUEST 
curl -X DELETE https://api.agentsworklog.dev/v1/activities/act_9Fq0Zt4 \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "act_9Fq0Zt4",
  "status": "archived",
  "archived_at": "2026-07-03T15:20:00Z"
}