Browse documentationApps

Resource guide

An app binds a folder to a process

App registration connects a workspace path, start command, port, and stable slug. An optional name is the human-facing label; when it is unset, clients display the registered folder name. An optional icon is a safe path relative to that app folder, such as icon.png or assets/icon.png—it is not an image URL or embedded bytes. Keep the command reproducible from the registered folder and choose visibility separately from process configuration. The API returns url for opening and sharing, and embedUrl for the embedded preview. Use these addresses rather than constructing or persisting a second app identity. An active custom hostname takes precedence in url; otherwise public apps use https://<app>--<workspace>.public.bento.ing/ (public-staging on staging), and private apps use the standard host. embedUrl always uses https://<app>--<workspace>.edge.bento.ing/ (edge-staging on staging). Standard addresses keep working. The public host serves only public apps; making an app private makes its public host return 404.

Public apps are served from Bento's CDN at their public host and custom domain; standard addresses and the embedded preview are never cached. The CDN keeps a GET or HEAD 200 that sets no cookie and is not an event stream, refreshing it in the background after 60 seconds. The app's Cache-Control decides: no-store, no-cache or private keeps a response out of the CDN, and s-maxage=N replaces the 60 seconds. The response to a request that carries cookies is kept only when the app sends s-maxage, its promise that the response is the same for everyone. A copy is served to every visitor of its URL, so send no-store on API and other dynamic responses, including pages that differ for signed-in visitors. Making an app private, pausing the workspace or deleting the app removes its cached copies within seconds.

Request body
{
  "path": "apps/status",
  "command": "bun run start",
  "apiScopes": ["services"],
  "port": 4173,
  "slug": "status",
  "name": "Status Board",
  "icon": "assets/icon.png"
}

apiScopes is the app server's least-privilege declaration, not a list of features the UI happens to show. Declare only the capabilities required by Bento API routes the server actually calls, and send [] when it calls none. The capability grammar and credential boundaries live in API keys and scopes; admin is deliberately unavailable to apps.

Bento does not add an install-time consent step. Declared scopes are visible before and after an app is installed, with elevated access called out; a workspace removes that authority by disabling or uninstalling the app, not by maintaining a second approval record.

Restart picks up new server code

A running app keeps the code it started with. After changing its server code, call POST /v1/workspaces/{workspaceSlug}/apps/{appSlug}/restart (bento app restart). It stops the process and starts it again with the same command, port and credentials, and answers with the app once the new process is serving. If the new process does not come up, it answers app_reconcile_failed with operation: "restart", a reason, and the app marked reconcile_failed; fix the code and restart again. Files served as-is, and data the app reads per request, need no restart.

Editors and owners can restart any app that is switched on and has its folder, including a read-only shared copy and an installed marketplace app: the process runs on their own computer. controls.restart says whether this caller may.

Runtime authority stays outside the drive

A service running inside Bento receives its separately managed BENTO_APP_API_KEY and BENTO_API_URL through its process environment; install commands do not receive the key. Bento owns that credential's refresh and recovery. Reuse the injected value rather than copying the managed key into app source. The credential policy owns private runtime storage and authorized export handling.

An externally hosted server uses a fresh exported instance of the app credential instead. API keys and scopes owns the shared identity, capability, lifetime and revocation rules.

Externally hosted apps

Keep an ordinary visible app registration for a server hosted on Vercel or another provider. Its small static page explains what the app does, says it is externally hosted, and links to the actual deployment URL when known. Keep that folder and app row when redeploying; no external app subtype or Bento hosting proxy is required.

After declaring the server's capabilities, export an app credential and install it through the host's server-side secret manager before deployment. Use returned key, apiUrl and gatewayBaseUrl as BENTO_APP_API_KEY, BENTO_API_URL and BENTO_GATEWAY_BASE_URL. Those origins identify the same deployment as the key, including staging. Capture the response in memory and pass it to the host's server-side secret store through stdin. Authorized API, CLI and MCP export results may contain the one-time plaintext; keep it out of public assets, browser variables, source control and incidental logs.

A workspace agent can complete registration, export, host configuration and deployment using its normal app-management authority. It does not require a human to create or copy a Bento key. Use the actual bento app credential create command when available, or the public export API with an explicit expiration choice. Production automation normally chooses never; honor a requested finite lifetime. The response reveals new plaintext once, so do not automatically retry an issuing POST after an uncertain network result. Inspect inventory and clean up unwanted issuance before an explicit retry.

To rotate, export another key, configure and deploy the host, confirm the deployed server uses it, then revoke the selected old credential ID. A full live inventory needs deliberate cleanup, not a retry loop or wholesale revocation. Declarations remain visible in normal app inspection.

