Get started

To call the Unstructured Serverless API, you need an API key and API URL:

  1. Go to https://app.unstructured.io.
  2. Enter your email address and then click Sign In to receive a magic link to sign in to your personalized dashboard, or authenticate yourself with your Google or GitHub account.
  3. Once you authenticate with the magic link or with your Google or GitHub account, your dashboard appears.
  4. On the sidebar, click API Keys, if it is not already selected.
  5. To get your API key, click the copy icon in the Actions column for your API key. Store your copied API key in a secure location. Do not share it with others.
  6. To get your API URL, click the copy icon next to the URL next to API URL. Store your copied API URL in a secure location. Do not share it with others.

Unstructured Serverless API keys do not work with the Free Unstructured API. If you try to use an Unstructured Serverless API key with a Free Unstructured API URL, the call will fail. Use your Unstructured Serverless API URL instead.

Try the quickstart.

Set up billing

Once you sign up for the Unstructured Serverless API, you can enjoy a free 14-day trial with usage capped at 1000 pages per day.

The free 14-day trial for the Unstructured Serverless API is different than the Free Unstructured API.

At the end of the 14-day free trial, or if you need to go past the trial’s page processing limits during the 14-day free trial, you must set up your billing information to keep using the Unstructured Serverless API:

  1. Go to https://app.unstructured.io and sign in.
  2. On the sidebar, click Billing.
  3. Click Manage Payment Method, follow the on-screen instructions to enter your payment details through Stripe, and then click Save card.

Your card is billed monthly based on your usage. The Billing page shows a billing overview for the current month and a list of your billing invoices.

We calculate a page as follows:

  • For these file types, a page is a page, slide, or image: .pdf, .pptx, and .tiff.
  • For .docx files that have page metadata, we calculate the number of pages based on that metadata.
  • For all other file types, we calculate the number of pages as the file’s size divided by 100 KB.

Quickstart

The following example illustrates how to preprocess an *.eml file using the Unstructured Serverless API.

There are several ways to use the Unstructured Serverless API, which all lead to the same result, so pick your preferred method: POST, CLI, SDK, or open source.

POST request

To work with the Unstructured Serverless API by calling the Unstructured REST API POST with curl, you will need to:

  • Set the UNSTRUCTURED_API_KEY environment variable to your Unstructured Serverless API key.
  • Set the UNSTRUCTURED_API_URL environment variable to your Unstructured Serverless API URL.

Get your API key and API URL.

Now, use curl to call the API, specifying where the source (input) file is to preprocess and the destination (output) where Unstructured will deliver the processed data.

curl -X POST $UNSTRUCTURED_API_URL \
     -H 'accept: application/json' \
     -H 'Content-Type: multipart/form-data' \
     -H 'unstructured-api-key: $UNSTRUCTURED_API_KEY' \
     -F 'files=@<local/path/to/input/file>' \
     -o '<local/path/to/output/file>'

If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

The result will look something like this:

Sample Output

POST requests support using only local machine paths as the source (input) for the files to preprocess and as the destination (output) that Unstructured sends the processed data to. To specify a source or destination other than a local machine, use the CLI, the Python SDK, or the open source library instead.
Unstructured does not recommend POST to process multiple files at a time. Instead, use the Unstructured CLI or the Unstructured Python SDK with their provided source connectors and destination connectors.

Learn more about how to use POST requests.

Unstructured CLI

To work with the Unstructured Serverless API by using the Unstructured CLI, you will need to:

  • Install Python, and then install the CLI package:

    pip install unstructured
    
  • Set the UNSTRUCTURED_API_KEY environment variable to your API key. Make sure to also set the UNSTRUCTURED_API_URL environment variable to your API URL. Get your API key and API URL.

Now, use the CLI to call the API, specifying where the source (input) files are to preprocess and the destination (output) where Unstructured will deliver the processed data:

CLI
unstructured-ingest \
  local \
    --input-path <local/path/to/input/files> \
    --output-dir <local/path/to/output/files> \
    --partition-by-api \
    --api-key $UNSTRUCTURED_API_KEY \
    --partition-endpoint $UNSTRUCTURED_API_URL

If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

To learn more about how to use the local command, run the command unstructured-ingest local --help.

Unstructured Python SDK and JavaScript/TypeScript SDK

To work with the Unstructured Serverless API in Python, JavaScript, or TypeScript, use the Unstructured Python SDK or JavaScript/TypeScript SDK.

The JavaScript/TypeScript SDK supports using only local machine paths as the source (input) for the files to preprocess and as the destination (output) that Unstructured sends the processed data to. To specify a source or destination other than a local machine, use the CLI, the Python SDK, or the open source library instead.

First, install your preferred SDK:

Next, use it to call the API. Be sure to set the UNSTRUCTURED_API_URL environment variable to your API URL Also set the UNSTRUCTURED_API_KEY environment variable to your API key. Get your API key and API URL.

If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

The partition method in the Python and JavaScript/TypeScript SDKs process single files only. To process multiple files at a time, use the Unstructured CLI or Unstructured Python SDK with their provided source connectors and destination connectors.

Learn more about how to use the Unstructured Python and JavaScript/TypeScript SDKs.

Calling the Unstructured API from the Unstructured open source library

You can call the Unstructured Serverless API directly from the Unstructured open source library. Unstructured recommends this approach only for rapid local script or code prototyping or simple proofs-of-concept, not for production scenarios.

You will need to:

  • Install Python, and then install the open source library:

    pip install unstructured
    
  • Set the UNSTRUCTURED_API_KEY environment variable to your API key. Make sure to set the UNSTRUCTURED_API_URL environment variable to your API URL. Get your API key and API URL.

Now, use the open source library to call the API, specifying the file to preprocess:

import os 

from unstructured.partition.api import partition_via_api

filename = "PATH_TO_FILE"

elements = partition_via_api(
  filename=filename,
  api_key=os.getenv("UNSTRUCTURED_API_KEY"),
  api_url=os.getenv("UNSTRUCTURED_API_URL")
)

If you do not have any files available, you can download some from the example-docs folder in the Unstructured repo on GitHub.

The partition_via_api function in the open source library processes single files only. To process multiple files at a time, use the Unstructured CLI or the open source library with their provided source connectors and destination connectors.

Learn more about how to use the Unstructured open source library.

Manage your account

To manage your account: Begin by going to https://app.unstructured.io and signing in.

To manage your API keys:

  • On the sidebar, click API Keys.
  • To create a key, click Generate New Key, and follow the on-screen instructions.
  • To enable or disable a key, switch On/Off in the column for that key to on or off.
  • To delete a key, click the trash can in the Actions column for that key.

To view your usage: On the sidebar, click Usage.

To view your billing costs and invoices and to manage your payment method: On the sidebar, click Billing.

To log out of your account: On the sidebar, click your email address, and then click Logout.

If you need direct assistance, our support team is just an email away. Contact us at support@unstructured.io.

Telemetry

We’ve partnered with Scarf to collect anonymized user statistics to understand which features our community is using and how to prioritize product decision-making in the future.

To learn more about how we collect and use this data, please read our Privacy Policy.

To opt out of this data collection, you can set the environment variable SCARF_NO_ANALYTICS=true before running any commands that call Unstructured Serverless API services.