> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landing.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Library

> Process documents using the ADE TypeScript library.

export const adeTypeScriptLibrary = 'ade-typescript';

export const dpt3pro = 'DPT-3 Pro';

export const ade = 'Agentic Document Extraction';

The [{adeTypeScriptLibrary}](https://github.com/landing-ai/ade-typescript) library wraps the {ade} 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

```bash theme={null}
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](./agentic-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

1. 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`.

   <CodeGroup>
     ```bash macOS/Linux theme={null}
     export VISION_AGENT_API_KEY="<your-api-key>"
     ```

     ```cmd Windows (Command Prompt) theme={null}
     set "VISION_AGENT_API_KEY=<your-api-key>"
     ```

     ```powershell Windows (PowerShell) theme={null}
     $env:VISION_AGENT_API_KEY="<your-api-key>"
     ```
   </CodeGroup>
2. Initialize the client. It reads the `VISION_AGENT_API_KEY` environment variable automatically:
   ```typescript theme={null}
   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.

1. Install the `dotenv` package:
   ```bash theme={null}
   npm install dotenv
   ```
2. Create a `.env` file in your project root and add your API key:
   ```bash theme={null}
   VISION_AGENT_API_KEY=<your-api-key>
   ```
3. Load the `.env` file before you initialize the client:
   ```typescript theme={null}
   import "dotenv/config"; // Loads .env into process.env.
   import LandingAIADE from "landingai-ade";

   const client = new LandingAIADE();
   ```

<Tip>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`.</Tip>

### 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):

1. The `apikey` passed to the client constructor.
2. 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](./agentic-api-key#troubleshoot-api-key-issues).

## Initialize the Client

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

```typescript theme={null}
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.

```typescript theme={null}
import LandingAIADE from "landingai-ade";

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

For more about using {ade} in the EU, see [European Union (EU)](./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`.

```typescript theme={null}
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](./parse).

## 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.

```typescript theme={null}
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](./extract).

<Tip>To define a typed schema, use [Zod](https://zod.dev) (v4 or later) and pass `z.toJSONSchema(YourSchema)` as the `schema`.</Tip>

## 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.

```typescript theme={null}
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](./parse-async) and [Asynchronous Extraction](./extract-async).

## Set the Model Version

The `model` parameter is optional. When you omit it, the API uses the latest {dpt3pro} model. To pin a specific version, pass a model string such as `dpt-3-pro-latest` or a dated snapshot. See [Model Version](./parse-input#model-version).

```typescript theme={null}
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`.

```typescript theme={null}
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](./parse-troubleshoot).

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.

```typescript theme={null}
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](https://github.com/landing-ai/ade-typescript). The README covers client configuration not documented here, including retries, timeouts, logging, raw response access, and customizing the fetch client.
* [API reference](https://docs.landing.ai/api-reference/parse/ade-parse)
* [Parse Documents](./parse) and [Extract Data](./extract)