Files

Authentication: JWT | API Key

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

EndpointsRequired permissions
Analysis, downloads, page detail, tombstones, review queue, list and read upload linksresources read and collection-items read
Approve, reject, re-analyzeresources update and collection-items read
Upload grant, create and revoke upload linkresources create and collection-items read
Upload grant that replaces a resourceresources create and update
Read policy, moderation taxonomycollection-structure read
Update policycollection-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. null for 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. null when 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 verdict
    • quarantine - the file waits for a reviewer
  • Name
    overrides
    Type
    object
    Default
    default:{}
    Description

    Map of finding kind to severity (block, suspicious or info). The allowed severities per kind are listed under finding kinds. malware, policy_rule and active_content accept no override.

  • Name
    acknowledge_explicit_delivery
    Type
    bool
    Default
    default:false
    Description

    Must be true when overrides.explicit is suspicious or info. The stored body keeps it only while an explicit override 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 allows document admits archive files.

  • Name
    tables
    Type
    string
    Default
    default:auto
    Description

    Table analysis for analyses that start after the change: auto, never or always.

  • 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_clean or disabled. A new agent_ready collection starts with when_clean. See original access.


Moderation Rule Object

  • Name
    label
    Type
    string | null
    Description

    A moderation label from the moderation taxonomy. Exactly one of label and parent is 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_rule finding the rule raises: block, suspicious or info.

  • Name
    id
    Type
    string
    Description

    Read-only. Derived from the action and the label or category: no-<slug> for block, review-<slug> for suspicious, tag-<slug> for info. An id sent 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. null for 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, purging or purged.

  • Name
    tombstone
    Type
    bool
    Description

    true when 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_ready or storage_only), content_tainted (bool) and tainted_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. null for a record with no file.

    • original and safe_copy - {available, reason}. reason is null when available is true; otherwise it is a download refusal reason.
    • active_content - {present, kinds, truncated}. present is null when the file was not checked. See active content.
    • original_access - the collection's original_access value.
    • origin - where the file came from, or null: channel (dashboard, management_api, upload_link, signed_upload or null), external (bool), created_by ({kind, name} or null), upload_link ({upload_id, title} or null) and end_user (string or null).

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, failed or a processing step.

  • Name
    verdict
    Type
    string | null
    Description

    clean, suspicious, blocked or rejected, 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_large or processing_failed.

  • Name
    error_code
    Type
    string | null
    Description

    Detailed reason code for a refused or failed file.

  • Name
    in_review
    Type
    bool
    Description

    true while 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 state last 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, suspicious or block.

  • 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. null once the file's personal data is redacted.

  • Name
    detail
    Type
    object | null
    Description

    Structured facts. Set for active_content (kinds, truncated) and pii (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_rule finding.


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.

reasonMeaning
forbiddenQuarantined, and the caller is not a reviewer.
withheld_by_moderationQuarantined by moderation: no safe copy or pages.
processingBeing scanned or analyzed.
failedProcessing failed.
not_publishedNever published.
blocked, rejected, erasedThe file is unavailable; its bytes are erased or being erased.
not_generatedNo safe copy or page for this analysis.
original_unavailableThe stored original cannot be found.
legacy_original_download_unsupportedThe original of this file cannot be downloaded.
original_withheldoriginal_access is when_clean and the file is not clean. detail.safe_copy says whether the safe copy is available.
original_disabledoriginal_access is disabled.

POSTapi.foxnose.net/v1/:env/collections/:collection/upload/

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 ready
    • draft - 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 with target_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, project and env. 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 carries axis (file_units), reason (plan_exhausted or spend_cap_reached), used_units (reserved units included), included_units, cap_usd, window_resets_at, and upgrade_url or raise_cap_url. A hosted upload link answers with {"code": "files_quota_exceeded"} only
  • Name
    403 Forbidden
    Description
    • permission_denied - insufficient permissions to perform this action
    • organization_blocked - the organization is blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • environment_not_found - the specified environment does not exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the replacement target does not exist in the collection
    • resource_owner_not_found - the owner does not exist
  • Name
    422 Unprocessable Content
    Description
    • validation_error - invalid body, mode: instant on a collection that requires file data, mode: draft with target_resource_key, or a collection whose schema cannot accept uploads
    • resource_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 the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • files_quota_unavailable - the allowance could not be read. Nothing was admitted. Retry after the Retry-After header

Request

POST
/v1/:env/collections/:collection/upload/
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
}

