Browse documentationFiles

Resource guide

Files are byte streams

Treat file reads and writes as HTTP byte transfers, not JSON wrappers. Preserve content length, ETag, byte-range responses, cancellation, and error status through your client. Read content types are inferred from known file extensions and otherwise remain application/octet-stream; the bytes are always authoritative.

Address paths deliberately

Normalize workspace-relative paths with the contract path grammar. Encode dynamic URL segments, reject traversal, and do not infer whether a path is a file or folder from its extension.

const encodedPath = segments.map(encodeURIComponent).join('/')
const rangeHeaders = { range: 'bytes=0-65535' }

The snippet illustrates safe path encoding and a bounded byte range; use the endpoint reference for the final public route template before shipping a client.

Page directory entries

Add ?list=1 to a directory path and walk the universal collection envelope. Listings are ordered by name and path, limit defaults to 50 and caps at 100, and nextCursor: null ends the walk. The cursor is opaque and bound to both the workspace and directory; pass it back unchanged with the same path. Directory mutations can change later pages, so key consumers by path and make repeated processing harmless. A malformed or rebound listing cursor returns 400 {"error":"invalid_cursor"}; other invalid listing query fields return invalid_request.

Listings have no entry ceiling: a directory of any size pages out completely. The 1,000-entry bound applies to operations that reproduce a folder — archive downloads, recursive copies, and publishes — not to reading its listing.

