Migrating to v2

How to migrate from Kognitos REST API v1 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.

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.

Authentication

v2 uses the same authentication mechanism as v1. All requests require the x-api-key header with an API key. 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.

Need help finding your identifiers? See How do I get an agent ID?, How do I get a process ID?, and How do I get a run ID? in the FAQ.

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.

See Example 5: Get a Specific Run.

Aspect	v1	v2
Endpoint	GET /v1/run/{worker_id}	GET /v2/runs/{id}
Path Parameters	worker_id	id (run ID)
Query Parameters	None	None
Request Body	None	None
Response	{ "state": "done", "answer": "{json having key and value of each output}" }	{ "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" }

Uploading Files

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

See Example 7: Start a New Run (with File Upload).

Aspect	v1	v2
Step 1: Request Upload URL	POST /v1/upload	POST /v2/files
Step 2: Upload File	Upload file content to returned pre-signed URL	Upload file content to returned pre-signed URL
Step 3: Reference in Run	Pass blob_url via attachments_key query parameter in /v1/invoke/{share_id}	Pass file_id in file_ids array in request body of /v2/runs

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.

See Example 6: Start a New Run.

Aspect	v1	v2
Endpoint	POST /v1/invoke/{share_id}	POST /v2/runs
Path Parameters	share_id	None
Query Parameters	attachments_key (optional)	None
Request Body	{ "fact": "value" }	{ "process_id": "abc123", "agent_id": "xyz789", "stage": "Published", "inputs": { "param1": "value1" }, "file_ids": ["file123"] }
Response	{ "worker_id": "worker123abc456" }	{ "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" }