GETapi.foxnose.net/v1/:env/collections/:collection/files/:resource/analysis/

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 exist
    • environment_not_found - the specified environment does not exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection

Request

GET
/v1/:env/collections/:collection/files/:resource/analysis/
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
        }
    }
}

POSTapi.foxnose.net/v1/:env/collections/:collection/files/:resource/approve/

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_publish or reverdict. A file uploaded in draft mode answers awaiting_publish: its uploader then publishes it.

  • Name
    reason
    Type
    string | null
    Description

    awaiting_user when 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 action
    • organization_blocked - the organization is blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • collection_not_found - the specified collection does not exist
    • resource_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 analysis
    • file_not_in_review - the file is not waiting for a reviewer, including a file already approved or published
    • file_quarantined - the file is still quarantined
    • file_erased - the file was erased

Request

POST
/v1/:env/collections/:collection/files/:resource/approve/
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 }
}

POSTapi.foxnose.net/v1/:env/collections/:collection/files/:resource/reject/

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 action
    • organization_blocked - the organization is fully blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • collection_not_found - the specified collection does not exist
    • resource_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 analysis
    • file_not_in_review - the file is not waiting for a reviewer
    • file_erased - the file was erased

Request

POST
/v1/:env/collections/:collection/files/:resource/reject/
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
    }
}

POSTapi.foxnose.net/v1/:env/collections/:collection/files/:resource/reanalyze/

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 carries axis (file_units), reason (plan_exhausted or spend_cap_reached), used_units (reserved units included), included_units, cap_usd, window_resets_at, and upgrade_url or raise_cap_url.
  • Name
    403 Forbidden
    Description
    • permission_denied - insufficient permissions to perform this action
    • organization_blocked - the organization is blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection
  • Name
    409 Conflict
    Description
    • file_not_ready - the record has no file
    • file_erased - the file was erased
    • file_not_scanned - no analysis of the file has passed the malware scan yet
    • original_unavailable - the original needed for the analysis is not stored
    • reanalysis_requires_agent_ready - the collection is storage_only, which has no content analysis to redo
  • Name
    429 Too Many Requests
    Description
    • rate_limited - the processing budget refuses new work. Retry after the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • files_quota_unavailable - the allowance could not be read. Nothing was admitted. Retry after the Retry-After header

Request

POST
/v1/:env/collections/:collection/files/:resource/reanalyze/
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_copy or page.

  • Name
    filename
    Type
    string | null
    Description

    Suggested file name.

  • Name
    content_type
    Type
    string | null
    Description

    application/octet-stream for an original, application/pdf for a safe-copy PDF, image/png for 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, or quarantined for 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 (with present, kinds and truncated) when the file carries active content, suspicious_findings when it has a suspicious or higher finding.


GETapi.foxnose.net/v1/:env/collections/:collection/files/:resource/file/original/

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 exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection
  • Name
    409 Conflict
    Description

    The download is refused. detail.reason holds a refusal reason. For original_disabled, original_withheld, original_unavailable and legacy_original_download_unsupported the error_code is the reason itself; otherwise it is file_download_refused. original_withheld also carries detail.safe_copy.

  • Name
    429 Too Many Requests
    Description
    • rate_limited - the project mints download URLs too fast. Retry after the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • download_unavailable - the URL could not be prepared. Retry

Request