Response
{
  "items": [
    {
      "name": "notes.md",
      "path": "notes.md",
      "type": "file",
      "size": 128,
      "mtime": "2026-08-26T12:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Hold the workspace drive

A file browser or indexer that revisits many folders can hold the drive's lightweight entries locally, much as a session client holds the workspace directory. The snapshot and stream carry names, metadata and file version tokens; download file contents only when needed. Both require files:read for the workspace. Direct upload or download grants cannot read this tree.

  1. Snapshot. Read GET /v1/workspaces/{workspaceSlug}/drive and pass each nextCursor back unchanged as cursor until done: true. Save the first chunk's generation and highWaterSeq; every chunk belongs to that pair. Only the first chunk carries total. Decode rows with decodeDriveTreeRows from @repo/contract, and publish the copy only after every chunk arrives.
  2. Follow. Open the events endpoint with that generation and Last-Event-ID set to highWaterSeq (or use after when no header is available). The header wins. Apply upsert rows and removed paths, keeping the higher row seq, then commit the frame's id as the resume position. A cursor frame advances that position without requiring a row change and may carry updated index readiness. Reconnect using the same generation and the last committed position; SSE and resume explains connection handling.
  3. Reset. A reset ends the stream when the generation changed or replay is no longer available or economical. Take a fresh snapshot before following again. A stream_error with unavailable calls for reconnecting; authorization refusals end access.

Entries marked contents: "live" are boundaries: their children are omitted from the copy, so list them from the VM. While index.complete is false, also revalidate open folders with ordinary listings. A rebuild from empty answers 503 index_building; keep the previous copy and list folders from the VM while retrying. A 404 from the tree endpoint means this VM does not serve it yet: use ordinary folder listings. It does not mean the drive is empty.

CLI and MCP expose snapshot chunks; use curl for the live stream. Pass a returned nextCursor to the next invocation.

bento drive get --workspace "$WORKSPACE"
bento drive get --workspace "$WORKSPACE" --cursor "$NEXT_CURSOR"

Call the MCP tool drive_get with {"workspaceSlug":"acme"}, then with {"workspaceSlug":"acme","query":{"cursor":"<nextCursor>"}} for each continuation.

curl -sS -N -H "Authorization: Bearer $BENTO_API_KEY" \
  -H "Last-Event-ID: $HIGH_WATER_SEQ" \
  "$BENTO_API_URL/v1/workspaces/$WORKSPACE/drive/events?generation=$GENERATION"

Distinguish drive usage from folder size

The file usage endpoint reports the filesystem's used bytes and total capacity. At the Drive root, this includes all disk usage, including system data, and reads allocation counters without walking files. For a subfolder, the response also includes recursive logical bytes and entry counts under folder; hidden files count, and symlinks count as links without following their targets. Request folder details on demand, since their cost grows with the subtree. A failed measurement is an error, not zero usage.

Ask for a path that may not exist

A missing path answers 404 — the drive's ordinary way of saying a folder is gone rather than empty. When your client is asking after a file that is allowed not to exist (an agent's agent.json, a skills folder that was never created), add ?optional=1 to the read, stat, or listing and a missing path answers an empty 204 instead. Everything else — a present file, a symlink conflict, a workspace that is missing, provisioning, or paused — answers exactly as it would without the flag.

Cache reads and guard saves

A matching If-None-Match returns an empty 304 with the current ETag and last-modified date. If-Modified-Since also returns 304 when unchanged, unless If-None-Match is present: the entity-tag condition takes precedence. File dates compare at HTTP's one-second precision; invalid date values supply no condition. A conditional response is evaluated before a byte range.

Editors should retain the ETag returned by a read and send it in If-Match when saving. A 412 means the file changed after it was opened; reload it or require the user to deliberately replace the newer version.

To create without replacing, send If-None-Match: *. An existing file or a race with another creator returns 412 precondition_failed; treat that as a collision, choose the next candidate path, and retry the PUT with the same create-only header.

If-Unmodified-Since can guard a save by date when no If-Match is supplied. Both guards are checked again after the upload arrives, so a newer version written during transfer can refuse the save. Prefer the exact ETag when edits can happen within the same second.

Separate read and write grants

Tools that index or preview content need files:read. Editors and uploaders need files:write. Request both only when the workflow genuinely performs both roles.

Mint a grant for direct uploads

Writing a file through this API carries its bytes across it, which is right for a document and impossible for something multi-gigabyte. For anything a person picked off disk, mint a short-lived grant with a credential that has files:write and send the bytes to the workspace VM instead. pathPrefix is the drive-relative folder the grant covers; an empty string is the drive root.

Request body
{
  "pathPrefix": "agents/research/uploads"
}

The response's vmBaseUrl and uploadPath identify the VM's direct files endpoint, while uploadToken is the bearer for that upload. Append one URL-encoded filename to uploadPath and send the bytes with PUT directly to vmBaseUrl; do not send the workspace API key to the VM. expiresAt is the latest time a new upload may begin, not a deadline for finishing one — a transfer already under way is not cut off when it passes.

The grant covers that one folder tree and is write-only. Clients choose a visible filename before uploading and handle same-name collisions themselves.

A single file has a published size limit, and it is enforced on the Content-Length the request declares — so an upload that cannot be accepted is refused before its bytes are sent, with a 413 naming the limit in limitBytes. A request that declares no length is not measured against it and is bounded only by the workspace's free space.

Listings and stat report a symbolic link as its own entry: type: "symlink" with a target string holding the link text verbatim. A link is listed whether or not its target exists — a dangling link is a legal, visible entry, because workspaces mirror real development trees where links routinely point at paths that come and go. Listings can therefore now contain a third type value; clients that switch on entry types should treat unrecognized values as opaque entries rather than failing the listing. For a link entry, size is the byte length of the target text and mtime is the link's own modification time.

Addressing a link never silently follows it — only a content read does. A GET on a link path serves the target's bytes when the target resolves inside the workspace, and a successful read through a link is byte-for-byte a read of the target: same ETag, length, range, and conditional behavior. When the target dangles or escapes the workspace, the read fails with 409 symlink_unresolvable carrying the link's target — never a silent fallback. Writes are stricter: a PUT, mkdir, or directory listing addressed at a link path fails with 409 path_is_symlink rather than acting through the link. Directory links in intermediate path segments resolve normally while they stay inside the workspace; link discipline applies to the path's final component.

Make structural changes explicit

Use the JSON action endpoint for directories, moves, copies, recursive deletion, and link creation. Collision overwrites and recursion are opt-in. Recursive work is bounded by the gateway before mutation, so clients should surface a limit error instead of retrying an unsafe operation with broader local semantics.

Create or retarget a link:

Request body
{
  "operation": "symlink",
  "path": "current",
  "target": "releases/v2"
}

target is stored verbatim — relative targets are the portable choice, and targets outside the workspace are legal to store but never readable through the link. symlink replaces an existing symlink at path (that is how you retarget) and conflicts with any other existing entry type; replacing a file with a link — or a link with a file — is always an explicit delete followed by a create. This mirrors how PUT overwrites files in place: same-type replacement is direct, cross-type replacement is deliberate.

Links participate in structural operations as ordinary entries. A copy reproduces a link as a link with the same verbatim target — it never follows one — so a relative target is reinterpreted at the destination and may dangle there; the same applies to moves. Deleting a link removes the link itself: a recursive delete of a directory containing a link-to-directory removes the link entry, never the target's tree.

Work with recordings

When you record with the Bento menu bar app, each take uploads to recordings/<recording-id>/ at the drive root, which file sync and Google Drive backup leave out. The workspace adds the take to its recording library, transcribes it, and serves its pictures, audio and timed marks.

One endpoint reads and edits the library. Its body names a recording operation and that operation's parameters, plus an id you choose to match the answer to the request. Reading needs files:read; changing the library needs files:write.

Request body
{
  "id": "4f0c6a2e-0d4c-4b8e-9a1b-2f6f3c1d9e7a",
  "operation": "recording.get",
  "params": { "recordingId": "8b1e2f3a-5c6d-4e7f-8a9b-0c1d2e3f4a5b" }
}

The response echoes the id with either ok: true and its data, or ok: false and an error. A result larger than the inline budget arrives as a lease; read it with artifact.read. Long work such as transcription or export returns a job to observe rather than blocking the request. From a terminal, bento recording operation create sends the same envelope and can wait for jobs and save delivered pictures.

Files

14 operations
GET/v1/workspaces/{workspaceSlug}/drive

Read one chunk of the workspace drive snapshot; drive grants are refused

CLI
bento drive get
Scope
ws:{workspaceSlug}:files:read
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
    }
  },
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "highWaterSeq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "done": {
      "type": "boolean"
    },
    "generation": {
      "type": "string",
      "minLength": 1
    },
    "index": {
      "type": "object",
      "properties": {
        "names": {
          "type": "string",
          "enum": [
            "ready",
            "building"
          ]
        },
        "complete": {
          "type": "boolean"
        }
      },
      "required": [
        "names",
        "complete"
      ],
      "additionalProperties": false
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "rows": {
      "type": "object",
      "properties": {
        "pathPrefix": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "pathSuffix": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "type": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2
          }
        },
        "size": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "mtime": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "string",
                "pattern": "^-?(0|[1-9][0-9]*)$"
              }
            ]
          }
        },
        "ctime": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "string",
                    "pattern": "^-?(0|[1-9][0-9]*)$"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "ino": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "string",
                    "pattern": "^-?(0|[1-9][0-9]*)$"
                  }
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "seq": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "other": {
          "type": "object",
          "properties": {
            "dev": {
              "type": "string",
              "pattern": "^(?:0|[1-9a-f][0-9a-f]*)?$"
            },
            "etag": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "mtime": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "name": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string",
                    "minLength": 1
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "target": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "live": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 1
              }
            }
          },
          "required": [
            "dev",
            "etag",
            "mtime",
            "name",
            "target",
            "live"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "pathPrefix",
        "pathSuffix",
        "type",
        "size",
        "mtime",
        "ctime",
        "ino",
        "seq",
        "other"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "highWaterSeq",
    "nextCursor",
    "done",
    "generation",
    "index",
    "rows"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "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)"
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "forbidden"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "index_building"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false,
      "description": "The index is rebuilding (503)"
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/drive/events

Stream workspace drive changes after a sequence; drive grants are refused

Scope
ws:{workspaceSlug}:files:read
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "after": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "generation": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "generation"
  ],
  "additionalProperties": false
}
Headers
  • Last-Event-ID — Resume after this drive sequence; wins over `after`.
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "upsert"
            },
            "seq": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "rows": {
              "type": "object",
              "properties": {
                "pathPrefix": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "pathSuffix": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "type": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 2
                  }
                },
                "size": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "mtime": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "string",
                        "pattern": "^-?(0|[1-9][0-9]*)$"
                      }
                    ]
                  }
                },
                "ctime": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "anyOf": [
                          {
                            "type": "integer",
                            "minimum": -9007199254740991,
                            "maximum": 9007199254740991
                          },
                          {
                            "type": "string",
                            "pattern": "^-?(0|[1-9][0-9]*)$"
                          }
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "ino": {
                  "type": "array",
                  "items": {
                    "anyOf": [
                      {
                        "anyOf": [
                          {
                            "type": "integer",
                            "minimum": -9007199254740991,
                            "maximum": 9007199254740991
                          },
                          {
                            "type": "string",
                            "pattern": "^-?(0|[1-9][0-9]*)$"
                          }
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "seq": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  }
                },
                "other": {
                  "type": "object",
                  "properties": {
                    "dev": {
                      "type": "string",
                      "pattern": "^(?:0|[1-9a-f][0-9a-f]*)?$"
                    },
                    "etag": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "mtime": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string",
                            "format": "date-time",
                            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "name": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string",
                            "minLength": 1
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "target": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "live": {
                      "type": "array",
                      "items": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 1
                      }
                    }
                  },
                  "required": [
                    "dev",
                    "etag",
                    "mtime",
                    "name",
                    "target",
                    "live"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "pathPrefix",
                "pathSuffix",
                "type",
                "size",
                "mtime",
                "ctime",
                "ino",
                "seq",
                "other"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "kind",
            "seq",
            "rows"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "removed"
            },
            "seq": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "paths": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "kind",
            "seq",
            "paths"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "cursor"
            },
            "seq": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "index": {
              "type": "object",
              "properties": {
                "names": {
                  "type": "string",
                  "enum": [
                    "ready",
                    "building"
                  ]
                },
                "complete": {
                  "type": "boolean"
                }
              },
              "required": [
                "names",
                "complete"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "kind",
            "seq"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "reset"
            },
            "seq": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "kind",
            "seq"
          ],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "forbidden",
            "unavailable"
          ]
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "forbidden"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "invalid_last_event_id"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false,
      "description": "Invalid drive sequence (400)"
    }
  ]
}
Delivery
Server-sent event stream
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/files/{path}?list=1

