Here’s a scenario that comes up more often than it should. Your team gets a SOC 2 audit request for every customer document touched in the last 90 days, and the reviewer wants file size, hash, and upload timestamp for each one. If you wrote those fields to a sync table at upload time, you’re in decent shape, but that table is now a maintenance liability. Storage providers change. Files get overwritten. Sync logic drifts. What you actually want is to fetch that metadata fresh at the moment you need it, directly from the source.
That’s exactly what the Filestack File API metadata endpoint gives you. Pass a file handle and a few query parameters, get a JSON payload back. No separate database, no sync job.
Key takeaways
- The metadata endpoint returns file attributes without writing anything to the Filestack database
- One request can return size, mimetype, hashes, EXIF, and storage location in a single JSON payload
- Hashes (MD5, SHA-1 through SHA-512) support file integrity verification for audit trails
- EXIF data requires security credentials; every other field is available with a standard GET
- Pairing this endpoint with webhook events covers most compliance logging needs without a separate metadata table
The metadata endpoint at a glance
| Method | URI | Returns |
|---|---|---|
| GET | /file/{HANDLE}/metadata | JSON |
The important distinction here: this metadata is generated at request time, not stored in the Filestack database. That means you’re always reading current file state rather than a snapshot from the moment of upload.
For most fields, a standard GET is all you need. EXIF data is the exception. It requires a valid policy and signature:
?policy={POLICY}&signature={SIGNATURE}
For anything you’re shipping to production, adding security credentials to all metadata requests is good practice even when not strictly required. The Filestack security documentation covers how to generate policies and signatures.
Choosing which fields to return
Every query parameter is optional and boolean. You get back exactly what you ask for, nothing more. That keeps response payloads lean and latency low, especially useful when you’re hitting this endpoint from a webhook handler or a compliance job processing hundreds of files.
A request for the fields most audit logs need looks like this:
curl -X GET “https://www.filestackapi.com/api/file/HMJ1BsmYSFeukx6RlYE8/metadata?size=true&mimetype=true&uploaded=true&filename=true”
Response:
{
{"filename":"filestack-mark.png",
"mimetype":"image/png",
"size":1268638,
"uploaded":1779118017598.307}
}
The uploaded field returns a Unix timestamp in milliseconds. If your audit log expects an ISO 8601 string, convert it server-side before writing.
Available non-hash fields:
| Parameter | What it returns |
|---|---|
| size | File size in bytes |
| mimetype | MIME type |
| filename | Original filename |
| uploaded | Upload timestamp |
| writeable | Whether the file can be overwritten |
| cloud | Whether the file was stored via Cloud API |
| source_url | Whether the file was stored from a URL |
| upload_status | Upload status |
File integrity with hashes
The hash family covers MD5, SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. All are computed at request time against the current file, so they reflect any overwrites or updates since the original upload.
SHA-256 is the right choice for most audit and compliance work. It’s what SOC 2 auditors and HIPAA workflows typically expect, and it aligns with NIST recommendations for SHA-2.
curl -X GET “https://www.filestackapi.com/api/file/HMJ1BsmYSFeukx6RlYE8/metadata?sha256=true&size=true&uploaded=true”
Response:
{
{"sha256":"223ce0dd3e9601747c6fafb9be40cef48617edbc27bfe61f0465f4c013135a5a",
"size":1268638,
"uploaded":1779118017598.307}
}
To verify file integrity, store the hash at upload time (or pull it immediately after upload) and compare it against a fresh request whenever you need to confirm the file has not changed. A mismatch flags a modification.
The full hash parameter list:
| Parameter | Algorithm |
|---|---|
| md5 | MD5 |
| sha1 | SHA-1 |
| sha224 | SHA-224 |
| sha256 | SHA-256 |
| sha384 | SHA-384 |
| sha512 | SHA-512 |
EXIF data for image workflows
EXIF metadata, which includes capture date, camera model, GPS coordinates, and orientation, is available for image files but requires security credentials on every request.
curl -X GET “https://www.filestackapi.com/api/file/{HANDLE}/metadata?exif=true&policy={POLICY}&signature={SIGNATURE}”
The response includes the full EXIF payload from the image. For media platforms and geolocation features, this is useful for things like sorting images by capture date, auto-rotating based on orientation, or surfacing GPS coordinates without storing them separately.
One thing to note: EXIF data reflects what’s embedded in the file itself. If a user strips or modifies EXIF before upload, that’s what you’ll get back. The API reads what’s there.
For image dimensions specifically, use the imagesize task in the Processing API rather than EXIF, since not all images carry dimension data in their EXIF headers.
Storage location fields
Three parameters expose where a file physically lives. These are useful when you’re running multi-provider setups or need to confirm that a file landed in the right bucket after a storage migration.
curl -X GET “https://www.filestackapi.com/api/file/{HANDLE}/metadata?location=true&path=true&container=true”
Response:
{
"location": "S3",
"path": "kWg7nloGTWmHFi5nlbF9_contract_v2.png",
"container": "your-s3-bucket-name"
}
Supported storage providers include S3, Azure, Google Cloud Storage, Rackspace, and Dropbox. The location field returns the provider name. The container field returns the bucket or container name. The path field returns the object key within that container.
A practical pattern: on-demand audit logging
Here’s how this fits into a real compliance workflow. When an audit event fires (a file is accessed, a record is flagged for review, a batch job runs), a middleware function pulls metadata for the relevant file handle, writes it to your audit log, and returns.
// Node.js example: fetch metadata on audit event and write to log
const axios = require("axios");
async function logFileMetadata(handle, auditLogDb) {
const url = `https://www.filestackapi.com/api/file/${handle}/metadata`;
const params = {
size: true,
mimetype: true,
filename: true,
uploaded: true,
sha256: true,
location: true,
container: true,
};
const response = await axios.get(url, { params });
const metadata = response.data;
const logEntry = {
handle,
fetchedAt: new Date().toISOString(),
...metadata,
};
await auditLogDb.insert(logEntry);
return logEntry;
}This function is stateless. It does not cache, it does not maintain a sync table, it fetches fresh on every call. For audit and compliance use cases, that’s often exactly what you want: a verifiable record of what the file looked like at the moment the audit event occurred.
When to fetch vs. when to store
The metadata endpoint is the right tool for some use cases and the wrong tool for others.
Fetch on demand when you need:
- Audit logs and compliance reports
- Hash-based integrity checks
- Admin views and file health dashboards
- One-off verification before a destructive operation
Store locally when you need:
- High-frequency reads (metadata on every page load)
- Denormalized fields used in search indexes
- Offline access or disaster recovery scenarios
For event-driven capture, the Filestack Webhooks API can trigger a metadata fetch at upload time and write it to your database automatically. That covers teams that want both approaches: a stored snapshot at upload, and fresh verification on demand.
The full parameter reference for the metadata endpoint is in the File API documentation. If you want to try this against a real file handle, dev.filestack.com gives you API access and a handle to test with.
A Product Marketing Manager at Filestack with four years of dedicated experience. As a true technology enthusiast, they pair marketing expertise with a deep technical background. This allows them to effectively translate complex product capabilities into clear value for a developer-focused audience.
Read More →