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