Wallfacer
On this page

Quickstart: API

This quickstart uses the managed coding workflow: create an environment, wait for its snapshot, create a task with a prompt, then send a follow-up message.

For direct VM control, see Virtual Machines.

Prerequisites

  • A Wallfacer account
  • A Wallfacer API token
  • A GitHub repository that Wallfacer can access
  • curl and jq

Set the base URL and token:

export WALLFACER_API="https://api.wallfacer.ai/v1"
export WALLFACER_TOKEN="your-token-here"

Step 1: Get Your Account ID

export ACCOUNT_ID=$(
  curl -s "$WALLFACER_API/accounts" \
    -H "Authorization: Bearer $WALLFACER_TOKEN" \
    | jq -r ".data[0].id"
)

echo "$ACCOUNT_ID"

Step 2: Create An Environment

Replace acme/my-api with your repo.

ENV_RESPONSE=$(
  curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/environments" \
    -H "Authorization: Bearer $WALLFACER_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: quickstart-env-001" \
    -d '{
      "name": "api-quickstart",
      "visibility": "private",
      "manifest": {
        "version": 1,
        "platform": { "os": "linux/amd64" },
        "sources": [
          {
            "repo": "acme/my-api",
            "workspace": "/workspace/my-api",
            "branch": "main"
          }
        ],
        "setup": [
          {
            "name": "install",
            "run": "npm ci",
            "working_dir": "/workspace/my-api"
          }
        ]
      }
    }'
)

export ENVIRONMENT_ID=$(echo "$ENV_RESPONSE" | jq -r ".data.id")
echo "$ENVIRONMENT_ID"

Creating the environment starts snapshot generation. That snapshot is what makes later task and VM boots fast.

Step 3: Wait For The Snapshot

while true; do
  status=$(
    curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/environments/$ENVIRONMENT_ID" \
      -H "Authorization: Bearer $WALLFACER_TOKEN" \
      | jq -r ".data.base_snapshot.status // \"none\""
  )

  echo "snapshot: $status"

  case "$status" in
    ready) break ;;
    failed) echo "snapshot failed"; exit 1 ;;
    *) sleep 10 ;;
  esac
done

If generation fails, inspect Snapshots and Logs.

Step 4: Create A Task

Including prompt starts a session automatically.

TASK_RESPONSE=$(
  curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/tasks" \
    -H "Authorization: Bearer $WALLFACER_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: quickstart-task-001" \
    -d '{
      "title": "Add a health endpoint",
      "prompt": "Add a /health endpoint that returns JSON and include a small test.",
      "environment_id": "'$ENVIRONMENT_ID'"
    }'
)

export TASK_ID=$(echo "$TASK_RESPONSE" | jq -r ".data.id")
echo "$TASK_ID"

Step 5: Find The Session

export SESSION_ID=$(
  curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/tasks/$TASK_ID/sessions" \
    -H "Authorization: Bearer $WALLFACER_TOKEN" \
    | jq -r ".data[0].id"
)

echo "$SESSION_ID"

The session owns the VM, branch, and conversation for this attempt.

Step 6: Send A Follow-Up

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/tasks/$TASK_ID/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-message-001" \
  -d '{"message": "Also update the README with the new endpoint."}' \
  | jq ".data"

Sending a message can resume an idle session. To stop the attempt explicitly, close the session:

curl -s -X PATCH "$WALLFACER_API/accounts/$ACCOUNT_ID/tasks/$TASK_ID/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

Next