> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Organize your Coval resources into separate workspaces within your organization

Use workspaces to separate agents, evaluations, metrics, and content by project, team, or environment. New organizations start with a default workspace that cannot be renamed, archived, or deleted.

## Workspace limits

The number of workspaces available depends on your plan:

| Plan | Workspaces |
| - | - |
| Starter | 2 |
| Growth | 5 |
| Enterprise | Unlimited |

Your default workspace and all active or archived custom workspaces count toward your limit. Deleting a custom workspace frees a slot. Archiving does not.

## Using workspaces in the Coval app

### Switch workspaces

Select an active workspace from the sidebar switcher. You stay on the same page, but workspace-specific filters and open resource details reset. Select **Configure** for workspace settings.

### Manage workspaces

Go to **Settings > Workspaces** to see workspace names, types, and statuses. Organization admins can create workspaces and use the actions menu to rename, archive, or delete a custom workspace. Archived workspaces can only be deleted from this menu.

### Create a workspace

Click **New Workspace** and enter a display name. Coval generates a unique identifier automatically. The workspace is created with Active status.

### Delete a workspace

Deleting removes a workspace from the list and blocks access to its resources. The app and API have no restore action, so treat deletion as permanent.

## Using the workspaces API

Base URL: `https://api.coval.dev/v1`
Authentication: include your API key in the `X-API-Key` header. Your key needs `workspaces:read` for list and get, and `workspaces:write` for create, rename, archive, and delete. See [API keys](/guides/api-keys).

| Method | Endpoint | Action |
| - | - | - |
| `GET` | `/workspaces` | List active and archived workspaces |
| `POST` | `/workspaces` | Create a workspace |
| `GET` | `/workspaces/{workspace_id}` | Get a workspace |
| `PATCH` | `/workspaces/{workspace_id}` | Rename a workspace |
| `POST` | `/workspaces/{workspace_id}/archive` | Archive a workspace |
| `DELETE` | `/workspaces/{workspace_id}` | Delete a workspace |

### List workspaces

```bash theme={null}
curl https://api.coval.dev/v1/workspaces \
  -H "X-API-Key: your_api_key"
```

Returns all active and archived workspaces. Deleted workspaces are excluded.

### Create a workspace

```bash theme={null}
curl -X POST https://api.coval.dev/v1/workspaces \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Production"}'
```

Send `display_name`, containing 1 to 200 characters after trimming whitespace. Use the generated `workspace.id` from the response in subsequent calls.

The deprecated `slug` fields remain for compatibility. A supplied slug is validated but ignored during creation.

Creation at or above your limit returns `409 Conflict`, with the limit and deletion guidance. A temporary service failure returns `503 Service Unavailable` without creating a workspace. Retry later.

### Get a workspace

```bash theme={null}
curl https://api.coval.dev/v1/workspaces/WORKSPACE_ID \
  -H "X-API-Key: your_api_key"
```

Returns an active or archived workspace by ID. Deleted workspaces return `404 Not Found`.

### Update a workspace

```bash theme={null}
curl -X PATCH https://api.coval.dev/v1/workspaces/WORKSPACE_ID \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New Name"}'
```

Updates the display name. Default workspaces return `409 Conflict`.

### Archive a workspace

```bash theme={null}
curl -X POST https://api.coval.dev/v1/workspaces/WORKSPACE_ID/archive \
  -H "X-API-Key: your_api_key"
```

Archives the workspace. Repeating the request returns the archived workspace without error. Default workspaces return `409 Conflict`.

### Delete a workspace

```bash theme={null}
curl -X DELETE https://api.coval.dev/v1/workspaces/WORKSPACE_ID \
  -H "X-API-Key: your_api_key"
```

Marks the workspace as deleted and returns it with status `DELETED`. Default workspaces return `409 Conflict`.

## Scoping API requests to a workspace

Use the `X-Coval-Workspace-Id` header for workspace-scoped resources (agents, runs, metrics, test sets). Set it to the `workspace.id` from the workspaces API:

```bash theme={null}
curl https://api.coval.dev/v1/runs/RUN_ID \
  -H "X-API-Key: your_api_key" \
  -H "X-Coval-Workspace-Id: WORKSPACE_ID"
```

For workspace-scoped endpoints, omitting the header normally selects your active default workspace. An explicit ID must identify an active workspace in your organization. A nonexistent, cross-organization, archived, or deleted workspace returns `403 Forbidden`. Check each endpoint's reference for workspace support.

> **Note:** Workspace lifecycle endpoints use the organization or the ID in the path, not `X-Coval-Workspace-Id`. This lets you manage archived workspaces without selecting them.

## Related pages

<CardGroup cols={2}>
  <Card title="API Reference" icon="square-terminal" href="/api-reference/v1/introduction">
    Explore the full API documentation
  </Card>

  <Card title="API Keys" icon="key" href="/guides/api-keys">
    Create and manage API keys for authentication
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.