---
title: "saveFileV2"
method: POST
path: "/v2/files"
tags: ["File"]
---

# saveFileV2

`POST /v2/files`

Saves a permanent file entity. Updates an existing file entity when `_id` is passed.

Saves metadata to file entity and stores a version when `s3ref` or `source_url` is passed.

## Query parameters

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

## Request body

- union
  - 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.
  - BatchSaveFileVersionPayload[] — Batch version mode: array of s3ref payloads to add multiple versions to a single file entity. All payloads must target the same file entity (_id or file_entity_id). Requires version_only=true query parameter. S3 operations run in parallel, with a single entity update at the end.
    - `_id` union
      - string — Target file entity to add version to
      - string, uuid — Target file entity to add version to
    - `file_entity_id` string — Deprecated, use _id instead
    - `filename` string
    - `mime_type` string
    - `access_control` 'private' | 'public-read'
    - `s3ref` S3Ref, required
      - `bucket` string, required
      - `key` string, required

## Response `200`

Created or updated 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
- `404` — The requested resource was not found
- `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)