About

REST API

An overview of the Kognitos REST API.

Overview

The Kognitos REST API provides a programmatic interface for interacting with Kognitos. It allows developers to manage agents, processes, files, and runs.

Version 2 is the latest version of the Kognitos REST API.

Authentication

Authentication is handled via an API Key. You must include your key in the x-api-key header for every request:

x-api-key: YOUR_API_KEY

Obtaining an API Key

  1. Log in to your Kognitos account.

  2. Navigate to User Icon > API Keys.

  3. Click on New API Key. Assign it a name and a scope.

  4. Click Create to generate your secret key. Store the key securely, as it won't be shown again.

For detailed instructions on generating and managing API keys, see the API Keys Guide.

Base URLs

Our REST API is available in different regions. Use the base URL that matches your region when making requests:

Region
Base URL

US Region

https://rest-api.app.kognitos.com

EU Region

https://rest-api.eu.kognitos.com

UK Region

https://rest-api.uk.kognitos.com

Core Concepts

Agents

Agents are the execution environments for your processes. Each agent has its own:

  • Set of available processes

  • Execution resources

  • Security context

  • Configuration settings

Processes

Processes are reusable automation workflows that:

  • Define the steps to execute

  • Specify required inputs and expected outputs

  • Can be in Draft (development) or Published (production-ready) mode

  • Are versioned for change tracking

Runs

Runs are individual executions of a process.

  • Each run has a unique ID for tracking.

  • Runs execute asynchronously.

  • Status transitions: Pending → Running → Succeeded/Failed/Cancelled

  • The output of a run is available after successful completion.

State
Description

Pending

Run is queued for execution.

Running

Run is currently executing.

Succeeded

Run completed successfully.

Failed

Run encountered an error.

Cancelled

Run was cancelled by user.

TimedOut

Run exceeded maximum execution time.

Files

Files can be uploaded to Kognitos through the following process:

  1. Request an upload URL from the API

  2. Upload the file directly to the provided URL

This approach:

  • Supports large file uploads

  • Provides better performance

  • Enables direct cloud storage integration

Last updated

Was this helpful?