GeezerVison

What & why

Problem: The Transform Platform's API Keys page hands you https://platform-api.transform.unstructured.io/api/v1, and the docs tell you to pass that value as server_url. Do it and every Platform call in this SDK fails with a 404: listing jobs, creating a workflow, checking a connector. The same URL works with curl, so the URL looks right and the SDK looks broken, and there is nothing in the error to point at the real cause. Anyone starting from the app's own copy button hits this on their first call.

Change: Treat hosts under unstructured.io as Unstructured API hosts, so a copied /api/v1 suffix is stripped from server_url the way it already was for unstructuredapp.io. Also clean the base URL for an operation-level server_url= override, which bypassed the cleaning hook entirely.

Linked ticket

none

Client-facing follow-up: reported while writing the Transform Python quickstart, where every SDK sample had to be written against a URL different from the one the app displays.

The bug

Every Platform operation in this SDK already carries its own path prefix. jobs.list_jobs requests /api/v1/jobs/, workflows.create_workflow requests /api/v1/workflows/, and so on. So the base URL must not carry /api/v1 of its own.

clean_server_url exists to strip exactly that kind of pasted-in path, but it only did so when the host contained unstructuredapp.io:

if "unstructuredapp.io" in parsed_url.netloc:
    ...
    clean_url = urlunparse(parsed_url._replace(path="", ...))
else:
    # For other domains, we want to keep the path
    clean_url = urlunparse(parsed_url._replace(params="", query="", fragment=""))

platform-api.transform.unstructured.io does not match, so the path was kept and the operation path was appended on top, giving /api/v1/api/v1/jobs/, which matches no route.

basesdk.py is generated, so the customization needs protecting: it is now in .genignore, the mechanism this repo already uses for general.py, users.py, retries.py and partition.py, with a guard test alongside the existing ones asserting that both the _get_url call and the .genignore entry survive. Without it a regeneration silently drops the fix and the doubled prefix returns. Freezing the file freezes the generated request, retry and hook plumbing too, so the entry carries the same un-freeze procedure general.py documents.

Three smaller problems came out of the same code while fixing it. The host test was a substring match, so unstructuredapp.io.example.com was treated as one of ours and had its path stripped and its scheme forced to HTTPS; it is now matched on domain boundaries and left alone. A server_url= passed to a single operation never reached the cleaning hook at all, because the hook runs at SDK init; that override is now cleaned in BaseSDK._get_url, the one point every operation's base URL passes through. And a fully qualified host carrying the terminal root dot (api.unstructuredapp.io.) has to be recognized explicitly, since the old substring test matched it by accident and the domain-boundary test does not; the path is stripped as before and the host keeps its dot, which changes the Host header and SNI and is the caller's choice to make.

What the patch changes, and what it does not

Every server_url shape the existing tests, the docs and the app use, run through clean_server_url on main and on this branch. Seven results change; sixteen are byte-identical.

The first five changed rows are the reported bug. The last two are the substring-match fix: those hosts are not ours, so they keep their path and their scheme.

Impact

Customers: Anyone using the Python SDK against the Transform Platform can now paste the API URL shown in the app, or set it from the documented UNSTRUCTURED_API_URL, and have jobs, workflows, sources, destinations and templates calls work. Today that exact value 404s on every call. Users who already worked around it by passing the bare host are unaffected; that keeps working. Users on unstructuredapp.io are unaffected; their URLs were already cleaned.

Internal (devs / ops / other teams): The docs can stop steering readers away from the URL the product displays. No service imports this code; it is a client library published to PyPI.

Wire contract / clients: No request or response shape changes. The only behavior change is which URL a request is sent to, and only for base URLs that were previously producing a doubled path. The one case where a user could notice a difference is a self-hosted deployment on a host under unstructuredapp.io or unstructured.io that genuinely serves the API beneath a subpath; that path is now stripped. Hosts outside those domains keep their path exactly as before, which the existing localhost subpath tests cover.

Deployment target considerations: This is a PyPI client library, not a deployed service, so SaaS / DI / in-VPC / on-prem / SND deploys are unaffected. Air-gapped users pointing the SDK at their own hostname keep the existing keep-the-path behavior, since their host is not under an Unstructured domain.

