> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md).

# API Versions and Compatibility

API versions define request and response contracts. Choose one documented contract for each operation rather than mixing fields from different versions.

![Keep each execution contract consistent](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fth1uqopVaGUS4MzDh2kA%2Fapi-versions-and-compatibility.png?alt=media)

These are separate API contracts. Use the authentication, request fields, version selectors, and state names documented for the selected route.

<details>

<summary>Copy the example</summary>

```http
# REST v2: create a run, then poll its status
POST /v2/runs
GET  /v2/runs/{run_id}
# Success state: succeeded

# Legacy inference: run and inspect with its own contract
POST /inference/v0/run/{org_id}/{flow_id}
GET  /inference/v0/runs/{org_id}/{run_id}
# Success state: COMPLETED
```

</details>

## Before you begin

Access to the public API reference for the endpoint you use.

## API version concepts

| Term                   | Definition                                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API version            | The request and response contract selected by an API route. It is separate from the saved workflow version you ask the API to run.                          |
| Project version        | A specific saved configuration of a project. Select it explicitly when a result must be reproducible.                                                       |
| Schema                 | A definition of fields, types, required values, and supported constraints. Use it to validate the shape of data; it does not establish factual correctness. |
| HTTP status            | The numeric outcome returned for an HTTP request. Read the response body too; accepted work can still be running.                                           |
| Asynchronous operation | An operation acknowledged before its processing is complete. Retain its handle and follow its documented status or completion mechanism.                    |

## Choose an API version

1. Use `/v2/runs` when you need an asynchronous run ID to poll, resume, or cancel. Use `/inference/v0/run/{org_id}/{flow_id}` when you need the inline JSON or streaming response contract.
2. Select a saved project version. Read its input schema with that version number and pass the same number when starting the run. Do not read `latest` and then silently execute published content.
3. Build the body for that interface. V2 uses `input` inside a wrapper containing `project_id`; inference uses the input map itself.
4. Read the endpoint’s response and status names. V2 success is `succeeded`; legacy inference success is `COMPLETED`. Do not use one status parser for both without mapping these values.

Your client uses the field names and behavior required by its endpoint.

## Behavior and limitations

A project version selects workflow content; an API version selects the request contract. Legacy inference and v2 runs use different input shapes, state handling, and version selectors. An OpenAPI document’s metadata version is not necessarily the version prefix of every route it contains.

| Contract              | Input and version behavior                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| v2 run creation       | Wrap node-keyed values in `input`. Omitted or null `project_version` uses published content; `-1` selects editable content. |
| Legacy inference      | Use the selected route’s input schema. Omitted or `-1` version selects published content.                                   |
| MCP project execution | Use the discovered tool’s `inputs` field and version selection. Do not copy the v2 REST body unchanged.                     |

When migrating, compare authentication, field names, version selection, status values, and completion handling. Keep the original client available until the new path returns the required result.

## Related resources

Authentication: Bearer Tokens and Personal API Keys

[API quickstart with a pinned project version](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/quickstart.md)

[Execution interfaces and version selectors](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/run-workflows-end-to-end.md)

[Inference and streaming](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/legacy-inference-streaming-and-analytics.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
