Documentation for the app.nz AI agent cloud.

# Create a key (secret returned once)
curl -sX POST https://app.nz/api/keys \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"deploy bot"}'

# Use it on every other request
curl -s https://app.nz/api/me \
  -H "Authorization: Bearer pk_live_..."

curl -fsSL https://app.nz/cli.sh | sh
app login --api-key pk_live_...

# hand the build to a cloud agent
app agent run --prompt "build a neon snake HTML5 game" --repo you/neon-snake

# pull the agent's files, then ship to https://neon-snake.app.nz
app agent apply <task-id> --dir ./neon-snake
app apps deploy ./neon-snake

curl -s https://app.nz/v1/chat/completions \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "app/auto",
    "messages": [{"role": "user", "content": "Explain CRDTs in one paragraph."}],
    "reasoning_effort": "auto",
    "stream": false
  }'

curl -sX POST https://app.nz/api/agents/tasks \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "add usage analytics to the dashboard",
    "repo": "acme/ai-dashboard",
    "model": "app/auto-code",
    "reasoningEffort": "high",
    "machineType": "auto",
    "provider": "shared",
    "skills": ["github", "visualbench"],
    "spendCapUsd": 2.00,
    "autoMergePr": false
  }'

curl -sX POST https://app.nz/api/agents/tasks \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "devin",
    "prompt": "fix failing CI and open a pull request",
    "repo": "lee101/edukids",
    "baseBranch": "main",
    "autoMergePr": false
  }'

# CLI equivalent:
#   app agents-sdk run "fix failing CI and open a PR" --source devin --repo lee101/edukids
#   app agents-sdk providers      # see which providers are configured
#   app agents-sdk logs <id>      # read the normalized trace

# on the machine that will do the coding
app login
app worker --name desktop --dir ~/agent-work --engines codex,claude

# from any device (or the /agent composer with provider "Your machine")
app agent run --prompt "add a /health endpoint with a test" \
  --repo you/api --provider local --model app/auto-code

# see your machines (same data as the studio chips)
app worker status
curl -s https://app.nz/api/agents/workers -H "Authorization: Bearer pk_live_..."

curl -sX POST https://app.nz/api/artifacts \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"doc","title":"Runbook","mime":"text/markdown","data":"# Runbook\n\nShip it."}'

curl -sX POST https://app.nz/api/artifacts \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"sheet","title":"Budget","mime":"application/json","data":"[{"name":"Sheet1","rows":{"0":{"cells":{"0":{"text":"Item"},"1":{"text":"Cost"}}}}}]"}'

# Save responsive image variants back into /artifacts.
curl -sX POST https://app.nz/api/media/optimize \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "artifact_123",
    "kind": "image",
    "widths": [320, 640, 1280],
    "formats": ["webp"],
    "outputPath": "/optimized"
  }'

# Dynamic best-size image URL.
curl -L "https://app.nz/api/media/image/artifact_123?w=640&format=auto&q=85" \
  -H "Authorization: Bearer pk_live_..."

# CLI equivalents.
app media optimize --artifact-id artifact_123 --width 640 --width 1280 --format webp
app media pricing
app builds media-optimizer-cog

# Create a character with long-form Markdown knowledge.
curl -sX POST https://app.nz/api/characters \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPU Brain Operator",
    "description": "Helps operate the gpu-brain search stack.",
    "voice": "Kore",
    "documents": [{
      "name": "runbook.md",
      "content": "# Runbook\nUse gobed for low-latency KNN over text chunks. Never ingest image links."
    }]
  }'

# Start a chat with a given model.
CHAT=$(curl -sX POST https://app.nz/api/assistant/chats \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "character_url_name": "gpu-brain-operator",
    "model": "app/auto-fast",
    "reasoning_effort": "auto"
  }' | jq -r .chat.id)

# Send a message. The response is text/event-stream; relevant doc excerpts are
# retrieved server-side before the model call.
curl -N -sX POST https://app.nz/api/assistant/chats/$CHAT/messages \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content":"What should I check if KNN search looks stale?"}'

# Create the repo (private by default)
curl -sX POST https://app.nz/api/repos \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app","description":"demo","visibility":"public"}'
# -> {"repo":{"id":"repo_...","fullName":"you/my-app",...}}