Build an app agents can operate

A stateful app needs an HTTP API as well as its UI. Keep its data in app-owned storage and serve reads, mutations and the page from the registered process. Document the app's purpose, routes, inputs, results and failure behavior in a README.md inside its folder. That is the contract a later agent reads before operating the app.

Inside the workspace VM, discover the app through the app list and call it at http://127.0.0.1:<registered-port>. Read its README before sending a request. Use that API for requests such as adding a task; change source only when the user wants the app itself changed. External callers use the app's returned URL and its normal access policy; they cannot use the VM's loopback address.

Push data changes to an already-open page over server-sent events. Serve text/event-stream, flush updates promptly, send heartbeat comments while quiet, and release timers and listeners when the request closes. Set the application server's idle timeout longer than its heartbeat. Keep API and event requests same-origin so they work through the embedded app and its proxy. Apps do not support WebSocket upgrades; use SSE for server-to-page updates.

The edge ends long streams cleanly before the hosting deadline. Native EventSource reconnects, so reread canonical state when the connection opens as well as when an update arrives; changes may occur while disconnected. A client can start with:

const events = new EventSource('/events')
events.onopen = () => refresh()
events.onmessage = () => refresh()
// Close the EventSource when this view is disposed.

refresh() reads the app's own API; route names and event payloads belong to the app, not Bento. Verify a data mutation through that API while the embedded page is open: the page must update without a reload. Check the response and persisted data as well as the visible result. If the API succeeds but the page stays stale, inspect event delivery and reconnect handling before claiming the app works. Update the README whenever its API changes.

Reconcile, do not duplicate

List existing apps before creating one from automation. Update command, install command, or port on the existing slug; use deletion only when the public identity should disappear. Name and icon updates are metadata-only: they do not reinstall or restart the app, and sending the same icon path again deliberately advances updatedAt so clients can refresh bytes replaced at that path. Public visibility is a deliberate exposure boundary, not a health-check mechanism.

Runtime writes are complete only after Bento's computer accepts the workspace configuration. Apps report whether that reconciliation is pending, complete, or needs attention. A reconciliation failure is a structured API error: preserve the returned app, show the reason, and refresh the list instead of assuming the optimistic change became durable. Failed runtime edits retain the last accepted command, install command, and port while retaining name and icon changes from the request; failed deletes retain the app registration. A workspace holds at most 100 apps; registering one more answers 409 app_limit, so delete an app the workspace no longer needs before retrying.

Shared apps arrive as replicas

Accepting a share whose folder registers apps materializes real app rows in the recipient workspace, tagged with their origin (sourceShareId, sourceAppId) and with the access that share grants (sourceShareMode). Its apiScopes declaration travels with the registration, but no key does: the recipient workspace mints its own runtime credential. A replica is a real app on the recipient's own computer at the recipient's own URL, so sharing an app is sharing files: a write-mode recipient may change its runtime and publish their copy, and doing so never changes the origin app's visibility. A read-mode recipient may do neither. The recipient's own control is the disabled flag: disabling a replica is durable — origin updates never resurrect it — and re-enabling is the same idempotent endpoint. A replica records who disabled it and when, so the state is auditable. A replica is removed by dropping the share, never by deleting the app. Only replicas can be disabled: the same request on an app the workspace registered itself answers 403 forbidden; stop serving one by deleting it.

Keep policy on the server

The apps scope permits access to this resource but does not replace workspace roles. Viewers can list and inspect apps. Editors can register apps, change runtime configuration, make a public app workspace-only, and delete it. Only owners can expose an app publicly.

Role alone cannot answer what a caller may do to a given app, because a replica lives in a workspace the recipient owns while its permissions come from the share. Every app therefore carries its own resolved controls (updateRuntime, restart, makePublic, makePrivate, delete, manageDomain); the list-level capabilities answers only the workspace-wide question of whether this caller may register an app. Present controls from those values, and still handle authorization failures because roles and shares can change after a client loads.

A custom domain changes the address, not admission

Each app can attach one hostname. Editors and owners can manage it, including for a disabled, broken, shared, or installed app; viewers can inspect its status and DNS instructions. A binding belongs to this local app and does not travel with shared files or marketplace content.

Attach returns the durable reservation while provider work proceeds. Repeating the same hostname returns the same binding; another hostname on that app or a hostname already reserved elsewhere returns a conflict. Follow the returned DNS instructions and conflicts. Bento checks automatically while setup is pending; Recheck also requests a new check after DNS changes or retries an exhausted removal. Only active bindings serve content or become standalone addresses. Provider failures retain diagnostics so the user can repair setup and retry.

