Sign in

v3

latestOpenAPI 3.0.32026-07-21354289.5 KB
File

saveFileV2

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.

post/v2/files

Query parameters

activity_idstring ulid

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

Example:01F130Q52Q6MWSNS8N2AVXV4JN

Activity to include in event feed

fill_activityboolean

Update the diff and entity for the custom activity included in the query. Pending state on activity is automatically ended when activity is filled.

strictboolean

When passed true, the response will contain only fields that match the schema, with non-matching fields included in __additional

asyncboolean

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

delete_temp_fileboolean

Delete the temp file from S3 after copying it permanently

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

OR

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 or updated File Entity

_titlestring required
_schema'file' required
_orgstring required
_tagsstring[]
_purposestring[]
_manifeststring[]

Manifest ID used to create/update the entity

filenamestring required
type'document' | 'document_template' | 'text' | 'image' | 'video' | 'audio' | 'spreadsheet' | 'presentation' | 'font' | 'archive' | 'application' | 'unknown' 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"
    }
  ]
}