Skip to content

Workflow Endpoint: Python SDK - run workflows with local sources #714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 12, 2025
Merged

Workflow Endpoint: Python SDK - run workflows with local sources #714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 82 additions & 14 deletions api-reference/workflow/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1825,13 +1825,6 @@ the `POST` method to call the `/workflows/<workflow-id>/run` endpoint (for `curl

<AccordionGroup>
<Accordion title="Python SDK (remote source and remote destination)">
<Note>
If the target workflow was originally created programmatically by the Unstructured Python SDK or with a REST API client such as `curl` or Postman,
and the workflow uses a local source connector, you can run the workflow only with a REST API client such as `curl` or Postman,
as described later in this section.
You cannot run the workflow with the Python SDK or the Unstructured user interface (UI), even though the workflow is visible in the UI.
</Note>

```python
import os

Expand All @@ -1852,13 +1845,6 @@ the `POST` method to call the `/workflows/<workflow-id>/run` endpoint (for `curl
```
</Accordion>
<Accordion title="Python SDK (async) (remote source and remote destination)">
<Note>
If the target workflow was originally created programmatically by the Unstructured Python SDK or with a REST API client such as `curl` or Postman,
and the workflow uses a local source connector, you can run the workflow only with a REST API client such as `curl` or Postman,
as described later in this section.
You cannot run the workflow with the Python SDK or the Unstructured user interface (UI), even though the workflow is visible in the UI.
</Note>

```python
import os
import asyncio
Expand All @@ -1882,6 +1868,88 @@ the `POST` method to call the `/workflows/<workflow-id>/run` endpoint (for `curl
asyncio.run(run_workflow())
```
</Accordion>
<Accordion title="Python SDK (local source and local or remote destination)">
In the following code, replace `</path/to/input/file>` with a relative or absolute path to a local input file for Unstructured to process. You can add multiple files, with one entry per file.

```python
import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import RunWorkflowRequest
from unstructured_client.models.shared import InputFiles

input_files = []

for filename in [
"<path/to/input/file>",
"<path/to/input/file>"
]:
with open(filename, "rb") as f:
input_files.append(
InputFiles(
content=f.read(),
file_name=filename
)
)

with UnstructuredClient(api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")) as client:
response = client.workflows.run_workflow(
request={
"workflow_id": "<workflow-id>"
"body_run_workflow": {
"input_files": input_files
}
}
)

print(response.raw_response)
```

For a local destination, to access the processed files' data, [download a processed local file](#download-a-processed-local-file-from-a-job) from the workflow's job run.
</Accordion>
<Accordion title="Python SDK (async) (local source and local or remote destination)">
In the following code, replace `</path/to/input/file>` with a relative or absolute path to a local input file for Unstructured to process. You can add multiple files, with one entry per file.

```python
import os
import asyncio

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import RunWorkflowRequest
from unstructured_client.models.shared import InputFiles

async def run_workflow():
input_files = []

for filename in [
"<path/to/input/file>",
"<path/to/input/file>"
]:
with open(filename, "rb") as f:
input_files.append(
InputFiles(
content=f.read(),
file_name=filename
)
)

with UnstructuredClient(api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")) as client:
response = client.workflows.run_workflow(
request={
"workflow_id": "<workflow-id>"
"body_run_workflow": {
"input_files": input_files
}
}
)

print(response.raw_response)

asyncio.run(run_workflow())
```

For a local destination, to access the processed files' data, [download a processed local file](#download-a-processed-local-file-from-a-job) from the workflow's job run.
</Accordion>
<Accordion title="curl (remote source and remote destination)">
```bash
curl --request 'POST' --location \
Expand Down
48 changes: 24 additions & 24 deletions api-reference/workflow/workflows.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,9 +116,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```python
Expand Down Expand Up @@ -198,9 +198,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```python
Expand Down Expand Up @@ -363,9 +363,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```python
Expand Down Expand Up @@ -449,9 +449,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` or Postman. [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```python
Expand Down Expand Up @@ -565,9 +565,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` (or Postman). [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` (or Postman). [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```bash
Expand Down Expand Up @@ -602,9 +602,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as `curl` (or Postman). [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as `curl` (or Postman). [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

```bash
Expand Down Expand Up @@ -680,9 +680,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as Postman (or `curl`). [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as Postman (or `curl`). [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

1. In the method drop-down list, select **POST**.
Expand Down Expand Up @@ -728,9 +728,9 @@ specify the settings for the workflow, as follows:
A workflow with a local source has the following limitations:

- The workflow cannot be set to run on a repeating schedule.
- The workflow cannot be run with the Unstructured Python SDK or from the Unstructured user interface (UI),
even though the workflows is visible in the UI. However, you can
run the workflow with REST API clients such as Postman (or `curl`). [Learn how](/api-reference/workflow/overview#run-a-workflow).
- The workflow cannot be run from the Unstructured user interface (UI),
even though the workflow is visible in the UI. However, you can
run the workflow with the Unstructured Python SDK, or REST API clients such as Postman (or `curl`). [Learn how](/api-reference/workflow/overview#run-a-workflow).
</Note>

1. In the method drop-down list, select **POST**.
Expand Down