API

API

Create computers, run commands in them, put them to sleep and delete them, from any language that can send an HTTP request. JSON in, JSON out.

https://api.homemade.devOpenAPI 3.1

Your first computer

Four requests, from a key to a command’s output.

  1. Authenticate

    Create a key under Account → API keys, or with homemade api-key create. It is shown once. Send it as a bearer token.

    export HOMEMADE_API_KEY=hmk_…curl https://api.homemade.dev/api/me \  -H "Authorization: Bearer $HOMEMADE_API_KEY"
  2. Create a computer

    It starts from the project’s latest build of main. Pass branch, size or name to choose. The answer comes at once, while it starts.

    curl -X POST https://api.homemade.dev/api/vms \  -H "Authorization: Bearer $HOMEMADE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"projectId": "k3v9q2m7x1d8r4tp"}'
    Response
    {  "vm": {    "name": "misty-fern-142",    "branch": "main",    "state": "queued"  }}
  3. Wait until it runs

    Poll every few seconds until vm.state is running. Stop if it ends in failed or stopped.

    until [ "$(curl -s https://api.homemade.dev/api/vms/$VM_ID \  -H "Authorization: Bearer $HOMEMADE_API_KEY" \  | jq -r '.vm.state')" = running ]; do sleep 2; done
  4. Run a command

    Runs in the project folder as the computer’s user and answers when it ends. Add ?stream=1 for anything that runs longer than a minute.

    curl -X POST https://api.homemade.dev/api/vms/$VM_ID/exec \  -H "Authorization: Bearer $HOMEMADE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"command": "node --version && git log -1 --oneline"}'
    Response
    {  "exitCode": 0,  "stdout": "v26.13.1\n3f9c2e1 Add checkout page\n",  "stderr": "",  "durationMs": 41,  "timedOut": false}

Endpoints

The most used ones. Errors come back as a status and a JSON error a person can read.

POST/api/vmsCreate a computer
GET/api/vmsList computers
GET/api/vms/{vmId}Get one, with its services
POST/api/vms/{vmId}/execRun a command
POST/api/vms/{vmId}/sleepPut it to sleep
POST/api/vms/{vmId}/wakeWake it
PATCH/api/vms/{vmId}Rename, auto-sleep, access
DELETE/api/vms/{vmId}Delete it
GET/api/projectsList projects
GET/api/meWho the key belongs to