Process an individual file by making a direct POST request

Whether you’re using the free Unstructured API, the Unstructured Serverless API, Unstructured API on Azure/AWS, or your local deployment of Unstructured API, you can work with the API by sending single-file POST requests to it.

Unstructured recommends that you use the Unstructured Ingest CLI or the Unstructured Ingest Python library if any of the following apply to you:

• You need to work with documents in cloud storage.
• You want to cache the results of processing multiple files in batches.
• You want more precise control over document-processing pipeline stages such as partitioning, chunking, filtering, staging, and embedding.

To make POST requests, you will need:

These environment variables:

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

Let’s start with a simple example in which you send a PDF file (*.pdf) to partition via Unstructured API.

 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=@sample-docs/report.pdf' \
  -F 'strategy=hi_res' \
  -o 'sample-docs/report.json'

In the example above we’re sending the request to the Free Unstructured API, in which case the API URL is the same for all users: https://api.unstructured.io/general/v0/general and is represented by the environment variable UNSTRUCTURED_API_URL. Note, however, that you still need to authenticate yourself with your individual API Key, represented by the environment variable UNSTRUCTURED_API_KEY. Learn how to obtain an API key in the Getting Started section of the documentation: Free Unstructured API guide and Unstructured Serverless API guide.

If you are using the Unstructured Serverless API, you need to replace the URL in this example with the unique API URL that you have received in the same email as your API key. For Unstructured API on Azure/AWS, use the API URL that you configured through those services.

Parameters & examples

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

• 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-POST.postman_collection.json
   

5. On the sidebar, click Collections.

6. Expand Unstructured POST.

7. Click one of the following:

   • To call the Unstructured Serverless API, click (Serverless API) Basic Request.
   • To call the Free Unstructured API, click (Free API) Basic Request.

8. On the Headers tab, next to unstructured-api-key, enter your Unstructured API key in the Value column.

   Unstructured Serverless API keys do not work with the Free Unstructured API. If you try to use a Serverless API key with a Free API URL, the call will fail. Get a Serverless API key and its related Serverless API URL.

   Free Unstructured API keys do not work with the Unstructured Serverless API. If you try to use a Free API key with a Serverless API URL, the call will fail. Get a Free API key and its related Free API URL.

9. On the Body tab, next to files, click the Select files box in the Value column.

10. Click New file from local machine.

11. Browse to and select the file that you want Unstructured to process.

12. Click Send.

To download the processed data to your local machine, in the response area, click the ellipses, and then click Save response to file.