API Overview

The Wallfacer API gives you two ways to automate cloud development work.

Use the managed coding API when you want Wallfacer to own the VM lifecycle and run an AI coding session. Use the lower-level VM API when you want direct infrastructure control: boot a VM from an environment, run commands, inspect ports, and destroy it yourself.

This guide explains the model and common workflows. For complete parameters, response schemas, and status codes, use the API Reference.

Base URL

https://api.wallfacer.ai/v1

All examples use paths under this base URL. For example, GET /v1/accounts means:

GET https://api.wallfacer.ai/v1/accounts

OpenAPI Specification

The API publishes its own OpenAPI description at https://api.wallfacer.ai/v1/openapi.yaml. It always describes the currently deployed API, so tooling that reads it stays in step with what the endpoints actually do.

Fetch it to generate a client, import the API into Postman or Insomnia, or drive your own code generation.

curl -s https://api.wallfacer.ai/v1/openapi.yaml -o wallfacer-openapi.yaml

The endpoint is public and needs no token. The API Reference renders this same description as browsable documentation.

Core Model

Most resources belong to an account. You usually start by listing accounts, then pass the chosen account ID into account-scoped routes.

Resource	What it represents
Account	A workspace boundary for environments, tasks, VMs, users, invitations, secrets, snapshots, and logs.
Agent	An AI identity in the account that tasks run as. Commits, pull requests, and credentials resolve to it. Hiring one provisions its own computer (an environment).
Environment	A reusable runtime definition: platform, repos, setup, services, commands, simulator config, and agent config.
Secret	A write-only encrypted value scoped to one environment and referenced from the manifest as `${secrets.NAME}`.
Snapshot	One environment generation attempt. A ready snapshot becomes the environment's fast-boot base. Failed attempts are kept for logs.
VM	A running machine booted from an environment, optionally pinned to a specific snapshot.
Task	A unit of coding work, such as "fix checkout tests."
Session	One agent run under a task. Sessions own VM boot, branch identity, messages, and idle behavior.
Message	A user or assistant turn, plus internal transcript events used by clients.
Attachment	Extra task context in MCP resource shape, such as ticket text or an external reference.

Choose a Workflow

Managed coding

Use tasks, sessions, messages, and attachments when you want Wallfacer to run an AI coding workflow.

Typical flow:

Create or choose an environment for the repository.
Create a task with a prompt and optional attachments.
Wallfacer creates a session, boots a VM, and sends the first message to the agent.
Poll the session or messages until work appears.
Send follow-up messages or close the session when done.

The task owns the work item. The session owns the individual attempt, VM, branch, and conversation.

Direct infrastructure

Use environments, VMs, commands, logs, and snapshots when you want programmatic VM control without the managed chat layer.

Typical flow:

Create an environment with a manifest.
Wait for its base snapshot to be ready.
Create a VM from the environment.
Poll the VM until ready is true.
Run commands or use exposed service ports.
Destroy the VM when finished.

VMs always boot from environments. The public API does not accept raw manifests on VM creation.

Common Endpoint Map

This is a map, not a reference. Use the API Reference for exact fields.

Goal	Main routes
Discover account IDs	`GET /v1/accounts`
Configure a runtime	`POST /v1/accounts/{account}/environments`
Store environment secrets	`POST /v1/accounts/{account}/environments/{environment}/secrets`
Watch snapshot generation	`GET /v1/accounts/{account}/environments/{environment}` and `GET /v1/accounts/{account}/environments/{environment}/snapshots`
Boot direct compute	`POST /v1/accounts/{account}/vms`
Run a shell command	`POST /v1/accounts/{account}/vms/{vm}/commands`
Start managed coding work	`POST /v1/accounts/{account}/tasks`
Attach task context	`POST /v1/accounts/{account}/tasks/{task}/attachments`
Start another attempt	`POST /v1/accounts/{account}/tasks/{task}/sessions`
Send follow-up instructions	`POST /v1/accounts/{account}/tasks/{task}/sessions/{session}/messages`
Store a credential for agents	`POST /v1/accounts/{account}/credentials`
Grant a credential to one agent	`PUT /v1/accounts/{account}/credentials/{credential}/grants/{agent}`
Read the people directory	`GET /v1/accounts/{account}/people`
Direct an agent with an objective	`POST /v1/accounts/{account}/agents/{agent}/objectives`
See what an agent owes	`GET /v1/accounts/{account}/agents/{agent}/todos`
Search across your account	`GET /v1/accounts/{account}/search`
Inspect setup and runtime failures	Log routes under VMs, environments, snapshots, and sessions
Control an iOS simulator	Simulator routes under `GET /v1/accounts/{account}/vms/{vm}/simulator`