Full domain responses include checking: true while an active or failed binding has a queued or running recheck. An active hostname keeps serving during the check. Observe the domain detail or workspace collection until checking is absent and lastCheckedAt advances, then use the returned status and diagnostics as the result. Initial setup still uses pending and verifying.

Removal stops custom-host serving within seconds (cached copies are deleted in the background) and cleans up the provider assignment in the background. A removing binding keeps its reservation until cleanup finishes. When cleanup needs attention, retryRequired identifies the manual retry; the existing Bento address continues to work. The workspace collection uses the usual opaque continuation cursor and may return fewer rows than the requested limit.

A provider write with an uncertain outcome requires operator repair. operatorRepairRequired identifies this state; ordinary Recheck cannot clear it. The hostname stays reserved until support confirms the remote work has settled and resumes cleanup. This prevents a delayed provider add or delete from changing a later attachment.

Public custom-host content retains the app's indexing directives. Standard Bento addresses, private content, and platform authentication or error responses remain excluded from indexing.

A private app is reachable without being public

Visibility governs standalone access, not whether members can use the app. An anonymous browser opening a private app document can sign in through Bento and return to its original host and deep path. This works on its standard address and an active custom domain. API calls, iframe requests, and denied signed-in visitors receive the ordinary refusal instead of a sign-in redirect.

GET /v1/workspaces/{workspaceSlug}/apps/{appSlug}/launch mints the short-lived access grant after checking current app access. Its optional host and path query parameters must be supplied together; the host must be that app's standard address or current active custom domain. The path stays relative to that host, and any old duet_access parameter is replaced. The default launch always uses the standard Bento address. Embedded views use this host for both public and private apps, so customer DNS cannot interrupt an embedded view. Standalone Open and Copy link actions use the active custom address where offered; attaching never publishes the app.

Apps

16 operations
GET/v1/workspaces/{workspaceSlug}/apps/domains

List current app domains in a workspace

