> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> The anatomy of Events.

The Flatfile platform encompasses a comprehensive suite of tools. Firstly, it offers a REST API, which can be accessed through the <Tooltip tip="View API reference">[REST API](https://reference.flatfile.com/)</Tooltip>, empowering users to effortlessly manipulate resources. Additionally, an Event bus is available for seamless subscription to resource-related notifications.

To simplify the process of utilizing the Flatfile API, the Flatfile PubSub Client serves as a lightweight wrapper. It enables developers to seamlessly trigger API calls upon receiving Events from any PubSub driver, thus ensuring a smooth and streamlined integration process.

#### The anatomy of an Event

Flatfile Events adhere to a standardized structure, and Event listeners have the flexibility to handle Events within Flatfile using any of the following syntaxes.

[See API Reference](https://reference.flatfile.com/api-reference/events/create-an-event)

### Using Events

Once an Event is received, it is routed to any awaiting listeners which are added with `addEventListener()` or its alias `on()`.

An Event context is passed to an **EventFilter**

```typescript theme={"system"}
export type EventFilter = Record<string, Arrayable<string>>;

// example event context
{
  context: {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "actorId": "us_ag_1234"
  }
}
```

#### Building with events

By leveraging the robust capabilities of our @flatfile/listener library, we can seamlessly intercept any Event and execute a callback function based on the values encapsulated within the Event itself.

```typescript theme={"system"}
listener.on(
  "job:ready",
  { job: "space:configure" },
  async (event: FlatfileEvent) => {
    //do something here
  }
);
```

## Event Topics

Utilize the reference provided by the response of each Event topic to determine the desired
outcome or plan subsequent actions accordingly.

### Workbook

#### `workbook:created`

<ParamField path="workbook:created" type="readonly">
  Called when a new workbook is created.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "workbook:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `workbook:updated`

<ParamField path="workbook:updated" type="readonly">
  Called when workbook metadata is updated. For example, updating the name of a
  workbook. Adding data to a workbook does not emit this Event.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "workbook:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_ag_1234"
  }
}
```

#### `workbook:deleted`

<ParamField path="workbook:deleted" type="readonly">
  Called when a workbook is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "workbook:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_ag_1234"
  }
}
```

#### `workbook:expired`

<ParamField path="workbook:expired" type="readonly">
  Called when a workbook is expired.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "workbook:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234"
  }
}
```

### Document

#### `document:created`

<ParamField path="document:created" type="readonly">
  Called when a document is created on a workbook.
</ParamField>

```json theme={"system"}
{
  "domain": "document",
  "topic": "document:created",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}
```

#### `document:updated`

<ParamField path="document:updated" type="readonly">
  Called when a document is updated on a workbook.
</ParamField>

```json theme={"system"}
{
  "domain": "document",
  "topic": "document:updated",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}
