# List Workspaces

## GET `/v1/workspaces`

List Workspaces visible to the signed-in person, with their effective role. personal=all also lists colleagues' personal Workspaces when the caller has permission; otherwise the list stays limited to directly assigned personal Workspaces.

## Authentication

Use a person's Bearer access token or console session. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

## Request example

```bash
curl --fail-with-body -X GET "https://api.augenta.ai/v1/workspaces" \
  -H "Authorization: Bearer $AUGENTA_ACCESS_TOKEN"
```

## Parameters

<a id="request-parameters-limit"></a>

### `request.parameters.limit`

`integer` · optional

query parameter.

Default: `50`.

Minimum: `1`. Maximum: `200`.

<a id="request-parameters-page"></a>

### `request.parameters.page`

`string` · optional

query parameter.

Min length: `1`. Max length: `4096`.

<a id="request-parameters-personal"></a>

### `request.parameters.personal`

`string` · optional

query parameter.

Allowed values: `"all"`.

## Response 200

One bounded resource page. Follow nextPageUrl unchanged; the authenticated page retains caller, active organization, filters and limit. Access is rechecked on every request. Administration lists use live keyset reads and may change between pages.

Content-Type: `application/json`

<a id="response-200-object"></a>

### `response.200.object`

`string` · always present

Allowed values: `"list"`.

<a id="response-200-url"></a>

### `response.200.url`

`string` · always present

<a id="response-200-data"></a>

### `response.200.data`

`array<value>` · always present

<a id="response-200-data-object"></a>

### `response.200.data.object`

`string` · always present

The resource type. Always workspace.

Allowed values: `"workspace"`.

<a id="response-200-data-id"></a>

### `response.200.data.id`

`string` · always present

Workspace identity used in routes and memory selectors.

Min length: `1`.

<a id="response-200-data-orgid"></a>

### `response.200.data.orgId`

`string` · always present

Owning Organization's Augenta ID.

Min length: `1`.

<a id="response-200-data-name"></a>

### `response.200.data.name`

`string` · always present

Display name. Renaming does not change the Workspace ID.

<a id="response-200-data-status"></a>

### `response.200.data.status`

`string` · always present

Current Workspace lifecycle state.

<a id="response-200-data-kind"></a>

### `response.200.data.kind`

`string` · always present

Shared Workspace or provisioned personal Default Workspace. Personal Workspaces have separate lifecycle rules.

<a id="response-200-data-owneruserid"></a>

### `response.200.data.ownerUserId`

`string` · conditional

Owner of a personal Workspace, when applicable.

<a id="response-200-data-synthesiscadence"></a>

### `response.200.data.synthesisCadence`

`string` · conditional

Configured consolidation cadence, when set.

<a id="response-200-data-createdbyuserid"></a>

### `response.200.data.createdByUserId`

`string` · always present

Person who created the Workspace.

<a id="response-200-data-createdat"></a>

### `response.200.data.createdAt`

`string` · always present

Recorded Workspace creation time.

<a id="response-200-data-updatedat"></a>

### `response.200.data.updatedAt`

`string` · always present

Recorded Workspace configuration update time.

<a id="response-200-data-_etag"></a>

### `response.200.data._etag`

`string` · conditional

Revision for an If-Match update or archive, when available.

<a id="response-200-data-workspacerole"></a>

### `response.200.data.workspaceRole`

`string` · conditional

The signed-in person's effective Workspace role, when loaded.

<a id="response-200-data-via"></a>

### `response.200.data.via`

`string` · conditional

Source of effective access, such as direct or inherited membership, when loaded.

<a id="response-200-data-members"></a>

### `response.200.data.members`

`object` · conditional

Initial membership page, loaded by include=members on the detail read. Follow its nextPageUrl for more.

<a id="response-200-data-members-object"></a>

### `response.200.data.members.object`

`string` · always present

Allowed values: `"list"`.

<a id="response-200-data-members-url"></a>

