# Migrating to V2

## Overview

This guide describes how to migrate from the Kognitos REST API v1 *(deprecated)* to v2, which offers improved resource organization, more detailed responses, and additional endpoints.

This table shows how v1 endpoints map to their v2 equivalents, along with new capabilities:

| Operation                 | v1                           | v2                       |
| ------------------------- | ---------------------------- | ------------------------ |
| **Start a Process Run**   | `POST /v1/invoke/{share_id}` | `POST /v2/runs`          |
| **Get Run Status**        | `GET /v1/run/{worker_id}`    | `GET /v2/runs/{id}`      |
| **Upload Files**          | `POST /v1/upload`            | `POST /v2/files`         |
| **List Runs**             | *Not available*              | `GET /v2/runs`           |
| **List Processes**        | *Not available*              | `GET /v2/processes`      |
| **Get Process Details**   | *Not available*              | `GET /v2/processes/{id}` |
| **Check REST API Health** | *Not available*              | `GET /v2/health`         |

## Migrating to v2

The REST API v2 endpoints are immediately accessible using your existing API keys and identifiers. Migrating your automations involves updating request structures and handling the new, enhanced responses.

{% hint style="success" %}
**We recommend migrating to v2 at your earliest convenience**. While an end-of-life date for v1 has not yet been announced, transitioning now ensures you benefit from v2's enhanced capabilities and continued support.
{% endhint %}

### Authentication

v2 uses the same authentication mechanism as v1. All requests require the `x-api-key` header with an [API key](/legacy/legacy-experience/account/api-keys.md). You can continue using your current API keys without regenerating or reconfiguring them.

### Base URLs

v2 uses the same region-specific base URLs as v1:

* **US Region**: `rest-api.app.kognitos.com`
* **EU Region**: `rest-api.eu.kognitos.com`
* **UK Region**: `rest-api.uk.kognitos.com`

### Identifiers

The same **agent\_id** and **process\_id** values work in v2 without modification. These identifiers are retrieved the same way. No identifier format changes or migrations are required.

However, v1's **worker\_id** concept does not exist in v2. In v1, you received a `worker_id` from `POST /v1/invoke/{share_id}` and used it to check the run status with `GET /v1/run/{worker_id}`.

In v2, runs are identified by a **run ID,** which is part of a more comprehensive run object.

### Endpoints

The following sections detail the key differences between v1 and v2 endpoints for each operation. In general, v2 uses more structured request formats and returns richer response objects with additional metadata.

#### Checking Run Status

Update your response parsing logic to extract data from the detailed run object with status, timestamps, and metadata fields.

<table><thead><tr><th width="175.2109375">Aspect</th><th>v1</th><th>v2</th></tr></thead><tbody><tr><td><strong>Endpoint</strong></td><td><code>GET /v1/run/{worker_id}</code></td><td><code>GET /v2/runs/{id}</code></td></tr><tr><td><strong>Path Parameters</strong></td><td><code>worker_id</code></td><td><code>id</code> <em>(run ID)</em></td></tr><tr><td><strong>Query Parameters</strong></td><td>None</td><td>None</td></tr><tr><td><strong>Request Body</strong></td><td>None</td><td>None</td></tr><tr><td><strong>Response</strong></td><td><code>{ "state": "done", "answer": "{json having key and value of each output}" }</code></td><td><code>{ "agent_id": "abc123def456", "created_at": "2021-01-01T12:00:00", "file_ids": ["file789abc", "file456xyz"], "id": "run789xyz", "name": "Process invoice", "outputs": [{"name": "total_items", "value": 42}, {"name": "customer_id", "value": "cus123abc"}], "process_id": "proc456def", "stage": "Draft", "status": "Created" }</code></td></tr></tbody></table>

#### Uploading Files

Both v1 and v2 use a multi-step upload process with pre-signed URLs.

<table><thead><tr><th width="234.77734375">Aspect</th><th>v1</th><th>v2</th></tr></thead><tbody><tr><td><strong>Step 1: Request Upload URL</strong></td><td><code>POST /v1/upload</code></td><td><code>POST /v2/files</code></td></tr><tr><td><strong>Step 2: Upload File</strong></td><td>Upload file content to returned pre-signed URL</td><td>Upload file content to returned pre-signed URL</td></tr><tr><td><strong>Step 3: Reference in Run</strong></td><td>Pass <code>blob_url</code> via <code>attachments_key</code> query parameter in <code>/v1/invoke/{share_id}</code></td><td>Pass <code>file_id</code> in <code>file_ids</code> array in request body of <code>/v2/runs</code></td></tr></tbody></table>

#### Starting a Run

Instead of using a share ID in the URL path, put all the run details *(process ID, agent ID, stage, inputs, and file references)* directly in the request body. Update your automation logic as needed to parse the comprehensive run object returned in the response.

<table><thead><tr><th width="171.93359375">Aspect</th><th>v1</th><th>v2</th></tr></thead><tbody><tr><td><strong>Endpoint</strong></td><td><code>POST /v1/invoke/{share_id}</code></td><td><code>POST /v2/runs</code></td></tr><tr><td><strong>Path Parameters</strong></td><td><code>share_id</code></td><td>None</td></tr><tr><td><strong>Query Parameters</strong></td><td><code>attachments_key</code> <em>(optional)</em></td><td>None</td></tr><tr><td><strong>Request Body</strong></td><td><code>{ "fact": "value" }</code></td><td><code>{ "process_id": "abc123", "agent_id": "xyz789", "stage": "Published", "inputs": { "param1": "value1" }, "file_ids": ["file123"] }</code></td></tr><tr><td><strong>Response</strong></td><td><code>{ "worker_id": "worker123abc456" }</code></td><td><code>{ "agent_id": "abc123def456", "created_at": "2021-01-01T12:00:00", "file_ids": [...], "id": "run789xyz", "name": "Process invoice", "outputs": [{"name": "total_items", "value": 42}, ...], "process_id": "proc456def", "stage": "Draft", "status": "Created" }</code></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/rest-api/migrating-to-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.