# Sandbox files

`GET /v1/containers/{id}/files` lists the files the shell or bash helper left in a sandbox; two
more routes read one file's details and its bytes.

## Request

Send them with an API key. A sandbox's id is the name you gave it in the helper, or the
`container_id` the helper's result carried; a sandbox of another account answers 404. The
[Helpers](/docs/helpers) guide sets the shell and bash helpers to work.

| Route | Does |
|---|---|
| `GET /v1/containers/{id}/files` | lists the sandbox's files, in path order |
| `GET /v1/containers/{id}/files/{file}` | answers one file's details |
| `GET /v1/containers/{id}/files/{file}/content` | answers the file's bytes |

### List

`GET /v1/containers/{id}/files` takes the sandbox's id in the address, and its other fields
after `?`.

| Field | Needed | You send |
|---|---|---|
| `id` | yes | the sandbox's id |
| `limit` | no | how many files one page holds, 1 to 100; absent, 100 |
| `after` | no | the `last_id` the previous page answered, for the next page |

Souk Bot's shell helper wrote a sales report in the sandbox Yacine named `souk-reports`. The
samples list its files; put your sandbox's id in place of that name.

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
SANDBOX = "souk-reports"
ADDRESS = f"https://opendunes.com/v1/containers/{SANDBOX}/files"

request = urllib.request.Request(
    ADDRESS,
    headers={"Authorization": "Bearer " + API_KEY},
)
with urllib.request.urlopen(request) as response:
    page = json.load(response)

for file in page["data"]:
    print(file["id"], file["path"], file["bytes"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const SANDBOX = "souk-reports";
const ADDRESS = `https://opendunes.com/v1/containers/${SANDBOX}/files`;

const response = await fetch(ADDRESS, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const page = await response.json();

for (const file of page.data) console.log(file.id, file.path, file.bytes);
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	sandbox = "souk-reports"
	address = "https://opendunes.com/v1/containers/" + sandbox + "/files"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	req, err := http.NewRequest("GET", address, nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var page struct {
		Data []struct {
			ID    string `json:"id"`
			Path  string `json:"path"`
			Bytes int64  `json:"bytes"`
		} `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&page); err != nil {
		panic(err)
	}
	for _, file := range page.Data {
		fmt.Println(file.ID, file.Path, file.Bytes)
	}
}
```

```bash cURL
SANDBOX="souk-reports"
ADDRESS="https://opendunes.com/v1/containers/$SANDBOX/files"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY"
```

### One file, its bytes

`GET /v1/containers/{id}/files/{file}` and `GET /v1/containers/{id}/files/{file}/content` take
the sandbox's id and the file's id in the address, and nothing else.

| Field | Needed | You send |
|---|---|---|
| `file` | yes | the file's `id`, from the list: `cfile_` and its path in base64url |

## Response

`GET /v1/containers/{id}/files` answers `200 OK` with a page of files.

| Field | Holds |
|---|---|
| `object` | `list` |
| `data` | the files on this page, each the object below |
| `first_id` | the `id` of the first file on this page, or `null` |
| `last_id` | what to send as `after` for the next page; it can name a place past this page's last file. `null` only when the page is empty and none follows |
| `has_more` | `true` when another page follows |

`GET /v1/containers/{id}/files/{file}` answers `200 OK` with one file.

| Field | Holds |
|---|---|
| `id` | the file's id |
| `object` | `container.file` |
| `container_id` | the sandbox, under your name for it |
| `path` | where the file sits in the sandbox |
| `bytes` | its size, in bytes |
| `created_at` | when the file was last copied out of the sandbox, in Unix seconds |
| `source` | `assistant`: the helper wrote it |

`GET /v1/containers/{id}/files/{file}/content` answers the bytes themselves, in the file's own
type, or `application/octet-stream` when it has none.

A page of one file, *illustrative*:

```json
{
  "object": "list",
  "data": [
    {
      "id": "cfile_b3V0L3ZlbnRlcy5jc3Y",
      "object": "container.file",
      "container_id": "souk-reports",
      "path": "out/ventes.csv",
      "bytes": 2048,
      "created_at": 1790668800,
      "source": "assistant"
    }
  ],
  "first_id": "cfile_b3V0L3ZlbnRlcy5jc3Y",
  "last_id": "cfile_b3V0L3ZlbnRlcy5jc3Y",
  "has_more": false
}
```

## What it cost

Free. Listing, reading and downloading a sandbox's files are never charged. The time the
sandbox ran is charged on the request whose helper ran it.

## Errors

`error.code` carries the status, and `error.message` says why.

| Status | When |
|---|---|
| 400 | `limit` is not a whole number from 1 to 100, or `after` is over 256 characters |
| 401 | the key is missing, wrong, disabled or expired |
| 403 | the key is kept to other addresses |
| 404 | no sandbox of yours has that id, or it holds no file with that id |
| 429 | too many reads at once; `Retry-After` says when to ask again |
| 500 | an unexpected error; the message is generic |
| 503 | the sandboxes cannot be read right now; ask again shortly |
| 504 | the sandbox did not answer in time |
