# 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, an agent 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`, `milestone.created`, `milestone.updated`, `milestone.deleted`, `ticket.created`, `ticket.updated`, `ticket.moved`, `tag.created`, `tag.updated`, `tag.deleted`, `ticket_status.created`, `ticket_status.updated`, `ticket_status.deleted`, `view.created`, `view.updated`, `view.deleted`, `agent_instructions.updated`, `agent_instructions.reset`, `agent.registered`, `agent.revoked`, `agent_message.sent`, `agent_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 an agent 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.
- `actorAgentAuthorizationId` (nullable string, required): The ID of the registered agent 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 an agent acted for. Null when an account API key made it.
- `actorEmail` (nullable string, required): That person's email address, or null.
- `agentName` (nullable string, required): The agent 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,
  "actorAgentAuthorizationId": "Ag5HvB1mZr8K",
  "actorName": "Maya Patel",
  "actorEmail": "maya@acme.dev",
  "agentName": "Codex"
}
```

## List events

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

Returns the workspace's 50 most recent events, newest first. Any member can list events.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.

### Returns

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

### Request

```bash
curl https://api.qa.clankership.net/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,
    "actorAgentAuthorizationId": "Ag5HvB1mZr8K",
    "actorName": "Maya Patel",
    "actorEmail": "maya@acme.dev",
    "agentName": "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.