The Knowledge API · Reference

Activity

Time-ordered events across the sources that carry a clock.

Activity returns time-ordered events across the sources that carry a clock — commits, PRs, work item transitions, and database schema changes. It answers "what changed?" rather than "what exists?"

Request

bash

POST /projects/:project_id/knowledge/activity

Headers:

Header	Required	Description
`X-API-Key`	One of	Service-level key for server-to-server calls
`Authorization`	One of	`Bearer <jwt>` for user-scoped calls
`Content-Type`	Yes	`application/json`

Body:

json

{
  "sources": ["commits", "work_items"],
  "since": "2025-11-25T00:00:00Z",
  "until": "2025-12-01T00:00:00Z",
  "limit": 25
}

Field	Type	Required	Description
`sources`	string[]	No	Filter to specific sources. Omit for all time-ordered sources
`since`	string	No	ISO 8601 start of window
`until`	string	No	ISO 8601 end of window
`limit`	number	No	Max events to return. Default: 25. Max: 100

Response

json

{
  "events": [
    {
      "ref": "commits:github:acme/api:def5678",
      "source": "commits",
      "event_type": "commit",
      "timestamp": "2025-11-30T16:42:00Z",
      "title": "fix: rotate session token on role downgrade",
      "actor": "maria.garcia",
      "metadata": {
        "sha": "def5678abc",
        "repository": "acme/api",
        "files_changed": 3
      }
    },
    {
      "ref": "work_items:jira:PROJ-412",
      "source": "work_items",
      "event_type": "transition",
      "timestamp": "2025-11-30T16:50:00Z",
      "title": "PROJ-412: Rotate session tokens on privilege change",
      "actor": "maria.garcia",
      "metadata": {
        "from_status": "in_progress",
        "to_status": "done"
      }
    }
  ],
  "sources_queried": ["commits", "work_items"],
  "total_events": 2,
  "has_more": false
}

Which sources carry a clock

Not all sources produce activity events. Code and graph are structural — they describe what exists, not when it changed. The time-ordered sources are:

Source	Event types
`commits`	commit
`pull_requests`	opened, merged, closed
`work_items`	created, transition, commented
`database`	schema_change (when detected on sync)

Empty result

An empty time window returns a valid response with an empty list:

json

{
  "events": [],
  "sources_queried": ["commits", "work_items"],
  "total_events": 0,
  "has_more": false
}

Next: Auth model.