List one workspace directory with file stats

CLI
bento file list --path notes/plan.md
Scope
ws:{workspaceSlug}:files:read
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
    },
    "list": {
      "type": "string",
      "const": "1"
    },
    "optional": {
      "description": "Answer a missing path with an empty 204 instead of 404.",
      "type": "string",
      "const": "1"
    }
  },
  "required": [
    "list"
  ],
  "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": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "path": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "file",
              "directory",
              "symlink"
            ]
          },
          "size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "mtime": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
          },
          "target": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "path",
          "type",
          "size",
          "mtime"
        ],
        "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": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "const": "symlink_unresolvable"
            },
            "target": {
              "type": "string"
            }
          },
          "required": [
            "error",
            "target"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "const": "path_is_symlink"
            }
          },
          "required": [
            "error"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Symlink conflict (409)"
    },
    {
      "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}/files/{path}?search

Search a folder and everything below it by name, path and document text. Results come from an index on the workspace VM, so they can lag the drive; meta.index says how far behind it is. Paths with any segment starting with "." and derived folders such as node_modules are never indexed, so no result does not mean no file. Terms of two letters or more match by word prefix; a one-letter term matches that whole word only. "voice" does not find "invoice". Text is read only from pdf, docx, pptx, xlsx, md, txt, csv and html files.

CLI
bento file search --path / --search "q3 board" --ext pdf --ext pptx
Scope
ws:{workspaceSlug}:files:read
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
    },
    "search": {
      "type": "string",
      "maxLength": 512,
      "description": "Words to match by prefix. Empty lists the newest files first."
    },
    "ext": {
      "description": "File extensions to keep, lowercase and without the dot (pdf, docx). Excludes folders.",
      "maxItems": 32,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9]{1,16}$"
      }
    },
    "modifiedAfter": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "modifiedBefore": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "sort": {
      "description": "Defaults to relevance for a query and modified for an empty one.",
      "type": "string",
      "enum": [
        "relevance",
        "modified",
        "name",
        "size"
      ]
    }
  },
  "required": [
    "search"
  ],
  "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": {
          "entry": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1
              },
              "path": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "file",
                  "directory",
                  "symlink"
                ]
              },
              "size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "mtime": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              "target": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "path",
              "type",
              "size",
              "mtime"
            ],
            "additionalProperties": false
          },
          "matchedIn": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "name",
                "path",
                "contents"
              ]
            }
          },
          "snippet": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string"
              },
              "highlights": {
                "type": "array",
                "items": {
                  "type": "array",
                  "prefixItems": [
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  ]
                }
              }
            },
            "required": [
              "text",
              "highlights"
            ],
            "additionalProperties": false
          },
          "contentStatus": {
            "type": "string",
            "enum": [
              "indexed",
              "pending",
              "failed",
              "names-only"
            ]
          },
          "contentFailure": {
            "type": "string",
            "enum": [
              "timeout",
              "memory",
              "corrupt",
              "encrypted",
              "decompressed_too_large",
              "io"
            ]
          }
        },
        "required": [
          "entry",
          "matchedIn",
          "contentStatus"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "index": {
          "type": "object",
          "properties": {
            "names": {
              "type": "string",
              "enum": [
                "ready",
                "building"
              ]
            },
            "contents": {
              "type": "object",
              "properties": {
                "indexed": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "pending": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "failed": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "paused": {
                  "type": "string",
                  "const": "storage_full"
                }
              },
              "required": [
                "indexed",
                "pending",
                "failed"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "names",
            "contents"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "index"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "anyOf": [
        {
          "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)"
        },
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "enum": [
                "invalid_request",
                "not_found",
                "not_directory",
                "path_is_symlink"
              ]
            }
          },
          "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}/files/{path}?usage=1

Read drive usage and capacity, with recursive size for a subfolder

CLI
bento file usage --path reports
Scope
ws:{workspaceSlug}:files:read
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "usage": {
      "type": "string",
      "const": "1"
    }
  },
  "required": [
    "usage"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "usedBytes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "capacityBytes": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "folder": {
      "type": "object",
      "properties": {
        "bytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "folders": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "documents": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "bytes",
        "folders",
        "documents"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "usedBytes",
    "capacityBytes"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "path_is_symlink",
        "not_directory"
      ]
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/files/{path}?stat=1

Read file or directory metadata without transferring file bytes

CLI
bento file stat --path notes/plan.md
Scope
ws:{workspaceSlug}:files:read
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "optional": {
      "description": "Answer a missing path with an empty 204 instead of 404.",
      "type": "string",
      "const": "1"
    }
  }
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "entry": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "path": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "file",
            "directory",
            "symlink"
          ]
        },
        "size": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "mtime": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "target": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "path",
        "type",
        "size",
        "mtime"
      ],
      "additionalProperties": false
    },
    "etag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "entry",
    "etag"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/files/{path}?preview

