TypeScript Library

The library wraps the APIs so you can parse and extract documents from TypeScript and JavaScript. The library is published as the landingai-ade package and generated from the API specification. The v2 APIs live under the client.v2 sub-client (for example, client.v2.parse).

Install the Library

npm install landingai-ade

Set Your API Key

The library reads your API key from the VISION_AGENT_API_KEY environment variable. Generate an API key first, then set it using any of the methods below. Do not hard-code your API key in source files.

Method 1: Set the API Key as an Environment Variable

Set the environment variable. To persist the key across sessions on macOS or Linux, add the export command to your shell profile (.zshrc or .bashrc), then run source ~/.zshrc.
export VISION_AGENT_API_KEY="<your-api-key>"
set "VISION_AGENT_API_KEY=<your-api-key>"
$env:VISION_AGENT_API_KEY="<your-api-key>"
Initialize the client. It reads the VISION_AGENT_API_KEY environment variable automatically:
import LandingAIADE from "landingai-ade"; const client = new LandingAIADE();

Method 2: Store the API Key in a .env File

Store your API key in a .env file. The library reads the key from the environment; it does not load .env files on its own, so use the dotenv package to load the file.

Install the dotenv package:
npm install dotenv
Create a .env file in your project root and add your API key:
VISION_AGENT_API_KEY=<your-api-key>

Load the .env file before you initialize the client:

import "dotenv/config"; // Loads .env into process.env.
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

In Node.js 20.6 or later, you can skip the dotenv package and run your script with node --env-file=.env your-script.js.

API Key Precedence

If the API key is set in more than one place, the library resolves it in this order (the first match wins):

The apikey passed to the client constructor.
The VISION_AGENT_API_KEY environment variable, whether you set it directly or loaded it from a .env file. A value already set in your environment is not overridden by a .env file.

For help with missing-key errors, keys that fail to load, or keys that resolve to the wrong account, see Troubleshoot API Key Issues.

Initialize the Client

Create a client. It reads VISION_AGENT_API_KEY from the environment automatically.

import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

By default, the library uses the US endpoints. If your API key is from the EU region, set the environment option to eu. API keys are region-specific: an EU key works only with the EU environment.

import LandingAIADE from "landingai-ade";

const client = new LandingAIADE({ environment: "eu" });

For more about using in the EU, see European Union (EU).

Parse a Document

Use client.v2.parse to convert a document into Markdown, a structure tree, and per-element grounding. Pass a local file as a read stream with the document parameter, or a remote file with document_url.

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const response = await client.v2.parse({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
});
console.log(response.markdown);

The response is a V2ParseResponse with markdown, structure, and metadata. For the full parameters and response shape, see Parse Documents.

Extract Data

Use client.v2.extract to pull structured fields from parsed Markdown. Provide the Markdown as a string with markdown (or a remote URL with markdown_url) and a schema. The schema parameter accepts a JSON Schema object or a JSON string.

import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

// Parse first to get Markdown, then extract.
const parseResponse = await client.v2.parse({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
});

const extractResponse = await client.v2.extract({
  markdown: parseResponse.markdown,
  schema: {
    type: "object",
    properties: {
      revenue: { type: "string", description: "Q1 2024 revenue" },
    },
  },
});
console.log(extractResponse.extraction);

The response is a V2ExtractResult with extraction, extraction_metadata, markdown, and metadata. For the full parameters and response shape, see Extract Data.

To define a typed schema, use Zod (v4 or later) and pass z.toJSONSchema(YourSchema) as the schema.

Process Documents Asynchronously

For large documents or long-running work, use the async jobs interface. The client exposes parseJobs and extractJobs, each with create, get, list, and wait methods. The wait method polls until the job reaches a terminal state and returns the finished job.

import fs from "fs";
import LandingAIADE, { type V2ParseResponse } from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
});
const done = await client.v2.parseJobs.wait(job.job_id);
console.log((done.result as V2ParseResponse).markdown);

Set the optional service_tier parameter on create to "priority" for faster turnaround, or omit it to run on the standard tier. For the full workflow, service tiers, and saving output to a URL, see Parse Asynchronously and Asynchronous Extraction.

Set the Model Version

The model parameter is optional. When you omit it, the API uses the latest model. To pin a specific version, pass a model string such as dpt-3-pro-latest or a dated snapshot. See Model Version.

import fs from "fs";

const response = await client.v2.parse({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
});

Save Output to a File

Pass the optional saveTo parameter on parse or extract to write the full response to a JSON file. Pass a directory to use an auto-generated file name, or a path ending in .json to choose the exact file. The async job create methods do not accept saveTo.

import fs from "fs";

const response = await client.v2.parse({
  document: fs.createReadStream("document.pdf"),
  saveTo: "./output",
});

Handle Errors

The synchronous parse and extract methods throw V2SyncTimeoutError if the request exceeds the server’s synchronous time limit (HTTP 504). For large documents, use the async jobs interface instead. When a parse partially succeeds (some pages fail), the API returns the full response with an HTTP 206 status, and the failed pages are listed in metadata. See Troubleshoot Parsing. The job wait method returns the finished job regardless of outcome, so check job.status. To throw instead when a job fails, pass raiseOnFailure: true, which throws JobFailedError. If a job does not finish within the timeout, wait throws JobWaitTimeoutError. These v2 helper errors do not extend APIError, so catch them by name.

import fs from "fs";
import LandingAIADE, { JobFailedError, JobWaitTimeoutError, type V2ParseResponse } from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
});
try {
  const done = await client.v2.parseJobs.wait(job.job_id, { timeout: 600000, raiseOnFailure: true });
  console.log((done.result as V2ParseResponse).markdown);
} catch (error) {
  if (error instanceof JobFailedError) {
    console.error(`Job failed: ${error.message}`);
  } else if (error instanceof JobWaitTimeoutError) {
    console.error("Job did not finish in time; poll again with parseJobs.get().");
  } else {
    throw error;
  }
}

Additional Resources

TypeScript library on GitHub. The README covers client configuration not documented here, including retries, timeouts, logging, raw response access, and customizing the fetch client.
API reference
Parse Documents and Extract Data

Get Started

Client Libraries

Parsing

Extraction

General

Security

Administration

TypeScript Library

Install the Library

Set Your API Key

Method 1: Set the API Key as an Environment Variable

Method 2: Store the API Key in a .env File

API Key Precedence

Initialize the Client

Parse a Document

Extract Data

Process Documents Asynchronously

Set the Model Version

Save Output to a File

Handle Errors

Additional Resources

​Install the Library

​Set Your API Key

​Method 1: Set the API Key as an Environment Variable

​Method 2: Store the API Key in a .env File

​API Key Precedence

​Initialize the Client

​Parse a Document

​Extract Data

​Process Documents Asynchronously

​Set the Model Version

​Save Output to a File

​Handle Errors

​Additional Resources

Install the Library

Set Your API Key

Method 1: Set the API Key as an Environment Variable

Method 2: Store the API Key in a .env File

API Key Precedence

Initialize the Client

Parse a Document

Extract Data

Process Documents Asynchronously

Set the Model Version

Save Output to a File

Handle Errors

Additional Resources