---
title: "Analyze a Box file without downloading it manually"
method: POST
path: "/api/v1/dms/box/analyze"
tags: ["DMS"]
---

# Analyze a Box file without downloading it manually

`POST /api/v1/dms/box/analyze`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/dms/box/analyze`
- Auth: HTTP bearer

Pass a Box file_id and Nexus downloads + extracts the text (Gemini OCR for .pdf/.docx, direct read for .txt/.md) + analyzes it with Node A. Charges 1 credit only on success. The user behind the API key must have an active Box connection in dms_connections. Max file size: 50 MB.

## Request body

- object
  - `file_id` string, required: Box file id (16 digits)
  - `jurisdiction` string, required
  - `legal_branch` string: Default: civil
  - `language` string
  - `mode` 'standard' | 'deep': deep = Node B audit (Premium)
  - `write_metadata` boolean: Writes the analysis result back to the Box file as metadata (global properties template: nexus_jurisdiction, nexus_legal_branch, nexus_risk, nexus_summary, nexus_model, nexus_analyzed_at). Best-effort: the analysis does not fail if the write fails. Requires the Box root_readwrite scope (already granted).

## Response `200`

{ analysis, jurisdiction, legalBranch, model, processingMs, metadata_written, source: {provider, file_id, file_name, ...} }

## Other responses

- `402`: INSUFFICIENT_CREDITS — balance < 1 | SPEND_CAP_REACHED — the key's monthly cap (per-key monthly cap; `debitCredits` now receives `apiKeyId`). type `insufficient_credits_error`, code `SPEND_CAP_REACHED`, not retryable.
- `403`: BOX_NOT_CONNECTED | INSUFFICIENT_SCOPE
- `409`: BYO_PROVIDER_REQUIRED — BYO-mandatory account without an enabled BYO configuration (fail-closed, no charge).
- `413`: FILE_TOO_LARGE — file > 50 MB
- `422`: `OUTPUT_WITHHELD_BY_POLICY` (type `policy_error`) — enforced surface (parity with `/v1/analyze`): delegated verification enforcement active and the output had real broken citations. **No credits are charged.** `error.details` follows the `WithholdDetails` schema.

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)