Migrate from v1

This guide helps you move endpoints from the v1 dedicated endpoints API to dedicated model inference (v2). It explains what changed, what stays the same, and how to recreate a v1 endpoint under the v2 resource model.

You can no longer create a v1 endpoint or restart a stopped or paused one. Both operations fail with endpoints_v1_create_access_disabled (HTTP 403) in the API (POST /v1/endpoints), SDK versions before 3.0 (client.endpoints.create(...)), Together CLI 2.x (tg endpoints create), and the Together AI console. To create a new endpoint or bring a stopped v1 endpoint back online, deploy the model on v2 as described in Migrate an endpoint. For this error and related symptoms, see Troubleshooting.

Endpoints already running on v1 keep serving and stay supported until further notice, so you can migrate them on your own schedule. Migrating also unlocks v2-only capabilities such as traffic splitting, A/B tests, shadow experiments, metric-based autoscaling, and monitoring dashboards.

What stays the same

The inference API hasn’t changed. You still send requests to POST /v1/chat/completions (and the other inference endpoints) with your endpoint name in the model field. Dedicated model inference is served at https://api-inference.together.ai:

curl -s -X POST https://api-inference.together.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOGETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-project-slug/my-endpoint",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The same applies to billing: dedicated model inference still bills per minute per running replica by hardware. See Pricing for details. The main thing you’ll need to change in your application is the model string. When you recreate an endpoint in v2, it gets a new endpoint string (<project_slug>/<endpoint_name>), so update your inference calls to use the new name.

What’s changed

v1 modeled a dedicated endpoint as a single model running on a hardware type. v2 splits that into a small resource model so one endpoint can host more than one model version and shift traffic between them:

Endpoint: A stable inference URL. It no longer carries the model or hardware itself.
Deployment: Binds a model and a config to an endpoint with an autoscaling policy. A deployment is what runs replicas and serves traffic. One endpoint can host several deployments at once.
Config: Describes how a model runs, including the hardware selectors and optimization profile. In v1 you passed a hardware ID and decoding flags. In v2 you select a published config instead.
Traffic split: Routes requests across an endpoint’s deployments by weight. Even if it’s READY, a deployment receives no traffic until you route traffic to it.

Read Concepts to review the full resource model before you migrate.

Feature mapping

v1	v2	Notes
One model per endpoint.	Endpoint plus one or more deployments.	The endpoint is now only a stable URL. The deployment runs the model.
`--hardware <hardware_id>`	A published config (`cr_...`).	Hardware is chosen through a config’s selectors, not a hardware ID flag. See Choose a config.
`--min-replicas` / `--max-replicas` on the endpoint	`--min-replicas` / `--max-replicas` on the deployment.	Autoscaling is a property of the deployment. On a running deployment `min-replicas` is at least `1`.
`--inactive-timeout <minutes>` on the endpoint	`--inactive-timeout <minutes>` on the deployment.	Off unless you set it (v1 defaulted to 60). Accepts `30` to `1440` minutes. See Automatic idle shutdown.
`--no-speculative-decoding` and other decoding flags.	Config optimization profile.	Decoding optimizations are properties of the config you select, not per-endpoint flags.
`--availability-zone`	No direct equivalent yet.	Contact support if you have a specific zone requirement.
Custom model upload.	Fine-tuned model upload.	Uploads are restricted to fine-tuned variants of the supported models. See Upload a fine-tuned model.
Low-rank adapter (LoRA) deployment.	Adapter upload, then a deployment per adapter.	Upload the adapter and deploy it like any other model. See Upload a LoRA adapter.
`tg endpoints adapters add` (several adapters on one endpoint).	Adapters attached to a deployment of their base model.	Available for adapters from post-training on supported base models. Deploy other adapters one per deployment.

Command mapping

In Together CLI 2.x and SDK versions before 3.0, the tg endpoints commands and client.endpoints methods call the v1 API. In v2, the same operations are available from the tg endpoints and tg models commands of Together CLI 3.0 and from the /v2 management API at https://api.together.ai. A few operations, such as editing a traffic split and listing deployments, are available from the SDK and API, not the CLI. The following table maps each v1 command to its v2 equivalent:

v1 operation (CLI 2.x)	v2 equivalent (CLI 3.0)
`tg endpoints hardware --model <model>`	`tg models configs <model_id>` (configs encode the hardware).
`tg endpoints create --model <m> --hardware <h>`	`tg endpoints deploy <model_id> --endpoint <name> [--config <config_id>]` (creates the endpoint, deployment, and traffic split in one step).
`tg endpoints update --min-replicas --max-replicas <id>`	`tg endpoints update <deployment_id> --min-replicas <n> --max-replicas <n>` (pass the deployment ID, and the CLI resolves the endpoint).
`tg endpoints stop <id>`	`tg endpoints update <deployment_id> --min-replicas 0 --max-replicas 0` (scales the deployment to `0/0`).
`tg endpoints start <id>`	`tg endpoints update <deployment_id> --min-replicas 1 --max-replicas <n>` (raises both bounds to `1` or more).
`tg endpoints list` / `retrieve <id>`	`tg endpoints ls` and `tg endpoints get <endpoint_id>`. List deployments from the SDK or API.
`tg endpoints delete <id>`	Stop the deployment, then smart-delete with `tg endpoints rm <deployment_id>` and `tg endpoints rm <endpoint_id>`. See Delete resources.

For the individual CLI commands and SDK methods behind these operations, see Manage deployments.

Migrate an endpoint

To move a v1 endpoint to v2, recreate it under the v2 resource model. Your v1 endpoint keeps serving while you stand up the v2 one, so you can cut over with no downtime. While both endpoints run during the cutover, you pay for the GPUs of both, so retire the v1 endpoint as soon as traffic is on v2.

Find the model and a config: Look up the model your v1 endpoint runs in the list of supported models, then list the configs published for it. Save the model ID (ml_...) and the ID of the config you choose (cr_...).
Deploy the model: With Together CLI 3.0, run tg endpoints deploy <model_id> --endpoint <name> --config <config_id>, adding --min-replicas and --max-replicas to match your v1 endpoint’s replica bounds. This creates the endpoint, deployment, and traffic split, and returns while the deployment provisions in the background. Save the endpoint string (your-project-slug/<name>).
Cut over: Update your application’s model field to the new endpoint string and send a test request.
Retire the v1 endpoint: Once traffic is on v2, stop the v1 endpoint to end its billing.

The quickstart walks through deploying and calling a v2 endpoint end to end.

Manage remaining v1 endpoints

The 3.0 SDKs and CLI removed the v1 methods and commands, so manage your remaining v1 endpoints with the v1 REST API at https://api.together.ai/v1/endpoints until you migrate them.

List v1 endpoints

List your dedicated v1 endpoints to find the ID of each one:

cURL

curl -s "https://api.together.ai/v1/endpoints?type=dedicated&mine=true" \
  -H "Authorization: Bearer $TOGETHER_API_KEY"

Each endpoint in data has an id (endpoint-...), a name that v1 inference requests pass as model, and a state, which is STARTED while the endpoint is running. To stop or delete an endpoint, pass its id as <ENDPOINT_ID>.

Stop a v1 endpoint

You can’t restart a stopped v1 endpoint. To serve its model again, you need to redeploy the model on v2.

To stop a v1 endpoint and end its billing, set its state to STOPPED:

cURL

curl -s -X PATCH "https://api.together.ai/v1/endpoints/<ENDPOINT_ID>" \
  -H "Authorization: Bearer $TOGETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "STOPPED"}'

Delete a v1 endpoint

Deleting a v1 endpoint is permanent. A stopped endpoint doesn’t bill, so delete one only when you no longer need its record:

cURL

curl -s -X DELETE "https://api.together.ai/v1/endpoints/<ENDPOINT_ID>" \
  -H "Authorization: Bearer $TOGETHER_API_KEY"

A successful delete returns HTTP 204 with an empty body.

Migrate fine-tuned models

Uploaded models carry over, but you must re-upload them into the v2 model catalog and reference them by model ID in a deployment:

Fine-tuned models: See Upload a fine-tuned model.
LoRA adapters: Re-upload each adapter and deploy it on its own deployment. See Upload a LoRA adapter. Serving several adapters on one deployment is available only for adapters from post-training.

Note the eligibility change: in v1 you could upload arbitrary models, but a v2 upload must be a fine-tuned variant of a base model architecture that Together AI already serves.

Troubleshooting

