GEgetaptly
Files

Get a presigned URL for a direct file upload

First step of the direct file-upload flow. Issues a presigned S3 POST policy and records a pending upload.

Uploading a file takes three steps:

  1. Get a URL — call this endpoint. It returns { fileId, url, fields }.
  2. Upload directly to S3 — send a multipart/form-data POST to url. Include every key/value from fields as form fields first, then the file itself as the last field named file. The upload goes straight to S3; it does not pass through this API. A successful upload returns HTTP 204 from S3.
  3. Mark the upload complete — call POST /api/files/upload-complete with the fileId from step 1. This records the file and returns its download URL.

The presigned policy enforces the content type and a 1 byte–50 MB size range. Both extension and contentType must be on the accepted lists.

attachEntityType is channel, aptlet, knowledge, or template, and attachEntityId is the channel id, aptlet uuid, knowledge doc id, or communication template id respectively. The target must exist (scoped to your company) or the request is rejected. The file is stored under that entity's folder.

post/api/files/upload-url

Request

Request body

namestring required

Original file name.

extensionstring required

File extension (lowercase, no dot). Must be an accepted extension.

sizeinteger required

File size in bytes. Must be 1–52428800 (50 MB).

contentTypestring required

MIME type. Must be an accepted content type.

attachEntityType'channel' | 'aptlet' | 'knowledge' | 'template' required

The kind of entity the file is attached to.

attachEntityIdstring required

The channel id (channel), aptlet uuid (aptlet), knowledge doc id (knowledge), or communication template id (template) the file belongs to. Must exist within your company.

Example request

{
  "name": "invoice.pdf",
  "extension": "pdf",
  "size": 20480,
  "contentType": "application/pdf",
  "attachEntityType": "channel",
  "attachEntityId": "7f3c2a1b9d4e5f6a7b8c9d0e"
}

Response

Presigned upload policy.

fileIdstring

ID to pass to /api/files/upload-complete.

urlstring

S3 endpoint to POST the multipart form to.

fieldsobject

Form fields that must be included in the multipart POST (the file part goes last).

Changes

No recorded changes to this operation across all 1 revision of this API.