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

# Migrating an existing decisions integration

> Move an existing decisions integration to Torchcast.

The Torchcast Decision API uses the standard decisions API request, response and error shapes for `POST /v1/decisions`. Most existing integrations move with three changes.

## What to change

1. **Base URL**: send requests to `https://api.torchcast.ai/v1/decisions`.
2. **API key**: create a key in the [console](https://console.torchcast.ai/console) and send it as `Authorization: Bearer tcd_...`.
3. **Model id**: use `torchcast-decider-latest`, or a pinned id from [`GET /v1/models`](/models#list-the-models).

```bash cURL theme={null}
curl https://api.torchcast.ai/v1/decisions \
  -H "Authorization: Bearer $TORCHCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "torchcast-decider-latest",
    "state": "Please cancel my subscription at the end of this month.",
    "questions": {
      "churn_risk": { "type": "noul", "instructions": "Does the customer want to stop paying?" }
    }
  }'
```

Your existing parsing of `answers`, `usage` and `error` keeps working.

## Rules to check

### The response `model` is the pinned id

The `model` field of a successful response is always the pinned id that answered, never the alias you sent. If you call `torchcast-decider-latest`, expect `model` to be a pinned id such as `torchcast-decider-4b-v1-1-api-1`. If your code compares the response `model` with the requested one, compare against the alias's `target_model` from `GET /v1/models` instead, or drop the check. See [Models](/models).

### Question names

Question names must be 1 to 64 characters of letters, digits, `_` and `-`. Names with spaces, dots or other characters are rejected with `400 invalid_request`. Rename such questions, for example `"is defect?"` to `is_defect`.

### Option names

`choice` option names must be 1 to 128 characters, and each must be unique within its question. A JSON body that repeats a key anywhere (in `questions`, in `criteria`, or inside the `state`) is rejected with `400`, rather than silently keeping the last value.

### Strict request fields

Fields other than `model`, `state` and `questions` at the top level, and other than `type`, `instructions` and `criteria` in a question, are rejected with `400 invalid_request`, with `param` naming the field.

### Body size

Request bodies can be up to 28 MiB. See [Limits](/limits#request-limits).

### Other behavior

* Validation errors are always `400`, never `422`.
* `x-request-id` is generated by Torchcast on every response; a value you send is ignored.
* There is no `Idempotency-Key` support: a repeated successful request is charged again. See [Limits](/limits#retries-and-idempotency).
* Prices and per-model limits come from `GET /v1/models`. See [Billing](/billing).


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