# Real git — clone/push over smart HTTP, an API key as the Basic-auth password
git clone https://app.nz/you/my-app.git
cd my-app && git checkout -b feature/x && git commit --allow-empty -m x
git push https://token:[email protected]/you/my-app.git feature/x

# Open a PR against main
curl -sX POST https://app.nz/api/repos/repo_.../pulls \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Add feature x","sourceBranch":"feature/x","targetBranch":"main"}'

# @mention an agent on the PR thread — it launches on the PR branch and replies
curl -sX POST https://app.nz/api/repos/repo_.../pulls/1/comments \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"@agent add input validation and a test for the empty case"}'

# Easiest: push a whole build directory with the app CLI. It creates the
# site on first run, uploads every text file, and prunes anything removed.
app login --api-key pk_live_...
npm run build                         # e.g. Vite -> dist/
app sites deploy my-app dist --title "My app"
#   Live at https://app.nz/sites/my-app/
#     and  https://my-app.app.nz/

# Or drive the REST API directly:
SITE=$(curl -sX POST https://app.nz/api/sites \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-landing","title":"My landing"}')

ID=$(echo "$SITE" | jq -r .site.id)

# Publish index.html — live at /sites/my-landing/ and my-landing.app.nz
curl -sX PUT https://app.nz/api/sites/$ID/files \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"path":"index.html","content":"<!doctype html><h1>Hi</h1>"}'

curl -sX POST https://app.nz/api/cogs \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"fast-vfx","image":"r8.im/lee101/fast-vfx","hardware":"gpu-rtx4090"}'
# -> {"model":{"id":"cog_...","status":"idle",...}}

curl -sX POST https://app.nz/api/cogs/cog_.../predict \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input":{"video":"https://example.com/clip.mp4","num_levels":25}}'
# -> {"prediction":{"id":"pred_...","status":"starting"}}

# Poll for the result (a cold start can take a couple of minutes)
curl -s https://app.nz/api/cogs/predictions/pred_... \
  -H "Authorization: Bearer pk_live_..."

# Audio-to-audio (audex-s2s template): one spoken turn per prediction
curl -sX POST https://app.nz/api/cogs/cog_.../predict \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input":{"task":"converse","audio":"data:audio/webm;base64,...","system_prompt":"You are a cheerful pirate captain."}}'
# -> output: {"transcript":"...","response_text":"...","audio":"data:audio/mpeg;base64,..."}

curl -sX POST https://app.nz/api/notebooks \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"fraud analysis"}'

curl -sX POST https://app.nz/api/notebooks/nb-1a2b3c4d/sessions \
  -H "Authorization: Bearer pk_live_..." \
  -d '{"machineType":"gpu-rtx3090"}'
# -> {"session":{"id":"...","status":"provisioning","priceHourly":"$0.264"}}

# Inspect the catalog
curl -s https://app.nz/api/plans | jq

# From the CLI (app login first)
app plan show
app plan subscribe ultra
app billing usage

# One-time setup: onboard (opens Stripe-hosted KYC, bank account)
app payments enable --country NZ --description "Pro subscriptions"

# From your app's server (never expose the key in browser code):
curl -sX POST https://app.nz/api/payments/checkout \
  -H "Authorization: Bearer $APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2900, "description": "Pro plan", "recurring": "month",
       "successUrl": "https://myapp.app.nz/thanks"}'
# → redirect the buyer to the returned "url"

app payments sales            # who paid
app payments balance          # available / pending / instant
app payments payout --amount 100.00 --instant   # ~30 min, 1.5% fee
app payments offset --amount 50.00              # $50 earnings → 50,000 hosting credits

# Find downloadable image-to-3D assets
curl -s 'https://app.nz/api/animation-library?q=product&kind=image3d&limit=10' | jq

# Download portable geometry
curl -L 'https://app.nz/api/animation-library/image3d-sneaker/download?format=obj' -o sneaker.obj

# Equivalent CLI flow
app animation search product --kind image3d
app animation download image3d-sneaker --format obj --output sneaker.obj

# MCP tools: search_animation_library, download_animation_asset,
# create_image_to_3d_recipe, generate_terrain_recipe

app chat "research R2-backed model hosting" --web --deep --papers
app ra1 generate --prompt "a cat astronaut" --count 2
app papers search "diffusion transformers" --limit 5
app search "best vector database 2026" --depth 2