Skip to main content
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: 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 with coval 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

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

Create a workspace

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

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

Update a workspace

Updates the display name. Default workspaces return 409 Conflict.

Archive a workspace

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

Delete a workspace

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:
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.

API Reference

Explore the full API documentation

API Keys

Create and manage API keys for authentication