Polyscope

https://getpolyscope.com/docs
Admin
Polyscope is a native Mac app that runs multiple AI coding agents in parallel, each in isolated...
Tokens:21,329
Snippets:221
Trust Score:5.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Full Polyscope Configuration Example

Source: https://getpolyscope.com/docs/core-concepts/polyscope-json

A comprehensive example of the polyscope.json file, demonstrating the structure for scripts (setup, archive, run), runMode, preview URL, and tasks.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"],
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "autostart": true },
      { "label": "Tests", "command": "npm run test:watch" }
    ]
  },
  "runMode": "replace",
  "preview": {
    "url": "https://{{folder}}.test"
  },
  "tasks": [
    {
      "label": "Security review",
      "prompt": "Review the codebase for security vulnerabilities..."
    }
  ]
}
```

--------------------------------

### Start Polyscope Server

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Starts the Polyscope server process. Once running, the server registers with the Polyscope relay and becomes accessible via the Polyscope desktop app, browser, or mobile app.

```bash
polyscope-server
```

--------------------------------

### Full Example: Create Workspace from GitHub Issue and Wait (PHP)

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

A comprehensive example demonstrating the Polyscope SDK workflow. It shows how to find a repository, create a workspace from a GitHub issue, and retrieve details about the created workspace. It also includes basic error handling for server offline scenarios.

```php
use Polyscope\Laravel\Facades\Polyscope;
use Polyscope\Laravel\Exceptions\ServerOfflineException;

try {
    // Find the repository
    $repositories = Polyscope::repositories();
    $repo = collect($repositories)->firstWhere('name', 'my-app');

    // Create a workspace from a GitHub issue
    $workspace = $repo->createWorkspace([
        'prompt' => 'Fix the issue described below',
        'issue_url' => 'https://github.com/org/my-app/issues/42',
    ]);

    echo "Workspace created: {$workspace->id}\n";
    echo "Branch: {$workspace->branch}\n";
    echo "Preview: {$workspace->previewUrl}\n";
} catch (ServerOfflineException $e) {
    echo "Server is offline. Please start it and try again.\n";
}
```

--------------------------------

### Setup Scripts Configuration (JSON)

Source: https://getpolyscope.com/docs/core-concepts/polyscope-json

Defines automatic scripts to run after a workspace is created, such as installing dependencies or building assets. Supports single commands or arrays of sequential commands.

```json
{
  "scripts": {
    "setup": "npm ci && npm run build"
  }
}
```

```json
{
  "scripts": {
    "setup": ["herd link", "herd isolate 8.4", "herd secure"]
  }
}
```

--------------------------------

### Install Polyscope SDK

Source: https://getpolyscope.com/docs/integrations/javascript-sdk

Install the official Polyscope SDK package via npm to begin integration.

```bash
npm install @polyscope/sdk
```

--------------------------------

### Install Polyscope Server Binary

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Downloads and installs the latest `polyscope-server` binary using a curl script. It auto-detects the system architecture and installs to `~/.local/bin/`. The installation directory can be customized using the `POLYSCOPE_INSTALL_DIR` environment variable.

```bash
curl -fsSL https://getpolyscope.com/install/server | bash
```

```bash
POLYSCOPE_INSTALL_DIR=/opt/polyscope curl -fsSL https://getpolyscope.com/install/server | bash
```

--------------------------------

### Full Featured Laravel Setup in Polyscope JSON

Source: https://getpolyscope.com/docs/digging-deeper/run-scripts

This comprehensive JSON configuration for a Laravel project in Polyscope includes setup and archive scripts, multiple autostarting run scripts with 'replace' mode, and a preview URL utilizing the '{{folder}}' placeholder. It showcases advanced configuration options for a development environment.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"],
    "run": [
      { "label": "Queue Worker", "command": "php artisan queue:work", "autostart": true, "runMode": "replace" },
      { "label": "Vite", "command": "npm run dev", "autostart": true, "runMode": "replace" },
      { "label": "Tests", "command": "php artisan test --watch" }
    ]
  },
  "runMode": "replace",
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

--------------------------------

### Create Workspace from GitHub Issue in TypeScript

Source: https://getpolyscope.com/docs/integrations/javascript-sdk

A complete workflow example demonstrating initializing the Polyscope client, fetching repositories, and creating a workspace linked to a specific GitHub issue.

```typescript
import { Polyscope, ServerOfflineError } from "@polyscope/sdk";

