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

# SDK v3 migration

> Update code and scripts that use Together Python SDK 2.x, TypeScript SDK 0.58, or CLI 2.x for the breaking changes in Python SDK 3.0, TypeScript SDK 1.0, and CLI 3.0.

Here are the main breaking changes to be aware of when you upgrade to Together Python SDK 3.0, TypeScript SDK 1.0, or Together CLI 3.0:

* Dedicated model inference and GPU clusters are no longer in the `beta` namespace.
* `/v1` is dropped from the base URL.
* `whoami` returns a typed identity.
* Deprecated APIs and import paths have been removed.

Together CLI 3.0 ships in the same `together` package as the Python SDK and renames its commands to match.

Upgrade the SDKs and CLI with `uv` or `npm`:

```bash theme={null}
# Python SDK
uv add "together>=3.0.0"

# TypeScript SDK
npm install together-ai@latest

# Together CLI
uv tool install "together[cli]" --upgrade
```

## Dedicated model inference out of the `beta` namespace

Dedicated model inference resources moved to the top level of the client, and their CLI commands moved out of `tg beta`:

| 2.x | 3.0 |
| :- | :- |
| `client.beta.endpoints.*` | `client.endpoints.*` |
| `client.beta.models.*` | `client.models.*` |
| `tg beta endpoints <command>` | `tg endpoints <command>` |
| `tg beta models <command>` | `tg models <command>` |

Method names, parameters, and CLI flags didn't change, except that in Python, `endpoints.adapters.retrieve()`, `update()`, and `delete()` no longer take the `adapter_model_id` cross-check parameter. Pass the attachment ID (`dad_...`) alone.

The types moved too. In Python, import them from `together.types` instead of `together.types.beta` (for example, `together.types.Endpoint`). In TypeScript, the `Beta.Endpoints` and `Beta.Models` type namespaces are now top level.

## GPU clusters out of the `beta` namespace

The `client.beta.clusters` and `tg beta clusters` aliases are gone. Use the top-level names, which have worked since Python SDK 2.40.0, TypeScript SDK 0.58.0, and CLI 2.40.0, so you can switch before you upgrade:

| 2.x | 3.0 |
| :- | :- |
| `client.beta.clusters.*` | `client.clusters.*` |
| `tg beta clusters <command>` | `tg clusters <command>` |

Two cluster parameters are also gone:

* **Autoscaling flag:** `clusters.create()` no longer takes `auto_scaled`. Use `auto_scale` with `auto_scale_max_gpus`.
* **Remediation ID:** `clusters.remediations.create()` no longer takes `remediation_id`, and `tg clusters remediations create` no longer takes `--remediation-id`. The service assigns the ID, so read it from the response.

## Removed v1 dedicated endpoint methods

In 2.x, the top-level `client.endpoints` and `client.models` methods and the `tg endpoints` and `tg models` commands called the v1 dedicated endpoints API. In 3.0, the same names call dedicated model inference. These v1 methods are gone from the Python SDK:

* `endpoints.create()`, `list()`, `retrieve()`, `update()`, and `delete()` with v1 arguments.
* `endpoints.list_hardware()` and `endpoints.list_avzones()`.
* `endpoints.adapters.add()`, `remove()`, and `list(endpoint_id)`.
* `models.list(dedicated=...)`, `models.upload()`, and `models.uploads.status()`.

The TypeScript SDK removes the same methods in camelCase, such as `endpoints.listHardware()` and `endpoints.listAvzones()`.

The CLI removes these commands and flags:

* `tg endpoints create`, `start`, `stop`, `hardware`, `availability-zones`, and `adapters`.
* `tg models list --type` and `tg models upload --model-name --model-source`.

`tg endpoints list`, `retrieve`, `update`, and `delete` still exist, but they now manage dedicated model inference resources and take its arguments.