Render a model file as a turntable or still preview image

CLI
bento file preview --path models/chair.glb --preview still
Scope
ws:{workspaceSlug}:files:read
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "preview": {
      "type": "string",
      "enum": [
        "turntable",
        "still"
      ]
    }
  },
  "required": [
    "preview"
  ],
  "additionalProperties": false
}
Response
Raw byte stream
Errors
Preview refused (409, 422 or 503)
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "preview_unsupported",
        "preview_installing",
        "preview_failed"
      ]
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false,
  "description": "Preview refused (409, 422 or 503)"
}
Delivery
Standard response
Retry
Not declared idempotent
GET/v1/workspaces/{workspaceSlug}/files/{path}

Stream one file with ETag and single-range support

CLI
bento file get --path notes/plan.md
Scope
ws:{workspaceSlug}:files:read
Request
No JSON request body
Query
Query parameters JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "optional": {
      "description": "Answer a missing path with an empty 204 instead of 404.",
      "type": "string",
      "const": "1"
    }
  }
}
Headers
  • Range — Request one byte range.
  • If-None-Match — Return 304 when the current ETag matches.
  • If-Modified-Since — Return 304 when the file is unchanged.
Response
Raw byte stream
Errors
Symlink conflict (409)
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "symlink_unresolvable"
        },
        "target": {
          "type": "string"
        }
      },
      "required": [
        "error",
        "target"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "path_is_symlink"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ],
  "description": "Symlink conflict (409)"
}
Delivery
Standard response
Retry
Not declared idempotent
PUT/v1/workspaces/{workspaceSlug}/files/{path}

