Unstructured API

The Unstructured API is a self-hosted REST API designed to partition documents using the open-source unstructured library. It automatically detects uploaded file types, selects the appropriate partitioner, and returns document elements in JSON or CSV format.

Key Capabilities:

• Supports all file types compatible with unstructured[all-docs].
• Provides multiple PDF/image strategies: auto, fast, hi_res, and ocr_only.
• Supports table and image-block extraction, OCR language selection, page breaks, and coordinates.
• Offers by_title chunking with overlap controls.
• Handles single-file and multi-file requests.
• Provides API documentation at http://localhost:8000/general/docs and an OpenAPI schema at http://localhost:8000/general/openapi.json once the server is running.

The sample-docs directory provides several file types to test the library's parsers:

• example-10k.html: A 10-K SEC filing in HTML format (suitable for testing the HTML parser).
• layout-parser-paper.pdf: A PDF document (suitable for testing PDF parsing and layout analysis).
• factbook.xml and factbook.xsl: Example XML and XSL files (suitable for testing stylesheet processing).

To run the Unstructured API locally, ensure you have the following requirements:

• Python 3.12
• uv
• System dependencies required by the specific document types you intend to process (refer to the unstructured full installation guide).

Setup Steps:

1. Install the locked runtime and dependencies:

   make install

2. Start the development server:

   make run-web-app

3. Verify the server is healthy:

   curl --fail http://localhost:8000/healthcheck

Basic Usage Example: Partition a sample file using a POST request:

curl --request POST \
  --url http://localhost:8000/general/v0/general \
  --header 'accept: application/json' \
  --form 'files=@sample-docs/family-day.eml'

You can download an example 10-K in inline XBRL format using curl.

Important: The SEC website requires a User-Agent header containing your organization and email address, otherwise the request will be rejected. Replace ${organization} and ${email} with your actual details.

curl -O \
  -A '${organization} ${email}' \
  https://www.sec.gov/Archives/edgar/data/311094/000117184321001344/0001171843-21-001344.txt

To test the HTML parser with a real-world SEC filing, you can download an example 10-K in inline XBRL format using curl.

Important: The SEC website requires a User-Agent header containing your organization and email address; otherwise, the request will be rejected. Replace ${organization} and ${email} with your actual details.

curl -O \
  -A '${organization} ${email}' \
  https://www.sec.gov/Archives/edgar/data/311094/000117184321001344/0001171843-21-001344.txt

The sample-docs directory contains various file formats to test the library's parsers:

• example-10k.html: A 10-K SEC filing in HTML format.
• layout-parser-paper.pdf: A PDF copy of the layout parser paper.
• factbook.xml and factbook.xsl: Example XML and XSL files for testing stylesheets.

You can run the API using pre-built multi-platform images (amd64 and arm64) from Quay.

Run published image:

docker pull quay.io/unstructured-io/unstructured-api:latest
docker run --rm --name unstructured-api -p 8000:8000 \
  quay.io/unstructured-io/unstructured-api:latest

Note: Pin a specific release or commit tag instead of latest for reproducible deployments.

Build locally:

make docker-build
make docker-start-api

# Run published image
docker pull quay.io/unstructured-io/unstructured-api:latest
docker run --rm --name unstructured-api -p 8000:8000 \
  quay.io/unstructured-io/unstructured-api:latest

# Build locally
make docker-build
make docker-start-api

The API includes a patch for FastAPI's Request.form() to support clients (like Speakeasy) that send array-like form data using bracketed keys (e.g., key[]).

The API automatically transforms these keys by removing the trailing [] before processing the data, allowing standard FastAPI parameter parsing to work with these explicit form structures.

The Unstructured Pipeline API is a FastAPI application designed to partition documents using the Unstructured library. It provides endpoints for document processing and includes built-in support for CORS and custom OpenAPI documentation.

Server Configuration

The API defines two primary server environments:

• Hosted API: https://api.unstructured.io (ID: prod)
• Development server: http://localhost:8000 (ID: local)

API Documentation

• Swagger UI: Accessible at /general/docs
• OpenAPI JSON: Accessible at /general/openapi.json

from fastapi import FastAPI

app = FastAPI(
    title="Unstructured Pipeline API",
    summary="Partition documents with the Unstructured library",
    # ... other config
)