Overview
The Unstructured UI features a no-code user interface for transforming your unstructured data into data that is ready for Retrieval Augmented Generation (RAG).
The Unstructured Workflow Endpoint, part of the Unstructured API, enables a full range of partitioning, chunking, embedding, and enrichment options for your files and data. It is designed to batch-process files and data in remote locations; send processed results to various storage, databases, and vector stores; and use the latest and highest-performing models on the market today. It has built-in logic to deliver the highest quality results at the lowest cost.
This page provides an overview of the Unstructured Workflow Endpoint. This endpoint enables Unstructured UI automation usage scenarios as well as for documentation, reporting, and recovery needs.
Getting started
Choose one of the following options to get started with the Unstructured Workflow Endpoint:
- Follow the quickstart, which uses the Unstructured Python SDK from a remote hosted Google Collab notebook.
- Start using the Unstructred Python SDK.
- Start using a REST client, such as
curl
or Postman.
Quickstart
This quickstart uses the Unstructured Python SDK to call the Unstructured Workflow Endpoint to get your data RAG-ready. The Python code for this quickstart is in a remote hosted Google Collab notebook. Data is processed on Unstructured-hosted compute resources.
The requirements are as follows:
- A compatible source (input) location that contains your data for Unstructured to process. See the list of supported source types. This quickstart uses an Amazon S3 bucket as the source location. If you use a different source type, you will need to modify the quickstart notebook accordingly.
- For document-based source locations, compatible files in that location. See the list of supported file types. If you do not have any files available, you can download some from the example-docs folder in the
Unstructured-IO/unstructured-ingest
repository in GitHub. - A compatible destination (output) location for Unstructured to put the processed data. See the list of supported destination types. For this quickstart’s destination location, a different folder in the same Amazon S3 bucket as the source location is used. If you use a different destination S3 bucket or a different destination type, you will need to modify the quickstart notebook accordingly.
Sign up, sign in, and get your API key
-
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.
-
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.
Create and set up the S3 bucket
This quickstart uses an Amazon S3 bucket as both the source location and the destination location. (You can use other source and destination types that are supported by Unstructured. If you use a different source or destination type, or if you use a different S3 bucket for the destination location, you will need to modify the quickstart notebook accordingly.)
Inside of the S3 bucket, a folder named input
represents the
source location. This is where your files to be processed will be stored.
The S3 URI to the source location will be s3://<your-bucket-name>/input
.
Inside of the same S3 bucket, a folder inside named output
represents the destination location. This
is where Unstructured will put the processed data.
The S3 URI to the destination location will be s3://<your-bucket-name>/output
.
Learn how to create an S3 bucket and set it up for Unstructured. (Do not run the Python SDK code or REST commands at the end of those setup instructions.)
Run the quickstart notebook
After your S3 bucket is created and set up, follow the instructions in this quickstart notebook.
View the processed data
After you run the quickstart notebook, go to your destination location to view the processed data.
Unstructured Python SDK
Watch the following 4-minute video to learn how to use the Python SDK to call the Unstructured Workflow Endpoint to create connectors in the Unstructured UI.
Watch the following 4-minute video to learn how to use the Python SDK to call the Unstructured Workflow Endpoint to create workflows and jobs in the Unstructured UI.
Open a related notebook that covers many of the concepts that are shown in the preceding videos.
The Unstructured Python SDK, beginning with version 0.30.6, allows you to call the Unstructured Workflow Endpoint through standard Python code.
To install the Unstructured Python SDK, run the following command from within your Python virtual environment:
If you already have the Unstructured Python SDK installed, upgrade to at least version 0.30.6 by running the following command instead:
The Unstructured Python SDK code examples, shown later on this page and on related pages, use the following environment variable, which you can set as follows:
This environment variable enables you to more easily run the following Unstructured Python SDK examples and help prevent you from storing scripts that contain sensitive API keys in public source code repositories.
To get your Unstructured API key, do the following:
-
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.
-
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.
Calls made by the Unstructured Python SDK’s unstructured_client
functions for creating, listing, updating,
and deleting connectors, workflows, and jobs in the Unstructured UI all use the Unstructured Workflow Endpoint URL (https://platform.unstructuredapp.io/api/v1
) by default. You do not need to
use the server_url
parameter to specify this API URL in your Python code for these particular functions.
If you signed up through the For Enterprise page, your API URL and API key creation guidance
might be different. For guidance, email Unstructured Sales at sales@unstructured.io.
If your API URL is different, be sure to substitute https://platform.unstructuredapp.io/api/v1
for your
API URL throughout the following examples.
To specify an API URL in your code, set the server_url
parameter in the UnstructuredClient
constructor to the target API URL.
The Unstructured Workflow Endpoint enables you to work with connectors, workflows, and jobs in the Unstructured UI.
- A source connector ingests files or data into Unstructured from a source location.
- A destination connector sends the processed data from Unstructured to a destination location.
- A workflow defines how Unstructured will process the data.
- A job runs a workflow at a specific point in time.
For general information about these objects, see:
Skip ahead to start learning about how to use the Unstructured Python SDK to work with connectors, workflows, and jobs programmatically.
REST endpoints
The Unstructured Workflow Endpoint is callable from a set of Representational State Transfer (REST) endpoints, which you can call through standard REST-enabled
utilities, tools, programming languages, packages, and libraries. The examples, shown later on this page and on related pages, describe how to call the Unstructured Workflow Endpoint with
curl
and Postman. You can adapt this information as needed for your preferred programming languages and libraries, for example by using the
requests
library with Python.
You can also use the Unstructured Workflow Endpoint - Swagger UI to call the REST endpoints
that are available through https://platform.unstructuredapp.io
. To use the Swagger UI, you must provide your Unstructured API key with each call. To
get this API key, see the quickstart, earlier on this page.
curl and Postman
The following curl
examples use the following environment variables, which you can set as follows:
These environment variables enable you to more easily run the following curl
examples and help prevent
you from storing scripts that contain sensitive URLs and API keys in public source code repositories.
To get your Unstructured API key, do the following:
-
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.
-
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 following Postman examples use variables, which you can set as follows:
-
In Postman, on your workspace’s sidebar, click Environments.
-
Click Globals.
-
Create two global variables with the following settings:
- Variable:
UNSTRUCTURED_API_URL
- Type:
default
- Initial value:
https://platform.unstructuredapp.io/api/v1
- Current value:
https://platform.unstructuredapp.io/api/v1
- Variable:
UNSTRUCTURED_API_KEY
- Type:
secret
- Initial value:
<your-unstructured-api-key>
- Current value:
<your-unstructured-api-key>
- Variable:
-
Click Save.
These variables enable you to more easily run the following examples in Postman and help prevent you from storing Postman collections that contain sensitive URLs and API keys in public source code repositories.
To get your Unstructured API key, do the following:
-
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.
-
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 Unstructured Workflow Endpoint enables you to work with connectors, workflows, and jobs in the Unstructured UI.
- A source connector ingests files or data into Unstructured from a source location.
- A destination connector sends the processed data from Unstructured to a destination location.
- A workflow defines how Unstructured will process the data.
- A job runs a workflow at a specific point in time.
For general information about these objects, see:
Skip ahead to start learning about how to use the REST endpoints to work with connectors, workflows, and jobs programmatically.
Restrictions
The following Unstructured SDKs, tools, and libraries do not work with the Unstructured Workflow Endpoint:
- The Unstructured JavaScript/TypeScript SDK
- Local single-file POST requests to the Unstructured Partition Endpoint
- The Unstructured open source Python library
- The Unstructued Ingest CLI
- The Unstructured Ingest Python library
The following Unstructured API URL is also not supported: https://api.unstructuredapp.io/general/v0/general
(the Unstructured Partition Endpoint URL).
Connectors
You can list, get, create, update, and delete source connectors. You can also list, get, create, update, and delete destination connectors.
For general information, see Connectors.
List source connectors
To list source connectors, use the UnstructuredClient
object’s sources.list_sources
function (for the Python SDK) or
the GET
method to call the /sources
endpoint (for curl
or Postman).
To filter the list of source connectors, use the ListSourcesRequest
object’s source_type
parameter (for the Python SDK)
or the query parameter source_type=<type>
(for curl
or Postman),
replacing <type>
with the source connector type’s unique ID
(for example, for the Amazon S3 source connector type, S3
for the Python SDK or s3
for curl
or Postman).
To get this ID, see Sources.
Get a source connector
To get information about a source connector, use the UnstructuredClient
object’s sources.get_source
function (for the Python SDK) or
the GET
method to call the /sources/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the source connector’s unique ID. To get this ID, see List source connectors.
Create a source connector
To create a source connector, use the UnstructuredClient
object’s sources.create_source
function (for the Python SDK) or
the POST
method to call the /sources
endpoint (for curl
or Postman).
In the CreateSourceConnector
object (for the Python SDK) or
the request body (for curl
or Postman),
specify the settings for the connector. For the specific settings to include, which differ by connector, see
Sources.
For the Python SDK, replace <type>
with the source connector type’s unique ID (for example, for the Amazon S3 source connector type, S3
).
To get this ID, see Sources.
Update a source connector
To update information about a source connector, use the UnstructuredClient
object’s sources.update_source
function (for the Python SDK) or
the PUT
method to call the /sources/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the source connector’s unique ID. To get this ID, see List source connectors.
In the UpdateSourceConnector
object (for the Python SDK) or
the request body (for curl
or Postman), specify the settings for the connector. For the specific settings to include, which differ by connector, see
Sources.
For the Python SDK, replace <type>
with the source connector type’s unique ID (for example, for the Amazon S3 source connector type, S3
).
To get this ID, see Sources.
You must specify all of the settings for the connector, even for settings that are not changing.
You can change any of the connector’s settings except for its name
and type
.
Delete a source connector
To delete a source connector, use the UnstructuredClient
object’s sources.delete_source
function (for the Python SDK) or
the DELETE
method to call the /sources/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the source connector’s unique ID. To get this ID, see List source connectors.
List destination connectors
To list destination connectors, use the UnstructuredClient
object’s destinations.list_destinations
function (for the Python SDK) or
the GET
method to call the /destinations
endpoint (for curl
or Postman).
To filter the list of destination connectors, use the ListDestinationsRequest
object’s destination_type
parameter (for the Python SDK) or
the query parameter destination_type=<type>
(for curl
or Postman),
replacing <type>
with the destination connector type’s unique ID
(for example, for the Amazon S3 source connector type, S3
for the Python SDK or s3
for curl
or Postman).
To get this ID, see Destinations.
Get a destination connector
To get information about a destination connector, use the UnstructuredClient
object’s destinations.get_destination
function (for the Python SDK) or
the GET
method to call the /destinations/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the destination connector’s unique ID. To get this ID, see List destination connectors.
Create a destination connector
To create a destination connectors, use the UnstructuredClient
object’s destinations.create_destination
function (for the Python SDK) or
the POST
method to call the /destinations
endpoint (for curl
or Postman).
In the CreateDestinationConnector
object (for the Python SDK) or
the request body (for curl
or Postman),
specify the settings for the connector. For the specific settings to include, which differ by connector, see
Destinations.
For the Python SDK, replace <type>
with the destination connector type’s unique ID (for example, for the Amazon S3 source connector type, S3
).
To get this ID, see Destinations.
Update a destination connector
To update information about a destination connector, use the UnstructuredClient
object’s destinations.update_destination
function (for the Python SDK) or
the PUT
method to call the /destinations/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the destination connector’s unique ID. To get this ID, see List destination connectors.
In the UpdateDestinationConnector
object (for the Python SDK) or
the request body (for curl
or Postman), specify the settings for the connector. For the specific settings to include, which differ by connector, see
Destinations.
You must specify all of the settings for the connector, even for settings that are not changing.
You can change any of the connector’s settings except for its name
and type
.
Delete a destination connector
To delete a destination connector, use the UnstructuredClient
object’s destinations.delete_destination
function (for the Python SDK) or
the DELETE
method to call the /destinations/<connector-id>
endpoint (for curl
or Postman), replacing
<connector-id>
with the destination connector’s unique ID. To get this ID, see List destination connectors.
Workflows
You can list, get, create, run, update, and delete workflows.
For general information, see Workflows.
List workflows
To list workflows, use the UnstructuredClient
object’s workflows.list_workflows
function (for the Python SDK) or
the GET
method to call the /workflows
endpoint (for curl
or Postman).
To filter the list of workflows, use one or more of the following ListWorkflowsRequest
parameters (for the Python SDK) or
query parameters (for curl
or Postman):
source_id=<connector-id>
, replacing<connector-id>
with the source connector’s unique ID. To get this ID, see List source connectors.destination_id=<connector-id>
, replacing<connector-id>
with the destination connector’s unique ID. To get this ID, see List destination connectors.status=WorkflowState.<status>
(for the Python SDK) orstatus=<status>
(forcurl
or Postman), replacing<status>
with one of the following workflow statuses:ACTIVE
orINACTIVE
(for the Python SDK) oractive
orinactive
(forcurl
or Postman).
You can specify multiple query parameters, for example ?source_id=<connector-id>&status=<status>
.
Get a workflow
To get information about a workflow, use the UnstructuredClient
object’s workflows.get_workflow
function (for the Python SDK) or
the GET
method to call the /workflows/<workflow-id>
endpoint (for curl
or Postman), replacing
<workflow-id>
with the workflow’s unique ID. To get this ID, see List workflows.
Create a workflow
To create a workflow, use the UnstructuredClient
object’s workflows.create_workflow
function (for the Python SDK) or
the POST
method to call the /workflows
endpoint (for curl
or Postman).
In the CreateWorkflow
object (for the Python SDK) or
the request body (for curl
or Postman),
specify the settings for the workflow. For the specific settings to include, see
Create a workflow.
Run a workflow
To run a workflow manually, use the UnstructuredClient
object’s workflows.run_workflow
function (for the Python SDK) or
the POST
method to call the /workflows/<workflow-id>/run
endpoint (for curl
or Postman), replacing
<workflow-id>
with the workflow’s unique ID. To get this ID, see List workflows.
To run a workflow on a schedule instead, specify the schedule
setting in the request body when you create or update a
workflow. See Create a workflow or Update a workflow.
Update a workflow
To update information about a workflow, use the UnstructuredClient
object’s workflows.update_workflow
function (for the Python SDK) or
the PUT
method to call the /workflows/<workflow-id>
endpoint (for curl
or Postman), replacing
<workflow-id>
with the workflow’s unique ID. To get this ID, see List workflows.
In UpdateWorkflow
object (for the Python SDK) or
the request body (for curl
or Postman), specify the settings for the workflow. For the specific settings to include, see
Update a workflow.
Delete a workflow
To delete a workflow, use the UnstructuredClient
object’s workflows.delete_workflow
function (for the Python SDK) or
the DELETE
method to call the /workflows/<workflow-id>
endpoint (for curl
or Postman), replacing
<workflow-id>
with the workflow’s unique ID. To get this ID, see List workflows.
Jobs
You can list, get, and cancel jobs.
A job is created automatically whenever a workflow runs on a schedule; see Create a workflow. A job is also created whenever you run a workflow; see Run a workflow.
For general information, see Jobs.
List jobs
To list jobs, use the UnstructuredClient
object’s jobs.list_jobs
function (for the Python SDK) or
the GET
method to call the /jobs
endpoint (for curl
or Postman).
To filter the list of jobs, use one or both of the following ListJobsRequest
parameters (for the Python SDK) or
query parameters (for curl
or Postman):
workflow_id=<workflow-id>
, replacing<workflow-id>
with the workflow’s unique ID. To get this ID, see List workflows.status=<status>
, replacing<status>
with one of the following job statuses:completed
,failed
,im progress
,scheduled
, andstopped
.
For curl
or Postman, you can specify multiple query parameters as ?workflow_id=<workflow-id>&status=<status>
.
Get a job
To get information about a job, use the UnstructuredClient
object’s jobs.get_job
function (for the Python SDK) or
the GET
method to call the /jobs/<job-id>
endpoint (for curl
or Postman), replacing
<job-id>
with the job’s unique ID. To get this ID, see List jobs.
Cancel a job
To cancel a running job, use the UnstructuredClient
object’s jobs.cancel_job
function (for the Python SDK) or
the POST
method to call the /jobs/<job-id>/cancel
endpoint (for curl
or Postman), replacing
<job-id>
with the job’s unique ID. To get this ID, see List jobs.
Download a processed local file from a job
This applies only to jobs that use a workflow with a local source and a local destination.
To download a processed local file from a completed job, use GET
to call the /jobs/<job-id>/download
endpoint, replacing
<job-id>
with the job’s unique ID. To get this ID, see List jobs.
You must also provide Unstructured’s IDs for the file to download and the workflow’s output node. To get these IDs, see Get a job. In the response:
- Unstructured’s IDs for the file to download and the workflow’s output node are in the
output_node_files
array. - The ID for the file to download is in the
output_node_files
array’sfile_id
field. - The ID for the workflow’s output node is in the
output_node_files
array’snode_id
field.
Currently, you cannot use the Unstructured user interface (UI) or the Unstructured Python SDK to download a file from a job that uses a workflow with a local source and a local destination.
Was this page helpful?