---
title: "saveFile"
method: POST
path: "/v1/files"
tags: ["Deprecated"]
deprecated: true
---

# saveFile

`POST /v1/files`

> **Deprecated.**

**DEPRECATED** - Will be removed on **2025-06-30**. Use `POST /v2/files` instead.

## Migration Guide
Replace calls to this endpoint with `saveFileV2`:

| v1 Feature | v2 Feature | Notes |
|------------|------------|-------|
| `activity_id` param | `activity_id` param | No change |
| `async` param | `async` param | No change |
| - | `fill_activity` param | New in v2 |
| - | `strict` param | New in v2 |
| - | `delete_temp_file` param | New in v2, defaults to true |

The v2 endpoint supports additional parameters for better control over file saving behavior.

---

Create / Update a permanent File entity.

Makes file object permanent and saves metadata to file entity.

## Query parameters

- `activity_id` string, ulid — See https://github.com/ulid/spec
- `async` boolean
- `version_only` boolean

## Request body

- union
  - SaveS3FilePayload
    - `_id` union
      - string — if passed, adds a new version to existing file entity
      - string, uuid — if passed, adds a new version to existing file entity
    - `file_entity_id` string — Deprecated, use _id instead
    - `relations` FileRelationItem[] — List of entities to relate the file to
      - `entity_id` string, required
      - `_schema` string — URL-friendly identifier for the entity schema
      - `_tags` string[]
    - `_tags` string[]
    - `_purpose` string[]
    - `_manifest` string[] — Manifest ID used to create/update the entity
    - `filename` string
    - `type` 'document' | 'document_template' | 'text' | 'image' | 'video' | 'audio' | 'spreadsheet' | 'presentation' | 'font' | 'archive' | 'application' | 'unknown'
    - `mime_type` string — MIME type of the file
    - `size_bytes` integer — File size in bytes
    - `readable_size` string — Human readable file size
    - `etag` string — Content hash (S3 ETag) of the latest file version. For single-part uploads this is the hex MD5 of the content and is stable across orgs, so identical content yields an identical etag. Used to detect real content changes without re-downloading the bytes.
    - `access_control` 'private' | 'public-read'
    - `public_url` string, url — Direct URL for file (public only if file access control is public-read)
    - `custom_download_url` string, uri — Custom external download url used for the file
    - `custom_download_url_auth` 'presigned' | 'token' — Authorization mode for the custom_download_url. `presigned` (the default) uses an HMAC-signed URL; `token` authorizes the download via the caller's bearer token, matched against the exact stored custom_download_url. In token mode the File API returns the unsigned custom_download_url (no expires_at/signature query params) so the stored url matches exactly.
    - `preview_summary_de` string — Compact German summary for hover and list preview surfaces.
    - `short_summary_de` string — Short German paragraph summary for file preview surfaces.
    - `preview_summary_en` string — Compact English summary for hover and list preview surfaces.
    - `short_summary_en` string — Short English paragraph summary for file preview surfaces.
    - `file_summary_execution_id` string, uuid — AI execution that produced the current summary. Used to correlate user feedback.
    - `s3ref` S3Ref
      - `bucket` string, required
      - `key` string, required
  - SaveFileFromSourceURLPayload
    - `_id` union
      - string — if passed, adds a new version to existing file entity
      - string, uuid — if passed, adds a new version to existing file entity
    - `file_entity_id` string — Deprecated, use _id instead
    - `relations` FileRelationItem[] — List of entities to relate the file to
      - `entity_id` string, required
      - `_schema` string — URL-friendly identifier for the entity schema
      - `_tags` string[]
    - `_tags` string[]
    - `_purpose` string[]
    - `_manifest` string[] — Manifest ID used to create/update the entity
    - `filename` string
    - `type` 'document' | 'document_template' | 'text' | 'image' | 'video' | 'audio' | 'spreadsheet' | 'presentation' | 'font' | 'archive' | 'application' | 'unknown'
    - `mime_type` string — MIME type of the file
    - `size_bytes` integer — File size in bytes
    - `readable_size` string — Human readable file size
    - `etag` string — Content hash (S3 ETag) of the latest file version. For single-part uploads this is the hex MD5 of the content and is stable across orgs, so identical content yields an identical etag. Used to detect real content changes without re-downloading the bytes.
    - `access_control` 'private' | 'public-read'
    - `public_url` string, url — Direct URL for file (public only if file access control is public-read)
    - `custom_download_url` string, uri — Custom external download url used for the file
    - `custom_download_url_auth` 'presigned' | 'token' — Authorization mode for the custom_download_url. `presigned` (the default) uses an HMAC-signed URL; `token` authorizes the download via the caller's bearer token, matched against the exact stored custom_download_url. In token mode the File API returns the unsigned custom_download_url (no expires_at/signature query params) so the stored url matches exactly.
    - `preview_summary_de` string — Compact German summary for hover and list preview surfaces.
    - `short_summary_de` string — Short German paragraph summary for file preview surfaces.
    - `preview_summary_en` string — Compact English summary for hover and list preview surfaces.
    - `short_summary_en` string — Short English paragraph summary for file preview surfaces.
    - `file_summary_execution_id` string, uuid — AI execution that produced the current summary. Used to correlate user feedback.
    - `source_url` string, uri — Custom external download url used for the file
  - SaveCustomFilePayload
    - `_id` union
      - string — if passed, adds a new version to existing file entity
      - string, uuid — if passed, adds a new version to existing file entity
    - `file_entity_id` string — Deprecated, use _id instead
    - `relations` FileRelationItem[] — List of entities to relate the file to
      - `entity_id` string, required
      - `_schema` string — URL-friendly identifier for the entity schema
      - `_tags` string[]
    - `_tags` string[]
    - `_purpose` string[]
    - `_manifest` string[] — Manifest ID used to create/update the entity
    - `filename` string
    - `type` 'document' | 'document_template' | 'text' | 'image' | 'video' | 'audio' | 'spreadsheet' | 'presentation' | 'font' | 'archive' | 'application' | 'unknown'
    - `mime_type` string — MIME type of the file
    - `size_bytes` integer — File size in bytes
    - `readable_size` string — Human readable file size
    - `etag` string — Content hash (S3 ETag) of the latest file version. For single-part uploads this is the hex MD5 of the content and is stable across orgs, so identical content yields an identical etag. Used to detect real content changes without re-downloading the bytes.
    - `access_control` 'private' | 'public-read'
    - `public_url` string, url — Direct URL for file (public only if file access control is public-read)
    - `custom_download_url` string, uri — Custom external download url used for the file
    - `custom_download_url_auth` 'presigned' | 'token' — Authorization mode for the custom_download_url. `presigned` (the default) uses an HMAC-signed URL; `token` authorizes the download via the caller's bearer token, matched against the exact stored custom_download_url. In token mode the File API returns the unsigned custom_download_url (no expires_at/signature query params) so the stored url matches exactly.
    - `preview_summary_de` string — Compact German summary for hover and list preview surfaces.
    - `short_summary_de` string — Short German paragraph summary for file preview surfaces.
    - `preview_summary_en` string — Compact English summary for hover and list preview surfaces.
    - `short_summary_en` string — Short English paragraph summary for file preview surfaces.
    - `file_summary_execution_id` string, uuid — AI execution that produced the current summary. Used to correlate user feedback.

## Response `201`

Created File Entity

- FileEntity
  - `_title` string, required
  - `_schema` 'file', required
  - `_org` string, required
  - `_id` union, required
    - string — Empty string (used when file ID not yet assigned)
    - string, uuid — Valid UUID v4
  - `_tags` string[]
  - `_purpose` string[]
  - `_manifest` string[] — Manifest ID used to create/update the entity
  - `filename` string, required
  - `type` 'document' | 'document_template' | 'text' | 'image' | 'video' | 'audio' | 'spreadsheet' | 'presentation' | 'font' | 'archive' | 'application' | 'unknown', required
  - `mime_type` string — MIME type of the file
  - `size_bytes` integer — File size in bytes
  - `readable_size` string — Human readable file size
  - `etag` string — Content hash (S3 ETag) of the latest file version. For single-part uploads this is the hex MD5 of the content and is stable across orgs, so identical content yields an identical etag. Used to detect real content changes without re-downloading the bytes.
  - `access_control` 'private' | 'public-read', required
  - `public_url` string, url — Direct URL for file (public only if file access control is public-read)
  - `custom_download_url` string, uri — Custom external download url used for the file
  - `custom_download_url_auth` 'presigned' | 'token' — Authorization mode for the custom_download_url. `presigned` (the default) uses an HMAC-signed URL; `token` authorizes the download via the caller's bearer token, matched against the exact stored custom_download_url. In token mode the File API returns the unsigned custom_download_url (no expires_at/signature query params) so the stored url matches exactly.
  - `preview_summary_de` string — Compact German summary for hover and list preview surfaces.
  - `short_summary_de` string — Short German paragraph summary for file preview surfaces.
  - `preview_summary_en` string — Compact English summary for hover and list preview surfaces.
  - `short_summary_en` string — Short English paragraph summary for file preview surfaces.
  - `file_summary_execution_id` string, uuid — AI execution that produced the current summary. Used to correlate user feedback.
  - `source_url` string — Source URL for the file. Included if the entity was created from source_url, or when ?source_url=true
  - `s3ref` object
    - `bucket` string, required
    - `key` string, required
  - `versions` FileItem[], required
    - `s3ref` S3Ref
      - `bucket` string, required
      - `key` string, required
    - `filename` string
    - `size_bytes` integer
    - `readable_size` string
    - `mime_type` string
    - `etag` string — Content hash (S3 ETag) of this file version
  - `_updated_at` string, date-time
  - `_created_at` string, date-time
  - `_acl` BaseEntityAcl — Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
    - `view` string[]
    - `edit` string[]
    - `delete` string[]
  - `_owners` BaseEntityOwner[]
    - `org_id` string, required
    - `user_id` string
  - `__additional` object, nullable — Additional fields that are not part of the schema

## Other responses

- `400` — Invalid request parameters or payload
- `401` — Authentication required or invalid credentials
- `500` — An unexpected error occurred on the server

---

[API](https://skmtc.net/epilot/apis/file-api.md) · [All operations](https://skmtc.net/epilot/apis/file-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/epilot/file-api/revisions/4d61b97f1e97/schema)