Overview

The Unstructured Platform API is separate from Unstructured Serverless API services.

For information about Unstructured Serverless API services, see the Unstructured Serverless API services overview.

The Unstructured Platform features a no-code user interface for transforming your unstructured data into data that is ready for Retrieval Augmented Generation (RAG).

The Unstructured Platform also provides a back-end API for automation usage scenarios as well as for documentation, reporting, and recovery needs. This page provides an overview of the Unstructured Platform API.

Requirements

To use the Unstructured Platform API, you must have:

An Unstructured account, created through the For Developers page, with one of the following plans:
- A pay-per-page plan.
- A subscribe-and-save plan
An Unstructured API key, created through your Unstructured account console.

If you signed up through the For Enterprise page, your API key creation process might be different. For API key creation guidance, email Unstructured Sales at sales@unstructured.io.
Free Unstructured API keys are not supported.

To create an API key, do the following:
1. Sign in to the Unstructured Platform. Learn how.
2. At the bottom of the sidebar, click your user icon, and then click Account Settings.
3. On the API Keys tab, click Generate New Key.
4. Enter some descriptive name for the API key, and then click Save.
5. Click the Copy icon for your new API key. The API key’s value is copied to your system’s clipboard.
The Unstructured Platform API URL. This is typically https://platform.unstructuredapp.io, which is unique to the Unstructured Python SDK; and https://platform.unstructuredapp.io/api/v1 for standard REST-enabled utilities (such as curl), tools (such as Postman), programming languages, packages, and libraries.

Important: Do not use https://platform.unstructuredapp.io/api/v1 with the Unstructured Python SDK, or else calls made by the Python SDK will fail. Use https://platform.unstructuredapp.io instead.
Do not use the Unstructured Serverless API URL, which is separate from the Unstructured Platform API URL.

If you signed up through the For Enterprise page, your API URL might be different. For API URL 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.

The Unstructured Platform API is offered as follows:

As part of the Unstructured Python SDK beginning with version 0.30.0, which you can call through standard Python code.

To install the Unstructured Python SDK, run the following command from within your Python virtual environment:
```
pip install "unstructured-client>=0.30.0"
```
If you already have the Unstructured Python SDK installed, upgrade to at least version 0.30.0 by running the following command instead:
```
pip install --upgrade "unstructured-client>=0.30.0"
```
As a set of Representational State Transfer (REST) endpoints, which you can call through standard REST-enabled utilities, tools, programming languages, packages, and libraries. The following sections describe how to call the Unstructured Platform API 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 Platform API - Swagger UI to call the REST endpoints that are available through https://platform.unstructuredapp.io.

The Unstructured Platform API is separate from Unstructured Serverless API services and Unstructured Ingest.

Because of this separation, the following Unstructured SDKs, tools, and libraries do not work with the Unstructured Platform API:

The Unstructured JavaScript/TypeScript SDK
Local single-file POST requests to Unstructured Serverless API services
The Unstructured open source Python library
The Unstructued Ingest CLI
The Unstructured Ingest Python library

Free Unstructured API accounts are also not supported.

The following Unstructured API URLs are also not supported:

https://api.unstructuredapp.io/general/v0/general (the Unstructured Serverless API URL)
https://api.unstructured.io/general/v0/general (the Free Unstructured API URL)

Basics

The Unstructured Platform API enables you to work with connectors, workflows, and jobs in the Unstructured Platform.

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:

The following sections provide examples, showing the use of the Unstructured SDK for Python for all of the supported API operations, as well as curl and Postman for all of the supported REST endpoints.

You can also use the Unstructured Platform API - Swagger UI to call the REST endpoints that are available through https://platform.unstructuredapp.io.

The following Unstructured Python SDK examples use the following environment variables, which you can set as follows:

export UNSTRUCTURED_API_URL="https://platform.unstructuredapp.io"
export UNSTRUCTURED_API_KEY="<your-unstructured-api-key>"

Important: Do not use https://platform.unstructuredapp.io/api/v1 with the Python SDK, or else calls made by the Python SDK will fail. Use https://platform.unstructuredapp.io instead.

The following curl and Postman examples use the following environment variables, which you can set as follows:

export UNSTRUCTURED_API_URL="https://platform.unstructuredapp.io/api/v1"
export UNSTRUCTURED_API_KEY="<your-unstructured-api-key>"

Important: For standard REST-enabled clients (such as curl), do not use https://platform.unstructuredapp.io (which is unique to the Unstructured Python SDK), or else calls made by these REST-enabled clients will fail. Use https://platform.unstructuredapp.io/api/v1 instead.

