Workspace limits
The number of workspaces available depends on your plan:
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 workspaces in the CLI
The CLI manages workspaces withcoval workspaces and runs any command in a workspace with --workspace <workspace_id> or the COVAL_WORKSPACE_ID environment variable. See CLI workspaces.
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.
List workspaces
Create a workspace
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
404 Not Found.
Update a workspace
409 Conflict.
Archive a workspace
409 Conflict.
Delete a workspace
DELETED. Default workspaces return 409 Conflict.
Scoping API requests to a workspace
Use theX-Coval-Workspace-Id header for workspace-scoped resources (agents, runs, metrics, test sets). Set it to the workspace.id from the workspaces API:
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
API Reference
Explore the full API documentation
API Keys
Create and manage API keys for authentication