# Create a Workspace

## POST `/v1/workspaces`

Create a shared Workspace and make its creator an administrator. Guests cannot create Workspaces. Personal Default Workspaces are provisioned separately.

## 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 POST "https://api.augenta.ai/v1/workspaces" \
  -H "Authorization: Bearer $AUGENTA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "<string>"
}'
```

## Body fields

<a id="request-body-name"></a>

### `request.body.name`

`string` · required

Min length: `1`. Max length: `120`.

<a id="request-body-id"></a>

### `request.body.id`

`string` · optional

## Response 201

The created Workspace resource.

Content-Type: `application/json`

```json
{
  "object": "workspace",
  "id": "release-guides",
  "orgId": "org_example",
  "name": "Release guides",
  "status": "active",
  "kind": "shared",
  "createdByUserId": "user_example",
  "createdAt": "2026-10-27T12:00:00Z",
  "updatedAt": "2026-10-27T12:00:00Z",
  "workspaceRole": "admin"
}
```

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

### `response.201.object`

`string` · always present

The resource type. Always workspace.

Allowed values: `"workspace"`.

<a id="response-201-id"></a>

### `response.201.id`

`string` · always present

Workspace identity used in routes and memory selectors.

Min length: `1`.

<a id="response-201-orgid"></a>

### `response.201.orgId`

`string` · always present

Owning Organization's Augenta ID.

Min length: `1`.

<a id="response-201-name"></a>

### `response.201.name`

`string` · always present

Display name. Renaming does not change the Workspace ID.

<a id="response-201-status"></a>

### `response.201.status`

`string` · always present

Current Workspace lifecycle state.

<a id="response-201-kind"></a>

### `response.201.kind`

`string` · always present

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

<a id="response-201-owneruserid"></a>

### `response.201.ownerUserId`

`string` · conditional

Owner of a personal Workspace, when applicable.

<a id="response-201-synthesiscadence"></a>

### `response.201.synthesisCadence`

`string` · conditional

Configured consolidation cadence, when set.

<a id="response-201-createdbyuserid"></a>

### `response.201.createdByUserId`

`string` · always present

Person who created the Workspace.

<a id="response-201-createdat"></a>

### `response.201.createdAt`

`string` · always present

Recorded Workspace creation time.

<a id="response-201-updatedat"></a>

### `response.201.updatedAt`

`string` · always present

Recorded Workspace configuration update time.

<a id="response-201-_etag"></a>

### `response.201._etag`

`string` · conditional

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

<a id="response-201-workspacerole"></a>

### `response.201.workspaceRole`

`string` · conditional

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

<a id="response-201-via"></a>

### `response.201.via`

`string` · conditional

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

<a id="response-201-members"></a>

### `response.201.members`

`object` · conditional

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

<a id="response-201-members-object"></a>

### `response.201.members.object`

`string` · always present

Allowed values: `"list"`.

<a id="response-201-members-url"></a>

### `response.201.members.url`

`string` · always present

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

### `response.201.members.data`

`array<value>` · always present

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

### `response.201.members.data.object`

`string` · always present

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

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

### `response.201.members.data.id`

`string` · always present

Min length: `1`.

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

### `response.201.members.data.userId`

`string` · always present

Min length: `1`.

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

### `response.201.members.data.organization`

`string` · always present

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

### `response.201.members.data.workspace`

`string` · conditional

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

### `response.201.members.data.name`

`string` · conditional

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

### `response.201.members.data.email`

`string` · conditional

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

### `response.201.members.data.role`

`string` · conditional

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

### `response.201.members.data.workspaceRole`

`string` · conditional

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

### `response.201.members.data.orgRole`

`string` · conditional

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

### `response.201.members.data.via`

`string` · conditional

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

### `response.201.members.data.addedAt`

`string` · conditional

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

### `response.201.members.data.addedByUserId`

`string` · conditional

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

### `response.201.members.data.permissions`

`array<string>` · conditional

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

### `response.201.members.data.memberClass`

`string` · conditional

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

### `response.201.members.data.hasSignedIn`

`boolean` · conditional

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

### `response.201.members.data.joinedAt`

`string` · conditional

<a id="response-201-members-nextpageurl"></a>

### `response.201.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.