These environment variables enable you to more easily run the following Unstructured Python SDK and curl examples and help prevent you from storing scripts that contain sensitive URLs and API keys in public source code repositories.

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
  
  Important: Do not use https://platform.unstructuredapp.io (which is unique to the Unstructured Python SDK), or else calls made by Postman will fail.
- Variable: UNSTRUCTURED_API_URL
- Type: secret
- Initial value: <your-unstructured-api-key>
- Current value: <your-unstructured-api-key>
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.

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, s3 for the Amazon S3 source connector type). To get this ID, see Sources.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import ListSourcesRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.sources.list_sources(
    request=ListSourcesRequest(
        source_type="<type>" # Optional, list only for this source type.
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

# Print the list in alphabetical order by connector name.
sorted_sources = sorted(
    response.response_list_sources, 
    key=lambda source: source.name.lower()
)

for source in sorted_sources:
    print(f"{source.name} ({source.id})")

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/sources" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list of source connectors:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/sources?source_type=<type>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

In the method drop-down list, select GET.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/sources
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
To filter the list of source connectors, on the Params tab, enter the following query parameter:
- Key: source_type, Value: <type>
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import GetSourceRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.sources.get_source(
    request=GetSourceRequest(
        source_id="<connector-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.source_connector_information

print(f"name: {info.name}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

In the method drop-down list, select GET.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/sources/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CreateSourceRequest
from unstructured_client.models.shared import CreateSourceConnector

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

destination_connector = CreateSourceConnector(
    name="<name>",
    type="<type>",
    config={
        # Specify the settings for the connector here.
    }
)

response = client.sources.create_source(
    request=CreateSourceRequest(
        create_source_connector=source_connector
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.source_connector_information

print(f"name: {info.name}")
print(f"id: {info.id}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

curl --request 'POST' --location \
"$UNSTRUCTURED_API_URL/sources" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the connector here.
}'

In the method drop-down list, select POST.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/sources
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the connector.
Click Send.

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.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import UpdateSourceRequest
from unstructured_client.models.shared import UpdateSourceConnector

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

destination_connector = UpdateSourceConnector(
    config={
        # Specify the settings for the connector here.
    }
)

response = client.sources.update_source(
    request=UpdateSourceRequest(
        source_id="<connector-id>",
        update_source_connector=source_connector
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.source_connector_information

print(f"name: {info.name}")
print(f"id: {info.id}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

curl --request 'PUT' --location \
"$UNSTRUCTURED_API_URL/sources/<connector-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the connector here.
}'

In the method drop-down list, select PUT.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/sources/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the connector.
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import DeleteSourceRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.sources.delete_source(
    request=DeleteSourceRequest(
        source_id="<connector-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

print(response.raw_response)

In the method drop-down list, select DELETE.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/sources/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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, s3 for the Amazon S3 destination connector type). To get this ID, see Destinations.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import ListDestinationsRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.destinations.list_destinations(
    request=ListDestinationsRequest(
        destination_type="<type>" # Optional, list only for this destination type.
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

# Print the list in alphabetical order by connector name.
sorted_destinations = sorted(
    response.response_list_destinations, 
    key=lambda destination: destination.name.lower()
)

for destination in sorted_destinations:
    print(f"{destination.name} ({destination.id})")

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/destinations" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list of destination connectors:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/destinations?destination_type=<type>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

In the method drop-down list, select GET.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/destinations
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
To filter the list of destination connectors, on the Params tab, enter the following query parameter:
- Key: destination_type, Value: <type>
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import GetDestinationRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.destinations.get_destination(
    request=GetDestinationRequest(
        destination_id="<connector-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.destination_connector_information

print(f"name: {info.name}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

In the method drop-down list, select GET.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/destinations/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CreateDestinationRequest
from unstructured_client.models.shared import CreateDestinationConnector

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

destination_connector = CreateDestinationConnector(
    name="<name>",
    type="<type>",
    config={
        # Specify the settings for the connector here.
    }
)

response = client.destinations.create_destination(
    request=CreateDestinationRequest(
        create_destination_connector=destination_connector
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.destination_connector_information

print(f"name: {info.name}")
print(f"id: {info.id}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

curl --request 'POST' --location \
"$UNSTRUCTURED_API_URL/destinations" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the connector here.
}'

In the method drop-down list, select POST.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/destinations
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the connector.
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import UpdateDestinationRequest
from unstructured_client.models.shared import UpdateDestinationConnector

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

destination_connector = UpdateDestinationConnector(
    config={
        # Specify the settings for the connector here.
    }
)

response = client.destinations.update_destination(
    request=UpdateDestinationRequest(
        destination_id="<connector-id>",
        update_destination_connector=destination_connector
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.destination_connector_information

print(f"name: {info.name}")
print(f"id: {info.id}")
    
for key, value in info.config.items():
    print(f"{key}: {value}")

curl --request 'PUT' --location \
"$UNSTRUCTURED_API_URL/destinations/<connector-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the connector here.
}'

In the method drop-down list, select PUT.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/destinations/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the connector.
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import DeleteDestinationRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.destinations.delete_destination(
    request=DeleteDestinationRequest(
        destination_id="<connector-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

print(response.raw_response)

In the method drop-down list, select DELETE.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/destinations/<connector-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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=<status>, replacing <status> with one of the following workflow statuses: active or inactive.

You can specify multiple query parameters, for example ?source_id=<connector-id>&status=<status>.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import ListWorkflowsRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.workflows.list_workflows(
    request=ListWorkflowsRequest(
        destination_id="<connector-id>", # Optional, list only for this destination connector ID.
        source_id="<connector-id>", # Optional, list only for this source connector ID.
        status="<status>" # Optional, list only for this workflow status.
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

# Print the list in alphabetical order by workflow name.
sorted_workflows = sorted(
    response.response_list_workflows, 
    key=lambda workflow: workflow.name.lower()
)

for workflow in sorted_workflows:
    print(f"{workflow.name} ({workflow.id})")

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/workflows" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list by source connector ID:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/workflows?source_id=<connector-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list by destination connector ID:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/workflows?destination_id=<connector-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list by workflow status:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/workflows?status=<status>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

In the method drop-down list, select GET.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/workflows
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
To filter the list of workflows, on the Params tab, enter one or more of the following query parameter:
- By source connector ID: Key: source_id, Value: <connector-id>
- By destination connector ID: Key: destination_id, Value: <connector-id>
- By workflow status: Key: status, Value: <status>
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import GetWorkflowRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.workflows.get_workflow(
    request=GetWorkflowRequest(
        workflow_id="<workflow-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.workflow_information

print(f"name:           {info.name}")
print(f"id:             {info.id}")
print(f"status:         {info.status}")
print(f"type:           {info.workflow_type}")
print("source(s):")

for source in info.sources:
    print(f"            {source}")

print("destination(s):")

for destination in info.destinations:
    print(f"            {destination}")

print("schedule(s):")

for crontab_entry in info.schedule.crontab_entries:
    print(f"            {crontab_entry.cron_expression}")

In the method drop-down list, select GET.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/workflows/<workflow-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CreateWorkflowRequest
from unstructured_client.models.shared import CreateWorkflow

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

workflow = CreateWorkflow(
    # Specify the settings for the workflow here.
)

response = client.workflows.create_workflow(
    request=CreateWorkflowRequest(
        create_workflow=workflow
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.workflow_information

print(f"name:           {info.name}")
print(f"id:             {info.id}")
print(f"status:         {info.status}")
print(f"type:           {info.workflow_type}")
print("source(s):")

for source in info.sources:
    print(f"            {source}")

print("destination(s):")

for destination in info.destinations:
    print(f"            {destination}")

print("schedule(s):")

for crontab_entry in info.schedule.crontab_entries:
    print(f"            {crontab_entry.cron_expression}")

curl --request 'POST' --location \
"$UNSTRUCTURED_API_URL/workflows" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the workflow here.
}'

In the method drop-down list, select POST.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/workflows
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the workflow.
Click Send.

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.

import os

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

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.workflows.run_workflow(
    request=RunWorkflowRequest(
        workflow_id="<workflow-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

print(response.raw_response)

In the method drop-down list, select POST.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/workflows/<workflow-id>/run

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import UpdateWorkflowRequest
from unstructured_client.models.shared import UpdateWorkflow

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

workflow = UpdateWorkflow(
    # Specify the settings for the workflow here.
)

response = client.workflows.update_workflow(
    request=UpdateWorkflowRequest(
        workflow_id="<workflow-id>",
        update_workflow=workflow
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.workflow_information

print(f"name:           {info.name}")
print(f"id:             {info.id}")
print(f"status:         {info.status}")
print(f"type:           {info.workflow_type}")
print("source(s):")

for source in info.sources:
    print(f"            {source}")

print("destination(s):")

for destination in info.destinations:
    print(f"            {destination}")

print("schedule(s):")

for crontab_entry in info.schedule.crontab_entries:
    print(f"            {crontab_entry.cron_expression}")

curl --request 'PUT' --location \
"$UNSTRUCTURED_API_URL/workflows/<workflow-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
--header 'content-type: application/json' \
--data \
'{
    # Specify the settings for the workflow here.
}'

In the method drop-down list, select PUT.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/workflows/<workflow-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
- Key: content-type, Value, application/json
On the Body tab, select raw and JSON, and specify the settings for the workflow.
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import DeleteWorkflowRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.workflows.delete_workflow(
    request=DeleteWorkflowRequest(
        workflow_id="<workflow-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

print(response.raw_response)

In the method drop-down list, select DELETE.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/workflows/<workflow-id>

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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: failed, finished, or running.

For curl or Postman, you can specify multiple query parameters as ?workflow_id=<workflow-id>&status=<status>.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import ListJobsRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.jobs.list_jobs(
    request=ListJobsRequest(
        workflow_id="<workflow-id>", # Optional, list only for this workflow ID.
        status="<status>", # Optional, list only for this job status.
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

# Print the list in alphabetical order by workflow name.
sorted_jobs = sorted(
    response.response_list_jobs, 
    key=lambda job: job.workflow_name.lower()
)

for job in sorted_jobs:
    print(f"{job.id} (workflow name: {job.workflow_name}, id: {job.workflow_id})")

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/jobs" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list by workflow ID:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/jobs?workflow_id=<workflow-id>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

To filter the list by job status:

curl --request 'GET' --location \
"$UNSTRUCTURED_API_URL/job?status=<status>" \
--header 'accept: application/json' \
--header "unstructured-api-key: $UNSTRUCTURED_API_KEY"

In the method drop-down list, select GET.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/jobs
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
To filter the list of jobs, on the Params tab, enter one or more of the following query parameter:
- By workflow ID: Key: workflow_id, Value: <workflow-id>
- By job status: Key: status, Value: <status>
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import GetJobRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.jobs.get_job(
    request=GetJobRequest(
        job_id="<job-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

info = response.job_information

print(f"id:            {info.id}")
print(f"status:        {info.status}")
print(f"workflow name: {info.workflow_name}")
print(f"workflow id:   {info.workflow_id}")

In the method drop-down list, select GET.
In the address box, enter the following URL:
```
{{UNSTRUCTURED_API_URL}}/jobs/<job-id>
```
On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

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.

import os

from unstructured_client import UnstructuredClient
from unstructured_client.models.operations import CancelJobRequest

client = UnstructuredClient(
    api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
)

response = client.jobs.cancel_job(
    request=CancelJobRequest(
        job_id="<job-id>"
    ),
    server_url=os.getenv("UNSTRUCTURED_API_URL")
)

print(response.raw_response)

In the method drop-down list, select POST.

In the address box, enter the following URL:

{{UNSTRUCTURED_API_URL}}/jobs/<job-id>/cancel

On the Headers tab, enter the following headers:
- Key: unstructured-api-key, Value: {{UNSTRUCTURED_API_KEY}}
- Key: accept, Value: application/json
Click Send.

Unstructured Platform

Getting started with Platform

Using Platform

Concepts

Requirements

Basics

Connectors

List source connectors

Get a source connector

Create a source connector

Update a source connector

Delete a source connector

List destination connectors

Get a destination connector

Create a destination connector

Update a destination connector

Delete a destination connector

Workflows

List workflows

Get a workflow

Create a workflow

Run a workflow

Update a workflow

Delete a workflow

Jobs

List jobs

Get a job

Cancel a job

Unstructured Platform

Getting started with Platform

Using Platform

Concepts

​Requirements

​Basics

​Connectors

​List source connectors

​Get a source connector

​Create a source connector

​Update a source connector

​Delete a source connector

​List destination connectors

​Get a destination connector

​Create a destination connector

​Update a destination connector

​Delete a destination connector

​Workflows

​List workflows

​Get a workflow

​Create a workflow

​Run a workflow

​Update a workflow

​Delete a workflow

​Jobs

​List jobs

​Get a job

​Cancel a job

Requirements

Basics

Connectors

List source connectors

Get a source connector

Create a source connector

Update a source connector

Delete a source connector

List destination connectors

Get a destination connector

Create a destination connector

Update a destination connector

Delete a destination connector

Workflows

List workflows

Get a workflow

Create a workflow

Run a workflow

Update a workflow

Delete a workflow

Jobs

List jobs

Get a job

Cancel a job