### `response.200.data.members.url`

`string` · always present

<a id="response-200-data-members-data"></a>

### `response.200.data.members.data`

`array<value>` · always present

<a id="response-200-data-members-data-object"></a>

### `response.200.data.members.data.object`

`string` · always present

Allowed values: `"organization_member"`, `"workspace_member"`.

<a id="response-200-data-members-data-id"></a>

### `response.200.data.members.data.id`

`string` · always present

Min length: `1`.

<a id="response-200-data-members-data-userid"></a>

### `response.200.data.members.data.userId`

`string` · always present

Min length: `1`.

<a id="response-200-data-members-data-organization"></a>

### `response.200.data.members.data.organization`

`string` · always present

<a id="response-200-data-members-data-workspace"></a>

### `response.200.data.members.data.workspace`

`string` · conditional

<a id="response-200-data-members-data-name"></a>

### `response.200.data.members.data.name`

`string` · conditional

<a id="response-200-data-members-data-email"></a>

### `response.200.data.members.data.email`

`string` · conditional

<a id="response-200-data-members-data-role"></a>

### `response.200.data.members.data.role`

`string` · conditional

<a id="response-200-data-members-data-workspacerole"></a>

### `response.200.data.members.data.workspaceRole`

`string` · conditional

<a id="response-200-data-members-data-orgrole"></a>

### `response.200.data.members.data.orgRole`

`string` · conditional

<a id="response-200-data-members-data-via"></a>

### `response.200.data.members.data.via`

`string` · conditional

<a id="response-200-data-members-data-addedat"></a>

### `response.200.data.members.data.addedAt`

`string` · conditional

<a id="response-200-data-members-data-addedbyuserid"></a>

### `response.200.data.members.data.addedByUserId`

`string` · conditional

<a id="response-200-data-members-data-permissions"></a>

### `response.200.data.members.data.permissions`

`array<string>` · conditional

