v3

latestOpenAPI 3.0.32026-07-21354289.5 KB

Deprecated

saveFile

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.

post/v1/files

Query parameters

activity_idstring ulid

See https://github.com/ulid/spec

Example:01F130Q52Q6MWSNS8N2AVXV4JN

Activity to include in event feed

asyncboolean

Don't wait for updated entity to become available in Search API. Useful for large migrations

version_onlyboolean

When true, only adds a new file version and updates the entity's s3ref to point to the new version, without overwriting the entity's existing top-level metadata. The entity's filename, type, and other fields are preserved as-is. The new version entry in the versions array will contain the file-level metadata (filename, mime_type, etc). Only applies when updating an existing entity (_id or file_entity_id is set).

Request body

Example request

{
  "relations": [
    {
      "entity_id": "ef7d985c-2385-44f4-9c71-ae06a52264f8",
      "_schema": "contact"
    }
  ],
  "_tags": [
    "tag1",
    "tag2"
  ],
  "_purpose": [
    "8d396871-95a0-4c9d-bb4d-9eda9c35776c",
    "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"
  ],
  "_manifest": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1234,
  "readable_size": "1.2 MB",
  "etag": "9bb58f26192e4ba00f01e2e7b136bbd8",
  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
  "custom_download_url": "https://some-api-url.com/download?file_id=123",
  "custom_download_url_auth": "token",
  "s3ref": {
    "bucket": "epilot-prod-user-content",
    "key": "123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
  }
}

Response

Created File Entity

_titlestring required

_schema'file' required

_orgstring required

_tagsstring[]

_purposestring[]

_manifeststring[]

Manifest ID used to create/update the entity

filenamestring required

mime_typestring

MIME type of the file

size_bytesinteger

File size in bytes

readable_sizestring

Human readable file size

etagstring

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_urlstring url

Direct URL for file (public only if file access control is public-read)

custom_download_urlstring 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_destring

Compact German summary for hover and list preview surfaces.

short_summary_destring

Short German paragraph summary for file preview surfaces.

preview_summary_enstring

Compact English summary for hover and list preview surfaces.

short_summary_enstring

Short English paragraph summary for file preview surfaces.

source_urlstring

Source URL for the file. Included if the entity was created from source_url, or when ?source_url=true

_updated_atstring date-time

_created_atstring date-time

__additionalobject nullable

Additional fields that are not part of the schema

Example response

{
  "_title": "document.pdf",
  "_org": "123",
  "_tags": [
    "tag1",
    "tag2"
  ],
  "_purpose": [
    "8d396871-95a0-4c9d-bb4d-9eda9c35776c",
    "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"
  ],
  "_manifest": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1234,
  "readable_size": "1.2 MB",
  "etag": "9bb58f26192e4ba00f01e2e7b136bbd8",
  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
  "custom_download_url": "https://some-api-url.com/download?file_id=123",
  "custom_download_url_auth": "token",
  "source_url": "https://productengineer-content.s3.eu-west-1.amazonaws.com/product-engineer-checklist.pdf",
  "s3ref": {
    "bucket": "epilot-prod-user-content",
    "key": "123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
  },
  "versions": [
    {
      "s3ref": {
        "bucket": "epilot-prod-user-content",
        "key": "123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
      },
      "filename": "document.pdf",
      "size_bytes": 1234,
      "readable_size": "1.2 MB",
      "mime_type": "image/jpeg",
      "etag": "9bb58f26192e4ba00f01e2e7b136bbd8"
    }
  ],
  "_acl": {
    "view": [
      "org:456"
    ],
    "edit": [
      "org:456"
    ],
    "delete": [
      "org:456"
    ]
  },
  "_owners": [
    {
      "org_id": "123",
      "user_id": "123"
    }
  ]
}