> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deprecation of truefoundry < 0.17.0; Repositories APIs moved from /api/ml to /api/svc prefix

> Install truefoundry 0.17.x or truefoundry-sdk 0.4.x on control plane 0.157+. The Repositories APIs have moved from /api/ml to /api/svc prefix. The /api/ml prefix will be removed in 0.188.x.

<Warning>
  **Applicable to:** Anyone who installs the [`truefoundry` Python package](https://pypi.org/project/truefoundry/) (CLI, SDK, experiment tracking, `tfy apply` in CI, or a pinned version in a job or notebook image), the [`truefoundry-sdk` package](https://pypi.org/project/truefoundry-sdk/) in **Python** or [TypeScript](https://www.npmjs.com/package/truefoundry-sdk), **or** anyone who calls the **Repositories APIs** from custom code.

  **Not applicable if** you never install these packages and never call the Repositories APIs from custom code.
</Warning>

## What Is Changing

Two things are changing together:

1. The **Repositories APIs** now use the `/api/svc` prefix instead of `/api/ml`.
2. Older **`truefoundry`** and **`truefoundry-sdk`** package versions that still call `/api/ml` are deprecated.

The APIs themselves are not going away. Only the old prefix and the old package versions are.

### 1. Repositories APIs move from `/api/ml` to `/api/svc`

The **Repositories APIs** are the HTTP APIs for:

* [Repositories](/docs/api-reference/mlrepos/get-ml-repo)
* [Artifacts and artifact versions](/docs/api-reference/artifacts/get-artifact)
* [Models and model versions](/docs/api-reference/models/get-model)
* [Prompts and prompt versions](/docs/api-reference/prompts/get-prompt)
* [Agent skills and agent skill versions](/docs/api-reference/agent-skills/get-agent-skill)
* Data directories

These APIs now live under **`/api/svc`**. HTTP method, query parameters, and request/response bodies are unchanged. Nested paths (`/*`) move the same way.

| API                                                                              | Old prefix (`/api/ml`)                                                 | New prefix (`/api/svc`)                                                  |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [Repositories](/docs/api-reference/mlrepos/get-ml-repo)                          | `/api/ml/v1/ml-repos`, `/api/ml/v1/ml-repos/*`                         | `/api/svc/v1/ml-repos`, `/api/svc/v1/ml-repos/*`                         |
| [Artifacts](/docs/api-reference/artifacts/get-artifact)                          | `/api/ml/v1/artifacts`, `/api/ml/v1/artifacts/*`                       | `/api/svc/v1/artifacts`, `/api/svc/v1/artifacts/*`                       |
| [Artifact versions](/docs/api-reference/artifacts/get-artifact-version)          | `/api/ml/v1/artifact-versions`, `/api/ml/v1/artifact-versions/*`       | `/api/svc/v1/artifact-versions`, `/api/svc/v1/artifact-versions/*`       |
| [Models](/docs/api-reference/models/get-model)                                   | `/api/ml/v1/models`, `/api/ml/v1/models/*`                             | `/api/svc/v1/models`, `/api/svc/v1/models/*`                             |
| [Model versions](/docs/api-reference/models/get-model-version)                   | `/api/ml/v1/model-versions`, `/api/ml/v1/model-versions/*`             | `/api/svc/v1/model-versions`, `/api/svc/v1/model-versions/*`             |
| [Agent skills](/docs/api-reference/agent-skills/get-agent-skill)                 | `/api/ml/v1/agent-skills`, `/api/ml/v1/agent-skills/*`                 | `/api/svc/v1/agent-skills`, `/api/svc/v1/agent-skills/*`                 |
| [Agent skill versions](/docs/api-reference/agent-skills/get-agent-skill-version) | `/api/ml/v1/agent-skill-versions`, `/api/ml/v1/agent-skill-versions/*` | `/api/svc/v1/agent-skill-versions`, `/api/svc/v1/agent-skill-versions/*` |
| [Prompts](/docs/api-reference/prompts/get-prompt)                                | `/api/ml/v1/prompts`, `/api/ml/v1/prompts/*`                           | `/api/svc/v1/prompts`, `/api/svc/v1/prompts/*`                           |
| [Prompt versions](/docs/api-reference/prompts/get-prompt-version)                | `/api/ml/v1/prompt-versions`, `/api/ml/v1/prompt-versions/*`           | `/api/svc/v1/prompt-versions`, `/api/svc/v1/prompt-versions/*`           |
| [Data directories](/docs/truefoundry_sdk/data_directories)                       | `/api/ml/v1/data-directories`, `/api/ml/v1/data-directories/*`         | `/api/svc/v1/data-directories`, `/api/svc/v1/data-directories/*`         |

Example:

```
https://<control-plane-url>/api/ml/v1/models
https://<control-plane-url>/api/svc/v1/models
```

* On control plane **0.157.x and later**, `/api/ml` is deprecated. Use `/api/svc`.
* On control plane **0.188.x**, `/api/ml` is **removed**. Calls to that prefix fail.

If you call these HTTP paths from your own code (scripts, services, or GitOps), search for `/api/ml/` and change the prefix. If you only use `truefoundry` or `truefoundry-sdk`, upgrade the package instead — you do not need to edit URLs by hand.

### 2. Older `truefoundry` and `truefoundry-sdk` versions are deprecated

`truefoundry` **0.17.x** and `truefoundry-sdk` **0.4.x** already call `/api/svc`.

Older package versions still call `/api/ml`. Those versions are deprecated:

* On control plane **\< 0.157.x**, `truefoundry` **\< 0.16.0** and `truefoundry-sdk` **\< 0.3.0** are deprecated.
* On control plane **0.157.x and later**, `truefoundry` **\< 0.17.0** and `truefoundry-sdk` **\< 0.4.0** are deprecated.
* On control plane **0.188.x**, requests from older `truefoundry` versions ( **\< 0.17.0** ) are **rejected**.

<Note>
  `truefoundry` **0.17.x** requires **Python 3.10 or later**. See [Minimum Python version raised to 3.10 — truefoundry v0.17.0](/docs/change-announcements/python-3.10-minimum-truefoundry-cli-v0.17.0).

  v0.17.0 also removes `run.log_images()` and `run.log_plots()`. Migrate those calls before upgrading: [Deprecation of Images and Plots in Job Runs — v0.156.0](/docs/change-announcements/deprecation-of-images-and-plots-in-job-runs-v0.156.0).
</Note>

### When this becomes a hard break

Requests from outdated `truefoundry` Python packages will be rejected only when **your tenant** reaches control plane **0.188.x**.
You will receive the following error message:

```
You are using an outdated version of `truefoundry`.
Run `pip install truefoundry>=0.17.0` to install the supported version.
```

Calls that still use `/api/ml` fail because that prefix is removed.

SaaS is expected to reach 0.188.x around **15 November 2026**. Self-hosted tenants are unaffected until they upgrade to 0.188.x.

| Milestone                                                                                  | When                                                                  |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Deprecation announcement                                                                   | **19 August 2026**                                                    |
| `/api/ml` deprecated; Repositories APIs served under `/api/svc`; older packages deprecated | Control plane **0.157.x**                                             |
| Older `truefoundry` packages rejected; `/api/ml` removed                                   | Control plane **0.188.x** (SaaS expected around **15 November 2026**) |

## Which version should I install?

The package version you need depends on your **control plane** version. Find it at the **top left, below the logo**.

<Info>
  **SaaS:** Your control plane is already on latest version. Install `truefoundry>=0.17.0` and `truefoundry-sdk>=0.4.0` now.
</Info>

<Warning>
  Do **not** install `truefoundry` 0.17.x or `truefoundry-sdk` 0.4.x on a control plane older than 0.157.x.
</Warning>

| Control plane  | `truefoundry`                 | `truefoundry-sdk` (Python and TypeScript) |
| -------------- | ----------------------------- | ----------------------------------------- |
| **\< 0.157.x** | `truefoundry>=0.16.0,<0.17.0` | `truefoundry-sdk>=0.3.0,<0.4.0`           |
| **≥ 0.157.x**  | `truefoundry>=0.17.0`         | `truefoundry-sdk>=0.4.0`                  |

| What                           | How to check                            |
| ------------------------------ | --------------------------------------- |
| Control plane                  | Top left, below the logo                |
| `truefoundry` (Python)         | `pip show truefoundry` or `tfy version` |
| `truefoundry-sdk` (Python)     | `pip show truefoundry-sdk`              |
| `truefoundry-sdk` (TypeScript) | `npm ls truefoundry-sdk`                |

## What You Need to Do

<Tabs>
  <Tab title="SaaS">
    <Steps>
      <Step title="Upgrade Python to 3.10 or later">
        Required before installing `truefoundry` 0.17.x. See [Minimum Python version raised to 3.10](/docs/change-announcements/python-3.10-minimum-truefoundry-cli-v0.17.0).
      </Step>

      <Step title="Upgrade the truefoundry package">
        ```bash theme={"dark"}
        pip install --upgrade "truefoundry>=0.17.0"
        ```
      </Step>

      <Step title="Upgrade truefoundry-sdk (if you use it)">
        `truefoundry-sdk` is published for both Python and TypeScript:

        <CodeGroup>
          ```bash Python theme={"dark"}
          pip install --upgrade "truefoundry-sdk>=0.4.0"
          ```

          ```bash TypeScript theme={"dark"}
          npm install "truefoundry-sdk@>=0.4.0"
          ```
        </CodeGroup>
      </Step>

      <Step title="Repeat everywhere the packages are pinned">
        Update laptops, CI (`tfy apply` and GitHub Actions), `requirements.txt` / lockfiles, and job or notebook images.
      </Step>

      <Step title="Update custom HTTP clients">
        If you call the Repositories APIs from your own code, change `/api/ml` to `/api/svc`. See the table in [What Is Changing](#1-repositories-apis-move-from-apiml-to-apisvc).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Self-hosted control plane">
    <Tip>
      We recommend you upgrade the control plane to **[0.162.10 or higher](/docs/changelog)** as soon as possible.
    </Tip>

    <Steps>
      <Step title="If your control plane is older than 0.157.x, pin the last compatible packages">
        Do **not** install `truefoundry` 0.17.x or `truefoundry-sdk` 0.4.x yet:

        ```bash theme={"dark"}
        pip install --upgrade "truefoundry>=0.16.0,<0.17.0"
        ```

        Pin `truefoundry-sdk` to **\< 0.4.0** if you use it:

        <CodeGroup>
          ```bash Python theme={"dark"}
          pip install --upgrade "truefoundry-sdk>=0.3.0,<0.4.0"
          ```

          ```bash TypeScript theme={"dark"}
          npm install "truefoundry-sdk@>=0.3.0 <0.4.0"
          ```
        </CodeGroup>
      </Step>

      <Step title="Upgrade the control plane">
        Upgrade to **[0.162.10 or higher](/docs/changelog)**. You can stay on `truefoundry` 0.16.x during this step — it still works until you reach 0.188.x.
      </Step>

      <Step title="Upgrade Python to 3.10 or later">
        Required before installing `truefoundry` 0.17.x. See [Minimum Python version raised to 3.10](/docs/change-announcements/python-3.10-minimum-truefoundry-cli-v0.17.0).
      </Step>

      <Step title="Upgrade to truefoundry 0.17.x and truefoundry-sdk 0.4.x">
        ```bash theme={"dark"}
        pip install --upgrade "truefoundry>=0.17.0"
        ```

        <CodeGroup>
          ```bash Python theme={"dark"}
          pip install --upgrade "truefoundry-sdk>=0.4.0"
          ```

          ```bash TypeScript theme={"dark"}
          npm install "truefoundry-sdk@>=0.4.0"
          ```
        </CodeGroup>

        Repeat this in CI, job or notebook images, and any lockfile that pins these packages.
      </Step>

      <Step title="Update custom HTTP clients">
        If you call the Repositories APIs from your own code, change `/api/ml` to `/api/svc`. See the table in [What Is Changing](#1-repositories-apis-move-from-apiml-to-apisvc).
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  Upgrade to `truefoundry>=0.17.0` (Python 3.10+) and `truefoundry-sdk>=0.4.0` before your control plane reaches **0.188.x**. After that version, older Python packages and `/api/ml` calls will fail.
</Warning>

## Related announcements

* [Deprecation of Images and Plots in Job Runs — v0.156.0](/docs/change-announcements/deprecation-of-images-and-plots-in-job-runs-v0.156.0)
* [Minimum Python version raised to 3.10 — truefoundry v0.17.0](/docs/change-announcements/python-3.10-minimum-truefoundry-cli-v0.17.0)

***

If you have questions or need help choosing a version, reach out to [**support@truefoundry.com**](mailto:support@truefoundry.com) — we're happy to assist.