# Workspace

Source: https://ceyo.ai/docs/signal/workspace

### Workspace

Read and update your workspace and manage immutable project and location packages.

### Get workspace

`GET /workspace`

Returns the workspace selected by the Bearer API key.

#### Response envelope

`workspace`:**Workspace**

The requested or updated workspace.

#### Workspace

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Workspace identifier. |
| `name` | string |  | Workspace display name. |
| `description` | string \| null |  | Workspace description. |
| `logo_url` | string \| null |  | Absolute URL of the workspace logo, when one is configured. |
| `status` | active \| suspended \| archived |  | Current workspace lifecycle status. |
| `created_at` | datetime |  | Workspace creation time. |
| `updated_at` | datetime |  | Most recent workspace update time. |

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/workspace' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "workspace": {
    "id": "87661f5e-5931-4535-9889-22192f943d27",
    "name": "Northstar Digital",
    "description": "AI visibility programs for customer brands.",
    "logo_url": "https://api.ceyo.ai/media/logos/opaque-logo-token",
    "status": "active",
    "created_at": "2026-01-12T09:30:00Z",
    "updated_at": "2026-07-30T14:20:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Update workspace

`PATCH /workspace`

Updates only the supplied workspace fields. Omitted fields remain unchanged.

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `name` | string |  | New workspace display name. Maximum: 200 characters. |
| `description` | string \| null |  | New description. Maximum: 5,000 characters; use null to clear it. |

> **JSON only**
>
> Supply only the fields you want to change. Workspace logos are not accepted by this operation.

#### Response envelope

`workspace`:**Workspace**

The requested or updated workspace.

#### Workspace

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Workspace identifier. |
| `name` | string |  | Workspace display name. |
| `description` | string \| null |  | Workspace description. |
| `logo_url` | string \| null |  | Absolute URL of the workspace logo, when one is configured. |
| `status` | active \| suspended \| archived |  | Current workspace lifecycle status. |
| `created_at` | datetime |  | Workspace creation time. |
| `updated_at` | datetime |  | Most recent workspace update time. |

#### Request and response

```curl
curl --request PATCH \
  --url 'https://api.signal.ceyo.ai/v1/workspace' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Northstar Digital",
  "description": "AI visibility programs for customer brands."
}'
```

```json
{
  "workspace": {
    "id": "87661f5e-5931-4535-9889-22192f943d27",
    "name": "Northstar Digital",
    "description": "AI visibility programs for customer brands.",
    "logo_url": "https://api.ceyo.ai/media/logos/opaque-logo-token",
    "status": "active",
    "created_at": "2026-01-12T09:30:00Z",
    "updated_at": "2026-07-30T14:20:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `422` | validation\_failed |  | One or more request fields are invalid. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |