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 one of the following means:
- The For Developers sign-up page.
- The For Enterprise sign-up page.
An Unstructured API key, created through the 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 account settings sidebar, click API Keys, if it is not already selected.
4. To get your API key, click the copy icon in the Actions column for your API key, and then click Key Only. Do not share your API key with others.
On the Account Settings page, do not use the API URL value that is displayed. This API URL will not work with the Unstructured Platform API. See the next bullet for the Unstructured Platform API URL.
The Unstructured Platform API URL, which is https://platform.unstructuredapp.io/api/v1

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 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 Python SDK
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 curl or 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 curl examples use 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>"

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.

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_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 GET method to call the /sources endpoint.

To filter the list of source connectors, use the query parameter source_type=<type>, 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.

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 GET method to call the /sources/<connector-id> endpoint, replacing <connector-id> with the source connector’s unique ID. To get this ID, see List source connectors.

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 POST method to call the /sources endpoint. In the request body, specify the settings for the connector. For the specific settings to include, which differ by connector, see Sources.

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 PUT method to call the /sources/<connector-id> endpoint, replacing <connector-id> with the source connector’s unique ID. To get this ID, see List source connectors.

In the request body, 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.

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 DELETE method to call the /sources/<connector-id> endpoint, replacing <connector-id> with the source connector’s unique ID. To get this ID, see List source connectors.

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 GET method to call the /destinations endpoint.

To filter the list of destination connectors, use the query parameter destination_type=<type>, 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.

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 GET method to call the /destinations/<connector-id> endpoint, replacing <connector-id> with the destination connector’s unique ID. To get this ID, see List destination connectors.

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 POST method to call the /destinations endpoint. In the request body, specify the settings for the connector. For the specific settings to include, which differ by connector, see Destinations.

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 PUT method to call the /destinations/<connector-id> endpoint, replacing <connector-id> with the destination connector’s unique ID. To get this ID, see List destination connectors.

In the request body, 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.

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 DELETE method to call the /destinations/<connector-id> endpoint, replacing <connector-id> with the destination connector’s unique ID. To get this ID, see List destination connectors.

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 GET method to call the /workflows endpoint.

To filter the list of workflows, use one or more of the following query parameters:

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>.

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 GET method to call the /workflows/<workflow-id> endpoint, replacing <workflow-id> with the workflow’s unique ID. To get this ID, see List workflows.

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 POST method to call the /workflows endpoint. In the request body, specify the settings for the workflow. For the specific settings to include, see Create a workflow.

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 POST method to call the /workflows/<workflow-id>/run endpoint, replacing <workflow-id> with the workflow’s unique ID. To get this ID, see List workflows.

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 PUT method to call the /workflows/<workflow-id> endpoint, replacing <workflow-id> with the workflow’s unique ID. To get this ID, see List workflows.

In the request body, specify the settings for the workflow. For the specific settings to include, see Update a workflow.

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 DELETE method to call the /workflows/<workflow-id> endpoint, replacing <workflow-id> with the workflow’s unique ID. To get this ID, see List workflows.

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 GET method to call the /jobs endpoint.

To filter the list of jobs, use one or both of the following query parameters:

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.

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

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 GET method to call the /jobs/<job-id> endpoint, replacing <job-id> with the job’s unique ID. To get this ID, see List jobs.

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 POST method to call the /jobs/<job-id>/cancel endpoint, replacing <job-id> with the job’s unique ID. To get this ID, see List jobs.

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