AgentsWorklog API reference
GitHub★

Notables

Notables are alignment signals — "know this before you start" context that isn't tied to a single branch. They default to about a 7-day life and link out to real docs rather than replacing them.

BASE URLhttps://api.agentsworklog.dev/v1

The Notable object

A notable is scoped to one repository, classified by category and severity, and expires automatically. When it references durable knowledge, doc_url points at the real doc.

Attributes

ParameterTypeDescription
id
string
Unique identifier, prefixed with not_.
repo
string
Repository the notable belongs to (owner/name).
title
string
One-line summary of the signal.
body
string
The caveat, in a sentence or two.
category
enum
migration, deprecation, security, flaky-test, other.
severity
enum
One of low, medium, high, critical.
doc_url nullable
string
Link to the real doc, when durable knowledge exists.
status
enum
active or archived.
expires_at
timestamp
When the notable auto-expires (~7 days, ISO 8601).
created_at
timestamp
When the notable was raised (ISO 8601).
THE NOTABLE OBJECT 
{
  "id": "not_2Bd8Xk1",
  "repo": "acme/web",
  "title": "Payments v2 migration in progress",
  "body": "Don't touch src/billing/** until PR #479 lands.",
  "category": "migration",
  "severity": "high",
  "doc_url": "https://docs.acme.dev/payments-v2",
  "status": "active",
  "expires_at": "2026-07-10T09:00:00Z",
  "created_at": "2026-07-03T09:00:00Z"
}
GET /v1/notables

List notables

Returns active notables for a repository, most recent first. Filter by category to narrow to a specific concern such as a migration or a security caveat.

Query parameters

ParameterTypeDescription
repo required
string
Repository to list, as owner/name.
status optional
enum
Filter by active or archived.
category optional
enum
Filter by category.
REQUEST 
curl https://api.agentsworklog.dev/v1/notables \
  -H "Authorization: Bearer $TOKEN" \
  -G -d "repo=acme/web" -d "category=migration"
RESPONSE 200 OK 
{
  "object": "list",
  "data": [
    {
      "id": "not_2Bd8Xk1",
      "title": "Payments v2 migration in progress",
      "category": "migration",
      "severity": "high"
    }
  ],
  "has_more": false
}
POST /v1/notables

Create a notable

Raises a new alignment signal. It starts active and expires after about 7 days unless archived first. Include a doc_url whenever the underlying knowledge belongs in real docs.

Body parameters

ParameterTypeDescription
title required
string
One-line summary of the signal.
body required
string
The caveat, in a sentence or two.
category required
enum
migration, deprecation, security, flaky-test, other.
severity optional
enum
Defaults to medium.
doc_url optional
string
Link to the real doc, when one exists.
REQUEST 
curl https://api.agentsworklog.dev/v1/notables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Flaky checkout e2e",
    "body": "checkout.e2e is intermittently red; a retry is not a real failure.",
    "category": "flaky-test"
  }'
RESPONSE 201 Created 
{
  "id": "not_7Qm1Rp0",
  "title": "Flaky checkout e2e",
  "category": "flaky-test",
  "severity": "medium",
  "status": "active",
  "expires_at": "2026-07-10T15:20:00Z"
}
DELETE /v1/notables/:id

Archive a notable

Resolves a notable before its expiry — for example when a migration lands. This is a soft delete: the notable moves to status archived and leaves the live feed, but remains retrievable.

REQUEST 
curl -X DELETE https://api.agentsworklog.dev/v1/notables/not_7Qm1Rp0 \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "not_7Qm1Rp0",
  "status": "archived",
  "archived_at": "2026-07-04T10:05:00Z"
}