Atomically write one file, optionally guarded by If-Match

CLI
bento file update --path notes/plan.md --body-file request.json
Scope
ws:{workspaceSlug}:files:write
Request
Raw byte stream
Headers
  • If-Match — Write only when the current ETag matches.
  • If-None-Match — Use `*` to create only when no file exists; an existing file or race returns 412.
  • If-Unmodified-Since — Write only when the file is unchanged.
  • Content-Type — Preserve the uploaded media type.
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "etag": {
      "type": "string"
    },
    "size": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "ok",
    "etag",
    "size"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "anyOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "const": "symlink_unresolvable"
                },
                "target": {
                  "type": "string"
                }
              },
              "required": [
                "error",
                "target"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "const": "path_is_symlink"
                }
              },
              "required": [
                "error"
              ],
              "additionalProperties": false
            }
          ],
          "description": "Symlink conflict (409)"
        },
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "const": "storage_full"
            }
          },
          "required": [
            "error"
          ],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "file_too_large"
        },
        "limitBytes": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "error",
        "limitBytes"
      ],
      "additionalProperties": false,
      "description": "File larger than the Drive accepts (413)"
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "precondition_failed"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
DELETE/v1/workspaces/{workspaceSlug}/files/{path}

Delete one file or empty directory

CLI
bento file delete --path notes/plan.md
Scope
ws:{workspaceSlug}:files:write
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
POST/v1/workspaces/{workspaceSlug}/files/actions