`client.models.list()` now lists the models in your project instead of the serverless catalog. For the serverless catalog, see [Serverless models](https://docs.together.ai/docs/serverless/models.md).

To move a v1 endpoint to dedicated model inference, see [Migrate from v1](https://docs.together.ai/docs/dedicated-endpoints/migrate-from-v1.md). To list, stop, or delete v1 endpoints that are still running, call the [v1 REST API](https://docs.together.ai/docs/dedicated-endpoints/migrate-from-v1.md#manage-remaining-v1-endpoints).

## Base URL without `/v1`

If you set `base_url`, `baseURL`, or `TOGETHER_BASE_URL`, drop the trailing `/v1`. Each method's path now carries its own API version (`/v1/chat/completions`, `/v2/projects/...`, `/v3/whoami`). The SDK doesn't strip `/v1` from the base URL, so a base URL that still ends in `/v1` sends requests to `/v1/v1/...`.

```python Python theme={null}
from together import Together

# 2.x: Together(base_url="https://api-inference.together.ai/v1")
client = Together(base_url="https://api-inference.together.ai")
```

```typescript TypeScript theme={null}
import Together from "together-ai";

// 0.58: new Together({ baseURL: "https://api-inference.together.ai/v1" })
const client = new Together({ baseURL: "https://api-inference.together.ai" });
```

OpenAI-compatible clients are unaffected. They still take `https://api.together.ai/v1` or `https://api-inference.together.ai/v1`.

The default base URL is `https://api.together.ai`, except for chat completions requests, which now go to `https://api-inference.together.ai` by default. When you set a base URL other than the default, every method uses it.

## `whoami` returns a typed identity

`client.whoami()` calls `GET /v3/whoami`. The response has a `type` field and nested `project` and `organization` objects instead of flat fields. For example, `project_id` is now `project.id`, and `project_slug` is now `project.slug`. Which fields are present depends on the credential:

| `type` | Credential | Fields |
| :- | :- | :- |
| `project_api_key` | Project API key. | `api_key`, `organization`, `project` |
| `org_api_key` | Organization API key. | `api_key`, `organization` |
| `user_jwt` | User session. | `user` |
| `user_org_jwt` | User session scoped to an organization. | `user`, `organization` |
| `user_org_project_jwt` | User session scoped to a project. | `user`, `organization`, `project` |

Only project-scoped credentials carry a `project`, so check `type` before you read it. The check also lets type checkers narrow the response:

```python Python theme={null}
from together import Together

client = Together()

# 2.x: project_id = client.whoami().project_id
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id
```

```typescript TypeScript theme={null}
import Together from "together-ai";

const client = new Together();

// 0.58: const { project_id: projectId } = await client.whoami();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;
```

To avoid calling `whoami()` for the project ID, set `TOGETHER_PROJECT_ID`, or pass `project_id` to `Together()` in Python or `projectID` to `new Together()` in TypeScript. Project-scoped methods use this project ID when you don't pass one.

## Removed aliases and import paths

* **Organization usage:** Both SDKs add `client.organization.usage.costs.list()`. In TypeScript, `client.organization` replaces the empty `client.beta.organization` namespace. In Python, the types moved from `together.types.beta.organization` to `together.types.organization`.
* **Post-training imports:** The `together.lib.beta.rl` and `together.lib.post_training` import paths are gone. Import from `together.post_training`.
* **Python errors and constants:** The `together.error` and `together.constants` modules are gone. Import exceptions such as `RateLimitError` from `together`.
* **Python v1 type aliases:** `together.types` no longer exports `ChatCompletion`, `ChatCompletionChunk`, `ChatCompletionUsage`, `ChatCompletionResponse`, `CompletionResponse`, `UsageData`, `ListEndpoint`, `ImageRequest`, or `ImageResponse`. Import the generated types from their submodules instead, such as `ChatCompletion` from `together.types.chat`.

## Removed APIs and parameters

* **Legacy function calling:** Chat completions no longer accept assistant messages with `function_call` or messages with the `function` role, and responses no longer include `function_call`. In TypeScript, the chat completion runner's `finalFunctionCall()` is gone too. Use `tools` and messages with the `tool` role, as in [Function calling](https://docs.together.ai/docs/inference/function-calling/overview.md).
* **Video keyframes and references:** `videos.create()` no longer takes top-level `frame_images` or `reference_images`. Pass them inside `media`, as in [Reference images and keyframes](https://docs.together.ai/docs/inference/videos/reference-and-keyframes.md).
* **Code interpreter:** `client.code_interpreter` in Python and `client.codeInterpreter` in TypeScript are gone, along with the API they called.
* **Fine-tuning delete:** `fine_tuning.delete()` no longer takes `force`.
* **TypeScript fine-tuning inputs:** `fineTuning.create()` no longer takes a top-level `train_on_inputs`. Pass it inside `training_method`. The Python SDK still accepts the keyword.
* **FP4 preparation inputs:** `adapter_object_id` and `adapter_revision_id` are gone from the `inputs` of `post_training.prepare_for_fp4_inference.create()` and `estimate_cost()`. Use `model_object_id` and `model_revision_id`.
* **File processing status:** File responses no longer include `processed`. Read `processing_status`.
* **TypeScript file checks:** `client.files.upload()` no longer takes a third `check` argument. Pass only the file path and the purpose. The SDK no longer checks file contents before uploading, but the server still validates them. The Python SDK keeps `check`.

## Getting help

* Browse the SDK source in the [together-py](https://github.com/togethercomputer/together-py) and [together-typescript](https://github.com/togethercomputer/together-typescript) repos.
* For code written against the v1 Python SDK, start with the [Python SDK v2 migration](https://docs.together.ai/docs/pythonv2-migration-guide.md).
* Report issues on [Discord](https://discord.com/channels/1082503318624022589/1228037496257118242) or [contact support](https://portal.usepylon.com/together-ai/forms/support-request).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.