sites

Run a command in the workspace

A bash command in the project's root, on a working copy of the draft in the site's own container: rg, grep, sed, find, cat, node. A build of the project is refused (400): workspace:commit sends the files through the same checks as every change and starts the real build, whose errors getSiteBuild reports. No network, at most 300 s. Files it changes stay uncommitted (listed in uncommitted) until workspace:commit. The workspace follows the draft: another change carries your uncommitted edits over.

POST/v1/sites/{site_id}/workspace:run

Request

curl --request POST \
  --url 'https://api.atelier201.com/v1/sites/<site_id>/workspace:run' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "command": "<string>"
}'

import json
import requests

url = "https://api.atelier201.com/v1/sites/<site_id>/workspace:run"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"command\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.atelier201.com/v1/sites/<site_id>/workspace:run", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "command": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.atelier201.com/v1/sites/<site_id>/workspace:run");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"command\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.atelier201.com/v1/sites/<site_id>/workspace:run", bytes.NewBuffer([]byte("{\"command\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.atelier201.com/v1/sites/<site_id>/workspace:run"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"command\":\"<string>\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.atelier201.com/v1/sites/<site_id>/workspace:run")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"command\":\"<string>\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "data": {
    "revision": "<string>",
    "exit_code": 123,
    "timed_out": true,
    "output": "<string>",
    "truncated": true,
    "uncommitted": [
      "<string>"
    ],
    "note": null
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

Requires sites:write. Costs no credits. The path ends in /workspace:run.

The workspace is a shell on a working copy of the site’s draft, in the site’s own container, offline. Use it for what a shell does well: rg, grep, find, cat, sed -i, node, and npx astro build to try a build in seconds. The command runs in the project’s root as an unprivileged user, and there is no network.

What the command changes stays uncommitted. The response lists those changes in uncommitted, one per line in the style of git status (M src/pages/index.astro). Nothing reaches the history until you commit the workspace, and visitors see nothing until you publish.

command is at most 8000 characters. timeout_ms is between 1000 and 300000 and defaults to 60000: a command still running at that point is stopped and timed_out is true. A command that fails is not an API error: the call succeeds and exit_code is not 0. output holds stdout and stderr together; past 8 KB it keeps the start and the end and truncated is true.

The workspace follows the draft. When another change has moved the draft since your last command, your uncommitted edits are carried over and note says so, the same when the workspace had to be rebuilt.

A site that is still being created answers result_not_ready, and a suspended or deleting site answers conflict.

Authorizations

Authorizationbearerin headerrequired

Path parameters

site_idstringrequired

The site's id, or its slug (the address before .atelier201.page).

Body

application/jsonrequired

commandstringrequiredlength: 1–8000 chars

A bash command, run in the project's root on a working copy of the draft: rg, grep, sed, find, cat, node... No network. Files it changes stay uncommitted until workspace:commit, which builds them and reports any build error. A build of the project here is refused: it took 30 s and duplicated that build.

timeout_msintegerrange: 1000–300000

Default 60000. The command is stopped past it.

Response

application/json

Run a shell command on the site's workspace

dataobjectrequired

Show child attributes

data.revisionstringrequiredlength: 40–40 chars

The draft revision the workspace started from.

data.exit_codeintegerrequiredrange: -9007199254740991–9007199254740991

data.timed_outbooleanrequired

data.outputstringrequired

stdout and stderr together; past 8 KB, its start and end.

data.truncatedbooleanrequired

data.uncommittedstring[]required

The workspace's uncommitted changes after the command, git status style ("M src/pages/index.astro").

data.notestringnullrequired

Said when the workspace was rebuilt or moved to a newer draft before the command.

request_idstringrequired

curl --request POST \ --url 'https://api.atelier201.com/v1/sites/<site_id>/workspace:run' \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "command": "<string>" }'

{ "data": { "revision": "<string>", "exit_code": 123, "timed_out": true, "output": "<string>", "truncated": true, "uncommitted": [ "<string>" ], "note": null }, "request_id": "<string>" }

{ "error": { "type": "<string>", "code": "<string>", "message": "<string>", "param": "<string>", "docs_url": "<string>", "action_url": "<string>", "details": {} }, "request_id": "<string>" }

Run a command in the workspace

Authorizations

Path parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown

Cookies