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. Every route is repo-scoped in the path.

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

The Notable object

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

Attributes

ParameterTypeDescription
id
string
Unique identifier, prefixed with ntb_.
title
string
One-line summary of the signal.
summary
string
The caveat, in a sentence or two.
category
enum
architecture, process, pattern, warning, migration, testing, security, dependency, api-contract, temporary-workaround, deprecation, release.
importance
enum
One of low, medium, high, critical.
status
enum
active, archived, or expired.
decision_url
string · nullable
Link to the real doc, when durable knowledge exists.
supersedes
string[]
Notable ids this record replaces.
applies_until
timestamp · nullable
Semantic end date, distinct from record expiry.
scope
object
{ areas, paths } the notable applies to.
blocking
boolean
Prominent warning flag — never a hard block.
expires_at
timestamp
When the notable auto-expires (~7 days, ISO 8601, UTC).
created_at
timestamp
When the notable was raised.
THE NOTABLE OBJECT 
{
  "id": "ntb_2Bd8Xk1",
  "type": "notable",
  "title": "Payments v2 migration in progress",
  "summary": "Don't touch src/billing/** until PR #479 lands.",
  "category": "migration",
  "importance": "high",
  "status": "active",
  "decision_url": "https://docs.acme.dev/payments-v2",
  "scope": { "areas": ["billing"], "paths": ["src/billing/**"] },
  "expires_at": "2026-07-10T09:00:00Z",
  "created_at": "2026-07-03T09:00:00Z"
}
GET /repos/{owner}/{repo}/notables

List notables

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

Query parameters

ParameterTypeDescription
importance optional
enum
Filter by importance level.
category optional
enum
Filter by category.
area optional
string
Filter by an area label in scope.
cursor optional
string
Pagination cursor from a prior next_cursor.
REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/notables \
  -H "Authorization: Bearer $TOKEN" \
  -G -d "category=migration"
RESPONSE 200 OK 
{
  "items": [
    {
      "id": "ntb_2Bd8Xk1",
      "title": "Payments v2 migration in progress",
      "category": "migration",
      "importance": "high"
    }
  ],
  "next_cursor": null
}
GET /repos/{owner}/{repo}/notables/{id}

Retrieve a notable

Fetches a single Notable by id. 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/notables/ntb_2Bd8Xk1 \
  -H "Authorization: Bearer $TOKEN"
RESPONSE 200 OK 
{
  "id": "ntb_2Bd8Xk1",
  "type": "notable",
  "title": "Payments v2 migration in progress",
  "summary": "Don't touch src/billing/** until PR #479 lands.",
  "category": "migration",
  "importance": "high",
  "status": "active",
  "decision_url": "https://docs.acme.dev/payments-v2",
  "scope": { "areas": ["billing"], "paths": ["src/billing/**"] },
  "expires_at": "2026-07-10T09:00:00Z",
  "created_at": "2026-07-03T09:00:00Z"
}
POST /repos/{owner}/{repo}/notables

Create a notable

Raises a new alignment signal. title, summary, importance, and category are required. It starts active and expires after about 7 days unless archived first. A category the repo has disabled returns 400 category_not_allowed.

Body parameters

ParameterTypeDescription
title required
string
One-line summary of the signal.
summary required
string
The caveat, in a sentence or two.
importance required
enum
One of low, medium, high, critical.
category required
enum
One of the twelve categories above.
decision_url optional
string
Link to the real doc, when one exists.
scope optional
object
{ areas, paths } the notable applies to.
applies_until optional
timestamp
Semantic end date for the caveat.
REQUEST 
curl https://your-instance.example.com/api/v1/repos/acme/web/notables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Flaky checkout e2e",
    "summary": "checkout.e2e is intermittently red; a retry is not a real failure.",
    "importance": "medium",
    "category": "testing"
  }'
RESPONSE 201 Created 
{
  "id": "ntb_7Qm1Rp0",
  "title": "Flaky checkout e2e",
  "category": "testing",
  "importance": "medium",
  "status": "active",
  "expires_at": "2026-07-10T15:20:00Z"
}
PATCH /repos/{owner}/{repo}/notables/{id}

Update a notable

Edits an existing notable — revise the text, bump importance, attach a decision_url, or extend applies_until. Only the fields you send change.

Body parameters

ParameterTypeDescription
summary optional
string
Revise the caveat text.
importance optional
enum
Change the importance level.
decision_url optional
string
Attach or change the doc link.
applies_until optional
timestamp
Extend or set the semantic end date.
REQUEST 
curl -X PATCH https://your-instance.example.com/api/v1/repos/acme/web/notables/ntb_7Qm1Rp0 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "importance": "high" }'
RESPONSE 200 OK 
{
  "id": "ntb_7Qm1Rp0",
  "importance": "high",
  "status": "active"
}
POST /repos/{owner}/{repo}/notables/{id}/archive

Archive a notable

Resolves a notable before its expiry — for example when a migration lands. The notable moves to status archived and leaves the live feed, but remains retrievable until it is purged. Archiving is idempotent.

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