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.
excludeandgitignoreskip an entry and everything under it. A skipped entry does not count againstlimit.- With
gitignore, a work tree in which git ignores more than 20000 paths fails with 413too_large. Useexcludethere. - A listing with more than
limitentries returnspagination.next_cursor. Pass it ascursor, 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_pathsnames the folders that miss entries that no page returns: a cut atper_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
userwhen set. Settinguserneeds write access to the sandbox. - Served at the access endpoint of the sandbox (
access_endpointofGET /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 409sandbox_update_requireduntil 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.~namereturns 422.
See Read files in the guide.
Authorization
apiKey API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.
In: header
Path Parameters
Sandbox ID (ULID)
Query Parameters
Path in the sandbox: absolute, or relative to the sandbox working directory
"."Levels to descend; 0 returns only the entry at path
int320 <= value <= 321Maximum number of entries of this page
int321 <= value <= 200005000Continue 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
length <= 8192Maximum 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
int321 <= value <= 20000Skip 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
items <= 64Skip 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
Guest user to run as, by name or uid; defaults to the image user. Needs write access to the sandbox
^[a-z_][a-z0-9_-]{0,31}$|^[0-9]{1,10}$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" ]}{ "detail": "Property foo is required but is missing.", "errors": [ { "location": "string", "message": "string", "value": null } ], "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "https://example.com/errors/example"}Download through a signed URL GET
Serve the file of a GET signed URL. - The `ETag`, `If-None-Match`, `Range` and `If-Range` rules of `GET files/content` apply. - A URL with `format` serves the archive of its path, like `GET files/archive`. - Needs no other credential. - Served at the access endpoint. The mint returns the full URL. See [Share a file with a signed URL](https://docs.tektona.ai/files#share-a-file-with-a-signed-url) in the guide.
Create a directory PUT
Create `path` and its missing parents, like `mkdir -p`. - An existing directory, or a symlink to one, returns `created=false` and keeps its mode. - Any other existing entry returns 409 `already_exists`. A parent that is a file returns 400 `not_a_directory`. - Needs write access to the sandbox. - 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.