Skip to content

Commit 29ecb9b

Browse files
Paul-CornellPaul-Cornell
authored
Free Unstructured API URL: Breaking changes for Python SDK >= 0.30.0 (#485)
1 parent e06d3e7 commit 29ecb9b

File tree

5 files changed

+94
-11
lines changed

5 files changed

+94
-11
lines changed

‎api-reference/api-services/examples.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,19 @@ import SharedAPIKeyURL from '/snippets/general-shared-text/api-key-url.mdx';
1111

1212
import NoURLForServerlessAPI from '/snippets/general-shared-text/no-url-for-serverless-api.mdx';
1313

14+
<Warning>
15+
**Important**: Beginning with Python SDK 0.30.0, note the following:
16+
17+
- For the Unstructured Serverless API URL, do not use `https://api.unstructuredapp.io/general/v0/general`, or else calls made by
18+
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
19+
- For the Free Unstructured API URL, do not use `https://api.unstructured.io/general/v0/general`, or else calls made by
20+
the Python SDK will fail. Use `https://api.unstructured.io` instead.
21+
- If your Python code previously used the `server_url` parameter inside of your `UnstructuredClient` constructor to specify your Unstructured API URL, you must move this `server_url` parameter into
22+
your code's `partition` or `partition_async` function calls instead, or else calls made by the Python SDK will fail. To learn how, see the following code examples.
23+
24+
[Learn more](/api-reference/api-services/sdk-python#migration-guide).
25+
</Warning>
26+
1427
<NoURLForServerlessAPI/>
1528

1629
import UseIngestOrPlatformInstead from '/snippets/general-shared-text/use-ingest-or-platform-instead.mdx';

‎api-reference/api-services/free-api.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,17 @@ The Free Unstructured API requires authentication via an API key. Here's how you
1919
5. Click **Submit**. You will receive a Free Unstructured API key at the **Email** you provided. Store your API key in a secure location. Do not share it with others.
2020
6. For the Free Unstructured API, the API URL is `https://api.unstructured.io/general/v0/general`
2121

22+
<Warning>
23+
**Important**: This article shows how to use Free Unstructured API with the Unstructured CLI and the
24+
Unstructured Ingest Python library. While you can also use this API URL with the Unstructured Python SDK,
25+
beginning with Python SDK 0.30.0, note the following:
26+
27+
- Do not use https://api.unstructured.io/general/v0/general, or else calls made by
28+
the Python SDK will fail. Use https://api.unstructured.io` instead.
29+
- If your Python code uses the `server_url` parameter inside of your `UnstructuredClient` constructor to specify this URL, you must move this `server_url` parameter into
30+
your code's `partition` or `partition_async` function calls instead, or else calls made by the Python SDK will fail.
31+
</Warning>
32+
2233
import FreeKeyNoServerlessURL from '/snippets/general-shared-text/free-api-key-no-serverless-access.mdx';
2334

2435
<FreeKeyNoServerlessURL />

‎api-reference/api-services/sdk-python.mdx‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,19 @@ import SharedAPIKeyURL from '/snippets/general-shared-text/api-key-url.mdx';
1818

1919
<SharedAPIKeyURL />
2020

21+
<Warning>
22+
**Important**: Beginning with Python SDK 0.30.0, note the following:
23+
24+
- For the Unstructured Serverless API URL, do not use `https://api.unstructuredapp.io/general/v0/general`, or else calls made by
25+
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
26+
- For the Free Unstructured API URL, do not use `https://api.unstructured.io/general/v0/general`, or else calls made by
27+
the Python SDK will fail. Use `https://api.unstructured.io` instead.
28+
- If your Python code previously used the `server_url` parameter inside of your `UnstructuredClient` constructor to specify your Unstructured API URL, you must move this `server_url` parameter into
29+
your code's `partition` or `partition_async` function calls instead, or else calls made by the Python SDK will fail. To learn how, see the following code examples.
30+
31+
[Learn more](#migration-guide).
32+
</Warning>
33+
2134
import NoURLForServerlessAPI from '/snippets/general-shared-text/no-url-for-serverless-api.mdx';
2235

2336
<NoURLForServerlessAPI/>
@@ -309,18 +322,19 @@ the names used in the SDKs are the same across all methods.
309322

310323
## Migration guide
311324

312-
There are major breaking changes in 0.30.0. If you encounter any errors when upgrading, please find the solution below.
325+
There are breaking changes beginning with Python SDK version 0.26.0 and again in 0.30.0. If you encounter any errors when upgrading, please find the solution below.
313326

314327
**If you see the error: `404 Not Found`**
315328

316329
Before 0.30.0, you could specify the following Unstructured API URL for the `server_url` parameter:
317330

318331
- For the Unstructured Serverless API: `https://api.unstructuredapp.io/general/v0/general`
332+
- For the Free Unstructured API: `https://api.unstructured.io/general/v0/general`
319333

320-
Beginning with 0.30.0, these Unstructured API URLs have changed as follows, respectively:
334+
Beginning with 0.30.0, these Unstructured API URLs have changed as follows:
321335

322336
- For the Unstructured Serverless API: `https://api.unstructuredapp.io` (remove `/general/v0/general`)
323-
- (New beginning with 0.30.0) For the Unstructured Platform API: `https://platform.unstructuredapp.io` (remove `/api/v1`)
337+
- For the Free Unstructured API: `https://api.unstructured.io` (remove `/general/v0/general`)
324338

325339
Also, before 0.30.0, the `server_url` parameter was part of the `UnstructuredClient` constructor. Beginning with 0.30.0, the `server_url`
326340
parameter has been moved into the `partition` and `partition_async` functions.
@@ -352,8 +366,6 @@ res = await client.general.partition_async(
352366
)
353367
```
354368

355-
There are minor breaking changes beginning with 0.26.0. If you encounter any errors when upgrading, please find the solution below.
356-
357369
**If you see the error: `AttributeError: 'PartitionParameters' object has no attribute 'partition_parameters'`**
358370

359371
Before 0.26.0, the SDK accepted a `PartitionParameters` object as input to the `sdk.general.partition` function. Beginning with 0.26.0, this object must be wrapped in a `PartitionRequest` object. The old behavior was deprecated in 0.23.0 and removed in 0.26.0.

‎api-reference/troubleshooting/api-key-url.mdx‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,9 @@ For the API URL, note the following:
4343
- For the [Unstructured Serverless API](/api-reference/api-services/saas-api-development-guide), the API URL is typically `https://api.unstructuredapp.io`, which is unique to
4444
the Unstructured Python SDK, beginning with 0.30.0; and `https://api.unstructuredapp.io/general/v0/general` for the Unstructured Python SDK before 0.30.0 and for standard REST-enabled utilities (such as `curl`),
4545
tools (such as Postman), programming languages, packages, and libraries. Be aware of the inclusion of `app` in this API URL.
46-
- For the [Free Unstructured API](/api-reference/api-services/free-api), the API URL is always `https://api.unstructured.io/general/v0/general`. Be aware that there is no `app` in this API URL.
46+
- For the [Free Unstructured API](/api-reference/api-services/free-api), the API URL is typically https://api.unstructured.io`, which is unique to
47+
the Unstructured Python SDK, beginning with 0.30.0; and `https://api.unstructured.io/general/v0/general` for the Unstructured Python SDK before 0.30.0 and for standard REST-enabled utilities (such as `curl`),
48+
tools (such as Postman), programming languages, packages, and libraries. Be aware that there is no `app` in this API URL.
4749

4850
<Note>The free 14-day trial of the Unstructured Serverless API or Unstructured Platform API is different than the Free Unstructured API.</Note>
4951

@@ -65,11 +67,19 @@ For the API key, note the following:
6567
- For the Unstructured Platform API URL, do not use `https://platform.unstructuredapp.io/api/v1`, or else calls made by
6668
the Python SDK will fail. Use `https://platform.unstructuredapp.io` instead.
6769
- For the Unstructured Serverless API URL, do not use `https://api.unstructuredapp.io/general/v0/general`, or else calls made by
68-
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
70+
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
71+
- For the Free Unstructured API URL, do not use https://api.unstructured.io/general/v0/general, or else calls made by
72+
the Python SDK will fail. Use https://api.unstructured.io` instead.
6973
</Warning>
7074

7175
- For the [Free Unstructured API](/api-reference/api-services/free-api), the API key is in your original email from Unstructured. If you cannot find the original email, you can regenerate it by going to [https://unstructured.io/api-key-free](https://unstructured.io/api-key-free).
7276

77+
<Warning>
78+
**Important**: For the Unstructured Python SDK beginning with 0.30.0,
79+
for the Free Unstructured API URL, do not use https://api.unstructured.io/general/v0/general, or else calls made by
80+
the Python SDK will fail. Use https://api.unstructured.io` instead.
81+
</Warning>
82+
7383
<Note>The free 14-day trial of the Unstructured Serverless API or Unstructured Platform API is different than the Free Unstructured API.</Note>
7484

7585
If you still believe you have the correct API URL and API key, try the following steps:
@@ -83,6 +93,36 @@ If you still believe you have the correct API URL and API key, try the following
8393

8494
**For the Unstructured Python SDK** (Unstructured Platform API, Unstructured Serverless API, and Free Unstructured API only)
8595

96+
- For the Unstructured Python SDK beginning with 0.30.0, if the `server_url` parameter is in your `UnstructuredClient` constructor, move it into
97+
your operational calling function such as `partition` or `partition_asyc` for Unstructured API services or `list_*`, `get_*`, `create_*`, `update_*`, or `delete_*` for the Unstructured Platform API. For example:
98+
99+
```python
100+
# Instead of this (before Python SDK 0.30.0):
101+
client = unstructured_client.UnstructuredClient(
102+
api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"),
103+
server_url=os.getenv("UNSTRUCTURED_API_URL")
104+
)
105+
106+
# Switch to this (beginning with Python SDK 0.30.0):
107+
client = unstructured_client.UnstructuredClient(
108+
api_key_auth=os.getenv("UNSTRUCTURED_API_KEY")
109+
)
110+
111+
# And then...
112+
113+
# For Unstructured API services:
114+
res = client.general.<partition|partition_async>(
115+
request=req,
116+
server_url=os.getenv("UNSTRUCTURED_API_URL")
117+
)
118+
119+
# Or for the Unstructured Platform API:
120+
res = client.<sources-destinations-workflows-jobs>.<list-get-create-delete-operation>(
121+
request=req,
122+
server_url=os.getenv("UNSTRUCTURED_API_URL")
123+
)
124+
```
125+
86126
- Check the value of the `server_url` parameter. Make sure it is set to the right API URL, or an environment variable representing the right API URL.
87127

88128
<Warning>
@@ -91,7 +131,9 @@ If you still believe you have the correct API URL and API key, try the following
91131
- For the Unstructured Platform API URL, do not use `https://platform.unstructuredapp.io/api/v1`, or else calls made by
92132
the Python SDK will fail. Use `https://platform.unstructuredapp.io` instead.
93133
- For the Unstructured Serverless API URL, do not use `https://api.unstructuredapp.io/general/v0/general`, or else calls made by
94-
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
134+
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
135+
- For the Free Unstructured API URL, do not use https://api.unstructured.io/general/v0/general, or else calls made by
136+
the Python SDK will fail. Use https://api.unstructured.io` instead.
95137
</Warning>
96138

97139
- Check the value of the `api_key_auth` parameter. Make sure it is set to the right API key, or an environment variable representing the right API key.
@@ -103,7 +145,7 @@ If you still believe you have the correct API URL and API key, try the following
103145
- For `serverURL`, make sure it is set to the right API URL, or an environment variable representing the right API URL, or...
104146
- For `server`, make sure it is set to `"saas-api"` for the Unstructured Serverless API, or `"free-api"` for the Free Unstructured API, or an environment variable representing one of these strings.
105147

106-
<Note>You can use `"saas-api"` and `"free-api"` only with the Unstructured SDKs.</Note>
148+
<Note>You can use `"saas-api"` and `"free-api"` only with the Unstructured JavaScript/TypeScript SDK.</Note>
107149

108150
- Make sure that only `serverURL` or `server` are specified&mdash;not both.
109151
- Make sure that if you specify `serverURL`, an actual API URL (or an environment variable representing an actual API URL) is specified (not `"saas-api"` or `"free-api"`, or an environment variable representing one of these strings).
@@ -158,13 +200,18 @@ If you still believe you have the correct API URL and API key, try the following
158200
- For the Unstructured Platform API URL, do not use `https://platform.unstructuredapp.io/api/v1`, or else calls made by
159201
the Python SDK will fail. Use `https://platform.unstructuredapp.io` instead.
160202
- For the Unstructured Serverless API URL, do not use `https://api.unstructuredapp.io/general/v0/general`, or else calls made by
161-
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
203+
the Python SDK will fail. Use `https://api.unstructuredapp.io` instead.
162204
</Warning>
163205

164206
**For the Free Unstructured API**
165207

166208
- Open your original email from Unstructured that contains your API key. Make sure it matches the one in your script, code, or environment variable. If you cannot find the original email, you can regenerate it by going to [https://unstructured.io/api-key-free](https://unstructured.io/api-key-free).
167209
- Make sure that you are using `https://api.unstructured.io/general/v0/general` (not `platform.unstructuredapp.io` or `api.unstructuredapp.io`) for the API URL.
168210

211+
<Warning>
212+
**Important**: For the Unstructured Python SDK beginning with 0.30.0 for the Free Unstructured API URL, do not use https://api.unstructured.io/general/v0/general, or else calls made by
213+
the Python SDK will fail. Use https://api.unstructured.io` instead.
214+
</Warning>
215+
169216
4. If you are still getting this issue, [contact us directly](https://unstructured.io/contact).
170217

‎snippets/general-shared-text/no-url-for-serverless-api.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<Info>
22
If you do not specify the API URL, your [Unstructured Serverless API](/api-reference/api-services/saas-api-development-guide) pay-as-you-go account will be used by default. You must always specify your Serverless API key.<br/><br/>
3-
To use the [Free Unstructured API](/api-reference/api-services/free-api), you must always specify your Free API key, and the Free API URL which is `https://api.unstructured.io/general/v0/general`<br/><br/>
3+
To use the [Free Unstructured API](/api-reference/api-services/free-api), you must always specify your Free API key, and the Free API URL which is `https://api.unstructured.io` for the Python SDK beginning with 0.30.0; and `https://api.unstructured.io/general/v0/general` for all other clients.<br/><br/>
44
To use the pay-as-you-go Unstructured API on Azure or AWS with the SDKs, you must always specify the corresponding API URL. See the [Azure](/api-reference/api-services/azure) or [AWS](/api-reference/api-services/aws) instructions.
55
</Info>

0 commit comments

Comments
 (0)