# Events

An event records one change in a workspace, such as a role change, a new invite or a ticket update, and who made it: a person, a clanker acting for a person, or an account API key.

## The Event object

One change in the workspace and who made it.

### Attributes

- `id` (string, required): Unique ID of the event.
- `type` (string, one of: `workspace.created`, `workspace.updated`, `workspace.icon_updated`, `member.role_changed`, `member.removed`, `member.auto_joined`, `invite.created`, `invite.role_changed`, `invite.resent`, `invite.revoked`, `invite.accepted`, `team.created`, `team.updated`, `team.member_added`, `team.member_removed`, `team.archived`, `team.restored`, `team.deleted`, `project.created`, `project.updated`, `project.archived`, `project.restored`, `project.reordered`, `milestone.created`, `milestone.updated`, `milestone.deleted`, `ticket.created`, `ticket.updated`, `ticket.moved`, `ticket.reordered`, `ticket.checklist_changed`, `ticket.checklist_item_checked`, `ticket.checklist_item_unchecked`, `ticket.checklist_item_started`, `ticket.checklist_item_stopped`, `ticket.document_written`, `ticket.question_asked`, `ticket.question_answered`, `ticket.branch_linked`, `ticket.branch_unlinked`, `ticket.pull_request_linked`, `ticket.pull_request_unlinked`, `tag.created`, `tag.updated`, `tag.deleted`, `ticket_status.created`, `ticket_status.updated`, `ticket_status.deleted`, `ticket_status.reordered`, `ticket_status.checklist_changed`, `ticket_status.instructions_changed`, `view.created`, `view.updated`, `view.deleted`, `view.reordered`, `clanker_instructions.updated`, `clanker_instructions.reset`, `clanker.registered`, `clanker.revoked`, `clanker_message.sent`, `clanker_message.delivered`, `clanker_message.completed`, `ticket.commented`, `product.created`, `product.updated`, `product.archived`, `product.restored`, `environment.created`, `environment.updated`, `environment.archived`, `environment.restored`, `deployment.created`, `deployment.updated`, `deployment.removed`, `profile.updated`, required): What happened, as subject.action, such as ticket.created.
- `subjectType` (nullable string, required): What the event is about, such as user, invite, workspace or ticket, or null.
- `subjectId` (nullable string, required): The ID of what the event is about, or null.
- `metadata` (object, required): Details recorded with the event, such as the ticket's identifier and title. The fields depend on the type.
- `createdAt` (string, required): When it happened, as an ISO 8601 timestamp.
- `actorUserId` (nullable string, required): The user ID of the person who made the change, or the person a clanker acted for. Null when an account API key made it.
- `actorAccountKeyId` (nullable string, required): The ID of the account API key that made the change, or null.
- `actorClankerAuthorizationId` (nullable string, required): The ID of the clanker that made the change for the person, or null.
- `actorName` (nullable string, required): The name of the person who made the change, or the person a clanker acted for. Null when an account API key made it.
- `actorEmail` (nullable string, required): That person's email address, or null.
- `clankerName` (nullable string, required): The clanker that made the change for the person, such as Codex, or null.

### Example

```json
{
  "id": "Ev4NpL7wQs2X",
  "type": "ticket.created",
  "subjectType": "ticket",
  "subjectId": "Tk7BnC5xLp9M",
  "metadata": {
    "identifier": "WEB-31",
    "title": "Add docs search"
  },
  "createdAt": "2026-10-14T09:05:12.000Z",
  "actorUserId": "Us3NfP8kLq2V",
  "actorAccountKeyId": null,
  "actorClankerAuthorizationId": "Ag5HvB1mZr8K",
  "actorName": "Maya Patel",
  "actorEmail": "maya@acme.dev",
  "clankerName": "Codex"
}
```

## List events

`GET /v1/workspaces/{slug}/events`

Returns the 50 most recent events the caller can read, newest first, or one ticket's activity with `ticket`. Members and viewers get the workspace's own events and those about the teams, projects and tickets they can open; a personal view's events go only to its person. Owners, admins and account API keys get every event. A ticket the caller cannot read fails with NotFound.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `ticket` (string, in query): Only this ticket's activity, by its ID, such as WEB-31.

### Returns

Returns an array of [Event](https://docs.clankership.com/api/events/object.md) objects. The status is 200.

### Request

```bash
curl https://api.clankership.com/v1/workspaces/{slug}/events \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
[
  {
    "id": "Ev4NpL7wQs2X",
    "type": "ticket.created",
    "subjectType": "ticket",
    "subjectId": "Tk7BnC5xLp9M",
    "metadata": {
      "identifier": "WEB-31",
      "title": "Add docs search"
    },
    "createdAt": "2026-10-14T09:05:12.000Z",
    "actorUserId": "Us3NfP8kLq2V",
    "actorAccountKeyId": null,
    "actorClankerAuthorizationId": "Ag5HvB1mZr8K",
    "actorName": "Maya Patel",
    "actorEmail": "maya@acme.dev",
    "clankerName": "Codex"
  }
]
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.