---
title: "Make an upload always available, or stop [write]"
method: PATCH
path: "/files/{file_id}"
tags: ["files"]
---

# Make an upload always available, or stop \[write\]

`PATCH /files/{file_id}`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/files/{file_id}`
- Auth: HTTP bearer

With `attach_by_default: true`, every session created in the workspace from then on starts with a read-only copy at `/workspace/shared/<filename>`, unless the session is created with `defaults: "none"`. Only a workspace upload that does not expire can carry the flag (400 otherwise). A file whose name is already taken in a session, or that would take the set past 64 MiB or 50 files, is skipped for that session; the session still starts.

## Path parameters

- `file_id` string, required

## Request body

- object
  - `attach_by_default` boolean, required

## Response `200`

OK

- File
  - `type` 'file', required
  - `id` string, required: file_…
  - `created_at` string, date-time, required
  - `filename` string, required
  - `mime_type` string, required
  - `size_bytes` integer, required
  - `downloadable` boolean, required: true for image uploads (readable within the workspace) and for the per-session copies minted when a file rides a message; false for other uploads (write-once)
  - `attach_by_default` boolean, required: Whether every new session in the workspace starts with a read-only copy under /workspace/shared/
  - `expires_at` string, date-time, nullable, required
  - `canonical` object: Optional reference for a currently readable canonical execution-generated meeting file. Ordinary uploads and older unprojected Recall files omit it. This is a discovery reference, not a permission grant: read GET /artifacts/{artifact_id} for current can_discuss and other authoritative controls before using existing private history/comments/policy/delete operations. Generated content remains read-only; no public sharing is implied.
    - `artifact_id` string, required
    - `origin` 'execution', required
    - `version` integer, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 2 info
  - added the optional property `canonical` to the response with the `200` status
  - added the optional property `error/request_id` to the response with the `default` status

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/files/:file_id/patch.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)