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.
{
"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 /v1 /workspaces /{workspaceSlug} /apps /domainsList current app domains in a workspace
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /domainInspect an app domain and its DNS instructions
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /domainAttach one custom hostname without changing app visibility
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /domain /recheckRequest a fresh domain check or retry exhausted removal
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /domainStop serving a custom hostname and schedule provider cleanup
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
/v1 /workspaces /{workspaceSlug} /appsList workspace apps, optionally filtered by exact id, the deepest app containing a cwd, or drive path
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /credentialsExport an independent app credential once with an explicit expiration
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /credentialsInspect the bounded live exported credential inventory without secrets
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /credentials /{credentialId}Revoke one exported app credential without replacing managed credentials
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /launchOpen an app through a short-lived access grant, optionally returning to its validated host and path
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
/v1 /workspaces /{workspaceSlug} /appsRegister a workspace folder as an app runtime with optional display metadata
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug}Get one registered app by slug
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug}Update app disabled state, visibility, display metadata, or runtime settings
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /restartStop and start an app with its current runtime, answering once it is ready or failed to come back
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug} /reanchorRepair a broken app anchor by slug after the automatic move rail cannot recover its folder
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
/v1 /workspaces /{workspaceSlug} /apps /{appSlug}Stop serving and unregister an app
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