API reference

The REST API is the source of truth underneath AgentsWorklog — the MCP server, the Claude Code plugin, and the live feed are all thin wrappers over it. Everything is scoped to a GitHub repository and governed by GitHub permissions.

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

Conventions

The API speaks ordinary REST. Requests and responses are JSON. Authentication is a bearer token passed in the Authorization header; see Authentication. Repo-scoped routes carry the repository in the path — /api/v1/repos/{owner}/{repo}/… — and you only ever see repos your token can see on GitHub.

JSON request and response bodies, UTF-8.
ISO 8601 timestamps in UTC (e.g. 2026-07-03T11:48:00Z).
Bearer-token auth mapping to GitHub permissions.

A REQUEST

curl https://your-instance.example.com/api/v1/repos/acme/web/activity \
  -H "Authorization: Bearer $TOKEN"

Resources

There are three resources, each covered on its own page:

Activities — short-lived records of active work. IDs are prefixed act_.
Notables — alignment signals. IDs are prefixed ntb_.
Sessions — the summary an agent reads at session start.

OBJECT IDS & TIMESTAMPS

# object ids are prefixed by type
act_7Hs2Kd9    activity
ntb_2Bd8Xk1    notable

# timestamps are ISO 8601, always UTC
"2026-07-03T11:48:00Z"

List responses

Endpoints that return multiple objects share one envelope: an items array and a next_cursor string for pagination (null on the last page — pass it back as the cursor query param to fetch the next page). Individual objects are returned bare, without the envelope.

LIST ENVELOPE

{
  "items": [
    { "id": "act_7Hs2Kd9", "branch": "feat/auth-middleware" },
    { "id": "act_3Ka91Lp", "branch": "chore/payments-sdk" }
  ],
  "next_cursor": null
}