Files
The Files endpoints handle the file lifecycle on the Manager. PDFs uploaded through these endpoints are referenced by their fileId in detection and redaction requests, and result files (such as the FDF produced by detection or the redacted PDF) are downloaded through the same endpoints. The cURL examples use the Manager’s default address (http://localhost:9982); substitute the host and port of your deployment as needed.
DEK tokens
Files are encrypted at rest on the Manager. The data encryption key (DEK) for each file is wrapped in a short-lived, AES-GCM-encrypted token, the DEK token, which is returned alongside the fileId in the upload response.
Every subsequent operation on that file requires the token: detection, redaction, and download. Without it, the service can’t decrypt the file even though it has it. The token is returned only once and can’t be retrieved later, so store it securely with the fileId it belongs to.
The token has an expiration time, returned as expiresAt. After it expires, the file is no longer accessible and must be re-uploaded. The same applies if the token is lost.
Result files produced by jobs (such as the FDF returned by a detection job, or the redacted PDF returned by a redaction job) are also encrypted, and each comes with its own DEK token in the job response.
Most requests carry one DEK token under dekToken. The redaction request carries two tokens, one for the input PDF and one for the FDF, so its fields are named pdfDekToken and fdfDekToken to disambiguate.
Endpoints
Upload from local file
POST /v1/files/upload/fromLocal
Upload a file as a multipart form. Only .pdf and .fdf files are accepted. The response contains the fileId and the DEK token required for all subsequent operations on the file.
Request body (multipart/form-data):
| Field | Type | Description |
|---|---|---|
file | binary | The file to upload. Must be .pdf or .fdf. |
Response — UploadFileResponse.
Status codes:
| Code | Meaning |
|---|---|
200 | The file was uploaded successfully. |
400 | The request was malformed, the file couldn’t be read, or its extension isn’t .pdf or .fdf. |
Example:
curl -X POST "http://localhost:9982/v1/files/upload/fromLocal" \
-F "file=@document.pdf"
Upload from URL
POST /v1/files/upload/fromUrl
Instructs the Manager to fetch a file from a URL and store it. The Manager must have network access to the URL. Only .pdf and .fdf files are accepted.
Request body — UploadFromUrlRequest.
Response — UploadFileResponse.
Status codes:
| Code | Meaning |
|---|---|
200 | The file was uploaded successfully. |
400 | The URL was missing, invalid, unreachable, or the file extension isn’t .pdf or .fdf. |
Example:
curl -X POST "http://localhost:9982/v1/files/upload/fromUrl" \
-H "Content-Type: application/json" \
-d '{"fileUrl": "https://example.com/document.pdf"}'
List files
GET /v1/files
Returns metadata for all files currently held by the Manager. DEK tokens aren’t returned by this endpoint.
Query parameters:
| Name | Type | Description |
|---|---|---|
OnlyResultFiles | boolean | When true, only files produced as job results are returned. Defaults to false. |
Response — GetFilesInfoResponse.
Example:
curl "http://localhost:9982/v1/files?OnlyResultFiles=true"
Get file info
GET /v1/files/{fileId}
Returns metadata for a single file. DEK tokens aren’t returned by this endpoint.
Path parameters:
| Name | Type | Description |
|---|---|---|
fileId | string (UUID) | The file identifier returned by an upload. |
Response — GetFileInfoResponse.
Example:
curl "http://localhost:9982/v1/files/$FILE_ID"
Download a file
POST /v1/files/download
Returns the raw file bytes. The DEK token is required so the Manager can decrypt the file.
Request body — DownloadFileRequest.
Response — the file bytes (application/octet-stream).
Status codes:
| Code | Meaning |
|---|---|
200 | The file was returned successfully. |
400 | The DEK token was missing or invalid. |
404 | No file with the given fileId exists. |
Example:
curl -X POST "http://localhost:9982/v1/files/download" \
-H "Content-Type: application/json" \
-d "{\"fileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}" \
--output downloaded.pdf
Delete a file
DELETE /v1/files/{fileId}
Permanently deletes the file. After deletion, the fileId and DEK token can’t be reused.
Path parameters:
| Name | Type | Description |
|---|---|---|
fileId | string (UUID) | The file identifier returned by an upload. |
Response — DeleteFileResponse, containing the metadata of the deleted file.
Example:
curl -X DELETE "http://localhost:9982/v1/files/$FILE_ID"
Schemas
UploadFileResponse schema
| Field | Type | Description |
|---|---|---|
fileId | string (UUID) | The identifier to use in subsequent operations on this file. |
dekToken | string | DEK token required for all subsequent operations. Store securely; it isn’t recoverable. |
expiresAt | string (UTC date-time) | Expiration time of the DEK token. After this point, the file is no longer accessible. |
UploadFromUrlRequest schema
| Field | Type | Description |
|---|---|---|
fileUrl | string | URL the Manager fetches the file from. The Manager must have network access to this URL. |
DownloadFileRequest schema
| Field | Type | Description |
|---|---|---|
fileId | string (UUID) | The file identifier returned by an upload. |
dekToken | string | DEK token returned alongside the fileId at upload time. |
GetFileInfoResponse schema
| Field | Type | Description |
|---|---|---|
id | string (UUID) | File identifier. |
createdAt | string (UTC date-time) | When the file was uploaded. |
origin | FileOrigin | How the file entered the Manager. |
name | string | Original file name, when available. |
sizeBytes | integer | File size in bytes. |
extension | FileExtension | Detected file extension. |
GetFilesInfoResponse schema
| Field | Type | Description |
|---|---|---|
files | array of GetFileInfoResponse | The files held by the Manager that match the request. |
DeleteFileResponse schema
Same shape as GetFileInfoResponse. Returns the metadata of the file at the moment it was deleted.
FileExtension enum
The Manager only accepts .pdf and .fdf uploads, so file responses return one of the following values:
| Value | Description |
|---|---|
pdf | A PDF document. |
fdf | An FDF file, typically a detection result that lists the entities and their on-page positions. |
unknown | The file was uploaded without a recognizable extension. |
FileOrigin enum
| Value | Description |
|---|---|
localFile | Uploaded from a local file through /v1/files/upload/fromLocal. |
url | Fetched from a URL through /v1/files/upload/fromUrl. |
jobResult | Produced as the result of a detection or redaction job. |