See the [OpenAPI specification](https://augenta.pages.dev/docs/openapi.json) for deeper fields.

<a id="response-200-data-members-data-memberclass"></a>

### `response.200.data.members.data.memberClass`

`string` · conditional

<a id="response-200-data-members-data-hassignedin"></a>

### `response.200.data.members.data.hasSignedIn`

`boolean` · conditional

<a id="response-200-data-members-data-joinedat"></a>

### `response.200.data.members.data.joinedAt`

`string` · conditional

<a id="response-200-data-members-nextpageurl"></a>

### `response.200.data.members.nextPageUrl`

`string | null` · always present

<a id="response-200-nextpageurl"></a>

### `response.200.nextPageUrl`

`string | null` · always present

<a id="response-200-organization"></a>

### `response.200.organization`

`object` · always present

<a id="response-200-organization-object"></a>

### `response.200.organization.object`

`string` · always present

The resource type. Always organization.

Allowed values: `"organization"`.

<a id="response-200-organization-id"></a>

### `response.200.organization.id`

`string` · always present

Augenta Organization ID used in resource routes.

Min length: `1`.

<a id="response-200-organization-name"></a>

### `response.200.organization.name`

`string` · always present

Organization display name.

<a id="response-200-organization-role"></a>

### `response.200.organization.role`

`string` · conditional

The signed-in person's organization role, when loaded.

<a id="response-200-organization-workosorgid"></a>

### `response.200.organization.workosOrgId`

`string` · conditional

External identity-provider reference, when present. Resource routes use id instead.

<a id="response-200-organization-membercount"></a>

### `response.200.organization.memberCount`

`integer | null` · always present

Full roster count, or null when the roster has not been read.

Minimum: `0`.

<a id="response-200-organization-members"></a>

### `response.200.organization.members`

`object` · conditional

Initial membership page, loaded by include=members on the detail read. Follow its nextPageUrl for more.

<a id="response-200-organization-members-object"></a>

### `response.200.organization.members.object`

`string` · always present

Allowed values: `"list"`.

<a id="response-200-organization-members-url"></a>

### `response.200.organization.members.url`

`string` · always present

<a id="response-200-organization-members-data"></a>

### `response.200.organization.members.data`

`array<value>` · always present

<a id="response-200-organization-members-data-object"></a>

### `response.200.organization.members.data.object`

`string` · always present

Allowed values: `"organization_member"`, `"workspace_member"`.

<a id="response-200-organization-members-data-id"></a>

### `response.200.organization.members.data.id`

`string` · always present

Min length: `1`.

<a id="response-200-organization-members-data-userid"></a>

### `response.200.organization.members.data.userId`

`string` · always present

Min length: `1`.

<a id="response-200-organization-members-data-organization"></a>

### `response.200.organization.members.data.organization`

`string` · always present

<a id="response-200-organization-members-data-workspace"></a>

### `response.200.organization.members.data.workspace`

`string` · conditional

<a id="response-200-organization-members-data-name"></a>

### `response.200.organization.members.data.name`

`string` · conditional

<a id="response-200-organization-members-data-email"></a>

### `response.200.organization.members.data.email`

`string` · conditional

<a id="response-200-organization-members-data-role"></a>

### `response.200.organization.members.data.role`

`string` · conditional

<a id="response-200-organization-members-data-workspacerole"></a>

### `response.200.organization.members.data.workspaceRole`

`string` · conditional

<a id="response-200-organization-members-data-orgrole"></a>

### `response.200.organization.members.data.orgRole`

`string` · conditional

<a id="response-200-organization-members-data-via"></a>

### `response.200.organization.members.data.via`

`string` · conditional

<a id="response-200-organization-members-data-addedat"></a>

### `response.200.organization.members.data.addedAt`

`string` · conditional

<a id="response-200-organization-members-data-addedbyuserid"></a>

### `response.200.organization.members.data.addedByUserId`

`string` · conditional

<a id="response-200-organization-members-data-permissions"></a>

### `response.200.organization.members.data.permissions`

`array<string>` · conditional

See the [OpenAPI specification](https://augenta.pages.dev/docs/openapi.json) for deeper fields.

<a id="response-200-organization-members-data-memberclass"></a>

### `response.200.organization.members.data.memberClass`

`string` · conditional

<a id="response-200-organization-members-data-hassignedin"></a>

### `response.200.organization.members.data.hasSignedIn`

`boolean` · conditional

<a id="response-200-organization-members-data-joinedat"></a>

### `response.200.organization.members.data.joinedAt`

`string` · conditional

<a id="response-200-organization-members-nextpageurl"></a>

### `response.200.organization.members.nextPageUrl`

`string | null` · always present

## Response 400

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

<a id="response-400-error"></a>

### `response.400.error`

`object` · always present

<a id="response-400-error-code"></a>

### `response.400.error.code`

`string` · always present

Stable. The Errors page lists every code.

<a id="response-400-error-message"></a>

### `response.400.error.message`

`string` · always present

Human-readable. May change; don't parse it.

<a id="response-400-error-retryable"></a>

### `response.400.error.retryable`

`boolean` · always present

<a id="response-400-error-retryafterseconds"></a>

### `response.400.error.retryAfterSeconds`

`integer` · conditional

Capacity retry interval, also present as Retry-After before stream headers commit. SSE error events retain this field after HTTP 200 is committed.

Minimum: `1`.

<a id="response-400-error-billingurl"></a>

### `response.400.error.billingUrl`

`string` · conditional

Top-up action when error.code is insufficient_balance (HTTP 402).

<a id="response-400-requestid"></a>

### `response.400.requestId`

`string` · always present

The request's id, as in the `X-Request-Id` response header.

## Response 401

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 403

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 404

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 409

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 429

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 500

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 503

Invalid parameters, unavailable resource, changed revision or insufficient human permissions. API keys cannot administer organizations or Workspaces.

Content-Type: `application/json`

Response fields use the same schema as Response 400.