```

#### `document:deleted`

<ParamField path="document:deleted" type="readonly">
  Called when a document is deleted on a workbook.
</ParamField>

```json theme={"system"}
{
  "domain": "document",
  "topic": "document:deleted",
  "context": {
    "actorId": "us_key_1234",
    "spaceId": "us_sp_1234",
    "accountId": "us_acc_1234",
    "documentId": "us_dc_1234",
    "environmentId": "us_env_1234"
  }
}
```

### Sheet

#### `sheet:updated`

<ParamField path="sheet:updated" type="readonly">
  Called when a sheet is updated. For example, running sheet level validations.
  Adding data to a sheet does not emit this event.
</ParamField>

```json theme={"system"}
{
  "domain": "sheet",
  "topic": "sheet:updated",
  "context": {
    "slugs": { "sheet": "contacts" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "contacts",
    "actorId": "us_ag_XRGmuGfL"
  }
}
```

#### `sheet:deleted`

<ParamField path="sheet:deleted" type="readonly">
  Called when a sheet is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "sheet",
  "topic": "sheet:deleted",
  "context": {
    "slugs": { "sheet": "contacts" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "contacts",
    "actorId": "us_ag_XRGmuGfL"
  }
}
```

### Snapshot

#### `snapshot:created`

<ParamField path="snapshot:created" type="readonly">
  Called when a snapshot is created of the sheet. This can be triggered by the
  API endpoint or when AI Assist is used to modify a sheet.
</ParamField>

```json theme={"system"}
{
  "domain": "sheet",
  "topic": "snapshot:created",
  "context": {
    "appId": "us_app_1234",
    "accountId": "us_acc_1234",
    "snapshotId": "us_ss_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "actorId": "us_ag_XRGmuGfL"
  }
}
```

### Record

#### `commit:created`

<ParamField path="commit:created" type="readonly">
  Commits are created when a cell in a Record (which is in a Sheet) is created
  or updated.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "commit:created",
  "context": {
    "slugs": { "sheet": "MasterWorkbook/Data" },
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "sheetSlug": "MasterWorkbook/Data",
    "versionId": "us_vr_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `commit:completed`

<ParamField path="commit:completed" type="readonly">
  This only runs when trackChanges is enabled on the workbook. This event fires
  when a commit has completed and any record changes have finished.
</ParamField>

```json theme={"system"}
{
  "domain": "workbook",
  "topic": "commit:completed",
  "context": {
    "appId": "us_app_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "versionId": "us_vr_1234",
    "actorId": "us_usr_1234",
    "commitId": "us_vr_1234"
  }
}
```

#### `layer:created`

<ParamField path="layer:created" type="readonly">
  Called when a new layer is created within a commit. A layer is a
  programmatically generated artifact of a commit. For example, when a data hook
  or formatting rule applies formatting or validation automatically. Layers
  cannot be updated or deleted, but you can ignore them to see the original
  source data.
</ParamField>

### File Upload

#### `file:created`

<ParamField path="file:created" type="readonly">
  Called when a file upload begins or a new file is created.
</ParamField>

```json theme={"system"}
{
  "domain": "file",
  "topic": "file:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `file:updated`

<ParamField path="file:updated" type="readonly">
  Called when a file is updated. For example, when a file has been extracted
  into a workbook.
</ParamField>

```json theme={"system"}
{
  "domain": "file",
  "topic": "file:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_acc_1234"
  },
  "payload": {
    "status": "complete",
    "workbookId": "us_wb_1234"
  }
}
```

#### `file:deleted`

<ParamField path="file:deleted" type="readonly">
  Called when a file is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "file",
  "topic": "file:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `file:expired`

<ParamField path="file:expired" type="readonly">
  Called when a file is expired.
</ParamField>

```json theme={"system"}
{
  "domain": "file",
  "topic": "file:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "fileId": "us_fl_1234"
  }
}
```

### Jobs

#### `job:created`

<ParamField path="job:created" type="readonly">
  Called when a new job is first created. Some jobs will enter an optional
  planning state at this time. A job with 'immediate' set to true will skip the
  planning step and transition directly to 'ready.'
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "created",
    "operation": "configure"
  }
}
```

#### `job:ready`

<ParamField path="job:ready" type="readonly">
  Called when a new job is ready to execute. Either the job has a complete plan
  of work or the job is configured to not need a plan. This is the only event
  most job implementations will care about. Once a ready job is acknowledged by
  a listener, it transitions into an executing state.
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:ready",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "ready",
    "operation": "configure"
  }
}
```

#### `job:updated`

<ParamField path="job:updated" type="readonly">
  Called when a job is updated. For example, when a listener updates the state
  or progress of the job. The event will emit many times as the listener
  incrementally completes work and updates the job.
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": null,
    "domain": "space", //event domain
    "status": "ready",
    "operation": "configure"
  }
}
```

#### `job:completed`

<ParamField path="job:completed" type="readonly">
  Called when a job has completed.
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:completed",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "space:configure", //this is domain:operation
    "info": "Configuring space...",
    "domain": "space", //event domain
    "status": "complete",
    "operation": "configure"
  }
}
```

#### `job:outcome-acknowledged`

<ParamField path="job:outcome-acknowledged" type="readonly">
  Called to trigger workflow actions after the user has acknowledged that the
  job has completed or failed. Background jobs will skip this step.
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:outcome-acknowledged",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "sheet:buildSheet", //this is domain:operation
    "info": null,
    "domain": "sheet", //event domain
    "status": "failed",
    "operation": "buildSheet"
  }
}
```

#### `job:failed`

<ParamField path="job:failed" type="readonly">
  Called when a job fails.
</ParamField>

