SandboxesFiles

List files

Return the entry at path and, down to depth, the entries under it.

  • The listing is one traversal, not one snapshot. It walks depth first: each folder is followed by its entries, and names sort in byte order.
  • Symlinks are never followed. A broken link is listed.
  • exclude and gitignore skip an entry and everything under it. A skipped entry does not count against limit.
  • With gitignore, a work tree in which git ignores more than 20000 paths fails with 413 too_large. Use exclude there.
  • A listing with more than limit entries returns pagination.next_cursor. Pass it as cursor, with the same other parameters, to list the next page. An entry added after the cursor position shows up on a later page; one added before it is missed.
  • truncated_paths names the folders that miss entries that no page returns: a cut at per_dir_limit, a folder above 100,000 entries, or a folder that the user cannot read.
  • Runs in the sandbox as the image user, or as user when set. Setting user needs write access to the sandbox.
  • Served at the access endpoint of the sandbox (access_endpoint of GET /v1/sandboxes/{sandboxId}), not at the API host.
  • A paused sandbox returns 409, unless resume=true. A sandbox that started before its files server existed returns 409 sandbox_update_required until it restarts.
  • A refused operation returns its code as the problem type.
  • A path that starts with ~ or ~/ names the home directory of the user that the operation runs as. ~name returns 422.

See Read files in the guide.

GET
/v1/sandboxes/{sandboxId}/files
AuthorizationBearer <token>

API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.

In: header

Path Parameters

sandboxId*string

Sandbox ID (ULID)

Query Parameters

path?string

Path in the sandbox: absolute, or relative to the sandbox working directory

Default"."
depth?integer

Levels to descend; 0 returns only the entry at path

Formatint32
Range0 <= value <= 32
Default1
limit?integer

Maximum number of entries of this page

Formatint32
Range1 <= value <= 20000
Default5000
cursor?string

Continue after the last entry of a previous page: pass its pagination.next_cursor. Keep path, depth, exclude, gitignore, per_dir_limit and user the same; limit can change. A cursor of another listing fails with 422 invalid_argument

Lengthlength <= 8192
per_dir_limit?integer

Maximum number of entries of each folder. A folder with more keeps its first entries in name order and joins truncated_paths; no page returns the rest. Use it to keep one large folder from filling the pages. Absent sets no cap

Formatint32
Range1 <= value <= 20000
exclude?array<string>|

Skip entries that match, and everything under them; repeat for more. A name without / matches at any depth, a name with / matches a path relative to path

Itemsitems <= 64
gitignore?boolean

Skip what git ignores in the work tree that holds path, and the .git folder. Runs git as the image user, so it needs write access to the sandbox. Fails with 422 not_a_git_repository outside a work tree

user?string

Guest user to run as, by name or uid; defaults to the image user. Needs write access to the sandbox

Match^[a-z_][a-z0-9_-]{0,31}$|^[0-9]{1,10}$
resume?boolean

Wake a paused sandbox to serve this request

Response Body

application/json

application/problem+json

curl -X GET "https://example.com/v1/sandboxes/string/files"
{  "entries": [    {      "gid": 0,      "group": "string",      "mode": 0,      "modified_at": "2019-08-24T14:15:22Z",      "name": "string",      "owner": "string",      "path": "string",      "size": 0,      "symlink_target": "string",      "type": "file",      "uid": 0    }  ],  "entry": {    "gid": 0,    "group": "string",    "mode": 0,    "modified_at": "2019-08-24T14:15:22Z",    "name": "string",    "owner": "string",    "path": "string",    "size": 0,    "symlink_target": "string",    "type": "file",    "uid": 0  },  "pagination": {    "has_more": true,    "next_cursor": "string"  },  "truncated": true,  "truncated_paths": [    "string"  ]}