|
| 1 | +--- |
| 2 | +title: Free Unstructured API |
| 3 | +description: This page describes how to obtain an API key to use with the free Unstructured API, the limitations of the free Unstructured API, and provides a quick start example. |
| 4 | +--- |
| 5 | + |
| 6 | +## Get an API key |
| 7 | + |
| 8 | +The Free Unstructured API requires authentication via an API key. Here's how you can obtain your API key: |
| 9 | + |
| 10 | +1. Navigate to the [Free Unstructured API](https://unstructured.io/api-key-free) page on our website. |
| 11 | +2. Fill out the registration form with your details: first name, last name, email, and company. Make sure your contact information is valid. |
| 12 | +3. Check the `I agree` box if you consent to Unstructured contacting you about our products and services. |
| 13 | +4. Carefully read the Terms and Conditions, and check the appropriate box to agree. |
| 14 | +5. Click "Submit". You will receive an API key to the provided email. |
| 15 | + |
| 16 | +Make sure to store your API key securely, and do not share publicly. |
| 17 | + |
| 18 | +<Note> |
| 19 | + When using the Free Unstructured API, you only need the API key to authenticate yourself. |
| 20 | + If you're using the SaaS Unstructured API, refer to the [SaaS Unstructured API](/api-reference/api-services/saas-api-development-guide) for the quick start documentation. |
| 21 | +</Note> |
| 22 | + |
| 23 | +## Free Unstructured API limitations |
| 24 | + |
| 25 | +The free Unstructured API is designed for prototyping purposes, and not for production use: |
| 26 | +* The API usage is limited to 1000 pages per month. |
| 27 | +* Unlike the users of SaaS Unstructured API, users of the free to do not get their own dedicated infrastructure. |
| 28 | +* The data sent over the free Unstructured API can be used for model training purposes, and other service improvements. |
| 29 | + |
| 30 | +If you require a production-ready API, consider using the [Saas Unstructured API](/api-reference/api-services/saas-api-development-guide) instead. |
| 31 | + |
| 32 | +## Quick Start Example |
| 33 | + |
| 34 | +Let's say you want to preprocess an `*.eml` file using the free Unstructured API. There are several ways |
| 35 | +you can do this, which all lead to the same result, so pick your preferred method. |
| 36 | + |
| 37 | +### POST request |
| 38 | + |
| 39 | +Supply your API key, and the file to preprocess: |
| 40 | + |
| 41 | +```bash |
| 42 | +# The URL is the same for all free Unstructured API users |
| 43 | +curl -X 'POST' 'https://api.unstructured.io/general/v0/general' |
| 44 | + -H 'accept: application/json' |
| 45 | + -H 'Content-Type: multipart/form-data' |
| 46 | + -H 'unstructured-api-key: 'YOUR_API_KEY' |
| 47 | + -F 'files=@sample-docs/family-day.eml' |
| 48 | +``` |
| 49 | +
|
| 50 | +The result will look something like this: |
| 51 | + |
| 52 | +
|
| 53 | +### Unstructured Python/JavaScript SDK |
| 54 | +
|
| 55 | +To work with the free Unstructured API in Python or JavaScript, use the |
| 56 | +Unstructured [Python SDK](https://github.com/Unstructured-IO/unstructured-python-client), or |
| 57 | +[JavaScript SDK](https://github.com/Unstructured-IO/unstructured-js-client). |
| 58 | +
|
| 59 | +First, install your preferred SDK: |
| 60 | +<CodeGroup> |
| 61 | +
|
| 62 | +```bash Python |
| 63 | +pip install unstructured-client |
| 64 | +``` |
| 65 | +
|
| 66 | +```bash JavaScript |
| 67 | +npm install unstructured-client |
| 68 | +``` |
| 69 | +</CodeGroup> |
| 70 | +
|
| 71 | +Next, use it to call the API: |
| 72 | +
|
| 73 | +<CodeGroup> |
| 74 | +
|
| 75 | +```python Python |
| 76 | +from unstructured_client import UnstructuredClient |
| 77 | +from unstructured_client.models import shared |
| 78 | +from unstructured_client.models.errors import SDKError |
| 79 | +
|
| 80 | +client = UnstructuredClient(api_key_auth="YOUR_API_KEY") |
| 81 | +filename = "sample-docs/family-day.eml" |
| 82 | +
|
| 83 | +with open(filename, "rb") as f: |
| 84 | + files=shared.Files( |
| 85 | + content=f.read(), |
| 86 | + file_name=filename, |
| 87 | + ) |
| 88 | +
|
| 89 | +req = shared.PartitionParameters(files=files) |
| 90 | +
|
| 91 | +try: |
| 92 | + resp = client.general.partition(req) |
| 93 | +except SDKError as e: |
| 94 | + print(e) |
| 95 | +``` |
| 96 | +
|
| 97 | +```javascript JavaScript |
| 98 | +import { UnstructuredClient } from "unstructured-client"; |
| 99 | +import { PartitionResponse } from "unstructured-client/dist/sdk/models/operations"; |
| 100 | +import * as fs from "fs"; |
| 101 | +
|
| 102 | +const key = "YOUR_API_KEY"; |
| 103 | +
|
| 104 | +const client = new UnstructuredClient({ |
| 105 | + security: { |
| 106 | + apiKeyAuth: key, |
| 107 | + }, |
| 108 | +}); |
| 109 | +
|
| 110 | +const filename = "sample-docs/family-day.eml"; |
| 111 | +const data = fs.readFileSync(filename); |
| 112 | +
|
| 113 | +client.general.partition({ |
| 114 | + files: { |
| 115 | + content: data, |
| 116 | + fileName: filename, |
| 117 | + }, |
| 118 | +}).then((res: PartitionResponse) => { |
| 119 | + if (res.statusCode == 200) { |
| 120 | + console.log(res.elements); |
| 121 | + } |
| 122 | +}).catch((e) => { |
| 123 | + console.log(e.statusCode); |
| 124 | + console.log(e.body); |
| 125 | +}); |
| 126 | +``` |
| 127 | +</CodeGroup> |
| 128 | +
|
| 129 | +### Calling the Unstructured API from the Unstructured open source library |
| 130 | +
|
| 131 | +Finally, you can call the Unstructured API directly from the Unstructured open source library: |
| 132 | +
|
| 133 | +```python |
| 134 | +from unstructured.partition.api import partition_via_api |
| 135 | +
|
| 136 | +filename = "sample-docs/family-day.eml" |
| 137 | +
|
| 138 | +elements = partition_via_api( |
| 139 | + filename=filename, |
| 140 | + api_key="YOUR API KEY", |
| 141 | +) |
| 142 | +``` |
| 143 | +
|
| 144 | +
|
| 145 | +
|
0 commit comments