Create a directory or symlink, move, copy, or bounded-recursively delete

CLI
bento file action create --body-file request.json
Scope
ws:{workspaceSlug}:files:write
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "const": "mkdir"
        },
        "path": {
          "type": "string"
        },
        "recursive": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": [
        "operation",
        "path"
      ]
    },
    {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "const": "move"
        },
        "source": {
          "type": "string"
        },
        "destination": {
          "type": "string"
        },
        "overwrite": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": [
        "operation",
        "source",
        "destination"
      ]
    },
    {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "const": "copy"
        },
        "source": {
          "type": "string"
        },
        "destination": {
          "type": "string"
        },
        "recursive": {
          "default": false,
          "type": "boolean"
        },
        "overwrite": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": [
        "operation",
        "source",
        "destination"
      ]
    },
    {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "const": "delete"
        },
        "path": {
          "type": "string"
        },
        "recursive": {
          "default": false,
          "type": "boolean"
        }
      },
      "required": [
        "operation",
        "path"
      ]
    },
    {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string",
          "const": "symlink"
        },
        "path": {
          "type": "string"
        },
        "target": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        }
      },
      "required": [
        "operation",
        "path",
        "target"
      ]
    }
  ]
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "affectedEntries": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}
Errors
Error body JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "const": "symlink_unresolvable"
            },
            "target": {
              "type": "string"
            }
          },
          "required": [
            "error",
            "target"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "error": {
              "type": "string",
              "const": "path_is_symlink"
            }
          },
          "required": [
            "error"
          ],
          "additionalProperties": false
        }
      ],
      "description": "Symlink conflict (409)"
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "const": "storage_full"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/file-downloads

Create a short-lived, headerless reference to one workspace file

CLI
bento file-download create --path notes/plan.md
Scope
ws:{workspaceSlug}:files:read
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "path": {
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "uri": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "mimeType": {
      "type": "string",
      "minLength": 1
    },
    "size": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "uri",
    "name",
    "mimeType",
    "size"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/file-uploads

Create a short-lived direct upload session for one Drive path prefix

CLI
bento file-upload create --path-prefix example
Scope
ws:{workspaceSlug}:files:write
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pathPrefix": {
      "type": "string"
    }
  },
  "required": [
    "pathPrefix"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vmBaseUrl": {
      "type": "string",
      "format": "uri"
    },
    "uploadPath": {
      "type": "string",
      "minLength": 1
    },
    "uploadToken": {
      "type": "string",
      "minLength": 1
    },
    "expiresAt": {
      "type": "number"
    }
  },
  "required": [
    "vmBaseUrl",
    "uploadPath",
    "uploadToken",
    "expiresAt"
  ],
  "additionalProperties": false
}
Delivery
Standard response
Retry
Not declared idempotent
POST/v1/workspaces/{workspaceSlug}/recordings/operations

