Parse a document - Unstructured

Parse needs one document source: input for a new upload or file_id for a previous upload. Your API key authenticates the request. All other controls are optional.

Send a document

Set UNSTRUCTURED_API_KEY to your API key and replace document.pdf with your file path. To run the Python or TypeScript example, first install the Python SDK or TypeScript SDK.

export UNSTRUCTURED_API_KEY="your-api-key"

Python
TypeScript
cURL

from unstructured_transform_client import TransformClient

with TransformClient() as client:
    result = client.parse.run(input="document.pdf")
    print(result)

import { readFile } from "node:fs/promises";
import { TransformClient, isAccepted } from "unstructured-transform-client";

const client = new TransformClient();
const file = new File([await readFile("document.pdf")], "document.pdf");
const outcome = await client.parse.run({ input: file });
if (isAccepted(outcome)) {
  console.log("Parse job ID:", outcome.body.id);
} else {
  console.log(outcome.body.markdown);
}

curl https://transform.unstructured.io/api/v2/parse \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -F "input=@document.pdf"

A synchronous request keeps the connection open until parsing completes. Multi-page documents can take about a minute or longer. That wait is expected. For an immediate response, use asynchronous processing. HTTP 200 returns a document result. Read markdown when processing completes. HTTP 202 means processing continues; retain the response’s Location header and follow request progress.

Choose the output

The default is output=markdown. Add -F "output=elements" to receive individual elements with text, type, and page metadata. In that representation, markdown is null. The optional include query parameter accepts coordinates and table_html only with elements output. Some elements might not include the coordinates or table HTML you request. Check whether each field is present before reading it.

Generate image descriptions

Image descriptions add generated text about images to your parsed document. Image descriptions are disabled by default. The following examples enable them. Use the same API key and SDK setup as Send a document.

Python
TypeScript
cURL

from unstructured_transform_client import TransformClient

with TransformClient() as client:
    result = client.parse.run(
        input="document.pdf",
        advanced_options={"enrichments": {"image_description": True}},
    )
    print(result)

import { readFile } from "node:fs/promises";
import { TransformClient, isAccepted } from "unstructured-transform-client";

const client = new TransformClient();
const file = new File([await readFile("document.pdf")], "document.pdf");
const outcome = await client.parse.run({
  input: file,
  advancedOptions: { enrichments: { imageDescription: true } },
});
if (isAccepted(outcome)) {
  console.log("Parse job ID:", outcome.body.id);
} else {
  console.log(outcome.body.markdown);
}

curl https://transform.unstructured.io/api/v2/parse \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -F "input=@document.pdf" \
  --form-string 'advanced_options={"enrichments":{"image_description":true}}'

The SDKs serialize the options for you. With cURL, send advanced_options as a JSON string in the multipart form. Image descriptions are the only supported enrichment option. See the Parse API reference. The sample text below describes the logo in the ACME Corp sample file. The JSON excerpt shows the corresponding Image element. Other response fields are omitted.

Markdown
JSON

No text available in the image. The logo consists of a dark navy blue circle outline containing a golden/amber colored triangle with a small dark navy blue triangle at the top center of the larger triangle.

{
  "type": "Image",
  "text": "No text available in the image. The logo consists of a dark navy blue circle outline containing a golden/amber colored triangle with a small dark navy blue triangle at the top center of the larger triangle."
}

Reuse your document

Use file_id instead of input for a previous upload. After Parse completes, use its id as parse_id to Extract fields. Choose Parse first when you need its Markdown, elements, or a completed Parse to reuse for multiple extractions. To extract fields directly from a document in one request, see Extract directly from a document. See the captured response and optional parameters. See Chain Parse and Extract for a complete sequence that passes the Parse ID into Extract.

​Send a document

​Choose the output

​Generate image descriptions

​Reuse your document

Send a document

Choose the output

Generate image descriptions

Reuse your document