CLI
bento app domain list
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "workspaceId": {
                "type": "string"
              },
              "appId": {
                "type": "string"
              },
              "hostname": {
                "type": "string",
                "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "verifying",
                  "active",
                  "failed",
                  "removing"
                ]
              },
              "records": {
                "maxItems": 32,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 32,
                      "pattern": "^[\\x20-\\x7e]+$"
                    },
                    "domain": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 253
                    },
                    "value": {
                      "type": "string",
                      "minLength": 1
                    },
                    "reason": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "domain",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "conflicts": {
                "maxItems": 32,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 253
                    },
                    "type": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 32,
                      "pattern": "^[\\x20-\\x7e]+$"
                    },
                    "value": {
                      "type": "string",
                      "minLength": 1
                    }
                  },
                  "required": [
                    "name",
                    "type",
                    "value"
                  ],
                  "additionalProperties": false
                }
              },
              "lastError": {
                "type": "string",
                "maxLength": 2000
              },
              "createdAt": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "updatedAt": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "lastCheckedAt": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "verifiedAt": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "retryRequired": {
                "type": "boolean"
              },
              "operatorRepairRequired": {
                "type": "boolean",
                "const": true
              },
              "checking": {
                "type": "boolean",
                "const": true
              }
            },
            "required": [
              "id",
              "workspaceId",
              "appId",
              "hostname",
              "status",
              "records",
              "conflicts",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          },
          "app": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "controls": {
                "type": "object",
                "properties": {
                  "manageDomain": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "manageDomain"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "id",
              "slug",
              "controls"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "domain",
          "app"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "invalid_request",
            "invalid_cursor",
            "forbidden",
            "domain_occupied",
            "hostname_in_use",
            "domain_cleanup_pending",
            "domain_not_configured",
            "not_found"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "invalid_cursor"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false,
      "description": "Opaque collection cursor is malformed or bound to another walk (400)"
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/apps/{appSlug}/domain

Inspect an app domain and its DNS instructions

CLI
bento app domain get --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "domain": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "workspaceId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            },
            "records": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "domain": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "domain",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "conflicts": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "name",
                  "type",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "lastError": {
              "type": "string",
              "maxLength": 2000
            },
            "createdAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "updatedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "lastCheckedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "verifiedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "retryRequired": {
              "type": "boolean"
            },
            "operatorRepairRequired": {
              "type": "boolean",
              "const": true
            },
            "checking": {
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "id",
            "workspaceId",
            "appId",
            "hostname",
            "status",
            "records",
            "conflicts",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request",
        "invalid_cursor",
        "forbidden",
        "domain_occupied",
        "hostname_in_use",
        "domain_cleanup_pending",
        "domain_not_configured",
        "not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
PUT/v1/workspaces/{workspaceSlug}/apps/{appSlug}/domain

Attach one custom hostname without changing app visibility

CLI
bento app domain update --app-slug example --hostname example
Scope
ws:{workspaceSlug}:apps
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "hostname"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "domain": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "workspaceId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            },
            "records": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "domain": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "domain",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "conflicts": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "name",
                  "type",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "lastError": {
              "type": "string",
              "maxLength": 2000
            },
            "createdAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "updatedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "lastCheckedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "verifiedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "retryRequired": {
              "type": "boolean"
            },
            "operatorRepairRequired": {
              "type": "boolean",
              "const": true
            },
            "checking": {
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "id",
            "workspaceId",
            "appId",
            "hostname",
            "status",
            "records",
            "conflicts",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request",
        "invalid_cursor",
        "forbidden",
        "domain_occupied",
        "hostname_in_use",
        "domain_cleanup_pending",
        "domain_not_configured",
        "not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Declared idempotent
POST/v1/workspaces/{workspaceSlug}/apps/{appSlug}/domain/recheck

Request a fresh domain check or retry exhausted removal

CLI
bento app domain recheck --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "domain": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "workspaceId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            },
            "records": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "domain": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "domain",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "conflicts": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "name",
                  "type",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "lastError": {
              "type": "string",
              "maxLength": 2000
            },
            "createdAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "updatedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "lastCheckedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "verifiedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "retryRequired": {
              "type": "boolean"
            },
            "operatorRepairRequired": {
              "type": "boolean",
              "const": true
            },
            "checking": {
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "id",
            "workspaceId",
            "appId",
            "hostname",
            "status",
            "records",
            "conflicts",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request",
        "invalid_cursor",
        "forbidden",
        "domain_occupied",
        "hostname_in_use",
        "domain_cleanup_pending",
        "domain_not_configured",
        "not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
DELETE/v1/workspaces/{workspaceSlug}/apps/{appSlug}/domain

Stop serving a custom hostname and schedule provider cleanup

CLI
bento app domain delete --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "domain": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "workspaceId": {
              "type": "string"
            },
            "appId": {
              "type": "string"
            },
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            },
            "records": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "domain": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "domain",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "conflicts": {
              "maxItems": 32,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 253
                  },
                  "type": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 32,
                    "pattern": "^[\\x20-\\x7e]+$"
                  },
                  "value": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "name",
                  "type",
                  "value"
                ],
                "additionalProperties": false
              }
            },
            "lastError": {
              "type": "string",
              "maxLength": 2000
            },
            "createdAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "updatedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "lastCheckedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "verifiedAt": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "retryRequired": {
              "type": "boolean"
            },
            "operatorRepairRequired": {
              "type": "boolean",
              "const": true
            },
            "checking": {
              "type": "boolean",
              "const": true
            }
          },
          "required": [
            "id",
            "workspaceId",
            "appId",
            "hostname",
            "status",
            "records",
            "conflicts",
            "createdAt",
            "updatedAt"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "domain"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request",
        "invalid_cursor",
        "forbidden",
        "domain_occupied",
        "hostname_in_use",
        "domain_cleanup_pending",
        "domain_not_configured",
        "not_found"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Declared idempotent
GET/v1/workspaces/{workspaceSlug}/apps

List workspace apps, optionally filtered by exact id, the deepest app containing a cwd, or drive path

CLI
bento app list
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "minLength": 1
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "id": {
      "type": "string",
      "minLength": 1
    },
    "cwd": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
    },
    "path": {
      "type": "string"
    },
    "scope": {
      "type": "string",
      "enum": [
        "subtree",
        "children",
        "self"
      ]
    }
  },
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "workspaceId": {
            "type": "string"
          },
          "anchorId": {
            "type": "string"
          },
          "anchorPath": {
            "type": "string"
          },
          "anchorState": {
            "type": "string",
            "enum": [
              "active",
              "broken",
              "orphaned"
            ]
          },
          "command": {
            "type": "string",
            "minLength": 1
          },
          "apiScopes": {
            "maxItems": 64,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "files:read",
                "files:write",
                "memory",
                "sessions",
                "agents",
                "services",
                "integrations",
                "apps",
                "share",
                "publish",
                "members"
              ]
            }
          },
          "installCommand": {
            "type": "string",
            "minLength": 1
          },
          "port": {
            "type": "integer",
            "minimum": 1,
            "maximum": 65535
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "icon": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "folder",
              "public"
            ]
          },
          "url": {
            "type": "string"
          },
          "embedUrl": {
            "type": "string"
          },
          "customDomain": {
            "type": "object",
            "properties": {
              "hostname": {
                "type": "string",
                "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "verifying",
                  "active",
                  "failed",
                  "removing"
                ]
              }
            },
            "required": [
              "hostname",
              "status"
            ],
            "additionalProperties": false
          },
          "runtimeStatus": {
            "type": "string",
            "enum": [
              "reconciling",
              "reconciled",
              "reconcile_failed"
            ]
          },
          "reconciliationError": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "sourceShareId": {
            "type": "string"
          },
          "sourceShareMode": {
            "type": "string",
            "enum": [
              "read",
              "write"
            ]
          },
          "sourceAppId": {
            "type": "string"
          },
          "listingSubscriptionId": {
            "type": "string"
          },
          "disabledAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "disabledByUserId": {
            "type": "string"
          },
          "createdByUserId": {
            "type": "string"
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "controls": {
            "type": "object",
            "properties": {
              "manageDomain": {
                "type": "boolean"
              },
              "updateRuntime": {
                "type": "boolean"
              },
              "restart": {
                "type": "boolean"
              },
              "makePublic": {
                "type": "boolean"
              },
              "makePrivate": {
                "type": "boolean"
              },
              "delete": {
                "type": "boolean"
              }
            },
            "required": [
              "manageDomain",
              "updateRuntime",
              "restart",
              "makePublic",
              "makePrivate",
              "delete"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "id",
          "workspaceId",
          "anchorId",
          "anchorPath",
          "anchorState",
          "command",
          "apiScopes",
          "port",
          "slug",
          "visibility",
          "url",
          "embedUrl",
          "runtimeStatus",
          "createdByUserId",
          "createdAt",
          "updatedAt",
          "controls"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "capabilities": {
          "type": "object",
          "properties": {
            "register": {
              "type": "boolean"
            }
          },
          "required": [
            "register"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "capabilities"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}
Errors
Opaque collection cursor is malformed or bound to another walk (400)
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "const": "invalid_cursor"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "description": "Opaque collection cursor is malformed or bound to another walk (400)"
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/apps/{appSlug}/credentials

Export an independent app credential once with an explicit expiration

CLI
bento app credential create --app-slug example --body-file request.json
Scope
ws:{workspaceSlug}:apps
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "expiration": {
      "anyOf": [
        {
          "type": "string",
          "const": "never"
        },
        {
          "type": "object",
          "properties": {
            "seconds": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740
            }
          },
          "required": [
            "seconds"
          ],
          "additionalProperties": false
        }
      ]
    }
  },
  "required": [
    "expiration"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "credentialId": {
      "type": "string",
      "minLength": 1
    },
    "prefix": {
      "type": "string",
      "pattern": "^duet_sk_.*"
    },
    "createdAt": {
      "type": "number",
      "minimum": 0
    },
    "expiresAt": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "key": {
      "type": "string",
      "pattern": "^duet_sk_.*"
    },
    "apiUrl": {
      "type": "string",
      "format": "uri"
    },
    "gatewayBaseUrl": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "credentialId",
    "prefix",
    "createdAt",
    "expiresAt",
    "key",
    "apiUrl",
    "gatewayBaseUrl"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "unauthorized",
            "forbidden",
            "invalid_request",
            "not_found",
            "internal_error",
            "app_disabled",
            "app_has_no_api_scopes",
            "app_credentials_not_configured"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "insufficient_scope"
        },
        "scope": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "scope"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "app_credential_limit"
        },
        "limit": {
          "type": "number",
          "const": 5
        }
      },
      "required": [
        "error",
        "limit"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/apps/{appSlug}/credentials

Inspect the bounded live exported credential inventory without secrets

CLI
bento app credential list --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "credentialId": {
            "type": "string",
            "minLength": 1
          },
          "prefix": {
            "type": "string",
            "pattern": "^duet_sk_.*"
          },
          "createdAt": {
            "type": "number",
            "minimum": 0
          },
          "expiresAt": {
            "anyOf": [
              {
                "type": "integer",
                "exclusiveMinimum": 0,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "credentialId",
          "prefix",
          "createdAt",
          "expiresAt"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "type": "null"
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "unauthorized",
            "forbidden",
            "invalid_request",
            "not_found",
            "internal_error",
            "app_disabled",
            "app_has_no_api_scopes",
            "app_credentials_not_configured"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "insufficient_scope"
        },
        "scope": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "scope"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "app_credential_limit"
        },
        "limit": {
          "type": "number",
          "const": 5
        }
      },
      "required": [
        "error",
        "limit"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
DELETE/v1/workspaces/{workspaceSlug}/apps/{appSlug}/credentials/{credentialId}

Revoke one exported app credential without replacing managed credentials

CLI
bento app credential revoke --app-slug example --credential-id example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "unauthorized",
            "forbidden",
            "invalid_request",
            "not_found",
            "internal_error",
            "app_disabled",
            "app_has_no_api_scopes",
            "app_credentials_not_configured"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "insufficient_scope"
        },
        "scope": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "scope"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "app_credential_limit"
        },
        "limit": {
          "type": "number",
          "const": 5
        }
      },
      "required": [
        "error",
        "limit"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Declared idempotent
GET/v1/workspaces/{workspaceSlug}/apps/{appSlug}/launch

Open an app through a short-lived access grant, optionally returning to its validated host and path

CLI
bento app launch --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "host": {
      "type": "string"
    },
    "path": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
Response
No structured response body
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/apps

Register a workspace folder as an app runtime with optional display metadata

CLI
bento app create --body-file request.json
Scope
ws:{workspaceSlug}:apps
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "minLength": 1
    },
    "command": {
      "type": "string"
    },
    "apiScopes": {
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "files:read",
          "files:write",
          "memory",
          "sessions",
          "agents",
          "services",
          "integrations",
          "apps",
          "share",
          "publish",
          "members"
        ]
      }
    },
    "installCommand": {
      "type": "string"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535
    },
    "slug": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "icon": {
      "type": "string"
    }
  },
  "required": [
    "path",
    "command",
    "apiScopes",
    "slug"
  ]
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "workspaceId": {
          "type": "string"
        },
        "anchorId": {
          "type": "string"
        },
        "anchorPath": {
          "type": "string"
        },
        "anchorState": {
          "type": "string",
          "enum": [
            "active",
            "broken",
            "orphaned"
          ]
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "apiScopes": {
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files:read",
              "files:write",
              "memory",
              "sessions",
              "agents",
              "services",
              "integrations",
              "apps",
              "share",
              "publish",
              "members"
            ]
          }
        },
        "installCommand": {
          "type": "string",
          "minLength": 1
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "folder",
            "public"
          ]
        },
        "url": {
          "type": "string"
        },
        "embedUrl": {
          "type": "string"
        },
        "customDomain": {
          "type": "object",
          "properties": {
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            }
          },
          "required": [
            "hostname",
            "status"
          ],
          "additionalProperties": false
        },
        "runtimeStatus": {
          "type": "string",
          "enum": [
            "reconciling",
            "reconciled",
            "reconcile_failed"
          ]
        },
        "reconciliationError": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "sourceShareId": {
          "type": "string"
        },
        "sourceShareMode": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ]
        },
        "sourceAppId": {
          "type": "string"
        },
        "listingSubscriptionId": {
          "type": "string"
        },
        "disabledAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disabledByUserId": {
          "type": "string"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "controls": {
          "type": "object",
          "properties": {
            "manageDomain": {
              "type": "boolean"
            },
            "updateRuntime": {
              "type": "boolean"
            },
            "restart": {
              "type": "boolean"
            },
            "makePublic": {
              "type": "boolean"
            },
            "makePrivate": {
              "type": "boolean"
            },
            "delete": {
              "type": "boolean"
            }
          },
          "required": [
            "manageDomain",
            "updateRuntime",
            "restart",
            "makePublic",
            "makePrivate",
            "delete"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspaceId",
        "anchorId",
        "anchorPath",
        "anchorState",
        "command",
        "apiScopes",
        "port",
        "slug",
        "visibility",
        "url",
        "embedUrl",
        "runtimeStatus",
        "createdByUserId",
        "createdAt",
        "updatedAt",
        "controls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/apps/{appSlug}

Get one registered app by slug

CLI
bento app get --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "workspaceId": {
          "type": "string"
        },
        "anchorId": {
          "type": "string"
        },
        "anchorPath": {
          "type": "string"
        },
        "anchorState": {
          "type": "string",
          "enum": [
            "active",
            "broken",
            "orphaned"
          ]
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "apiScopes": {
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files:read",
              "files:write",
              "memory",
              "sessions",
              "agents",
              "services",
              "integrations",
              "apps",
              "share",
              "publish",
              "members"
            ]
          }
        },
        "installCommand": {
          "type": "string",
          "minLength": 1
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "folder",
            "public"
          ]
        },
        "url": {
          "type": "string"
        },
        "embedUrl": {
          "type": "string"
        },
        "customDomain": {
          "type": "object",
          "properties": {
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            }
          },
          "required": [
            "hostname",
            "status"
          ],
          "additionalProperties": false
        },
        "runtimeStatus": {
          "type": "string",
          "enum": [
            "reconciling",
            "reconciled",
            "reconcile_failed"
          ]
        },
        "reconciliationError": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "sourceShareId": {
          "type": "string"
        },
        "sourceShareMode": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ]
        },
        "sourceAppId": {
          "type": "string"
        },
        "listingSubscriptionId": {
          "type": "string"
        },
        "disabledAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disabledByUserId": {
          "type": "string"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "controls": {
          "type": "object",
          "properties": {
            "manageDomain": {
              "type": "boolean"
            },
            "updateRuntime": {
              "type": "boolean"
            },
            "restart": {
              "type": "boolean"
            },
            "makePublic": {
              "type": "boolean"
            },
            "makePrivate": {
              "type": "boolean"
            },
            "delete": {
              "type": "boolean"
            }
          },
          "required": [
            "manageDomain",
            "updateRuntime",
            "restart",
            "makePublic",
            "makePrivate",
            "delete"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspaceId",
        "anchorId",
        "anchorPath",
        "anchorState",
        "command",
        "apiScopes",
        "port",
        "slug",
        "visibility",
        "url",
        "embedUrl",
        "runtimeStatus",
        "createdByUserId",
        "createdAt",
        "updatedAt",
        "controls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
PATCH/v1/workspaces/{workspaceSlug}/apps/{appSlug}

Update app disabled state, visibility, display metadata, or runtime settings

CLI
bento app update --app-slug example --port 3000
Scope
ws:{workspaceSlug}:apps
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "slug": {
      "not": {}
    },
    "command": {
      "type": "string"
    },
    "apiScopes": {
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "files:read",
          "files:write",
          "memory",
          "sessions",
          "agents",
          "services",
          "integrations",
          "apps",
          "share",
          "publish",
          "members"
        ]
      }
    },
    "installCommand": {
      "type": "string"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "icon": {
      "type": "string"
    },
    "disabled": {
      "type": "boolean"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "folder",
        "public"
      ]
    }
  }
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "workspaceId": {
          "type": "string"
        },
        "anchorId": {
          "type": "string"
        },
        "anchorPath": {
          "type": "string"
        },
        "anchorState": {
          "type": "string",
          "enum": [
            "active",
            "broken",
            "orphaned"
          ]
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "apiScopes": {
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files:read",
              "files:write",
              "memory",
              "sessions",
              "agents",
              "services",
              "integrations",
              "apps",
              "share",
              "publish",
              "members"
            ]
          }
        },
        "installCommand": {
          "type": "string",
          "minLength": 1
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "folder",
            "public"
          ]
        },
        "url": {
          "type": "string"
        },
        "embedUrl": {
          "type": "string"
        },
        "customDomain": {
          "type": "object",
          "properties": {
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            }
          },
          "required": [
            "hostname",
            "status"
          ],
          "additionalProperties": false
        },
        "runtimeStatus": {
          "type": "string",
          "enum": [
            "reconciling",
            "reconciled",
            "reconcile_failed"
          ]
        },
        "reconciliationError": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "sourceShareId": {
          "type": "string"
        },
        "sourceShareMode": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ]
        },
        "sourceAppId": {
          "type": "string"
        },
        "listingSubscriptionId": {
          "type": "string"
        },
        "disabledAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disabledByUserId": {
          "type": "string"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "controls": {
          "type": "object",
          "properties": {
            "manageDomain": {
              "type": "boolean"
            },
            "updateRuntime": {
              "type": "boolean"
            },
            "restart": {
              "type": "boolean"
            },
            "makePublic": {
              "type": "boolean"
            },
            "makePrivate": {
              "type": "boolean"
            },
            "delete": {
              "type": "boolean"
            }
          },
          "required": [
            "manageDomain",
            "updateRuntime",
            "restart",
            "makePublic",
            "makePrivate",
            "delete"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspaceId",
        "anchorId",
        "anchorPath",
        "anchorState",
        "command",
        "apiScopes",
        "port",
        "slug",
        "visibility",
        "url",
        "embedUrl",
        "runtimeStatus",
        "createdByUserId",
        "createdAt",
        "updatedAt",
        "controls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/apps/{appSlug}/restart

Stop and start an app with its current runtime, answering once it is ready or failed to come back

CLI
bento app restart --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "workspaceId": {
          "type": "string"
        },
        "anchorId": {
          "type": "string"
        },
        "anchorPath": {
          "type": "string"
        },
        "anchorState": {
          "type": "string",
          "enum": [
            "active",
            "broken",
            "orphaned"
          ]
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "apiScopes": {
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files:read",
              "files:write",
              "memory",
              "sessions",
              "agents",
              "services",
              "integrations",
              "apps",
              "share",
              "publish",
              "members"
            ]
          }
        },
        "installCommand": {
          "type": "string",
          "minLength": 1
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "folder",
            "public"
          ]
        },
        "url": {
          "type": "string"
        },
        "embedUrl": {
          "type": "string"
        },
        "customDomain": {
          "type": "object",
          "properties": {
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            }
          },
          "required": [
            "hostname",
            "status"
          ],
          "additionalProperties": false
        },
        "runtimeStatus": {
          "type": "string",
          "enum": [
            "reconciling",
            "reconciled",
            "reconcile_failed"
          ]
        },
        "reconciliationError": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "sourceShareId": {
          "type": "string"
        },
        "sourceShareMode": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ]
        },
        "sourceAppId": {
          "type": "string"
        },
        "listingSubscriptionId": {
          "type": "string"
        },
        "disabledAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disabledByUserId": {
          "type": "string"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "controls": {
          "type": "object",
          "properties": {
            "manageDomain": {
              "type": "boolean"
            },
            "updateRuntime": {
              "type": "boolean"
            },
            "restart": {
              "type": "boolean"
            },
            "makePublic": {
              "type": "boolean"
            },
            "makePrivate": {
              "type": "boolean"
            },
            "delete": {
              "type": "boolean"
            }
          },
          "required": [
            "manageDomain",
            "updateRuntime",
            "restart",
            "makePublic",
            "makePrivate",
            "delete"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspaceId",
        "anchorId",
        "anchorPath",
        "anchorState",
        "command",
        "apiScopes",
        "port",
        "slug",
        "visibility",
        "url",
        "embedUrl",
        "runtimeStatus",
        "createdByUserId",
        "createdAt",
        "updatedAt",
        "controls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/apps/{appSlug}/reanchor

Repair a broken app anchor by slug after the automatic move rail cannot recover its folder

CLI
bento app reanchor --app-slug example --path notes/plan.md
Scope
ws:{workspaceSlug}:apps
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    }
  },
  "required": [
    "path"
  ]
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "workspaceId": {
          "type": "string"
        },
        "anchorId": {
          "type": "string"
        },
        "anchorPath": {
          "type": "string"
        },
        "anchorState": {
          "type": "string",
          "enum": [
            "active",
            "broken",
            "orphaned"
          ]
        },
        "command": {
          "type": "string",
          "minLength": 1
        },
        "apiScopes": {
          "maxItems": 64,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "files:read",
              "files:write",
              "memory",
              "sessions",
              "agents",
              "services",
              "integrations",
              "apps",
              "share",
              "publish",
              "members"
            ]
          }
        },
        "installCommand": {
          "type": "string",
          "minLength": 1
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        },
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": "string"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "folder",
            "public"
          ]
        },
        "url": {
          "type": "string"
        },
        "embedUrl": {
          "type": "string"
        },
        "customDomain": {
          "type": "object",
          "properties": {
            "hostname": {
              "type": "string",
              "pattern": "^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "verifying",
                "active",
                "failed",
                "removing"
              ]
            }
          },
          "required": [
            "hostname",
            "status"
          ],
          "additionalProperties": false
        },
        "runtimeStatus": {
          "type": "string",
          "enum": [
            "reconciling",
            "reconciled",
            "reconcile_failed"
          ]
        },
        "reconciliationError": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "sourceShareId": {
          "type": "string"
        },
        "sourceShareMode": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ]
        },
        "sourceAppId": {
          "type": "string"
        },
        "listingSubscriptionId": {
          "type": "string"
        },
        "disabledAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "disabledByUserId": {
          "type": "string"
        },
        "createdByUserId": {
          "type": "string"
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "controls": {
          "type": "object",
          "properties": {
            "manageDomain": {
              "type": "boolean"
            },
            "updateRuntime": {
              "type": "boolean"
            },
            "restart": {
              "type": "boolean"
            },
            "makePublic": {
              "type": "boolean"
            },
            "makePrivate": {
              "type": "boolean"
            },
            "delete": {
              "type": "boolean"
            }
          },
          "required": [
            "manageDomain",
            "updateRuntime",
            "restart",
            "makePublic",
            "makePrivate",
            "delete"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspaceId",
        "anchorId",
        "anchorPath",
        "anchorState",
        "command",
        "apiScopes",
        "port",
        "slug",
        "visibility",
        "url",
        "embedUrl",
        "runtimeStatus",
        "createdByUserId",
        "createdAt",
        "updatedAt",
        "controls"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
DELETE/v1/workspaces/{workspaceSlug}/apps/{appSlug}

Stop serving and unregister an app

CLI
bento app delete --app-slug example
Scope
ws:{workspaceSlug}:apps
Request
No JSON request body
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Declared idempotent