> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Changes — a project-wide timeline of what changed and when
> A single feed of every prompt deploy, agent promotion, policy edit, and pipeline deploy in your project, so 'what changed?' is a page you visit instead of a question you Slack someone.
The Changes page answers the question every investigation starts with: what changed, and when? It merges prompt deploys, agent lifecycle transitions, guardrail/evaluator/alert edits, and deploys you report from your own CI pipeline into one chronological feed — no more cross-referencing the audit log, the prompts page, and a deploy Slack channel by hand.
From the project sidebar, go to **Monitor → Changes**.
Use the range selector (**Last 24 Hours**, **Last 7 Days**, **Last 30 Days**) to set the window. The feed is sorted newest-first.
Click any kind chip to narrow the feed to just that kind — click again to remove it. Chips are additive: select two kinds to see both.
Wire your CI pipeline to `POST /v1/projects/:id/changes` so pipeline deploys show up on the same timeline as everything else. See [Reporting changes from CI](#reporting-changes-from-ci) below.
## The eight change kinds
Every event on the timeline has one of eight kinds:
| Kind | What it captures | Source |
| ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------ |
| `prompt_deploy` | A prompt version created, edited, relabeled, rolled back, or deleted | Prompt deployments + audit log |
| `agent_lifecycle` | An agent promoted, demoted, or otherwise transitioned state | Agent lifecycle history |
| `policy_change` | A guardrail created, updated, enabled, disabled, or deleted | Audit log |
| `evaluator_change` | An evaluation created for a project | Audit log |
| `alert_change` | An alert rule created, updated, or deleted | Audit log |
| `config_change` | Dataset, project settings, retention, API key rotation, or a ZespanPilot auto-remediation action | Audit log |
| `incident_change` | An incident created, its status changed, or resolved | Audit log |
| `external` | A change reported from your own pipeline via the API | Changes API |
Each row also carries a **severity** (`info`, `notable`, or `high`), shown as a colored left border, and — where the underlying source captured one — a **View diff** popover showing the before/after values.
## Filters
| Filter | Where | Notes |
| -------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time range (`from` / `to`) | Range selector | Defaults to the last 7 days |
| Kind (`kinds`) | Kind chips | Comma-separated in the API; an unrecognized kind returns `400` |
| Agent (`agent`) | API only | Restricts results to events whose scope includes the named agent — `Incident` records have no agent field, so no UI surface (including the incident panel) sets this yet; call the API directly to use it |
If any underlying source doesn't respond in time, a banner marks the result as **partial** rather than silently showing an incomplete list as complete. The banner names which source(s) were slow.
## `ChangeEvent` fields
| Field | Type | Description |
| ------------ | ------------------- | ------------------------------------------------------------------------------- |
| `id` | string | Stable and unique across sources (`:`) |
| `kind` | string | One of the eight kinds above |
| `occurredAt` | string (ISO-8601) | When the change happened |
| `actor` | object \| null | `{ type: "user" \| "system" \| "api", id, name }` — who or what made the change |
| `title` | string | One-line summary shown as the row's title |
| `summary` | string \| null | Optional longer description |
| `href` | string | Relative deep link into the dashboard (e.g. `prompts/checkout-system`) |
| `scope` | object | `{ agents?, prompts?, models? }` — what the change affected |
| `diff` | object \| undefined | `{ before, after }` when the source captured a structured diff |
| `severity` | string | `info`, `notable`, or `high` |
## Changes around an incident
The incident detail page has its own "Changes around this incident" panel — the same feed, pivoted on an incident's start time instead of a date range, split into **Before** and **After** columns. See [Changes around this incident](/dashboard/incidents#changes-around-this-incident) on the Incidents page for details.
## Reporting changes from CI
Anything your own deploy pipeline does — a Kubernetes rollout, a feature-flag flip, an infra change — is invisible to Zespan unless you tell it. Report it with `POST /v1/projects/:id/changes` and it shows up on the timeline (and in the incident panel's before/after split) as an `external` event, right alongside prompt deploys and policy edits.
```bash Report a deploy from CI theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST "$ZESPAN_API_URL/v1/projects/$PROJECT_ID/changes" \
-H "x-api-key: $ZESPAN_API_KEY" \
-H "content-type: application/json" \
-d '{"title":"Deployed api@'"$GIT_SHA"'","source":"github","severity":"notable"}'
```
`$ZESPAN_API_URL` defaults to `https://api.zespan.com` — only set it if you're self-hosting. `$ZESPAN_API_KEY` is a project-scoped API key (see [API Keys](/account/api-keys)). An API key has no role attached — it's already scoped to exactly one project — so any valid key for the target project works; there's no separate permission check for API-key callers on this route.
### Request body
| Field | Type | Required | Notes |
| ------------ | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `title` | string | Yes | Max 200 characters |
| `summary` | string | No | Max 2000 characters |
| `href` | string (URL) | No | A link to attach to the event, e.g. your CI run |
| `occurredAt` | string (ISO-8601) | No | Defaults to now |
| `severity` | `"info"` \| `"notable"` \| `"high"` | No | Defaults to `"info"` |
| `source` | string | No | Max 50 characters, defaults to `"api"` — use it to identify the pipeline (`"github"`, `"circleci"`, `"terraform"`, ...) |
| `scope` | object | No | `{ agents?, prompts?, models? }` — scope the change to specific agents/prompts/models so it surfaces in agent-filtered views |
A successful call returns `201` with `{ id, title, occurredAt }`.
## Next steps
* [Incidents](/dashboard/incidents) — the before/after change panel on incident detail
* [Alerts](/dashboard/alerts) — notification rules that share the `alerts:manage` permission with reporting changes
* [Audit Log](/platform/audit) — the full, unfiltered event history that most change kinds are drawn from