A note on the diff size

The last commit is ruff format over the files this change touches, plus seven noqa directives for pre-existing lint that cannot be auto-fixed without changing behaviour. It is formatting only and carries no behaviour change, so reading the first two commits on their own gives you the whole fix. Two of the noqas are worth knowing about: raise err in basesdk.py re-raises whatever an after-error hook returned, which is not always the active exception, so ruff's suggested bare raise would be a real bug.

Risk / rollback

Low. Small changes to URL normalization plus a .genignore entry, revert-safe, no migration and no flag.

How it was verified

Ran the unit suite on Python 3.11, 3.12 and 3.13 and the contract suite, plus pylint (10.00/10) and mypy, all green, matching what CI runs. uv.lock is unchanged, so the UV_LOCKED=1 install holds. Reproduced the bug and then the fix against the live Transform Platform API without an API key, which is enough to tell the two apart: a route that exists answers 401, a route that does not answers 404. Not exercised with a real API key end to end, and not exercised against a self-hosted deployment.

Proof

Repro, against the live API, before the fix:

$ curl -s -o /dev/null -w '%{http_code}\n' https://platform-api.transform.unstructured.io/api/v1/jobs/
401
$ curl -s -o /dev/null -w '%{http_code}\n' https://platform-api.transform.unstructured.io/api/v1/api/v1/jobs/
404

Through the SDK, before the fix:

server_url='https://platform-api.transform.unstructured.io'
  request sent: https://platform-api.transform.unstructured.io/api/v1/jobs/
  status:       401

server_url='https://platform-api.transform.unstructured.io/api/v1'
  request sent: https://platform-api.transform.unstructured.io/api/v1/api/v1/jobs/
  status:       404

Failing tests at HEAD before the fix, _test_unstructured_client/unit/test_server_urls.py::test_platform_request_url_has_a_single_api_prefix plus the hook tests:

FAILED test_custom_hooks.py::test_unit_clean_server_url_fixes_malformed_transform_platform_url[https://platform-api.transform.unstructured.io/api/v1]
FAILED test_custom_hooks.py::test_unit_clean_server_url_fixes_malformed_transform_platform_url[http://platform-api.transform.unstructured.io/api/v1]
FAILED test_custom_hooks.py::test_unit_clean_server_url_fixes_malformed_transform_platform_url[platform-api.transform.unstructured.io/api/v1]
FAILED test_custom_hooks.py::test_unit_clean_server_url_fixes_malformed_transform_platform_url[platform-api.transform.unstructured.io]
FAILED test_custom_hooks.py::test_unit_clean_server_url_leaves_lookalike_domains_alone[http://unstructuredapp.io.example.com/api/v1]

E  Failed: transform platform ... Expected https://platform-api.transform.unstructured.io, got https://platform-api.transform.unstructured.io/api/v1

After the fix, the same live check across both ways of passing the URL:

client-level, bare host
  sent:   https://platform-api.transform.unstructured.io/api/v1/jobs/
  status: 401

client-level, URL from the app (/api/v1)
  sent:   https://platform-api.transform.unstructured.io/api/v1/jobs/
  status: 401

operation-level, bare host
  sent:   https://platform-api.transform.unstructured.io/api/v1/jobs/
  status: 401

operation-level, URL from the app (/api/v1)
  sent:   https://platform-api.transform.unstructured.io/api/v1/jobs/
  status: 401

Every case now reaches the real route. Suites after the fix: unit and contract both pass, pylint 10.00/10, mypy clean.

Dependencies / merge order

none

Worked Example

from unstructured_client import UnstructuredClient

# The value the app's API Keys page gives you, pasted as-is.
client = UnstructuredClient(
    api_key_auth="YOUR_KEY",
    server_url="https://platform-api.transform.unstructured.io/api/v1",
)

client.jobs.list_jobs(request={})
# before: GET https://platform-api.transform.unstructured.io/api/v1/api/v1/jobs/ -> 404 {"detail":"Not Found"}
# after:  GET https://platform-api.transform.unstructured.io/api/v1/jobs/, the real route

Release

Bumped to 0.46.2 with CHANGELOG and RELEASES entries.