Run a cloud recording operation using the unchanged recording envelope (maximum request 1 MiB). Read-only catalog operations require files:read; all others require files:write. Results above the requested inline budget use artifact.read leases.

CLI
bento recording operation create --body-file request.json
Scope
ws:{workspaceSlug}:files:read or ws:{workspaceSlug}:files:write
Request
Request JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "operation": {
      "type": "string",
      "minLength": 1
    },
    "params": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "resultDelivery": {
      "type": "object",
      "properties": {
        "inlineBytes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8388608
        }
      },
      "required": [
        "inlineBytes"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "operation",
    "params"
  ],
  "additionalProperties": false
}
Response
Response JSON schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "ok": {
              "type": "boolean",
              "const": true
            },
            "data": {},
            "id": {
              "type": "string",
              "minLength": 1
            },
            "wait": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "settled"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "timed_out"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "interrupted"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "minLength": 1
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        },
                        "retryAfterMs": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "details": {
                          "type": "object",
                          "properties": {
                            "retry": {
                              "type": "object",
                              "properties": {
                                "operation": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "params": {
                                  "type": "object",
                                  "propertyNames": {
                                    "type": "string"
                                  },
                                  "additionalProperties": {}
                                }
                              },
                              "required": [
                                "operation",
                                "params"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "additionalProperties": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "retryable",
                        "details"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs",
                    "error"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "required": [
            "ok",
            "data",
            "id"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "ok": {
              "type": "boolean",
              "const": false
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "minLength": 1
                },
                "message": {
                  "type": "string"
                },
                "retryable": {
                  "type": "boolean"
                },
                "retryAfterMs": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "maximum": 9007199254740991
                },
                "details": {
                  "type": "object",
                  "properties": {
                    "retry": {
                      "type": "object",
                      "properties": {
                        "operation": {
                          "type": "string",
                          "minLength": 1
                        },
                        "params": {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {}
                        }
                      },
                      "required": [
                        "operation",
                        "params"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": {}
                }
              },
              "required": [
                "code",
                "message",
                "retryable",
                "details"
              ],
              "additionalProperties": false
            },
            "id": {
              "type": "string",
              "minLength": 1
            },
            "wait": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "settled"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "timed_out"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "const": "interrupted"
                    },
                    "timeoutMs": {
                      "type": "integer",
                      "exclusiveMinimum": 0,
                      "maximum": 2147483647
                    },
                    "job": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attemptGeneration": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "attemptId": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": [
                        "id",
                        "attemptGeneration",
                        "attemptId"
                      ],
                      "additionalProperties": false
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "minLength": 1
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        },
                        "retryAfterMs": {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        "details": {
                          "type": "object",
                          "properties": {
                            "retry": {
                              "type": "object",
                              "properties": {
                                "operation": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "params": {
                                  "type": "object",
                                  "propertyNames": {
                                    "type": "string"
                                  },
                                  "additionalProperties": {}
                                }
                              },
                              "required": [
                                "operation",
                                "params"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "additionalProperties": {}
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "retryable",
                        "details"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "state",
                    "timeoutMs",
                    "error"
                  ],
                  "additionalProperties": false
                }
              ]
            }
          },
          "required": [
            "ok",
            "error",
            "id"
          ],
          "additionalProperties": false
        }
      ]
    },
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "ok": {
          "type": "boolean"
        },
        "resultDelivery": {
          "type": "object",
          "properties": {
            "token": {
              "type": "string",
              "minLength": 1
            },
            "sizeBytes": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 8388607
            },
            "expiresAtMs": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "sha256": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "mediaType": {
              "type": "string",
              "const": "application/json"
            }
          },
          "required": [
            "token",
            "sizeBytes",
            "expiresAtMs",
            "sha256",
            "mediaType"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "ok",
        "resultDelivery"
      ],
      "additionalProperties": false
    }
  ]
}
Delivery
Standard response
Retry
Not declared idempotent