# The organisation's changes, oldest first, for polling

> `GET /changes` · Scope: `read` · operationId `listChanges`

Any member, or an API key with the `read` scope (ADR-026). The organisation's changes in the order
they became visible, oldest first, as `{id, occurred_at, entity_type, entity_id, action}`: no values,
no actors, no personal data; read the entity for its current state. Keep `next_cursor` of the last
page and ask again later: a change appears only once every transaction that started before it has
finished, so a cursor never skips a change that commits late. `next_cursor` is set whenever the page
has items, also on the last page; an empty page keeps the cursor you sent (`next_cursor` null). Without
`cursor` the feed starts at the beginning of the organisation's history.

## Query parameters

- **limit** `integer` (default: 50): Maximum number of items to return.
- **cursor** `string`: Opaque cursor from a previous page's `next_cursor`.
- **types** `string[]`: Only these actions (all when omitted).

## Responses

### 200 (`application/json`)

One page of changes.

- **items** `Change[]` (required)
  - **action** `string` (required, one of: `battery.created`, `passport.published`, `passport.republished`, `passport.withdrawn`, `model_version.approved`, `import.committed`, `import.approved`, `lifecycle_event.recorded`, `condition.updated`): What changed (ADR-026): `battery.created` (a unit was created), `passport.published` (a unit's first passport version), `passport.republished` (a later version), `passport.withdrawn`, `model_version.approved`, `import.committed` (its units exist), `import.approved` (its values were approved), `lifecycle_event.recorded` (an event other than a condition update), `condition.updated` (measured condition data was accepted).
  - **entity_id** `string (uuid)` (required)
  - **entity_type** `string` (required, one of: `battery`, `model_version`, `import`): The resource to read after a change: `battery` (`getBattery`, `getPassport`, `listLifecycleEvents`, `getCondition`), `model_version` (`getModelVersion`) or `import` (`getImport`). Passport changes name the unit.
  - **id** `string (uuid)` (required)
  - **occurred_at** `string (date-time)` (required)
- **next_cursor** `string | null` (required): Cursor for the next page, or null when this is the last page.

### 400 (`application/problem+json`)

The request is malformed or failed validation (`validation_error`), or a token is invalid or expired (`invalid_token`).

### 401 (`application/problem+json`)

The API key is missing, unknown or revoked (`unauthenticated`).

### 403 (`application/problem+json`)

The API key may not perform this action (`forbidden`): it lacks the operation's scope, or the action needs more than a viewer's rights.

### default (`application/problem+json`)

Any other problem, e.g. `internal_error`.

## Example

```bash title="cURL"
curl -X GET "https://passport.kabin.sh/api/v1/changes" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"
```