Run

Run vision analysis on an image or PDF. The SDK handles upload, polling, and returns a structured envelope. The CLI is useful for one-off analysis and debugging.

SDK

import { createDocex } from "docexdev";

const docex = createDocex({
  apiKey: process.env.DOCEX_API_KEY,
  baseUrl: process.env.DOCEX_BASE_URL,
});

const result = await docex.run({
  file: "./invoice.pdf",
  prompt: "Extract line items, totals, and vendor details",
  outputFormat: "json",     // optional, default: "json"
  schemaId: "invoice/global-accounts-payable",  // optional
  schema: undefined,        // optional inline schema
  workflow: "fast",         // optional
  metadata: { source: "uploads-api" },  // optional
});

Parameters

Parameter	Type	Required	Description
`file`	`string \| { fileName, data }`	Yes	Local file path or object with `fileName` and `data` (Uint8Array/Buffer)
`prompt`	`string`	Yes	Plain-English description of the analysis task
`outputFormat`	`"json" \| "text"`	No	Output format. Default: `"json"`
`schemaId`	`string`	No	Built-in registry schema identifier
`schema`	`object`	No	Inline custom schema with `label`, `expectedFields`, and `promptScaffold`
`workflow`	`string`	No	Optional workflow label for dashboard filtering
`metadata`	`object`	No	Arbitrary metadata attached to the job

Response

The SDK polls automatically and returns the completed run envelope:

{
  "status": "completed",
  "result": { ... },
  "usage": { "requests": 1, "costUsd": 0.0321, "priceUsd": 0.0642 },
  "chargedUsd": 0.0642,
  "confidence": 0.95,
  "metadata": {}
}

CLI

# Analyze a local file
docex run invoice.pdf --prompt "Extract line items and totals"

# Specify output format
docex run screenshot.png --prompt "is_phishing, confidence_score" --format json

# Use a built-in schema
docex run license.heic --schema-id "trade-license/uae"

# Override env vars
docex run image.png --prompt "..." --api-key dx_live_... --base-url https://api.docex.dev