Skip to main content
A workspace is the foundation of your Yasumu project. It contains all your REST requests, environments, email configurations, and other resources stored as .ysl (Yasumu Schema Language) files.

​
Understanding workspaces

When you create a workspace in Yasumu, it initializes a yasumu directory in your project with the following structure: 
my-project/
└── yasumu/
    ├── workspace.ysl          # Workspace metadata and groups
    ├── smtp.ysl               # Email server configuration
    ├── yasumu-lock.json       # Dependency lock file
    ├── rest/                  # REST request definitions
    │   └── *.ysl
    └── environment/           # Environment configurations
        └── *.ysl
All files are plain text and can be committed to version control, making collaboration seamless.

​
Creating your first workspace

1

Open Yasumu

Launch the Yasumu application on your system.
2

Create new workspace

Click on “Create Workspace” or use the workspace menu to create a new workspace.
3

Choose location

Select or create a directory where your workspace will be initialized. This is typically your project root.
4

Name your workspace

Provide a meaningful name for your workspace. This will be stored in the workspace.ysl file:
@workspace

metadata {
  id: "v753h51r3e10zzcg5rkel8mv"
  name: "my-api-project"
  version: 0
}

snapshot 1768400471602

groups {}

​
Programmatic workspace creation

You can also create workspaces programmatically using the Yasumu Core API: 
import { Yasumu } from '@yasumu/core';

const yasumu = new Yasumu();

// Create a new workspace
const workspace = await yasumu.workspaces.create({
  name: 'My API Project',
  path: '/path/to/project',
  metadata: {
    description: 'API testing workspace',
    team: 'Backend Team'
  }
});

console.log(`Workspace created: ${workspace.name}`);
console.log(`Workspace ID: ${workspace.id}`);

​
Workspace properties

Once created, a workspace provides access to several key properties: 
// Access workspace information
workspace.id          // Unique workspace identifier
workspace.name        // Workspace name
workspace.path        // File system path
workspace.metadata    // Custom metadata object
workspace.createdAt   // Creation timestamp
workspace.updatedAt   // Last update timestamp

// Access workspace modules
workspace.rest         // REST API module
workspace.environments // Environment manager
workspace.emails       // Email/SMTP module

​
Opening existing workspaces

To open an existing workspace:
1

Use workspace menu

Click on the workspace selector in Yasumu’s interface.
2

Browse or select

Either browse to a directory containing a yasumu folder, or select from recent workspaces.
3

Activate workspace

The workspace will be loaded and set as active, giving you access to all its resources.

​
Programmatically opening workspaces

// Open workspace by ID
const workspace = await yasumu.workspaces.open({
  id: 'workspace-id-here'
});

// List all workspaces
const workspaces = await yasumu.workspaces.list();

// Get currently active workspace
const active = yasumu.workspaces.getActiveWorkspace();

​
Organizing with groups

Workspaces support groups (folders) to organize your REST requests: 
// Create a group for organizing requests
const group = await workspace.rest.createEntityGroup({
  name: 'User API',
  entity: 'rest',
  parentId: null, // null for root-level group
  workspaceId: workspace.id
});
Groups are stored in the workspace.ysl file: 
groups {
  w10lye9m7dsomdwoj9zooyf4: {
    id: "w10lye9m7dsomdwoj9zooyf4"
    name: "User API"
    entity: rest
    parentId: null
    workspaceId: "v753h51r3e10zzcg5rkel8mv"
  }
}

​
Workspace synchronization

Yasumu automatically synchronizes workspace changes. You can manually trigger synchronization: 
await workspace.synchronize();

​
Best practices

  • One workspace per project: Create a workspace at your project root for easy access
  • Commit .ysl files: All .ysl files should be committed to version control
  • Exclude secrets: Use environment secrets for sensitive data (stored locally, not in .ysl files)
  • Descriptive names: Use clear names for workspaces and groups
  • Regular sync: Let Yasumu handle synchronization automatically

​
Next steps

REST requests

Create and execute HTTP requests

Environment variables

Manage variables across environments

Team collaboration

Share workspaces with your team

Build docs developers (and LLMs) love

Get started for freeTalk to us