Skip to content

Files & S3 Storage ​

TiruPay can store and serve files on your behalf using S3-compatible object storage. A File object represents an uploaded file and holds its metadata alongside a reference to where the binary data lives in S3. Files are used for invoices, service logos, terms of service documents, images, and other attachments.

File Object ​

FieldTypeDescription
idstringUnique identifier
filenamestringOriginal filename
content_typestringMIME type (e.g. image/png, application/pdf)
sizeintegerFile size in bytes
categoryenumWhat kind of file this is (see Categories)
blur_hashstring | nullBlurHash preview string, computed automatically for images under 5 MB
widthinteger | nullWidth in pixels, if the file is an image
heightinteger | nullHeight in pixels, if the file is an image
focus_xnumber | nullRelative horizontal focus point (0-1) used when cropping generated variants. Defaults to the image's center if not set
focus_ynumber | nullRelative vertical focus point (0-1) used when cropping generated variants. Defaults to the image's center if not set
s3_keystringThe S3 object key
bucketstringThe S3 bucket the file lives in
service_idstringThe service this file belongs to
uploaded_bystring | nullID of the user who uploaded the file
s3_configuration_idstring | nullThe S3 configuration used for this file (null = default configuration)
deleted_atdatetime | nullWhen the file was deleted from S3 (null = still present)
created_atdatetimeWhen the file record was created
updated_atdatetimeWhen the file record was last updated

FilePublicLite vs FilePublic

Unauthenticated and regular user requests receive a reduced FilePublicLite response without s3_key, bucket, uploaded_by, service_id, and s3_configuration_id. Admins and service accounts receive the full FilePublic object.

Categories ​

The category determines what the file is used for and who can access it.

CategoryDescriptionWho can access
imageImages (e.g. service logos, product photos)Everyone (unauthenticated)
legal_documentLegal document versions (e.g. Terms of Service)Everyone, but only once the version is FINALIZED, PUBLISHED, or ARCHIVED. Admins always see all versions including DRAFT.
invoiceInvoice PDFs generated by TiruPayAdmins, Services, Users linked to the invoice's customer
article_documentArticle Document version files (e.g. purchasable manuals)Admins, Services, Users linked to a customer holding a grant for that specific version
mailFiles attached to emailsAdmins and Services only
taxTax export filesAdmins and Services only
otherGeneral attachmentsAdmins and Services only

BlurHash for images

TiruPay automatically computes a BlurHash for uploaded images smaller than 5 MB. Use the blur_hash field to render a lightweight placeholder before the full image loads.

Image Variants ​

For uploaded images smaller than 5 MB, TiruPay automatically generates a set of downscaled variants: one for every combination of aspect ratio and format below. Each variant is cropped around the file's focus point (focus_x/focus_y, defaulting to the image's center) so the relevant part of the image is not cut off.

Aspect ratioFormats
1:1avif, webp, jpeg
4:3avif, webp, jpeg
4:5avif, webp, jpeg

Request a specific variant instead of the original file by passing format and aspect_ratio to the download or stream endpoints. Both parameters must be given together.

Setting the focus point

Pass focus_x and focus_y (each 0-1) to POST /files/upload to control where variants are cropped around, e.g. to keep a face or logo centered in a wide source image. Omit them to crop around the image's center.

Variants are generated asynchronously

Variants are generated in the background alongside the BlurHash, so they may not exist yet immediately after upload. Requesting a variant that doesn't (yet) exist returns 404 Not Found.

S3 Configuration ​

By default, TiruPay stores files using a shared S3 configuration. Each service can optionally bring its own S3-compatible storage by configuring an S3Configuration.

FieldTypeDescription
urlstringS3-compatible endpoint URL
default_bucketstring | nullDefault bucket for this service. TiruPay generates one automatically if not set
access_keystringS3 access key
secret_keystringS3 secret key

When a file is uploaded, TiruPay picks the bucket in this order:

  1. The bucket parameter passed to the upload endpoint (if provided)
  2. The default_bucket from the service's S3Configuration
  3. An auto-generated bucket name for the service

