Using uploaded files

This guide uploads a test input and a helper script, then uses both in a request. The file store page covers limits and backends.

1. Upload

curl -s http://localhost:3000/api/v1/file \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@input-large.txt"

{ "file_id": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "size": 2483021, "already_exists": false }

Upload the checker script the same way. The executable bit is not stored with the file; you choose it when you reference the file.

2. Reference

{
  "stop_on_failure": true,
  "steps": [
    {
      "cmd": "gcc",
      "args": ["-O2", "-o", "main", "main.c"],
      "files": { "main.c": "..." },
      "cache": true
    },
    {
      "cmd": "./check.sh",
      "files": {
        "input.txt": { "file_id": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b" },
        "check.sh": { "file_id": "8c2e…", "executable": true }
      }
    }
  ]
}

Before the second task starts, Faber writes input.txt (mode 0644) and check.sh (mode 0755) into the workspace, next to the main binary from the first step.

3. Handle a missing file

If a file_id is not in the store (never uploaded, expired, deleted, or uploaded to a different instance), the request fails with HTTP 404 before any step runs:

{ "error": "…", "code": "file_not_found" }

Match on code, not on the message. Upload the file again and retry. Since uploads are idempotent, a client can simply re-upload everything it is about to reference when it sees file_not_found.

Mixing forms

A task’s files can mix plain strings, inline files and references:

"files": {
  "main.py": "print(open('data.bin','rb').read()[:4])",
  "data.bin": { "content": "AAECAwQ=", "encoding": "base64" },
  "big.csv": { "file_id": "…" }
}

All three end up as regular files in the workspace. For the step cache, only the bytes and the executable bit matter, so switching a file from inline to a reference does not invalidate cached layers.

Clean up

curl -s -X DELETE http://localhost:3000/api/v1/file/3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b \
  -H "Authorization: Bearer $API_KEY" -o /dev/null -w "%{http_code}\n"

Files also expire on their own FABER_STORE_TTL_SECS (one hour by default) after the last upload or read.