> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach and download files

> Upload files to give your agent context, and download files it produces.

The Files API lets you supply context to a Session — code repositories, configuration, reference docs, and so on. The Agent can read these files to understand the task.

## Workflow

<Steps>
  <Step title="Upload file">
    `POST /api/v1/cloud/files` — upload text-based content.
  </Step>

  <Step title="Mount on Session">
    `POST /api/v1/cloud/sessions/{session_id}/resources` — attach the uploaded file to the Session.
  </Step>

  <Step title="Agent uses it">
    The Agent reads the file's contents during the Session and completes the task.
  </Step>
</Steps>

## Upload a file

```
POST https://api.qoder.com/api/v1/cloud/files
Content-Type: multipart/form-data
```

### Parameters

| Field  | Type   | Required | Description     |
| ------ | ------ | -------- | --------------- |
| `file` | binary | Yes      | File contents   |
| `name` | string | No       | Custom filename |

<Note>
  Use the File object's `downloadable` field to decide whether `/content` is available.
</Note>

<Tabs>
  <Tab title="Single file">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./src/main.py"
    ```

    ## curl Upload Example

    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./src/main.py"
    ```

    Response:

    ```json theme={null}
    {
      "id": "file_019e6a18dc0978e9a2104c9b269748ac",
      "type": "file",
      "filename": "main.py",
      "size_bytes": 4096,
      "downloadable": false,
      "mime_type": "text/plain",
      "scope": null,
      "created_at": "2026-05-01T10:00:00Z"
    }
    ```

    Uploading multiple files:

    ```bash theme={null}
    # Upload one at a time
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./config.yaml"

    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./requirements.txt"
    ```

    ```json theme={null}
    {
      "id": "file_019e6a18dc0978e9a2104c9b269748ac",
      "type": "file",
      "filename": "main.py",
      "size_bytes": 4096,
      "downloadable": false,
      "mime_type": "text/plain",
      "scope": null,
      "created_at": "2026-05-01T10:00:00Z"
    }
    ```
  </Tab>

  <Tab title="Multiple files">
    ```bash theme={null}
    # Upload one at a time
    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./config.yaml"

    curl -X POST https://api.qoder.com/api/v1/cloud/files \
      -H "Authorization: Bearer $QODER_PAT" \
      -F "file=@./requirements.txt"
    ```
  </Tab>
</Tabs>

## Mount on a session

After uploading, use the Resources API to mount the file on a specific Session:

```
POST https://api.qoder.com/api/v1/cloud/sessions/{session_id}/resources
```

Request body — send a single file resource:

```json theme={null}
{
  "type": "file",
  "file_id": "file_abc123",
  "mount_path": "/data/input.txt"
}
```

<Tabs>
  <Tab title="Single file">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "resources": [
          {"type": "file", "file_id": "file_abc123"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Multiple files">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "resources": [
          {"type": "file", "file_id": "file_abc123"},
          {"type": "file", "file_id": "file_def456"},
          {"type": "file", "file_id": "file_ghi789"}
        ]
      }'
    ```
  </Tab>
</Tabs>

## Managing files

### Get file metadata

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "file_abc123",
    "mount_path": "/data/input.txt"
  }'
```

To attach multiple files after Session creation, call the endpoint once per file.

Filtering by `scope_id` is supported for Session-scoped files.

### Download a file

Files with `"downloadable": true` can be downloaded:

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_PAT" \
  -o output.txt
```

For non-downloadable files, requests to `/content` return `403 Forbidden`.

## End-to-end example

```bash theme={null}
# 1. Upload the source file
FILE_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@./app.py" | jq -r '.id')

echo "Uploaded: $FILE_ID"

# 2. Create a Session
SESSION_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123", "environment_id": "env_abc123"}' | jq -r '.id')

# 3. Mount the file on the Session
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}"

# 4. Send a task — the Agent can reference mounted files
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Review app.py and fix the bugs."}]}
    ]
  }'
```

## FAQ

**Q: How long are uploaded files retained?**

A: Files are retained until you explicitly delete them via `DELETE /api/v1/cloud/files/{file_id}`. A file that is still referenced by an active Session cannot be deleted — remove or detach the Session first.

**Q: Can I attach files when creating a Session?**

A: Yes. Pass file resources in the `resources` field when creating the Session. See [Sessions — Attach Resources at Creation](/cloud-agents/sessions#attach-resources-at-creation).

**Q: Why can't I download some files?**

A: For security, some files are only available for the Agent's internal use. To export results, use files whose File object returns `"downloadable": true`.

**Q: Which file formats are supported?**

A: The upload API accepts text-based files. Code, configuration, and plain-text reference documents work best.

## Next steps

<CardGroup cols={2}>
  <Card title="Start a session" icon="play" href="/cloud-agents/sessions">
    Attach files at session creation time.
  </Card>

  <Card title="Build persistent memory" icon="brain" href="/cloud-agents/memory-stores">
    Persist Agent knowledge across Sessions.
  </Card>

  <Card title="Files API" icon="code" href="/cloud-agents/api/files/upload">
    The full Files API surface.
  </Card>
</CardGroup>