GET
/v1/:env/collections/:collection/files/:resource/file/original/
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}
    }
}

GETapi.foxnose.net/v1/:env/collections/:collection/files/:resource/file/safe-copy/

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 exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection
  • Name
    409 Conflict
    Description
    • file_download_refused - the download is refused. detail.reason holds a refusal reason
  • Name
    429 Too Many Requests
    Description
    • rate_limited - the project mints download URLs too fast. Retry after the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • download_unavailable - the URL could not be prepared. Retry

Request

GET
/v1/:env/collections/:collection/files/:resource/file/safe-copy/
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": []
}

GETapi.foxnose.net/v1/:env/collections/:collection/files/:resource/file/pages/:page/

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 exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection
    • file_page_not_found - the generation has no such page
  • Name
    409 Conflict
    Description
    • file_download_refused - the download is refused. detail.reason holds a refusal reason
  • Name
    429 Too Many Requests
    Description
    • rate_limited - the project mints download URLs too fast. Retry after the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • download_unavailable - the URL could not be prepared. Retry

Request

GET
/v1/:env/collections/:collection/files/:resource/file/pages/:page/
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": []
}

GETapi.foxnose.net/v1/:env/collections/:collection/files/:resource/file/pages/:page/detail/

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_url expires.

  • Name
    redactions
    Type
    array of object | null
    Description

    Regions withheld from the page: reason (low_legibility, hidden_native_text, unread_text_region or degenerate_clip), box and label. 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, and unreliable: true when found only in text read with low confidence. Never the matched text.

  • Name
    pii_truncated
    Type
    bool | null
    Description

    true when a cap discarded some locations, so an empty pii does 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, and label or rule_id where 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, and label or rule_id where 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 trust in the File Analysis Object.

  • Name
    generation
    Type
    integer
    Description

    Analysis generation shown.

  • Name
    state
    Type
    string
    Description

    published or quarantined.

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 exist
    • collection_not_found - the specified collection does not exist
    • resource_not_found - the record does not exist in the collection
    • file_page_not_found - the generation has no such page
  • Name
    409 Conflict
    Description
    • file_download_refused - the page is not available. detail.reason holds a refusal reason
  • Name
    429 Too Many Requests
    Description
    • rate_limited - the project is over its view limit. Retry after the Retry-After header
  • Name
    503 Service Unavailable
    Description
    • download_unavailable - the page data could not be read. Retry

Request

GET
/v1/:env/collections/:collection/files/:resource/file/pages/:page/detail/
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"
}

GETapi.foxnose.net/v1/:env/collections/:collection/files-policy/

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 exist
    • environment_not_found - the specified environment does not exist
    • collection_not_found - the specified collection does not exist

Request

GET
/v1/:env/collections/:collection/files-policy/
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"
}

PUTapi.foxnose.net/v1/:env/collections/:collection/files-policy/

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 action
    • organization_blocked - the organization is fully blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • environment_not_found - the specified environment does not exist
    • collection_not_found - the specified collection does not exist
  • Name
    409 Conflict
    Description
    • original_access_requires_agent_ready - original_access: when_clean on a storage_only collection
  • Name
    422 Unprocessable Content
    Description
    • validation_error - invalid body, override or moderation rule
    • moderation_addon_not_installed - moderation_rules while moderation is not turned on for the collection

Request

PUT
/v1/:env/collections/:collection/files-policy/
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"
}

POSTapi.foxnose.net/v1/:env/collections/:collection/add-ons/moderation/install/

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

    installed while moderation is on, retired once 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 action
    • organization_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 exist
    • collection_not_found - the specified collection does not exist
  • Name
    409 Conflict
    Description
    • addon_already_installed - moderation is already on
    • addon_requires_agent_ready - the collection is storage_only
    • addon_field_conflict - the collection already has a field named moderation
    • addon_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 collection
    • managed_contract_violation - the collection's managed fields cannot be read or do not match what moderation needs