try {
    const polyscope = new Polyscope({ apiToken: "your-api-token" });

    const repositories = await polyscope.repositories();
    const repo = repositories.find((r) => r.name === "my-app");

    const workspace = await repo.createWorkspace({
        prompt: "Fix the issue described below",
        issueUrl: "https://github.com/org/my-app/issues/42",
    });

    console.log(`Workspace created: ${workspace.id}`);
    console.log(`Branch: ${workspace.branch}`);
    console.log(`Preview: ${workspace.previewUrl}`);
} catch (error) {
    if (error instanceof ServerOfflineError) {
        console.log("Server is offline. Please start it and try again.");
    }
}
```

--------------------------------

### Configure Polyscope Server with systemd

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Sets up `polyscope-server` to run as a systemd service for production environments. This involves creating a service file, enabling the service, and starting it. It ensures the server restarts automatically if it fails.

```bash
sudo tee /etc/systemd/system/polyscope-server.service > /dev/null <<EOF
[Unit]
Description=Polyscope Server
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$HOME/.local/bin/polyscope-server
Restart=always
RestartSec=5
Environment=HOME=$HOME

[Install]
WantedBy=multi-user.target
EOF
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable polyscope-server
sudo systemctl start polyscope-server
```

```bash
sudo systemctl status polyscope-server
```

--------------------------------

### Install Polyscope SDK via Composer

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Use the Composer package manager to install the Polyscope SDK dependency into your PHP project.

```bash
composer require beyondcode/polyscope
```

--------------------------------

### Initialize New Git Repository (Bash)

Source: https://getpolyscope.com/docs/core-concepts/repositories

This snippet demonstrates how to initialize a new git repository from scratch using bash commands. It creates a directory, initializes git, adds a README file, and makes an initial commit. This is useful for starting new projects before adding them to Polyscope.

```bash
mkdir my-new-project
cd my-new-project
git init
touch README.md
git add . && git commit -m "Initial commit"
```

--------------------------------

### Workspace Lifecycle Example

Source: https://getpolyscope.com/docs/core-concepts/workspaces

Illustrates the typical lifecycle of a Polyscope workspace, from creation to its final state.

```text
Created → Active → Merged / PR Created / Deleted
```

--------------------------------

### Configure Project Scripts and Preview

Source: https://getpolyscope.com/docs/core-concepts/polyscope-json

Defines setup, archive, and run scripts for project environments, along with preview URL settings. Supports both Laravel/Herd and Node.js project structures.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"],
    "run": [
      { "label": "Queue Worker", "command": "php artisan queue:work", "autostart": true },
      { "label": "Vite", "command": "npm run dev", "autostart": true }
    ]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

```json
{
  "scripts": {
    "setup": "npm install",
    "archive": "rm -rf dist",
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "autostart": true, "runMode": "replace" },
      { "label": "Tests", "command": "npm run test:watch" }
    ]
  },
  "preview": {
    "url": "http://localhost:3000"
  }
}
```

--------------------------------

### Polyscope Server Utility Commands

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Provides essential commands for interacting with the Polyscope server. These include checking the server's authentication and operational status, updating the server to the latest version, and logging out to remove stored credentials.

```bash
polyscope-server status
```

```bash
polyscope-server update
```

```bash
polyscope-server logout
```

--------------------------------

### Handle API Exceptions with Polyscope SDK (PHP)

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Provides examples of how to handle common API exceptions thrown by the Polyscope SDK. It demonstrates catching specific exceptions like `ValidationException` and `ServerOfflineException`, and accessing error details. The `RateLimitExceededException` includes a `rateLimitResetsAt` property for implementing retry logic.

```php
use Polyscope\Laravel\Exceptions\ValidationException;
use Polyscope\Laravel\Exceptions\ServerOfflineException;

try {
    $workspace = $polyscope->createWorkspace([
        'prompt' => 'Missing repository_id',
    ]);
} catch (ValidationException $e) {
    $errors = $e->errors(); // ['repository_id' => ['The repository id field is required.']]
} catch (ServerOfflineException $e) {
    // The target server is not connected
}
```

```php
use Polyscope\Laravel\Exceptions\RateLimitExceededException;

