Files

oikapi provides file upload and management with multiple storage backends.

Upload a file

POST /api/files/upload
Content-Type: multipart/form-data

file: <binary data>

The file is sent as the file form field. The response includes id, filename, original_name, mime_type, size, download_url, is_public, and created_at (HTTP 201). You can also upload from a URL:

POST /api/files/upload-from-url

File metadata

GET /api/files/{fileId}

Returns the full metadata record, including checksum_sha256, uploaded_by, download_url, and view_url.

Download a file

GET /api/files/{fileId}/download

Use GET /api/files/{fileId}/view to render the file inline instead of as an attachment.

Delete a file

DELETE /api/files/{fileId}

Returns HTTP 204. Deleted files are excluded from queries but can be recovered.

Attaching files to records

Use file or file_array field types to associate files with records:

POST /api/apps/support/tables/tickets/fields
{
  "name": "attachments",
  "type": "file_array"
}

Then reference file IDs when creating or updating records:

POST /api/apps/support/tables/tickets/records
{
  "title": "Bug report",
  "attachments": ["file-uuid-1", "file-uuid-2"]
}

Storage backends

The backend is selected with file_storage.provider:

Provider	Configuration
Local filesystem	file_storage.provider: "local"
S3-compatible (AWS S3, etc.)	file_storage.provider: "s3"
SeaweedFS (in-cluster, S3-compatible)	file_storage.provider: "seaweedfs"

Tracked metadata

Each uploaded file tracks:

• Filename and original filename
• File size in bytes
• MIME type
• SHA256 checksum (checksum_sha256)
• Upload and update timestamps
• Uploader user ID

Access control

Files can be public or private. Private files require authentication. Accessing a file attached to a record requires read permission on that record’s table; row-level and field-level access rules apply.