Sign in

v3

latestOpenAPI 3.0.32026-07-21354289.5 KB
File

getFile

Get a file entity by id

get/v2/files/{id}

Path parameters

string required

Empty string (used when file ID not yet assigned)

OR
string uuid required

Valid UUID v4

Query parameters

source_urlboolean

Generate a source_url for the file entity, if it doesn't have one

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

Response

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"
    }
  ]
}