Most migration errors have one cause: v1 create and restart are retired. This isn’t a permissions problem. Your models, fine-tuned checkpoints, hardware, and API key still work, so there’s nothing to enable or restore. To fix these errors, deploy the model on v2 as described in Migrate an endpoint.

Error or symptom	What to do
`endpoints_v1_create_access_disabled` (HTTP 403) when creating an endpoint through the API, an SDK version before 3.0, or Together CLI 2.x.	Create the endpoint on v2 instead, from the console, the SDK or API, or `tg endpoints deploy` in CLI 3.0.
A stopped or paused v1 endpoint won’t start again.	Stopped v1 endpoints can’t be restarted. Redeploy the same model as a new v2 endpoint. Fine-tuned models don’t need retraining (see Migrate fine-tuned models).
Creating a v1 endpoint still fails after you change replica bounds, autoscaling, or start settings.	Those settings don’t affect the v1 create restriction. Deploy the model on v2.
The SDK still calls the v1 endpoints API.	Upgrade to `together>=3.0.0` (release notes). In 3.0, `client.endpoints` and `client.models` call the v2 API, and the v1 methods are removed. For the v2 methods, see the v2 endpoint reference.
`tg endpoints create`, `hardware`, `start`, or `stop` is missing or calls v1.	These are Together CLI 2.x commands for v1, and CLI 3.0 removes them. Upgrade to CLI 3.0 and use the v2 commands, such as `tg endpoints deploy`. To stop a v1 endpoint that’s still running, use the v1 REST API.
You can’t find a `/v2/endpoints` route in the docs or SDK.	The v2 management API is served under `https://api.together.ai`. See the endpoint reference and CLI reference.

To get the v2 commands, install the CLI, or upgrade it if it’s already installed:

uv tool install "together[cli]" --upgrade

See the models and endpoints CLI reference for the full command set.

v2 capabilities

Migrating your endpoint to v2 gives you access to several new capabilities:

Split traffic across deployments: Host several deployments behind one endpoint URL and route requests between them by weight.
Run A/B tests: Compare a candidate deployment against a baseline on live traffic before you promote it.
Run a shadow experiment: Test a new deployment in production without affecting live traffic.
Run a rollout: Migrate live traffic from one deployment to another in steps, with automatic pauses when live metrics regress.
Autoscale on a metric: Scale each deployment on the metric that fits your workload, and stop it when you don’t need it to release the hardware.
Monitor endpoints: Track latency, throughput, and utilization in built-in dashboards, and trace lifecycle changes through the events feed.

Timeline and support

Existing v1 endpoints keep running until further notice, so you can migrate on your own schedule. Create all new endpoints and redeploy v1 endpoints that have stopped on v2.

Next steps

Concepts

Learn the project, model, config, endpoint, and deployment model.

Quickstart

Recreate an endpoint end to end with the CLI or SDK.

Choose a deployment profile

Find the config that replaces your v1 hardware ID.

Manage deployments

Create, inspect, scale, stop, and delete endpoints and deployments.

GET STARTED

SERVERLESS

INFERENCE APIS

DEDICATED MODEL INFERENCE

DEDICATED CONTAINER INFERENCE

POST-TRAINING

FINE-TUNING

GPU CLUSTERS

CODE EXECUTION

ADMINISTRATION

What stays the same

What’s changed

Feature mapping

Command mapping

Migrate an endpoint

Manage remaining v1 endpoints

List v1 endpoints

Stop a v1 endpoint

Delete a v1 endpoint

Migrate fine-tuned models

Troubleshooting

v2 capabilities

Timeline and support

Next steps

Concepts

Quickstart

Choose a deployment profile

Manage deployments

​What stays the same

​What’s changed

​Feature mapping

​Command mapping

​Migrate an endpoint

​Manage remaining v1 endpoints

​List v1 endpoints

​Stop a v1 endpoint

​Delete a v1 endpoint

​Migrate fine-tuned models

​Troubleshooting

​v2 capabilities

​Timeline and support

​Next steps

Concepts

Quickstart

Choose a deployment profile

Manage deployments

What stays the same

What’s changed

Feature mapping

Command mapping

Migrate an endpoint

Manage remaining v1 endpoints

List v1 endpoints

Stop a v1 endpoint

Delete a v1 endpoint

Migrate fine-tuned models

Troubleshooting

v2 capabilities

Timeline and support

Next steps