---
title: "Workspace"
description: "The `Workspace` entity."
section: "Reference"
group: "Types"
order: 277
---

## Definition

```ts
interface Workspace {
  id: string;
  organizationId: string;
  name: string;
  handle: string;
  ownerId: string;
  defaultServiceUserId: string | null;
  deletedAt: string | null;
  retentionTier: "short" | "medium" | "long" | "none" | null;
  createdAt: string;
  updatedAt: string;
}
```

## Fields

| Field                  | Type                                              | Notes                                                                                                                                                                                                                                                                                                |
| ---------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | `string`                                          | `readonly` `required`                                                                                                                                                                                                                                                                                |
| `organizationId`       | `string`                                          | `required` — Organization the workspace belongs to (immutable after creation).                                                                                                                                                                                                                       |
| `name`                 | `string`                                          | `required` — Human-readable workspace name.                                                                                                                                                                                                                                                          |
| `handle`               | `string`                                          | `required` — Unique workspace handle used in URLs and the workspace email address.                                                                                                                                                                                                                   |
| `ownerId`              | `string`                                          | `required` — User who owns the workspace.                                                                                                                                                                                                                                                            |
| `defaultServiceUserId` | `string \| null`                                  | `required` — Default headless caller identity for runs initiated without a human user (triggers, webhooks, cron, email ingest). Null briefly between workspace creation and the `workspace.created` handler running. Additional service users beyond the default can be created by workspace admins. |
| `deletedAt`            | `string \| null`                                  | `required` — ISO-8601 timestamp of soft-delete; null while active. Cleanup worker hard-deletes once `deletedAt + retentionTier.days` passes.                                                                                                                                                         |
| `retentionTier`        | `"short" \| "medium" \| "long" \| "none" \| null` | `required` — Retention tier snapshotted at delete time. `short`=7d, `medium`=30d, `long`=90d, `none`=never. Null while active.                                                                                                                                                                       |
| `createdAt`            | `string`                                          | `readonly` `required` — ISO-8601 timestamp of creation.                                                                                                                                                                                                                                              |
| `updatedAt`            | `string`                                          | `readonly` `required` — ISO-8601 timestamp of the last update.                                                                                                                                                                                                                                       |