# Update space

Update a space's name, description, or access settings.

Update one or more properties of a space. Only the fields included in the request body are updated.

- **Name and description** require edit access (`editable_by_users`, `editable_by_roles`, or space creator).
- **Access control fields** (`access_mode`, `access_users`, `access_departments`, `editable_by_users`, `editable_by_roles`, `visible_to_roles`) require owner access (space creator or `override_all_permissions` capability).
- Role and department IDs in access control fields are validated against the organization — invalid IDs return a `422 Validation Error`.


#### Path Parameters

**`space_id`** string required

The unique identifier of the space.

#### Request Body

All fields are optional. Only included fields are updated.

**`name`** string optional

New space name. Must be 1–255 characters.

**`description`** string optional

New space description.

**`access_mode`** string optional

New access mode: `private`, `organization`, or `public`.

**`access_users`** array of strings optional

New list of user IDs with view access.

**`access_departments`** array of strings optional

New list of department IDs with view access.

**`editable_by_users`** array of strings optional

New list of user IDs with edit access.

**`editable_by_roles`** array of strings optional

New list of role IDs with edit access.

**`visible_to_roles`** array of strings optional

New list of role IDs with view access.

## Returns

The updated Space object.

Request

```bash cURL
curl -X PATCH "https://api.aitronos.com/v1/spaces/space_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Knowledge Base", "access_mode": "organization"}'
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.patch(
    "https://api.aitronos.com/v1/spaces/space_abc123",
    headers={"X-API-Key": api_key},
    json={"name": "Updated Knowledge Base", "access_mode": "organization"},
)
print(response.json())
```


```javascript JavaScript
const response = await fetch(
  "https://api.aitronos.com/v1/spaces/space_abc123",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Updated Knowledge Base",
      access_mode: "organization",
    }),
  }
);
const data = await response.json();
```

Response

```json 200 OK
{
  "id": "space_abc123",
  "organization_id": "org_abc123",
  "created_by": "usr_abc123",
  "name": "Updated Knowledge Base",
  "description": "Shared memory for product team conversations",
  "vector_store_id": "vs_auto123",
  "access_mode": "organization",
  "access_users": null,
  "access_departments": null,
  "editable_by_users": null,
  "editable_by_roles": null,
  "visible_to_roles": null,
  "additional_vector_store_ids": ["vs_catalog456"],
  "last_activity_at": "2026-02-26T15:30:00Z",
  "created_at": "2026-02-26T10:00:00Z",
  "updated_at": "2026-02-26T16:00:00Z"
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action.",
    "system_message": "Edit access required",
    "type": "client_error",
    "status": 403,
    "details": { "space_id": "space_abc123" },
    "trace_id": "abc-123-def",
    "timestamp": "2026-02-26T10:00:00Z"
  }
}
```

## Related Resources

- [Create Space](/docs/api-reference/spaces/create)
- [Retrieve Space](/docs/api-reference/spaces/retrieve)
- [List Spaces](/docs/api-reference/spaces/list)
- [Delete Space](/docs/api-reference/spaces/delete)