Process an individual file by making a direct POST request

To make POST requests to the Unstructured Partition Endpoint, you will need:

These environment variables:

• UNSTRUCTURED_API_KEY - Your Unstructured API key value.
• UNSTRUCTURED_API_URL - Your Unstructured API URL.

To get your API key, do the following:

If you signed up for Unstructured through the For Enterprise page, or if you are using a self-hosted deployment of Unstructured, the following information about signing up, signing in, and getting your Unstructured API key might apply differently to you. For details, contact Unstructured Sales at [e-mail].

1. Go to https://platform.unstructured.io and use your email address, Google account, or GitHub account to sign up for an Unstructured account (if you do not already have one) and sign into the account at the same time. The Unstructured user interface (UI) appears.

2. Get your Unstructured API key:

   a. In the Unstructured UI, click API Keys on the sidebar.
   b. Click Generate API Key.
   c. Follow the on-screen instructions to finish generating the key.
   d. Click the Copy icon next to your new key to add the key to your system’s clipboard. If you lose this key, simply return and click the Copy icon again.
   

By following the preceding instructions, you are signed up for a Developer pay per page account by default.

To save money, consider switching to a Subscribe & Save account instead. To save even more money, consider switching to an Enterprise account instead.

The API base URL is https://api.unstructuredapp.io

Let’s start with a simple example in which you use curl to send a local PDF file (*.pdf) to partition via the Unstructured Partition Endpoint.

In this command, be sure to replace <path/to/file> with the path to your local PDF file.

curl --request 'POST' \
"$UNSTRUCTURED_API_URL/v1/partition_async" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-Type: multipart/form-data' \
--form 'strategy=vlm' \
--form 'vlm_model_provider=openai' \
--form 'vlm_model=gpt-4o' \
--form 'output_format=application/json' \
--form 'files=@<path/to/file>;type=application/pdf'

In the example above we’re representing the base API endpoint with the environment variable UNSTRUCTURED_API_URL. Note, however, that you also need to authenticate yourself with your individual API Key, represented by the environment variable UNSTRUCTURED_API_KEY. Learn how to obtain an API URL and API key in the Unstructured Partition Endpoint guide.

The results are printed to your terminal or Command Prompt with a format similar to the following:

{
   "partition_id": "<job-id>",
   "partition_status": "scheduled",
   "partition_status_message": "Partition job created"
}

Make a note of the <job-id> value.

Next, run the following curl command, replacing <job_id> with the <job_id> value:

curl --request 'GET' \
"$UNSTRUCTURED_API_URL/v1/partition_async/<job_id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

The results are printed to your terminal or Command Prompt with a format similar to the following:

{
   "partition_id": "<job-id>",
   "partition_status": "in_progress",
   "partition_status_message": "Started processing partition request",
   "elements": null
}

If the job is still in progress, repeat the curl command until the job is complete. However, if you run the curl command and the job has successfully completed, the results that are printed to your terminal or Command Prompt will contain the processed data within the elements array, for example:

{
    "partition_id": "<job-id>",
    "partition_status": "completed",
    "partition_status_message": "Partition job completed",
    "elements": [
        {
            "type": "...",
            "element_id": "...",
            "text": "...",
            "metadata": {
                "...": "..."
            }
        },
        {
            "type": "...",
            "element_id": "...",
            "text": "...",
            "metadata": {
                "...": "..."
            }
        }
    ]   
}

By default, the JSON is printed without indenting or other whitespace. You can pretty-print the JSON output by using utilities such as jq in future command runs.

You can also pipe the JSON output to a local file by using the curl option -o, —output <file> in future command runs.

Synchronous requests

The preceding section describes how to make asynchronous requests to the Unstructured Partition Endpoint. The Unstructured Partition Endpoint also supports synchronous requests.

To make a synchronous request, replace /v1/partition_async with /general/v0/general as follows:

curl --request 'POST' \
"$UNSTRUCTURED_API_URL/general/v0/general" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-Type: multipart/form-data' \
--form 'strategy=fast' \
--form 'output_format=application/json' \
--form 'files=@<path/to/file>;type=text/plain'

If the request is successfully completed, the processed data is returned directly to your terminal or Command Prompt, without needing to make any additional requests. However, you must wait for the request to complete and return the results.

While supported, synchronous requests are not recommended for the following reasons:

• A synchronous request must wait until the operation is complete, which might result in a timeout error.
• A waiting synchronous request is a poor user experience, as it can give the user the mistaken impression that nothing is happening.
• While waiting, you cannot poll to check the current status of a synchronous request.
• If the related network connection is lost during a synchronous request, the request might fail.

For these reasons, if you must make synchronous requests, they should be limited to processing only relatively small, text-based files, partitioning such files with only the fast partitioning strategy.

Parameters & examples

The API parameters are the same across all methods of accessing the Unstructured Partition Endpoint.

• Refer to the API parameters page for the full list of available parameters.
• Refer to the Examples page for some inspiration on using the parameters.

Postman collection

Unstructured offers a Postman collection that you can import into Postman to make POST requests through a graphical user interface.

1. Install Postman.

2. Sign in to Postman.

3. In your workspace, click Import.

   

4. In the Paste cURL, Raw text or URL box, enter the following URL, and then press Enter:

   https://raw.githubusercontent.com/Unstructured-IO/docs/main/examplecode/codesamples/api/Unstructured-REST-API-Partition-Endpoint.postman_collection.json
   

5. On the sidebar, click Collections.

6. Expand Unstructured REST.

7. Expand Partition Endpoint.

To create an asynchronous request, do the following:

1. Click Asynchronous Job Request.
2. On the Headers tab, next to unstructured-api-key, enter your Unstructured API key in the Value column.
3. On the Body tab, next to files, click the Select files box in the Value column.
4. Click New file from local machine.
5. Browse to and select the file that you want Unstructured to process.
6. Repeat steps 3-5 for any additional files that you want to process.
7. On the Body tab, add, remove, or modify any allowed parameters that you want to use.
8. Click Send. Note the value of the partition_id field in the response, as you will need it for the next procedure.

To check the status of an asynchronous request, do the following:

1. Click Asynchronous Job Status.
2. In the URL, replace <partition-id> with the partition_id value that you noted in the previous procedure.
3. On the Headers tab, next to unstructured-api-key, enter your Unstructured API key in the Value column.
4. Click Send.
5. Keep clicking Send periodically until the job is complete.
6. To download the processed data to your local machine, in the response area, click the ellipses, and then click Save response to file.

To create a synchronous request, do the following:

1. Click Synchronous Request.
2. On the Headers tab, next to unstructured-api-key, enter your Unstructured API key in the Value column.
3. On the Body tab, next to files, click the Select files box in the Value column.
4. Click New file from local machine.
5. Browse to and select the file that you want Unstructured to process.
6. On the Body tab, add, remove, or modify any allowed parameters that you want to use.
7. Click Send. Processing could take several minutes.
8. To download the processed data to your local machine, in the response area, click the ellipses, and then click Save response to file.