try {
    $polyscope->createWorkspace($data);
} catch (RateLimitExceededException $e) {
    $retryAfter = $e->rateLimitResetsAt - time();
}
```

--------------------------------

### Polyscope Configuration (`polyscope.json`)

Source: https://getpolyscope.com/docs/core-concepts/workspaces

Defines workspace behavior including setup and archive scripts, preview URLs, and reusable tasks.

```json
{
  "scripts": {
    "setup": "npm ci && npm run build",
    "archive": "rm -rf dist"
  },
  "preview": {
    "url": "http://localhost:3000"
  },
  "tasks": [
    {
      "label": "Security review",
      "prompt": "Review the codebase for security vulnerabilities..."
    }
  ]
}
```

--------------------------------

### Configure Polyscope Server with supervisord

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Configures `polyscope-server` to run as a process managed by `supervisord`. This involves adding a program configuration block to `supervisord.conf` and then reloading `supervisord` to apply the changes. It ensures the server starts automatically and restarts on failure.

```ini
[program:polyscope-server]
command=/home/youruser/.local/bin/polyscope-server
user=youruser
autostart=true
autorestart=true
stderr_logfile=/var/log/polyscope-server.err.log
stdout_logfile=/var/log/polyscope-server.out.log
environment=HOME="/home/youruser"
```

```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start polyscope-server
```

--------------------------------

### Configure Workspace Lifecycle Scripts

Source: https://getpolyscope.com/docs/core-concepts/workflows

Defines setup and archive scripts in polyscope.json to automate environment preparation and cleanup. Supports both single command strings and arrays of commands for complex workflows.

```json
{
  "scripts": {
    "setup": "npm ci && npm run build",
    "archive": "herd unlink"
  }
}
```

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

```json
{
  "scripts": {
    "setup": "npm install && npm run build",
    "archive": "rm -rf dist"
  },
  "preview": {
    "url": "http://localhost:3000"
  }
}
```

--------------------------------

### Configure Autostart Scripts in Polyscope JSON

Source: https://getpolyscope.com/docs/digging-deeper/run-scripts

This JSON configuration enables the 'autostart' feature for specific run scripts in Polyscope. Scripts marked with `"autostart": true` will launch automatically after workspace setup is complete. This is ideal for continuously running services like dev servers or queue workers.

```json
{
  "scripts": {
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "autostart": true },
      { "label": "Queue Worker", "command": "php artisan queue:work", "autostart": true }
    ]
  }
}
```

--------------------------------

### Authenticate Polyscope Server

Source: https://getpolyscope.com/docs/getting-started/standalone-server

Authenticates the `polyscope-server` with your Polyscope account. This initiates a device code flow, requiring you to visit a URL in your browser and enter a code to authorize the server. Credentials are then stored locally.

```bash
polyscope-server login
```

--------------------------------

### Polyscope Configuration File (JSON)

Source: https://getpolyscope.com/docs/core-concepts/repositories

This JSON configuration file, `polyscope.json`, allows customization of workspace behavior within a Polyscope repository. It defines setup and archive scripts, a preview URL pattern, and custom tasks with labels and prompts. This enables tailored workflows and agent interactions.

```json
{
  "scripts": {
    "setup": "npm install && npm run build",
    "archive": "npm run cleanup"
  },
  "preview": {
    "url": "http://{{folder}}.test"
  },
  "tasks": [
    {
      "label": "Security review",
      "prompt": "Review the codebase for security vulnerabilities..."
    }
  ]
}
```

--------------------------------

### Configure Polyscope Preview URL

Source: https://getpolyscope.com/docs/digging-deeper/visual-editor

This configuration snippet shows how to set up the preview URL in your `polyscope.json` file. It uses a placeholder `{{folder}}` which resolves to the workspace's folder name, enabling the preview panel in your workspace.

```json
{
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

--------------------------------

### Authenticate with Polyscope SDK

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Configure the SDK using an API token. In standalone PHP, initialize the client directly, while in Laravel, use the service configuration file.

```php
use Polyscope\Laravel\Polyscope;

$polyscope = new Polyscope('your-api-token');
```

```php
'polyscope' => [
    'token' => env('POLYSCOPE_TOKEN'),
],
```

--------------------------------

### Configure Polyscope with Laravel Herd

Source: https://getpolyscope.com/docs/integrations/laravel-herd

A sample polyscope.json configuration file that automates the linking and securing of a workspace within the Laravel Herd environment. It uses setup and archive scripts to manage the lifecycle of a .test domain.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

--------------------------------

### Manage Servers and Repositories

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Retrieve lists of connected servers and repositories. Repositories can be fetched globally or filtered by a specific server ID.

```php
$servers = $polyscope->servers();

foreach ($servers as $server) {
    echo $server->name;
    echo $server->platform;
    echo $server->online;
    echo $server->version;
}

$repositories = $polyscope->repositories();
$repositories = $polyscope->repositories(serverId: 'srv-1');
```

--------------------------------

### Manage Workspaces

Source: https://getpolyscope.com/docs/integrations/javascript-sdk

Create, retrieve, refresh, and delete workspaces. Workspaces can be initialized from repositories, GitHub issues, or pull requests.

```typescript
// Create a workspace
const workspace = await polyscope.createWorkspace({
    repositoryId: "repo-1",
    prompt: "Fix the login flow"
});

// Get a single workspace
const ws = await polyscope.workspace("ws-1");

// Refresh and delete
await ws.refresh();
await ws.delete();
```

--------------------------------

### Configure Global Run Mode in Polyscope JSON

Source: https://getpolyscope.com/docs/digging-deeper/run-scripts

This JSON configuration sets a global default for the 'runMode' in Polyscope. The 'runMode' determines the behavior when a script is already running: 'preserve' opens a new tab, while 'replace' kills the existing tab and starts fresh. This global setting can be overridden per script.

```json
{
  "runMode": "replace"
}
```

--------------------------------

### Repositories API

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Retrieve a list of all repositories, optionally filtered by server.

```APIDOC
## GET /repositories

### Description
Retrieve all repositories, optionally filtered by server.

### Method
GET

### Endpoint
/repositories

### Parameters
#### Query Parameters
- **serverId** (string) - Optional - The ID of the server to filter repositories by.

### Request Example
```php
// All repositories
$repositories = $polyscope->repositories();

// Repositories on a specific server
$repositories = $polyscope->repositories(serverId: 'srv-1');
```

### Response
#### Success Response (200)
- **repositories** (array) - An array of repository objects.
  - **name** (string) - The name of the repository.
  - **path** (string) - The local path of the repository.
  - **baseBranch** (string) - The default branch of the repository.
  - **hasRemote** (boolean) - Indicates if the repository has a remote origin.
  - **serverId** (string) - The ID of the server where the repository is located.

#### Response Example
```json
[
  {
    "name": "my-project",
    "path": "/Users/user/Projects/my-project",
    "baseBranch": "main",
    "hasRemote": true,
    "serverId": "srv-1"
  }
]
```
```

--------------------------------

### Override Run Mode Per Script in Polyscope JSON

Source: https://getpolyscope.com/docs/digging-deeper/run-scripts

This JSON snippet illustrates how to override the global 'runMode' setting for individual scripts within the `polyscope.json` file. It shows examples of setting 'replace' for a 'Dev Server' script and 'preserve' for a 'Lint' script, demonstrating granular control over script execution behavior.

```json
{
  "scripts": {
    "run": [
      { "label": "Dev Server", "command": "npm run dev", "runMode": "replace" },
      { "label": "Lint", "command": "npm run lint", "runMode": "preserve" }
    ]
  }
}
```

--------------------------------

### Manage Servers and Repositories

Source: https://getpolyscope.com/docs/integrations/javascript-sdk

Retrieve lists of connected servers and repositories. Repositories can be filtered by server ID to narrow down results.

```typescript
const servers = await polyscope.servers();

// List all repositories
const repositories = await polyscope.repositories();

// List repositories on a specific server
const serverRepos = await polyscope.repositories({ serverId: "srv-1" });
```

--------------------------------

### Static Preview URL Configuration (JSON)

Source: https://getpolyscope.com/docs/core-concepts/polyscope-json

Configures a fixed URL for the workspace preview, useful when the preview server runs on a known, static address like localhost:3000.

```json
{
  "preview": {
    "url": "http://localhost:3000"
  }
}
```

--------------------------------

### Workspace Lifecycle Management

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Create, retrieve, refresh, and delete workspaces. Workspaces can be initialized from repositories, GitHub issues, or pull requests.

```php
$workspace = $polyscope->createWorkspace([
    'repository_id' => 'repo-1',
    'prompt' => 'Fix the login flow and add tests',
]);

$workspace = $polyscope->workspace('ws-1');
$workspace->refresh();
$workspace->delete();
```

--------------------------------

### Use Folder Placeholder in Polyscope Script Command

Source: https://getpolyscope.com/docs/digging-deeper/run-scripts

This JSON configuration demonstrates the use of the `{{folder}}` placeholder within a script command in `polyscope.json`. This placeholder dynamically resolves to the workspace's folder name at runtime, allowing for flexible command construction, such as setting a host for a development server.

```json
{
  "scripts": {
    "run": [
      { "label": "Serve", "command": "php artisan serve --host={{folder}}.test" }
    ]
  }
}
```

--------------------------------

### Workspaces API

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Manage workspaces, including listing, creating, and retrieving details.

```APIDOC
## Workspaces API

### List Workspaces

#### Description
Retrieve a list of all workspaces, with options to filter by server, repository, or status.

#### Method
GET

#### Endpoint
/workspaces

#### Parameters
##### Query Parameters
- **server_id** (string) - Optional - Filter workspaces by server ID.
- **repository_id** (string) - Optional - Filter workspaces by repository ID.
- **status** (string) - Optional - Filter workspaces by their status (e.g., 'running', 'idle').

#### Request Example
```php
// All workspaces
$workspaces = $polyscope->workspaces();

// Filter by server, repository, or status
$workspaces = $polyscope->workspaces([
    'server_id' => 'srv-1',
    'repository_id' => 'repo-1',
    'status' => 'running',
]);
```

#### Response
##### Success Response (200)
- **workspaces** (array) - An array of workspace objects.
  - **id** (string) - The unique identifier for the workspace.
  - **status** (string) - The current status of the workspace (e.g., 'running', 'idle').
  - **branch** (string) - The branch associated with the workspace.
  - **previewUrl** (string) - A URL for previewing the workspace, if applicable.
  - **prUrl** (string) - The URL of the associated pull request, if created.

##### Response Example
```json
[
  {
    "id": "ws-1",
    "status": "running",
    "branch": "feature-branch",
    "previewUrl": "https://preview.example.com",
    "prUrl": null
  }
]
```

### Create Workspace

#### Description
Create a new workspace from a repository, optionally with a prompt and server specification.

#### Method
POST

#### Endpoint
/workspaces

#### Parameters
##### Request Body
- **repository_id** (string) - Required - The ID of the repository to create the workspace from.
- **prompt** (string) - Required - A description or task for the workspace.
- **server_id** (string) - Optional - The ID of the server to create the workspace on.

#### Request Example
```php
$workspace = $polyscope->createWorkspace([
    'repository_id' => 'repo-1',
    'prompt' => 'Fix the login flow and add tests',
    'server_id' => 'srv-1', // optional
]);
```

#### Response
##### Success Response (201)
- **workspace** (object) - The newly created workspace object.
  - **id** (string) - The unique identifier for the workspace.
  - **status** (string) - The current status of the workspace.
  - **branch** (string) - The branch associated with the workspace.
  - **previewUrl** (string) - A URL for previewing the workspace.
  - **prUrl** (string) - The URL of the associated pull request, if created.

##### Response Example
```json
{
  "id": "ws-new-123",
  "status": "pending",
  "branch": "feature-fix-login",
  "previewUrl": null,
  "prUrl": null
}
```

### Create Workspace from Repository Resource

#### Description
Create a workspace directly from a repository resource object.

#### Method
POST

#### Endpoint
/repositories/{repositoryId}/workspaces

#### Parameters
##### Path Parameters
- **repositoryId** (string) - Required - The ID of the repository.

##### Request Body
- **prompt** (string) - Required - A description or task for the workspace.
- **server_id** (string) - Optional - The ID of the server to create the workspace on.

#### Request Example
```php
$repository = $polyscope->repositories()[0];

$workspace = $repository->createWorkspace([
    'prompt' => 'Add rate limiting to the API',
]);

// Or use the shorthand
$workspace = $repository->createWorkspace('Add rate limiting to the API');
```

#### Response
##### Success Response (201)
- **workspace** (object) - The newly created workspace object (same structure as above).

##### Response Example
```json
{
  "id": "ws-repo-456",
  "status": "pending",
  "branch": "feature-rate-limit",
  "previewUrl": null,
  "prUrl": null
}
```

### Create Workspace from GitHub Issue

#### Description
Create a workspace directly from a GitHub issue URL.

#### Method
POST

#### Endpoint
/workspaces/from-issue

#### Parameters
##### Request Body
- **repositoryId** (string) - Required - The ID of the repository.
- **issueUrl** (string) - Required - The URL of the GitHub issue.
- **serverId** (string) - Optional - The ID of the server to create the workspace on.

#### Request Example
```php
$workspace = $polyscope->createWorkspaceFromIssue(
    repositoryId: 'repo-1',
    issueUrl: 'https://github.com/org/repo/issues/42',
    serverId: 'srv-1', // optional
);
```

#### Response
##### Success Response (201)
- **workspace** (object) - The newly created workspace object (same structure as above).

##### Response Example
```json
{
  "id": "ws-issue-789",
  "status": "pending",
  "branch": "issue-42-fix",
  "previewUrl": null,
  "prUrl": null
}
```

### Create Workspace from Pull Request

#### Description
Create a workspace directly from a GitHub pull request URL.

#### Method
POST

#### Endpoint
/workspaces/from-pull-request

#### Parameters
##### Request Body
- **repositoryId** (string) - Required - The ID of the repository.
- **pullRequestUrl** (string) - Required - The URL of the GitHub pull request.
- **serverId** (string) - Optional - The ID of the server to create the workspace on.

#### Request Example
```php
$workspace = $polyscope->createWorkspaceFromPullRequest(
    repositoryId: 'repo-1',
    pullRequestUrl: 'https://github.com/org/repo/pull/99',
    serverId: 'srv-1', // optional
);
```

#### Response
##### Success Response (201)
- **workspace** (object) - The newly created workspace object (same structure as above).

##### Response Example
```json
{
  "id": "ws-pr-101",
  "status": "pending",
  "branch": "pr-99-review",
  "previewUrl": null,
  "prUrl": "https://github.com/org/repo/pull/99"
}
```

### Get Single Workspace

#### Description
Retrieve details for a specific workspace by its ID.

#### Method
GET

#### Endpoint
/workspaces/{workspaceId}

#### Parameters
##### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace to retrieve.

#### Request Example
```php
$workspace = $polyscope->workspace('ws-1');

echo $workspace->status;
echo $workspace->branch;
echo $workspace->previewUrl;
echo $workspace->prUrl;
```

#### Response
##### Success Response (200)
- **workspace** (object) - The workspace object (same structure as list response).

##### Response Example
```json
{
  "id": "ws-1",
  "status": "running",
  "branch": "brave-bunny",
  "previewUrl": "https://preview.example.com/ws-1",
  "prUrl": null
}
```

### Refresh Workspace Data

#### Description
Refresh the data for a specific workspace.

#### Method
POST

#### Endpoint
/workspaces/{workspaceId}/refresh

#### Parameters
##### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace to refresh.

#### Request Example
```php
$workspace = $workspace->refresh();
```

#### Response
##### Success Response (200)
- **workspace** (object) - The updated workspace object (same structure as get single workspace response).

##### Response Example
```json
{
  "id": "ws-1",
  "status": "running",
  "branch": "brave-bunny",
  "previewUrl": "https://preview.example.com/ws-1",
  "prUrl": null
}
```

### Delete Workspace

#### Description
Delete a specific workspace.

#### Method
DELETE

#### Endpoint
/workspaces/{workspaceId}

#### Parameters
##### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace to delete.

#### Request Example
```php
$polyscope->deleteWorkspace('ws-1');

// Or from the resource directly
$workspace->delete();
```

#### Response
##### Success Response (204)
No content.

```

--------------------------------

### Authenticate with Polyscope

Source: https://getpolyscope.com/docs/integrations/javascript-sdk

Initialize the Polyscope client using an explicit API token or by relying on local desktop application credentials.

```typescript
import { Polyscope } from "@polyscope/sdk";

// Using an explicit token
const polyscope = new Polyscope({ apiToken: "your-api-token" });

// Using local desktop credentials
const polyscopeLocal = new Polyscope();
```

--------------------------------

### Create and Manage Workspace Pull Requests (PHP)

Source: https://getpolyscope.com/docs/integrations/laravel-php-sdk

Demonstrates how to create a pull request for a workspace using the Polyscope SDK. It shows two methods: one using the main Polyscope object and another using a workspace resource object. The `draft` parameter allows for creating a draft pull request.

```php
$polyscope->createWorkspacePullRequest(
    workspaceId: 'ws-1',
    title: 'Fix login flow',
    body: 'Resolves #42',
    draft: false,
);

// Or from the workspace resource
$workspace->pullRequest(
    title: 'Fix login flow',
    body: 'Resolves #42',
    draft: true,
);
```
Tokens:
Raw