Files
These endpoints manage the files of a files collection: the analysis of each file, reviewer decisions, downloads, the collection policy and hosted upload links. Concepts such as verdicts and findings, processing modes and original access are described in the Files guide. Metering is described in Billing & Usage.
A file is a resource of a files collection, so a file is addressed by the resource key of its record. Endpoints answer 400 collection_not_file_backed when the collection is not a files collection.
Path Parameters
- Name
:env- Type
- string
- Description
Unique identifier of the environment
- Name
:collection- Type
- string
- Description
Key of the files collection
- Name
:resource- Type
- string
- Description
Key of the resource that holds the file
Permissions
| Endpoints | Required permissions |
|---|---|
| Analysis, downloads, page detail, tombstones, review queue, list and read upload links | resources read and collection-items read |
| Approve, reject, re-analyze | resources update and collection-items read |
| Upload grant, create and revoke upload link | resources create and collection-items read |
| Upload grant that replaces a resource | resources create and update |
| Read policy, moderation taxonomy | collection-structure read |
| Update policy | collection-structure update |
A caller counts as a reviewer for a record when it holds resources update on it. A reviewer can download a quarantined file; other callers are refused with forbidden.
Files Policy Object
The live policy of a collection, returned by Get Files Policy and Update Files Policy.
- Name
version- Type
- integer | null
- Description
Version number of the live policy.
nullfor a collection that has no saved version.
- Name
enforce_from- Type
- integer | null
- Description
Oldest policy version whose verdicts are still honored. Files verdicted under an older version are withheld until they are re-verdicted. Moves to the new version when a change makes the policy stricter.
- Name
body- Type
- object
- Description
The policy settings. See the keys below.
- Name
config_hash- Type
- string | null
- Description
Hash of the stored policy body.
nullwhen there is no saved version.
- Name
created_at- Type
- datetime | null
- Description
Timestamp when the version was created, in ISO 8601 format.
Policy body
- Name
suspicious_action- Type
- string
- Default
- default:deliver
- Description
What happens to a file whose verdict is
suspicious.deliver- the file is published with its verdictquarantine- the file waits for a reviewer
- Name
overrides- Type
- object
- Default
- default:{}
- Description
Map of finding kind to severity (
block,suspiciousorinfo). The allowed severities per kind are listed under finding kinds.malware,policy_ruleandactive_contentaccept no override.
- Name
acknowledge_explicit_delivery- Type
- bool
- Default
- default:false
- Description
Must be
truewhenoverrides.explicitissuspiciousorinfo. The stored body keeps it only while anexplicitoverride exists.
- Name
allowed_kinds- Type
- array of string
- Default
- default:["image", "document"]
- Description
File kinds the collection accepts:
image,document,archive. At least one value. A policy that allowsdocumentadmitsarchivefiles.
- Name
tables- Type
- string
- Default
- default:auto
- Description
Table analysis for analyses that start after the change:
auto,neveroralways.
- Name
moderation_rules- Type
- array of object
- Default
- default:[]
- Description
Customer moderation rules. At most 50. Needs moderation turned on for the collection.
- Name
original_access- Type
- string
- Default
- default:allowed
- Description
Who may download the original:
allowed,when_cleanordisabled. A newagent_readycollection starts withwhen_clean. See original access.
Moderation Rule Object
- Name
label- Type
- string | null
- Description
A moderation label from the moderation taxonomy. Exactly one of
labelandparentis set.
- Name
parent- Type
- string | null
- Description
A moderation category from the taxonomy. The rule applies to the category and its labels.
- Name
max_confidence- Type
- number
- Description
Confidence from 0 to 100.
- Name
action- Type
- string
- Description
Severity of the
policy_rulefinding the rule raises:block,suspiciousorinfo.
- Name
id- Type
- string
- Description
Read-only. Derived from the action and the label or category:
no-<slug>forblock,review-<slug>forsuspicious,tag-<slug>forinfo. Anidsent in a request is ignored. Two rules with the same id are refused. Rules are stored sorted by id.
File Analysis Object
Returned by Get File Analysis and, with extra fields, by the reviewer actions.
- Name
resource_key- Type
- string
- Description
Key of the record that holds the file.
- Name
file_uuid- Type
- string | null
- Description
Identifier of the stored file.
nullfor a record with no file.
- Name
page_count- Type
- integer | null
- Description
Number of pages, once counted.
- Name
asset_state- Type
- string | null
- Description
present,purgingorpurged.
- Name
tombstone- Type
- bool
- Description
truewhen the file was blocked or rejected; its bytes are erased or being erased.
- Name
analysis- Type
- object | null
- Description
The active analysis. See Analysis.
- Name
trust- Type
- object | null
- Description
processing(agent_readyorstorage_only),content_tainted(bool) andtainted_paths(array of record paths whose values come from the uploader or the file). See the trust model.
- Name
checks- Type
- array of object
- Description
One receipt per detector:
detector,detector_version,status,started_at,finished_at.
- Name
findings- Type
- array of object
- Description
Every finding of the active analysis. See Finding.
- Name
file- Type
- object | null
- Description
What the caller can download now.
nullfor a record with no file.originalandsafe_copy-{available, reason}.reasonisnullwhenavailableistrue; otherwise it is a download refusal reason.active_content-{present, kinds, truncated}.presentisnullwhen the file was not checked. See active content.original_access- the collection'soriginal_accessvalue.origin- where the file came from, ornull:channel(dashboard,management_api,upload_link,signed_uploadornull),external(bool),created_by({kind, name}ornull),upload_link({upload_id, title}ornull) andend_user(string ornull).
Analysis
- Name
generation- Type
- integer
- Description
Generation number. A re-analysis starts a new generation.
- Name
state- Type
- string
- Description
Pipeline state, for example
published,awaiting_publish,blocked,rejected,failedor a processing step.
- Name
verdict- Type
- string | null
- Description
clean,suspicious,blockedorrejected, once decided.
- Name
verdict_reasons- Type
- array of string
- Description
Finding kinds behind the verdict. A moderation rule appears as
policy_rule:<rule id>.
- Name
public_reason- Type
- string | null
- Description
Coarse reason shown to uploaders:
malware,prohibited_content,unsupported_format,too_largeorprocessing_failed.
- Name
error_code- Type
- string | null
- Description
Detailed reason code for a refused or failed file.
- Name
in_review- Type
- bool
- Description
truewhile the file waits for a reviewer.
- Name
publish_requested_by- Type
- string | null
- Description
Who asked for the publish, when someone did.
- Name
policy_version- Type
- integer
- Description
Policy version the analysis ran under.
- Name
pipeline_version- Type
- string | null
- Description
Pipeline version that ran the analysis.
- Name
source_format- Type
- string | null
- Description
Detected file format.
- Name
scanned_at- Type
- datetime | null
- Description
When the malware scan passed.
- Name
step_times- Type
- object
- Description
Map of pipeline state to the time it was entered.
- Name
state_changed_at- Type
- datetime | null
- Description
When
statelast changed.
- Name
created_at- Type
- datetime | null
- Description
When the analysis was created.
Finding
- Name
kind- Type
- string
- Description
Finding kind. See finding kinds.
- Name
sub_kind- Type
- string | null
- Description
Finer classification within the kind.
- Name
severity- Type
- string
- Description
info,suspiciousorblock.
- Name
page- Type
- integer | null
- Description
Page the finding is on.
- Name
box- Type
- array | null
- Description
Location on the page as four fractions of the page size.
- Name
detector- Type
- string
- Description
Detector that produced the finding.
- Name
detector_version- Type
- string
- Description
Version of the detector.
- Name
score- Type
- number | null
- Description
Detector score.
- Name
evidence- Type
- any | null
- Description
Evidence recorded by the detector.
nullonce the file's personal data is redacted.
- Name
detail- Type
- object | null
- Description
Structured facts. Set for
active_content(kinds,truncated) andpii(entities,truncated; entity types and locations, never the matched text).
- Name
rule_id- Type
- string | null
- Description
Id of the moderation rule, for a
policy_rulefinding.
Download Refusal Reasons
A download that is not available carries one of these reason values. In the file block of the analysis they appear as reason; in a 409 response they appear as detail.reason.
reason | Meaning |
|---|---|
forbidden | Quarantined, and the caller is not a reviewer. |
withheld_by_moderation | Quarantined by moderation: no safe copy or pages. |
processing | Being scanned or analyzed. |
failed | Processing failed. |
not_published | Never published. |
blocked, rejected, erased | The file is unavailable; its bytes are erased or being erased. |
not_generated | No safe copy or page for this analysis. |
original_unavailable | The stored original cannot be found. |
legacy_original_download_unsupported | The original of this file cannot be downloaded. |
original_withheld | original_access is when_clean and the file is not clean. detail.safe_copy says whether the safe copy is available. |
original_disabled | original_access is disabled. |
Create Upload Grant
Issues a single-use grant to upload one file into a files collection. The grant reserves one file unit; see file units. A new resource is created from the uploaded file, or an existing resource is replaced. Successful and 402 responses carry X-FoxNose-File-Units-Remaining (units left in the window, can be negative, absent when the plan has no file allowance or it is unlimited) and, on paid plans with a cap, X-FoxNose-Cap-Usage (share of the cap used, 0 to 1).
Success Response: 200 OK
Attributes
- Name
mode- Type
- string
- Default
- default:instant
- Description
instant- the uploaded file is published as soon as it is readydraft- the uploaded file creates an unpublished revision. Required for a collection whose schema has required fields beyond the file
- Name
target_resource_key- Type
- string
- Default
- default:null
- Description
Key of an existing resource to replace. Cannot be combined with
mode: draft. A replacement keeps the resource's owner.
- Name
resource_owner- Type
- string
- Default
- default:null
- Description
Key of the owner resource. Required for a collection with
strict_reference, not accepted otherwise or withtarget_resource_key.
Other keys are rejected.
Response
- Name
publicKey- Type
- string
- Description
Public key that goes with the upload.
- Name
uploadBaseUrl- Type
- string
- Description
Origin the file is sent to.
- Name
authToken- Type
- string
- Description
Single-use upload token.
- Name
tokenExpire- Type
- integer
- Description
Token expiry as a Unix timestamp in seconds.
- Name
store- Type
- string
- Description
Always
auto.
- Name
metadata- Type
- object
- Description
nonce,projectandenv. Send it unchanged with the upload.
- Name
upload_id- Type
- string
- Description
Identifier of the upload.
- Name
status_token- Type
- string
- Description
Opaque token for the upload session.
- Name
rotation- Type
- integer
- Description
Counter of the session token. A higher value is newer.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
402 Payment Required- Description
files_quota_exceeded- the file-unit allowance or the spend cap is reached. The body carriesaxis(file_units),reason(plan_exhaustedorspend_cap_reached),used_units(reserved units included),included_units,cap_usd,window_resets_at, andupgrade_urlorraise_cap_url. A hosted upload link answers with{"code": "files_quota_exceeded"}only
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not existcollection_not_found- the specified collection does not existresource_not_found- the replacement target does not exist in the collectionresource_owner_not_found- the owner does not exist
- Name
422 Unprocessable Content- Description
validation_error- invalid body,mode: instanton a collection that requires file data,mode: draftwithtarget_resource_key, or a collection whose schema cannot accept uploadsresource_owner_required- the collection requires an owner
- Name
429 Too Many Requests- Description
rate_limited- too many grants for the owner or the key. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
files_quota_unavailable- the allowance could not be read. Nothing was admitted. Retry after theRetry-Afterheader
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/upload/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"mode": "instant",
"resource_owner": "k3mzq9ae"
}'
Response
{
"publicKey": "…",
"uploadBaseUrl": "https://…",
"authToken": "…",
"tokenExpire": 1763290800,
"store": "auto",
"metadata": {
"nonce": "…",
"project": "d7hazs1x",
"env": "7c9h4pwu"
},
"upload_id": "up_eu1_3f9c0a…",
"status_token": "eu1.…",
"rotation": 1
}
Get File Analysis
Returns the record's file with its active analysis, check receipts, findings and download availability. See the File Analysis Object.
Success Response: 200 OK
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/analysis/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"resource_key": "qw81ztrc",
"file_uuid": "5b0e3c1a-7a4e-4f0e-9b57-0f6c2f6d9d11",
"page_count": 2,
"asset_state": "present",
"tombstone": false,
"analysis": {
"generation": 1,
"state": "published",
"verdict": "suspicious",
"verdict_reasons": ["pii"],
"public_reason": null,
"error_code": null,
"in_review": false,
"publish_requested_by": null,
"policy_version": 3,
"pipeline_version": "…",
"source_format": "pdf",
"scanned_at": "2026-11-16T09:14:02+00:00",
"step_times": {},
"state_changed_at": "2026-11-16T09:14:31+00:00",
"created_at": "2026-11-16T09:14:00+00:00"
},
"trust": {
"processing": "agent_ready",
"content_tainted": true,
"tainted_paths": ["file.original_filename", "content"]
},
"checks": [
{
"detector": "guardrails",
"detector_version": "1",
"status": "passed",
"started_at": "2026-11-16T09:14:20+00:00",
"finished_at": "2026-11-16T09:14:24+00:00"
}
],
"findings": [
{
"kind": "pii",
"sub_kind": null,
"severity": "info",
"page": 1,
"box": null,
"detector": "guardrails",
"detector_version": "1",
"score": null,
"evidence": null,
"detail": {
"entities": [{"type": "EMAIL", "boxes": [[0.12, 0.2, 0.4, 0.23]]}],
"truncated": false
},
"rule_id": null
}
],
"file": {
"original": {"available": true, "reason": null},
"safe_copy": {"available": true, "reason": null},
"active_content": {"present": false, "kinds": {}, "truncated": false},
"original_access": "allowed",
"origin": {
"channel": "dashboard",
"external": false,
"created_by": {"kind": "user", "name": "Ada Lovelace"},
"upload_link": null,
"end_user": null
}
}
}
Approve File
Releases a file that is held for a reviewer. Needs resources update on the record. The request has no body.
Success Response: 200 OK, or 202 Accepted when the publish goes back through preparation or a new verdict and completes on its own.
The response is the File Analysis Object plus:
- Name
outcome- Type
- string
- Description
published,awaiting_publishorreverdict. A file uploaded in draft mode answersawaiting_publish: its uploader then publishes it.
- Name
reason- Type
- string | null
- Description
awaiting_userwhen a draft-mode upload waits for its uploader.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
- Name
409 Conflict- Description
file_not_ready- the file is still processing, or has no file or analysisfile_not_in_review- the file is not waiting for a reviewer, including a file already approved or publishedfile_quarantined- the file is still quarantinedfile_erased- the file was erased
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/approve/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"outcome": "published",
"reason": null,
"resource_key": "qw81ztrc",
"file_uuid": "5b0e3c1a-7a4e-4f0e-9b57-0f6c2f6d9d11",
"analysis": { "generation": 1, "state": "published", "verdict": "suspicious", "in_review": false }
}
Reject File
Rejects a file that is held for a reviewer. The analysis becomes rejected with public_reason prohibited_content and error_code rejected_by_reviewer, and erasure of the file's bytes starts. Needs resources update on the record. The request has no body. Repeating the call on a rejected file returns the same result.
Success Response: 200 OK
The response is the File Analysis Object.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is fully blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
- Name
409 Conflict- Description
file_not_ready- the file is still processing, or has no file or analysisfile_not_in_review- the file is not waiting for a reviewerfile_erased- the file was erased
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/reject/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"resource_key": "qw81ztrc",
"file_uuid": "5b0e3c1a-7a4e-4f0e-9b57-0f6c2f6d9d11",
"asset_state": "purging",
"tombstone": true,
"analysis": {
"generation": 1,
"state": "rejected",
"public_reason": "prohibited_content",
"error_code": "rejected_by_reviewer",
"in_review": false
}
}
Re-analyze File
Starts a new analysis generation of the file under the live policy. An in-flight generation is retired. A published generation keeps serving until the new one publishes. Needs resources update on the record. The request has no body.
A re-analysis reserves one file unit and is billed again; see Billing & Usage.
Success Response: 202 Accepted
The response is the File Analysis Object.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
402 Payment Required- Description
files_quota_exceeded- the file-unit allowance or the spend cap is reached. The body carriesaxis(file_units),reason(plan_exhaustedorspend_cap_reached),used_units(reserved units included),included_units,cap_usd,window_resets_at, andupgrade_urlorraise_cap_url.
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
- Name
409 Conflict- Description
file_not_ready- the record has no filefile_erased- the file was erasedfile_not_scanned- no analysis of the file has passed the malware scan yetoriginal_unavailable- the original needed for the analysis is not storedreanalysis_requires_agent_ready- the collection isstorage_only, which has no content analysis to redo
- Name
429 Too Many Requests- Description
rate_limited- the processing budget refuses new work. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
files_quota_unavailable- the allowance could not be read. Nothing was admitted. Retry after theRetry-Afterheader
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/reanalyze/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"resource_key": "qw81ztrc",
"file_uuid": "5b0e3c1a-7a4e-4f0e-9b57-0f6c2f6d9d11",
"analysis": { "generation": 2, "state": "scan_clean", "in_review": false }
}
Download Object
Returned by the three download endpoints. Each URL expires within five minutes.
- Name
url- Type
- string
- Description
Short-lived download URL.
- Name
expires_in- Type
- integer
- Description
Seconds until the URL expires.
- Name
expires_at- Type
- datetime | null
- Description
Expiry time in ISO 8601 format.
- Name
kind- Type
- string
- Description
original,safe_copyorpage.
- Name
filename- Type
- string | null
- Description
Suggested file name.
- Name
content_type- Type
- string | null
- Description
application/octet-streamfor an original,application/pdffor a safe-copy PDF,image/pngfor a page or an image's safe copy.
- Name
generation- Type
- integer
- Description
Analysis generation the copy comes from.
- Name
state- Type
- string
- Description
published, orquarantinedfor a file held for a reviewer.
- Name
active_content- Type
- object
- Description
{present, kinds, truncated}. See active content.
- Name
warnings- Type
- array of object
- Description
Entries with a
code:active_content(withpresent,kindsandtruncated) when the file carries active content,suspicious_findingswhen it has asuspiciousor higher finding.
Download Original
Returns a short-lived URL for the original file. Subject to the collection's original access. Each URL is audited.
Success Response: 200 OK. See the Download Object.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
- Name
409 Conflict- Description
The download is refused.
detail.reasonholds a refusal reason. Fororiginal_disabled,original_withheld,original_unavailableandlegacy_original_download_unsupportedtheerror_codeis the reason itself; otherwise it isfile_download_refused.original_withheldalso carriesdetail.safe_copy.
- Name
429 Too Many Requests- Description
rate_limited- the project mints download URLs too fast. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
download_unavailable- the URL could not be prepared. Retry
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/file/original/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"url": "https://…",
"expires_in": 300,
"expires_at": "2026-11-16T09:20:00+00:00",
"kind": "original",
"filename": "invoice-0042.pdf",
"content_type": "application/octet-stream",
"generation": 1,
"state": "published",
"active_content": {"present": false, "kinds": {}, "truncated": false},
"warnings": []
}
409 original_withheld
{
"error_code": "original_withheld",
"message": "This file cannot be downloaded now",
"detail": {
"reason": "original_withheld",
"safe_copy": {"available": true, "reason": null}
}
}
Download Safe Copy
Returns a short-lived URL for the safe copy: a PDF of the redacted page images, or a PNG for an image. Each URL is audited.
Success Response: 200 OK. See the Download Object.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collection
- Name
409 Conflict- Description
file_download_refused- the download is refused.detail.reasonholds a refusal reason
- Name
429 Too Many Requests- Description
rate_limited- the project mints download URLs too fast. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
download_unavailable- the URL could not be prepared. Retry
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/file/safe-copy/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"url": "https://…",
"expires_in": 300,
"expires_at": "2026-11-16T09:20:00+00:00",
"kind": "safe_copy",
"filename": "invoice-0042-safe.pdf",
"content_type": "application/pdf",
"generation": 1,
"state": "published",
"active_content": {"present": false, "kinds": {}, "truncated": false},
"warnings": []
}
Download Page
Returns a short-lived URL for the redacted PNG of one page. Pages are numbered from 1. Each URL is audited.
Success Response: 200 OK. See the Download Object.
Path Parameters
- Name
:page- Type
- integer
- Description
Page number
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collectionfile_page_not_found- the generation has no such page
- Name
409 Conflict- Description
file_download_refused- the download is refused.detail.reasonholds a refusal reason
- Name
429 Too Many Requests- Description
rate_limited- the project mints download URLs too fast. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
download_unavailable- the URL could not be prepared. Retry
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/file/pages/1/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"url": "https://…",
"expires_in": 300,
"expires_at": "2026-11-16T09:20:00+00:00",
"kind": "page",
"filename": "invoice-0042-page-1.png",
"content_type": "image/png",
"generation": 1,
"state": "published",
"active_content": {"present": false, "kinds": {}, "truncated": false},
"warnings": []
}
Get Page Detail
Returns one page as the dashboard viewer shows it: the redacted image, what was withheld, tables, located personal data and the text an agent receives. Availability follows the page download. The call is not audited and does not count against the download limit; it draws from a separate per-project view limit.
Success Response: 200 OK
- Name
page- Type
- integer
- Description
Page number.
- Name
of- Type
- integer | null
- Description
Number of pages in the file.
- Name
image_url- Type
- string
- Description
Short-lived URL of the redacted page image.
- Name
image_width- Type
- integer
- Description
Image width in pixels.
- Name
image_height- Type
- integer
- Description
Image height in pixels.
- Name
expires_in- Type
- integer
- Description
Seconds until
image_urlexpires.
- Name
redactions- Type
- array of object | null
- Description
Regions withheld from the page:
reason(low_legibility,hidden_native_text,unread_text_regionordegenerate_clip),boxandlabel. Boxes are[x0, y0, x1, y1]as fractions of the page size.
- Name
tables- Type
- array of object | null
- Description
Tables rendered as tables in the page text:
{box}.
- Name
pii- Type
- array of object | null
- Description
Located personal data:
type,label,box, andunreliable: truewhen found only in text read with low confidence. Never the matched text.
- Name
pii_truncated- Type
- bool | null
- Description
truewhen a cap discarded some locations, so an emptypiidoes not mean none were found.
- Name
text- Type
- string | null
- Description
The page text an agent receives, without the untrusted-content marking.
- Name
content_flags- Type
- array | null
- Description
Unreliable-text flags of the page.
- Name
verdict- Type
- string | null
- Description
Verdict of the analysis.
- Name
reasons- Type
- array of string
- Description
Finding kinds behind the verdict.
- Name
findings- Type
- array of object
- Description
Findings of the file, one entry per kind, sub-kind, severity, source and label:
code,sub_kind,severity,source,pages,removed_from_agents, andlabelorrule_idwhere the finding has one.
- Name
page_findings- Type
- array of object
- Description
Findings on this page:
code,sub_kind,severity,source,box,removed_from_agents, andlabelorrule_idwhere present.
- Name
removed_passages- Type
- integer
- Description
Number of concealed-text findings whose text is removed from the content agents receive.
- Name
trust- Type
- object
- Description
Same as
trustin the File Analysis Object.
- Name
generation- Type
- integer
- Description
Analysis generation shown.
- Name
state- Type
- string
- Description
publishedorquarantined.
redactions, tables, pii, pii_truncated, text and content_flags are null for a generation that stored no page data.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existresource_not_found- the record does not exist in the collectionfile_page_not_found- the generation has no such page
- Name
409 Conflict- Description
file_download_refused- the page is not available.detail.reasonholds a refusal reason
- Name
429 Too Many Requests- Description
rate_limited- the project is over its view limit. Retry after theRetry-Afterheader
- Name
503 Service Unavailable- Description
download_unavailable- the page data could not be read. Retry
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/qw81ztrc/file/pages/1/detail/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"page": 1,
"of": 2,
"image_url": "https://…",
"image_width": 1240,
"image_height": 1754,
"expires_in": 300,
"redactions": [
{"reason": "hidden_native_text", "box": [0.1, 0.8, 0.9, 0.82], "label": "Hidden text"}
],
"tables": [{"box": [0.1, 0.3, 0.9, 0.6]}],
"pii": [
{"type": "EMAIL", "label": "Email", "box": [0.12, 0.2, 0.4, 0.23]}
],
"pii_truncated": false,
"text": "Invoice 0042 …",
"content_flags": [],
"verdict": "suspicious",
"reasons": ["hidden_text"],
"findings": [
{
"code": "hidden_text",
"sub_kind": null,
"severity": "suspicious",
"source": "pdf_diff",
"pages": [1],
"removed_from_agents": true
}
],
"page_findings": [
{
"code": "hidden_text",
"sub_kind": null,
"severity": "suspicious",
"source": "pdf_diff",
"box": [0.1, 0.8, 0.9, 0.82],
"removed_from_agents": true
}
],
"removed_passages": 1,
"trust": {
"processing": "agent_ready",
"content_tainted": true,
"tainted_paths": ["file.original_filename", "content"]
},
"generation": 1,
"state": "published"
}
Get Files Policy
Returns the live policy of a files collection. A collection with no saved version returns the default body with version null.
Success Response: 200 OK. See the Files Policy Object.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not existcollection_not_found- the specified collection does not exist
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files-policy/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"version": 3,
"enforce_from": 2,
"body": {
"suspicious_action": "quarantine",
"overrides": {"pii": "suspicious"},
"allowed_kinds": ["image", "document"],
"tables": "auto",
"moderation_rules": [],
"original_access": "when_clean"
},
"config_hash": "9f2c…",
"created_at": "2026-11-12T10:02:11+00:00"
}
Update Files Policy
Replaces the policy. Omitted keys take their defaults. A body that matches the live policy changes nothing and returns the live version; any other body is saved as a new version. A stricter policy moves enforce_from and re-verdicts the collection; a looser one can release quarantined files. Changing only original_access re-verdicts nothing.
Success Response: 200 OK. See the Files Policy Object.
Attributes
The keys of the policy body: suspicious_action, overrides, acknowledge_explicit_delivery, allowed_kinds, tables, moderation_rules and original_access. Other keys are rejected. A moderation rule takes label or parent, max_confidence and action; see the Moderation Rule Object.
An overrides entry is refused when it names an unknown kind, an unoverridable kind or a severity outside the range allowed for the kind. An explicit override other than block needs acknowledge_explicit_delivery: true.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is fully blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not existcollection_not_found- the specified collection does not exist
- Name
409 Conflict- Description
original_access_requires_agent_ready-original_access: when_cleanon astorage_onlycollection
- Name
422 Unprocessable Content- Description
validation_error- invalid body, override or moderation rulemoderation_addon_not_installed-moderation_ruleswhile moderation is not turned on for the collection
Request
curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files-policy/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"suspicious_action": "quarantine",
"overrides": {"pii": "suspicious"},
"allowed_kinds": ["image", "document"],
"tables": "auto",
"moderation_rules": [
{"parent": "Explicit Nudity", "max_confidence": 80, "action": "block"}
],
"original_access": "when_clean"
}'
Response
{
"version": 4,
"enforce_from": 4,
"body": {
"suspicious_action": "quarantine",
"overrides": {"pii": "suspicious"},
"allowed_kinds": ["image", "document"],
"tables": "auto",
"moderation_rules": [
{
"id": "no-explicit-nudity",
"label": null,
"parent": "Explicit Nudity",
"max_confidence": 80,
"action": "block"
}
],
"original_access": "when_clean"
},
"config_hash": "c41d…",
"created_at": "2026-11-16T09:30:00+00:00"
}
Turn On Moderation
Turns on moderation for a files collection: adds the read-only moderation field to its records and allows moderation_rules in its policy. Published files that already have moderation results get their stored labels without being processed again. Needs collection-structure update on the collection. Send no body; a non-empty body is refused.
Success Response: 201 Created
- Name
manifest_id- Type
- string
- Description
moderation.
- Name
manifest_version- Type
- integer
- Description
Version of the setting.
- Name
state- Type
- string
- Description
installedwhile moderation is on,retiredonce it is turned off.
- Name
installed_at- Type
- datetime
- Description
When moderation was turned on.
- Name
retired_at- Type
- datetime | null
- Description
When it was turned off, or
null.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is fully blocked
- Name
400 Bad Request- Description
install_body_not_allowed- the request has a non-empty body
- Name
404 Not Found- Description
environment_not_found- the specified environment does not existcollection_not_found- the specified collection does not exist
- Name
409 Conflict- Description
addon_already_installed- moderation is already onaddon_requires_agent_ready- the collection isstorage_onlyaddon_field_conflict- the collection already has a field namedmoderationaddon_transition_limit- the collection reached its limit on add-on changes
- Name
422 Unprocessable Content- Description
addon_not_applicable- the collection is not a files collectionmanaged_contract_violation- the collection's managed fields cannot be read or do not match what moderation needs
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/claims_files/add-ons/moderation/install/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"manifest_id": "moderation",
"manifest_version": 1,
"state": "installed",
"installed_at": "2026-11-17T09:12:44Z",
"retired_at": null
}
Turn Off Moderation
Turns moderation off: removes the collection's moderation_rules. Labels already written stay on the records until a file is re-analyzed or erased. Needs collection-structure update on the collection. Any body is ignored.
Success Response: 200 OK
- Name
manifest_id- Type
- string
- Description
moderation.
- Name
manifest_version- Type
- integer
- Description
Version of the setting.
- Name
state- Type
- string
- Description
installedwhile moderation is on,retiredonce it is turned off.
- Name
installed_at- Type
- datetime
- Description
When moderation was turned on.
- Name
retired_at- Type
- datetime | null
- Description
When it was turned off, or
null.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this actionorganization_blocked- the organization is fully blocked
- Name
404 Not Found- Description
environment_not_found- the specified environment does not existcollection_not_found- the specified collection does not existaddon_not_installed- moderation is not on
- Name
422 Unprocessable Content- Description
managed_contract_violation- the collection's managed fields cannot be read or do not match what moderation needs
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/claims_files/add-ons/moderation/uninstall/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"manifest_id": "moderation",
"manifest_version": 1,
"state": "retired",
"installed_at": "2026-11-17T09:12:44Z",
"retired_at": "2026-11-18T10:03:02Z"
}
Get Moderation Taxonomy
Returns the moderation labels and categories that a policy's moderation_rules may name. Needs collection-structure read.
Success Response: 200 OK
- Name
version- Type
- integer
- Description
Version of the taxonomy.
- Name
max_rules- Type
- integer
- Description
Largest number of rules a policy may hold.
- Name
actions- Type
- array of string
- Description
Actions a rule accepts.
- Name
labels- Type
- array of object
- Description
Taxonomy entries:
name,parent(the parent category, ornull),levelandcategory. Alabelrule accepts everyname; aparentrule accepts a name withcategory: true.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not exist
Request
curl https://api.foxnose.net/v1/7c9h4pwu/files/moderation-taxonomy/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"version": 7,
"max_rules": 50,
"actions": ["info", "suspicious", "block"],
"labels": [
{"name": "Explicit", "parent": null, "level": 1, "category": true},
{"name": "Explicit Nudity", "parent": "Explicit", "level": 2, "category": true},
{"name": "Exposed Male Genitalia", "parent": "Explicit Nudity", "level": 3, "category": false}
]
}
List Tombstones
Lists the blocked and rejected files of a collection, newest first. Personal data of a tombstone (original_filename, raw_payload, uploaded_by, owner_key and finding evidence) is shown until the first of its personal-data stores is erased or falls due; afterwards those fields are null and redacted is true. Codes and dates stay.
Success Response: 200 OK
Paginated with limit and offset; at most 100 results a page.
Tombstone Object
- Name
resource_key- Type
- string | null
- Description
Key of the record the file was uploaded into.
- Name
file_uuid- Type
- string
- Description
Identifier of the file.
- Name
reason- Type
- string
- Description
blockedorrejected.
- Name
public_reason- Type
- string | null
- Description
Coarse reason code.
- Name
error_code- Type
- string | null
- Description
Detailed reason code.
- Name
verdict_reasons- Type
- array of string
- Description
Finding kinds behind the verdict.
- Name
generation- Type
- integer | null
- Description
Analysis generation.
- Name
asset_state- Type
- string
- Description
present,purgingorpurged.
- Name
blocked_at- Type
- datetime | null
- Description
When the erasure started.
- Name
purge_completed_at- Type
- datetime | null
- Description
When the erasure completed.
- Name
redacts_at- Type
- datetime | null
- Description
When personal data is redacted.
- Name
redacted- Type
- bool
- Description
trueonce personal data is redacted.
- Name
original_filename- Type
- string | null
- Description
Name the file was uploaded with.
- Name
raw_payload- Type
- object | null
- Description
Upload record stored for the file.
- Name
uploaded_by- Type
- string | null
- Description
Identifier of the uploader.
- Name
owner_key- Type
- string | null
- Description
Key of the owner the upload was scoped to.
- Name
findings- Type
- array of object
- Description
Findings of the analysis. See Finding.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not exist
Request
curl "https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/files/tombstones/?limit=20" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"resource_key": "a8s2k1lq",
"file_uuid": "0c3d9a2e-1f40-4a6b-8a5e-2d7c6b1e9f33",
"reason": "blocked",
"public_reason": "malware",
"error_code": null,
"verdict_reasons": ["malware"],
"generation": 1,
"asset_state": "purged",
"blocked_at": "2026-11-15T14:00:00+00:00",
"purge_completed_at": "2026-11-15T14:00:09+00:00",
"redacts_at": "2026-12-15T14:00:00+00:00",
"redacted": false,
"original_filename": "scan.pdf",
"raw_payload": {},
"uploaded_by": "5e1f0b7a-…",
"owner_key": "k3mzq9ae",
"findings": []
}
]
}
List Review Queue
Lists the files the environment holds for a reviewer across all its files collections, newest held first. A file is held when its policy quarantines suspicious files and no reviewer has approved it. Only collections and records the caller can read are listed, and count covers only those.
Success Response: 200 OK
Query Parameters
- Name
collection- Type
- string
- Description
Key of a collection to narrow the queue to. A collection that does not exist or cannot be read gives an empty page.
- Name
limit- Type
- integer
- Description
Maximum number of results to return. At most 100.
- Name
offset- Type
- integer
- Description
Number of results to skip for pagination.
Review Queue Row
- Name
resource_key- Type
- string
- Description
Key of the record.
- Name
file_uuid- Type
- string
- Description
Identifier of the file.
- Name
collection- Type
- string
- Description
Key of the collection.
- Name
file_name- Type
- string | null
- Description
Name the file was uploaded with.
- Name
generation- Type
- integer
- Description
Analysis generation.
- Name
state- Type
- string
- Description
Pipeline state.
- Name
verdict- Type
- string | null
- Description
Verdict of the analysis.
- Name
verdict_reasons- Type
- array of string
- Description
Finding kinds behind the verdict.
- Name
public_reason- Type
- string | null
- Description
Coarse reason code.
- Name
findings- Type
- object
- Description
Summary of live findings:
total,by_kindandby_severity(maps of name to count).
- Name
owner- Type
- object | null
- Description
The record's owner.
nullfor a collection withoutstrict_reference.
- Name
held_at- Type
- datetime | null
- Description
When the file started waiting for a reviewer.
- Name
thumbnail_url- Type
- string | null
- Description
Short-lived thumbnail URL.
nullfor a caller who is not the record's reviewer, for a file held by moderation, and when the project is over its view limit.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions to perform this action
- Name
404 Not Found- Description
not_found- the collection or file does not existenvironment_not_found- the specified environment does not exist
Request
curl "https://api.foxnose.net/v1/7c9h4pwu/files/review/?collection=invoices" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"resource_key": "qw81ztrc",
"file_uuid": "5b0e3c1a-7a4e-4f0e-9b57-0f6c2f6d9d11",
"collection": "invoices",
"file_name": "invoice-0042.pdf",
"generation": 1,
"state": "awaiting_publish",
"verdict": "suspicious",
"verdict_reasons": ["hidden_text"],
"public_reason": null,
"findings": {
"total": 1,
"by_kind": {"hidden_text": 1},
"by_severity": {"suspicious": 1}
},
"owner": null,
"held_at": "2026-11-16T09:14:31+00:00",
"thumbnail_url": "https://…"
}
]
}
Upload Link Object
A hosted upload link as returned by List, Get and Revoke.
- Name
upload_id- Type
- string
- Description
Identifier of the link.
- Name
created_by- Type
- object | null
- Description
Creator:
kind(userorapi_key),label(the name or description, filled only for callers who can see actors in the activity log) and the creator's identifier underuserorkey.
- Name
owner_key- Type
- string | null
- Description
Key of the record the files belong to.
nullwhen the caller cannot read it.
- Name
title- Type
- string | null
- Description
Title shown on the upload page.
- Name
instructions- Type
- string | null
- Description
Instructions shown on the upload page.
- Name
max_files- Type
- integer
- Description
Number of files the link accepts.
- Name
allowed_kinds- Type
- array of string
- Description
File kinds the link accepts: the link's own kinds limited by the collection's live policy.
- Name
consumed_count- Type
- integer
- Description
Number of files uploaded through the link.
- Name
created_at- Type
- datetime
- Description
Timestamp when the link was created.
- Name
expires_at- Type
- datetime
- Description
Timestamp when the link stops accepting uploads.
- Name
revoked_at- Type
- datetime | null
- Description
Timestamp when the link was revoked.
- Name
state- Type
- string
- Description
active,consumed,expiredorrevoked. A revoked link staysrevoked.
- Name
sessions- Type
- array of object
- Description
Upload sessions, oldest first:
created_at,expires_atandfiles. Each file entry hasstate(processing,ready,pending_revieworrejected),record_key(set forreadywhen the caller can read the record),public_reason(forrejected),file_name(when the caller can read the record) andprogress({step, of, step_name}over four steps:uploaded,malware_scan,analysis,ready).
The link token is returned once, in the upload_url of Create Upload Link, and is stored hashed.
Create Upload Link
Creates a hosted upload link for a collection with strict_reference. The owner must be a record the caller can read. A file uploaded through the link is published when processing accepts it; otherwise it waits for review or is rejected.
Success Response: 201 Created
Attributes
- Name
owner- Type
- string
- Required
- required
- Description
Key of the record the files belong to
- Maximum length: 64
- Name
title- Type
- string
- Required
- required
- Description
Title shown on the upload page
- Length: 1 to 80 characters after trimming
- No control characters
- Name
instructions- Type
- string
- Default
- default:null
- Description
Plain-text instructions shown on the upload page
- Maximum length: 500
- Line feeds allowed, other control characters not
- Name
max_files- Type
- integer
- Default
- default:1
- Description
Number of files the link accepts, from 1 to 10
- Name
allowed_kinds- Type
- array of string
- Default
- default:null
- Description
Narrows the collection's allowed kinds for this link:
image,document,archive. At least one value, each allowed by the collection's live policy.nullinherits the collection's kinds.
- Name
expires_in- Type
- integer
- Default
- default:1800
- Description
Lifetime in seconds, from 300 to 86400
Other keys are rejected.
Response
- Name
upload_id- Type
- string
- Description
Identifier of the link.
- Name
title- Type
- string
- Description
Title.
- Name
instructions- Type
- string | null
- Description
Instructions.
- Name
upload_url- Type
- string
- Description
The link to send to the uploader,
https://<host>/u#<token>. Returned once.
- Name
expires_at- Type
- datetime
- Description
Expiry time in ISO 8601 format.
- Name
max_files- Type
- integer
- Description
Number of files the link accepts.
- Name
allowed_kinds- Type
- array of string
- Description
Effective kinds of the link.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions, or the key belongs to another environmentorganization_blocked- the organization is fully blocked
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not existowner_not_found- the owner does not exist or the caller cannot read it
- Name
422 Unprocessable Content- Description
validation_error- invalid body, a kind the collection's policy does not allow, or a collection whose schema cannot accept uploadscollection_not_strict- the collection does not havestrict_referenceowner_required- no owner was given
The collection_not_strict, owner_required and owner_not_found responses carry the code under both code and error_code.
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/upload-links/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"owner": "k3mzq9ae",
"title": "Documents for your claim",
"instructions": "Upload the signed form and photos.",
"max_files": 5,
"allowed_kinds": ["image", "document"],
"expires_in": 3600
}'
Response
{
"upload_id": "up_eu1_7d21c4…",
"title": "Documents for your claim",
"instructions": "Upload the signed form and photos.",
"upload_url": "https://7c9h4pwu.example/u#q3J…",
"expires_at": "2026-11-16T10:30:00+00:00",
"max_files": 5,
"allowed_kinds": ["document", "image"]
}
List Upload Links
Lists the collection's upload links, newest first, with their sessions and per-file statuses. See the Upload Link Object.
Success Response: 200 OK
Query Parameters
- Name
state- Type
- string
- Default
- default:all
- Description
Given once.
active- not revoked, not consumed and not expiredended- the restall- every link
- Name
limit- Type
- integer
- Description
Maximum number of results to return. At most 100.
- Name
offset- Type
- integer
- Description
Number of results to skip for pagination.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions, or the key belongs to another environment
- Name
404 Not Found- Description
not_found- the collection or file does not existcollection_not_found- the specified collection does not exist
- Name
422 Unprocessable Content- Description
validation_error-stateis empty, repeated or not one of the listed values
Request
curl "https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/upload-links/?state=active" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"upload_id": "up_eu1_7d21c4…",
"created_by": {"kind": "user", "label": "Ada Lovelace", "user": "5e1f0b7a-…"},
"owner_key": "k3mzq9ae",
"title": "Documents for your claim",
"instructions": "Upload the signed form and photos.",
"max_files": 5,
"allowed_kinds": ["document", "image"],
"consumed_count": 1,
"created_at": "2026-11-16T09:30:00+00:00",
"expires_at": "2026-11-16T10:30:00+00:00",
"revoked_at": null,
"state": "active",
"sessions": [
{
"created_at": "2026-11-16T09:40:00+00:00",
"expires_at": "2026-11-16T10:30:00+00:00",
"files": [
{
"state": "ready",
"record_key": "qw81ztrc",
"file_name": "form.pdf",
"progress": {"step": 4, "of": 4, "step_name": null}
}
]
}
]
}
]
}
Get Upload Link
Returns one upload link. See the Upload Link Object. The upload_url is not returned again.
Success Response: 200 OK
Path Parameters
- Name
:upload_id- Type
- string
- Description
Identifier of the link
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions, or the key belongs to another environment
- Name
404 Not Found- Description
not_found- the collection or file does not exist, or the link does not exist in this collection (body{"code": "not_found"})collection_not_found- the specified collection does not exist
Request
curl https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/upload-links/up_eu1_7d21c4…/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"upload_id": "up_eu1_7d21c4…",
"created_by": {"kind": "api_key", "label": null, "key": "9b2e6c1d-…"},
"owner_key": "k3mzq9ae",
"title": "Documents for your claim",
"instructions": null,
"max_files": 5,
"allowed_kinds": ["document", "image"],
"consumed_count": 0,
"created_at": "2026-11-16T09:30:00+00:00",
"expires_at": "2026-11-16T10:30:00+00:00",
"revoked_at": null,
"state": "active",
"sessions": []
}
Revoke Upload Link
Revokes an upload link. The link mints no further grants and refuses every upload not completed before the revoke. Files already uploaded are unaffected. Revoking a revoked link returns the same result. The request has no body.
Success Response: 200 OK. The Upload Link Object with state revoked.
Errors
- Name
400 Bad Request- Description
collection_not_file_backed- the collection is not a files collection
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
403 Forbidden- Description
permission_denied- insufficient permissions, or the key belongs to another environment
- Name
404 Not Found- Description
not_found- the collection or file does not exist, or the link does not exist in this collection or its owner cannot be read by the caller (body{"code": "not_found"})collection_not_found- the specified collection does not exist
Request
curl -X POST https://api.foxnose.net/v1/7c9h4pwu/collections/invoices/upload-links/up_eu1_7d21c4…/revoke/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"upload_id": "up_eu1_7d21c4…",
"state": "revoked",
"revoked_at": "2026-11-16T09:50:00+00:00"
}
Get File Processing Usage
Splits the file units of a billing period by what they were spent on. Defaults to the open period. Available to the organization's owner and to members holding a permission in the organization. See file units.
Authentication: JWT
Success Response: 200 OK
Query Parameters
- Name
period_uid- Type
- string
- Description
Identifier of one of the organization's billing periods. Defaults to the open period.
Response
- Name
enabled- Type
- bool
- Description
Whether file units are billed in the period.
falsewhen the organization has no period.
- Name
breakdown- Type
- object | null
- Description
nullwhenenabledisfalse. Otherwiseperiod_uid,period_start,period_end,total_units,total_half_unitsandby_kind: entries withkind(files,pages,table_analysis, orotherfor events not covered by those),units,half_unitsandevents.
Errors
- Name
401 Unauthorized- Description
authentication_failed- authentication credentials were not provided or are invalid
- Name
404 Not Found- Description
organization_not_found- the organization does not exist or the caller has no accessnot_found- the billing period does not exist
Request
curl https://api.foxnose.net/organizations/dl55w3ds/usage/file-processing/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."
Response
{
"enabled": true,
"breakdown": {
"period_uid": "3f6c1d52-6b0a-4d8e-9a21-0e8f7c4b9a10",
"period_start": "2026-11-01T00:00:00+00:00",
"period_end": "2026-12-01T00:00:00+00:00",
"total_units": 112.5,
"total_half_units": 225,
"by_kind": [
{"kind": "files", "units": 40, "half_units": 80, "events": 80},
{"kind": "pages", "units": 60, "half_units": 120, "events": 120},
{"kind": "table_analysis", "units": 12.5, "half_units": 25, "events": 25}
]
}
}