FileURL (Semantic Module)

← Back to Modules Reference

The FileURL semantic module manages binary file attachments and downloadable assets—such as invoice PDFs, spreadsheet exports, legal contracts, and ZIP archives.

Decorating a property with FileURL connects it to API Now’s Two-Phase Upload Architecture. This allows your API to handle large file attachments safely by uploading binary files directly to cloud storage, enforcing maximum file size and MIME type allow lists, and protecting downloads with expiring signed URLs.

Technical Specifications

Attribute	Specification
Scope	`Property` (Applied to a text property)
Data Type	`String`
Default Max Size	`10485760` bytes (10 MB)
Default Allowed MIME Types	All non-executable binary files (or custom allow list)
Delivery Mechanism	Time-limited Read-Only Signed URLs (15-minute expiration)

Key Capabilities

1. Document & Binary Attachment Storage

Unlike ImageURL (which focuses on visual media and web image optimization), FileURL is tailored for non-image binary files. It supports PDF invoices, Microsoft Office / CSV spreadsheets, compressed archives, and text documents.

2. Generous Upload Limit (10 MB Default)

To accommodate comprehensive reports and multi-page documents, FileURL defaults to a 10 MB maximum file size limit (compared to 5 MB for images). This limit can be adjusted in the Domain Modeler configuration.

3. MIME Type Allow Lists (`allowedMimeTypes`)

You can restrict uploads to specific document formats:

For an invoice management system: configure allowedMimeTypes: ['application/pdf'].
For a data import feature: configure allowedMimeTypes: ['text/csv', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'].
When left unconfigured, all safe, non-executable binary file formats are permitted.

4. Two-Phase Upload Architecture

Binary data is never transmitted directly through standard CRUD endpoints:

Initiate (POST /.well-known/upload): Client requests an upload for a given filename and MIME type, receiving an expiring upload_url and a file_reference token.
Upload (PUT upload_url): Client streams the binary file directly to storage.
Persist: Client creates or updates the record, passing the file_reference token in the FileURL property.

Learn more about the underlying architecture in the File Uploads Guide.

5. Protected Downloads with Expiring Signed URLs

Files stored via FileURL are not left open on public web buckets. When clients retrieve records (GET /invoices/inv_101), the engine transparently generates a temporary Signed URL valid for 15 minutes, protected by your entity’s role-based access rules.

Configuration Options

When configuring the FileURL semantic in the Domain Modeler, you can adjust:

Option	Type	Default	Description
`maxSizeInBytes`	`number`	`10485760` (10 MB)	Maximum permitted file size in bytes.
`allowedMimeTypes`	`string[]`	`undefined` (all non-executable files)	Optional allow list of permitted MIME types.

API Lifecycle Examples

1. Initializing Document Upload

The client initiates a PDF attachment upload:

POST /api/v1/.well-known/upload
Content-Type: application/json

{
  "filename": "annual_report_2026.pdf",
  "contentType": "application/pdf"
}

Server Response (200 OK):

{
  "data": {
    "file_reference": "ref_doc_4f92b710",
    "upload_url": "https://storage.googleapis.com/app-bucket/tmp/ref_doc_4f92b710.pdf?GoogleAccessId=..."
  }
}

2. Associating the File with a Record

After uploading the binary content to the upload_url, the client creates the invoice:

POST /invoices
Content-Type: application/json

{
  "invoiceNumber": "INV-2026-001",
  "totalAmount": 1250.00,
  "pdfDocument": "ref_doc_4f92b710"
}

Server Response (201 Created):

{
  "data": {
    "id": "inv_101",
    "invoiceNumber": "INV-2026-001",
    "totalAmount": 1250.00,
    "pdfDocument": "https://storage.googleapis.com/app-bucket/uploads/invoices/inv_101/pdfDocument.pdf?X-Goog-Signature=..."
  }
}

3. Reading the Record (`GET`)

Clients receive a fresh, temporary signed download link:

GET /invoices/inv_101