Request

POST
/v1/:env/collections/:collection/add-ons/moderation/install/
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
}

POSTapi.foxnose.net/v1/:env/collections/:collection/add-ons/moderation/uninstall/

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

    installed while moderation is on, retired once 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 action
    • organization_blocked - the organization is fully blocked
  • Name
    404 Not Found
    Description
    • environment_not_found - the specified environment does not exist
    • collection_not_found - the specified collection does not exist
    • addon_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

POST
/v1/:env/collections/:collection/add-ons/moderation/uninstall/
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"
}

GETapi.foxnose.net/v1/:env/files/moderation-taxonomy/

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, or null), level and category. A label rule accepts every name; a parent rule accepts a name with category: 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 exist
    • environment_not_found - the specified environment does not exist

Request

GET
/v1/:env/files/moderation-taxonomy/
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}
    ]
}

GETapi.foxnose.net/v1/:env/collections/:collection/files/tombstones/

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

    blocked or rejected.

  • 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, purging or purged.

  • 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

    true once 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 exist
    • collection_not_found - the specified collection does not exist

Request

GET
/v1/:env/collections/:collection/files/tombstones/
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": []
        }
    ]
}

GETapi.foxnose.net/v1/:env/files/review/

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_kind and by_severity (maps of name to count).

  • Name
    owner
    Type
    object | null
    Description

    The record's owner. null for a collection without strict_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. null for 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 exist
    • environment_not_found - the specified environment does not exist

Request

GET
/v1/:env/files/review/
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://…"
        }
    ]
}

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 (user or api_key), label (the name or description, filled only for callers who can see actors in the activity log) and the creator's identifier under user or key.

  • Name
    owner_key
    Type
    string | null
    Description

    Key of the record the files belong to. null when 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, expired or revoked. A revoked link stays revoked.

  • Name
    sessions
    Type
    array of object
    Description

    Upload sessions, oldest first: created_at, expires_at and files. Each file entry has state (processing, ready, pending_review or rejected), record_key (set for ready when the caller can read the record), public_reason (for rejected), file_name (when the caller can read the record) and progress ({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.


POSTapi.foxnose.net/v1/:env/collections/:collection/upload-links/

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. null inherits 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 environment
    • organization_blocked - the organization is fully blocked
  • Name
    404 Not Found
    Description
    • not_found - the collection or file does not exist
    • collection_not_found - the specified collection does not exist
    • owner_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 uploads
    • collection_not_strict - the collection does not have strict_reference
    • owner_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

POST
/v1/:env/collections/:collection/upload-links/
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"]
}

GETapi.foxnose.net/v1/:env/collections/:collection/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 expired
    • ended - the rest
    • all - 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 exist
    • collection_not_found - the specified collection does not exist
  • Name
    422 Unprocessable Content
    Description
    • validation_error - state is empty, repeated or not one of the listed values

Request

GET
/v1/:env/collections/:collection/upload-links/
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}
                        }
                    ]
                }
            ]
        }
    ]
}

GETapi.foxnose.net/v1/:env/collections/:collection/upload-links/:upload_id/

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

GET
/v1/:env/collections/:collection/upload-links/:upload_id/
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": []
}

POSTapi.foxnose.net/v1/:env/collections/:collection/upload-links/:upload_id/revoke/

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

POST
/v1/:env/collections/:collection/upload-links/:upload_id/revoke/
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"
}

GETapi.foxnose.net/organizations/:org/usage/file-processing/

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. false when the organization has no period.

  • Name
    breakdown
    Type
    object | null
    Description

    null when enabled is false. Otherwise period_uid, period_start, period_end, total_units, total_half_units and by_kind: entries with kind (files, pages, table_analysis, or other for events not covered by those), units, half_units and events.

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 access
    • not_found - the billing period does not exist

Request

GET
/organizations/:org/usage/file-processing/
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}
        ]
    }
}

Was this page helpful?