Changing S3 configuration after upload

Changing a service's S3 configuration after files have already been uploaded will break existing file links. All previously uploaded files remain on the old bucket. Migrate them manually before switching configurations.

Self-hosted storage is outside TiruPay' control

If a service brings its own S3Configuration, the underlying bucket and its contents are owned and managed by that service's infrastructure, not by TiruPay. TiruPay' delete protections (e.g. for invoice, legal_document, and article_document files still in use) only guard the official API path - they cannot prevent a service from deleting, moving, or modifying objects directly through its own S3 provider. Services using their own storage are responsible for the integrity of the underlying bucket.

Uploading Files ​

POST /files/upload?service_id={id}

Upload a file as multipart/form-data. The file is stored in S3 and a File record is created in the database.

ParameterTypeDescription
service_idstringThe service to associate the file with
filefileThe file to upload (max 25 MB)
categoryenumFile category (default: other)
bucketstring | nullOverride the target bucket
focus_xnumber | nullRelative horizontal focus point (0-1) for cropping image variants. Defaults to center
focus_ynumber | nullRelative vertical focus point (0-1) for cropping image variants. Defaults to center

25 MB limit

Files larger than 25 MB are rejected.

Downloading Files ​

GET /files/{file_id}/download

Redirects (307) to a presigned S3 URL for the file. This is the preferred way to download a file - only use /stream below if your setup can't follow the redirect to S3 directly.

GET /files/{file_id}/stream

Proxies the file content through the TiruPay API server instead of redirecting to S3. The response includes a Content-Disposition: attachment header with the original filename. The optional chunk_size query parameter controls the streaming chunk size (max 52 000 bytes, default 8 192).

Both endpoints accept the same parameters:

ParameterTypeDescription
formatenum | nullFormat of an image variant to fetch instead of the original file (avif, webp, jpeg)
aspect_ratioenum | nullAspect ratio of an image variant to fetch instead of the original file (1:1, 4:3, 4:5)

format and aspect_ratio must be given together, or omitted together (400 Bad Request otherwise). Returns 404 Not Found if no variant exists for the given combination.

Returns 410 Gone if the file has been deleted from S3 (i.e. deleted_at is set).

Deleting Files ​

DELETE /files/{file_id}

Deletes the binary data from S3 and sets deleted_at on the file record. The file object itself is never removed from the database — it is kept for audit and reference purposes (e.g. invoice records that reference the file remain intact). Any generated image variants are removed entirely, both their binary data and their records.

Invoices cannot be deleted

Files with category invoice are protected and cannot be deleted through the API.

Legal and Article Documents cannot be deleted while in use

A legal_document file cannot be deleted while it is linked to any Document version. An article_document file cannot be deleted while it is linked to any Article Document version - customers may hold an active grant against it. Detach or supersede the version first.

Viewing and Downloading ​

Access is determined by the file's category (see Categories above). The same rules apply to the metadata endpoint (GET /files/{id}) and both download endpoints (GET /files/{id}/download, GET /files/{id}/stream), for the original file and any of its variants.

404 instead of 403

To prevent enumeration attacks, requests for inaccessible files return 404 Not Found rather than 403 Forbidden.

Uploading and deleting requires Admin

Only Admin accounts can upload (POST /files/upload) or delete (DELETE /files/{id}) files, and only within the services they have access to. Service accounts can view and download files but not upload or delete them.

Relationships ​

  • Services - Every file belongs to a service. A service can optionally provide its own S3 configuration.
  • Invoicing - Invoice PDFs are stored as invoice-category files. Users gain access to them through the customer linked to the invoice.
  • Legal Documents - Document version content is stored as legal_document-category files.
  • Article Documents - Purchasable document version content is stored as article_document-category files. Users gain access through a CustomerDocumentGrant.
  • Users - The uploaded_by field records which user uploaded the file. Users can access invoice files if they are linked to the corresponding customer.