# Workspaces

> Create, inspect and administer stored-memory destinations.

A Workspace is a destination for stored memory. Use [Consolidate](https://augenta.pages.dev/docs/consolidate.md) or
[Experiences](https://augenta.pages.dev/docs/experiences.md) to send source material; the administration routes below manage
its configuration and access. They require a person's credentials. API keys read and write
memory only within their assignments and cannot administer Workspaces.

See [the Workspace object](https://augenta.pages.dev/docs/api-reference/workspace-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                                                          | Purpose                                                  |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| [`POST /v1/workspaces`](https://augenta.pages.dev/docs/api-reference/create-workspace.md)                                | Create a shared Workspace.                               |
| [`GET /v1/workspaces`](https://augenta.pages.dev/docs/api-reference/list-workspaces.md)                                  | List visible Workspaces and effective roles.             |
| [`GET /v1/workspaces/{id}`](https://augenta.pages.dev/docs/api-reference/get-workspace.md)                               | Retrieve one Workspace, optionally including membership. |
| [`PATCH /v1/workspaces/{id}`](https://augenta.pages.dev/docs/api-reference/update-workspace.md)                          | Update its name or synthesis cadence.                    |
| [`POST /v1/workspaces/{id}/archive`](https://augenta.pages.dev/docs/api-reference/archive-workspace.md)                  | Archive a shared Workspace before deletion.              |
| [`DELETE /v1/workspaces/{id}`](https://augenta.pages.dev/docs/api-reference/delete-workspace.md)                         | Delete an archived Workspace's data.                     |
| [`GET /v1/workspaces/{id}/members`](https://augenta.pages.dev/docs/api-reference/list-workspace-members.md)              | List effective membership, including inherited access.   |
| [`PUT /v1/workspaces/{id}/members/{userId}`](https://augenta.pages.dev/docs/api-reference/set-workspace-member.md)       | Set a direct membership.                                 |
| [`DELETE /v1/workspaces/{id}/members/{userId}`](https://augenta.pages.dev/docs/api-reference/remove-workspace-member.md) | Remove a direct membership.                              |

## Fields

| Field                                       | Meaning                                                             |
| ------------------------------------------- | ------------------------------------------------------------------- |
| `object`                                    | Always `workspace`.                                                 |
| `id`, `orgId`                               | Workspace identity and its owning Organization.                     |
| `name`                                      | Display name. Renaming does not change the ID.                      |
| `status`                                    | Current Workspace lifecycle state.                                  |
| `kind`                                      | `shared` or a provisioned `personal` Default Workspace.             |
| `ownerUserId`                               | Owner of a personal Workspace, when applicable.                     |
| `workspaceRole`, `via`                      | Effective access and its source, when loaded.                       |
| `createdByUserId`, `createdAt`, `updatedAt` | Recorded creator and configuration lifecycle metadata.              |
| `_etag`                                     | Optional revision for an `If-Match` update or archive.              |
| `synthesisCadence`                          | Configured consolidation cadence, when set.                         |
| `members`                                   | Initial membership list page when requested with `include=members`. |

List pages use `{object: "list", data, nextPageUrl, url}`. `personal=all` also includes colleagues'
personal Workspaces when the caller has the permission to list them; other callers retain the
normal direct-membership selection. Preserve the returned URL, including that selection, across
pages. Administration list limits default to 50 and accept 1–200.

## Create a Workspace

```bash
curl --fail-with-body -sS "https://api.augenta.ai/v1/workspaces" \
  -H "Authorization: Bearer $AUGENTA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Research"}'
```

```json
{
  "object": "workspace",
  "id": "research",
  "orgId": "aug-example",
  "name": "Research",
  "status": "active",
  "kind": "shared",
  "createdByUserId": "user-example",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "updatedAt": "2026-10-28T12:00:00.000Z"
}
```

The creator becomes its first administrator. Guests cannot create Workspaces. Default personal
Workspaces are provisioned separately and cannot be renamed or archived. Organization owners
and administrators inherit Workspace administration; that access cannot be removed through a
direct membership route. A membership's resource ID is its `userId` within the parent Workspace.

Retrieve with `include=members` to load the initial membership page. Follow its `nextPageUrl`
unchanged. Setting or removing a direct membership and archiving return `204` with no body.
Deletion returns a separate progress result: `deleting` means repeat the operation as directed;
`deleted` means every required store is clear. It is not a Workspace resource response.

Workspace lists include the active `organization` resource. Membership lists include the parent
`workspace` resource. These context objects use the same schemas as detail reads; an unread
Organization member count is `null`.