```json theme={"system"}
{
  "domain": "job", //job domain
  "topic": "job:failed",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "sheetId": "us_sh_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "job": "sheet:buildSheet", //this is domain:operation
    "info": null,
    "domain": "sheet", //event domain
    "status": "failed",
    "operation": "buildSheet"
  }
}
```

#### `job:deleted`

<ParamField path="job:deleted" type="readonly">
  Called when a job is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "job",
  "topic": "job:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "jobId": "us_jb_1234",
    "actorId": "us_ag_1234"
  }
}
```

### Agents

#### `agent:created`

<ParamField path="agent:created" type="readonly">
  Called when a new agent is deployed.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "agent:created",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234"
  }
}
```

#### `agent:updated`

<ParamField path="agent:updated" type="readonly">
  Called when an agent is updated.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "agent:updated",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "agentId": "us_ag_1234"
  }
}
```

#### `agent:deleted`

<ParamField path="agent:deleted" type="readonly">
  Called when an agent is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "agent:deleted",
  "context": {
    "actorId": "us_ag_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234"
    "agentId": "us_ag_1234"
  }
}
```

### Space

#### `space:created`

<ParamField path="space:created" type="readonly">
  Called when a new space is created.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `space:updated`

<ParamField path="space:updated" type="readonly">
  Called when a space is updated.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `space:deleted`

<ParamField path="space:deleted" type="readonly">
  Called when a space is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `space:expired`

<ParamField path="space:expired" type="readonly">
  Called when a space is expired.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:expired",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "workbookId": "us_wb_1234"
  }
}
```

#### `space:archived`

<ParamField path="space:archived" type="readonly">
  Called when a space is archived.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:archived",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}
```

#### `space:guestAdded`

<ParamField path="space:guestAdded" type="readonly">
  Called when a guest is added.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:guestAdded",
  "context": {
    "actorId": "us_usr_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}
```

#### `space:guestRemoved`

<ParamField path="space:guestRemoved" type="readonly">
  Called when a guest's access is revoked from a space.
</ParamField>

```json theme={"system"}
{
  "domain": "space",
  "topic": "space:guestRemoved",
  "context": {
    "actorId": "us_usr_1234",
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234"
  }
}
```

### Secret

#### `secret:created`

<ParamField path="secret:created" type="readonly">
  Called when a new secret is created.
</ParamField>

```json theme={"system"}
{
  "domain": "secret",
  "topic": "secret:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `secret:updated`

<ParamField path="secret:updated" type="readonly">
  Called when a secret is updated.
</ParamField>

```json theme={"system"}
{
  "domain": "secret",
  "topic": "secret:updated",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}
```

#### `secret:deleted`

<ParamField path="secret:deleted" type="readonly">
  Called when a secret is deleted.
</ParamField>

```json theme={"system"}
{
  "domain": "secret",
  "topic": "secret:deleted",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  }
}
```

### Data clips

#### `data-clip:created`

<ParamField path="data-clip:created" type="readonly">
  Called when a new data clip is created.
</ParamField>

```json theme={"system"}
{
  "domain": "data-clip",
  "topic": "data-clip:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "accountId": "us_acc_1234",
    "dataClipId": "us_acc_1234",
    "stauts": "OPEN",
  }
}
```

#### `data-clip:updated`

<ParamField path="data-clip:updated" type="readonly">
  Called when a data clip's details are updated.
</ParamField>

<Note>
  This is not called when records are updated in a data clip.
</Note>

````json theme={"system"}
{
  "domain": "data-clip",
  "topic": "data-clip:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "accountId": "us_acc_1234",
    "dataClipId": "us_acc_1234",
    "stauts": "OPEN",
  }
}

#### `data-clip:deleted`

<ParamField path="data-clip:deleted" type="readonly">
  Called when a data clip is deleted.
</ParamField>

```json
{
  "domain": "data-clip",
  "topic": "data-clip:created",
  "context": {
    "accountId": "us_acc_1234",
    "environmentId": "us_env_1234",
    "spaceId": "us_sp_1234",
    "actorId": "us_usr_1234"
  },
  "payload": {
    "accountId": "us_acc_1234",
    "dataClipId": "us_acc_1234",
    "stauts": "OPEN",
  }
}
````