API

For agents: Use bearer auth for owner reads and mutations. Send JSON. Handle structured { "error": { "code", "message" } } responses.

Base URL

https://api.userland.fun

All owner reads and mutations use:

Authorization: Bearer ap_live_...
Content-Type: application/json

Endpoints

• POST /v0/accounts
• POST /v0/auth/token
• GET /v0/apps
• PUT /v0/apps
• GET /v0/apps/:app_id
• PUT /v0/apps/:app_id
• DELETE /v0/apps/:app_id
• GET /v0/apps/:app_id/releases
• POST /v0/apps/:app_id/rollback
• GET /v0/apps/:app_id/resources
• GET /v0/apps/:app_id/events
• GET /v0/apps/:app_id/secrets
• PUT /v0/apps/:app_id/secrets/:NAME
• DELETE /v0/apps/:app_id/secrets/:NAME
• POST /v0/apps/:app_id/admin-invites

Use /openapi.json for the machine-readable API contract.

Publish request

PUT /v0/apps creates an app and first release. PUT /v0/apps/:app_id publishes another release for an existing app.

{
  "app": { "name": "Hello App", "visibility": "public" },
  "runtime": { "static_root": "public", "fallback": "index.html" },
  "resources": {},
  "files": [
    {
      "path": "public/index.html",
      "content_type": "text/html; charset=utf-8",
      "content_base64": "PCFkb2N0eXBlIGh0bWw+PGgxPkhlbGxvPC9oMT4="
    }
  ],
  "message": "Initial release",
  "provenance": { "source": "agent" }
}

The response includes status, app_id, release_id, origin, previous_release_id, and activation.

Activation

• live means the release is serving.
• pending_secrets means required secrets are missing.
• requires_migration means the release was stored but did not become live because a resource change needs an explicit migration plan.

Events and rollback

Use GET /v0/apps/:app_id/events?severity=error&limit=25 to inspect owner-visible failures. Use rollback only with a compatible retained release.