# Overview

The Kognitos REST API lets you programmatically manage automations, trigger runs, monitor exceptions, and more. Use it to integrate Kognitos into your existing systems, build custom dashboards, or automate operational workflows.

## Base URL

```
https://app.us-1.kognitos.com/api/v1
```

{% hint style="info" %}
All API paths in this documentation are relative to the base URL above.
{% endhint %}

## Authentication

Every request requires a **Personal Access Token (PAT)** in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

PATs are created from the Kognitos UI. See [API Keys](/guides/api-reference/api-keys.md) for setup instructions.

## Quick Start

### Prerequisites

* A Kognitos account with at least one published automation
* An [API Key](/guides/api-reference/api-keys.md)

### 1. Verify Your Key

Test your API key by listing your organizations:

{% tabs %}
{% tab title="Request" %}

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/me/organizations"
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "user_organizations": [
    {
      "name": "organizations/abc123def456",
      "title": "Acme Corp",
      "owner_display_name": "Jane Smith",
      "owner_email": "jane@acme.com",
      "create_time": "2025-01-15T10:30:00Z"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Copy the organization ID from the `name` field (the part after `organizations/`). You will need it for all subsequent calls.

### 2. List Workspaces

Find the workspace that contains your automations:

{% tabs %}
{% tab title="Request" %}

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces"
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "workspaces": [
    {
      "name": "organizations/abc123def456/workspaces/ws789xyz",
      "title": "Finance",
      "create_time": "2025-02-01T14:00:00Z",
      "creator_display_name": "Jane Smith"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Copy the workspace ID from the `name` field (the part after `workspaces/`).

### 3. Invoke an Automation

Start a run of your automation:

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces/{workspace_id}/automations/{automation_id}:invoke" \
  -d '{
    "stage": "AUTOMATION_STAGE_PUBLISHED"
  }'
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "run_id": "organizations/abc123def456/workspaces/ws789xyz/automations/auto_001/runs/run_abc123"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use `AUTOMATION_STAGE_PUBLISHED` for production runs. Use `AUTOMATION_STAGE_DRAFT` to test a draft version.
{% endhint %}

### 4. Check Run Status

Monitor your run until it completes:

{% tabs %}
{% tab title="Request" %}

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}"
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "name": "organizations/abc123def456/workspaces/ws789xyz/automations/auto_001/runs/run_abc123",
  "state": {
    "completed": {
      "outputs": {
        "invoice_total": {
          "number": { "lo": 1500 }
        }
      }
    },
    "update_time": "2025-03-10T09:05:30Z"
  },
  "stage": "AUTOMATION_STAGE_PUBLISHED",
  "create_time": "2025-03-10T09:05:00Z"
}
```

{% endtab %}
{% endtabs %}

### Run States

| State       | Meaning                                        |
| ----------- | ---------------------------------------------- |
| `pending`   | Run is queued, waiting to start                |
| `running`   | Run is actively executing                      |
| `completed` | Run finished successfully (includes `outputs`) |
| `failed`    | Run encountered an unrecoverable error         |
| `waiting`   | Run is paused, waiting for input or guidance   |

### 5. Archive a Run

Archive a completed run to remove it from the default run list:

```bash
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:archive"
```

{% hint style="info" %}
The endpoint returns a standard success response on completion.
{% endhint %}

{% hint style="info" %}
Archived runs are hidden from the default run list but remain accessible through filtered queries. Archiving does not delete the run or its data.
{% endhint %}

## Resource Names

Resources use hierarchical names that encode their parent relationships:

```
organizations/{org_id}
organizations/{org_id}/workspaces/{workspace_id}
organizations/{org_id}/workspaces/{workspace_id}/automations/{automation_id}
organizations/{org_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}
```

Most endpoints require `organization_id` and `workspace_id` as path parameters. You can find these IDs by listing your organizations and workspaces.

## Pagination

List endpoints return paginated results. Use `page_size` and `page_token` to navigate:

```bash
# First page
curl -H "Authorization: Bearer $API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces?page_size=10"

# Next page (use next_page_token from previous response)
curl -H "Authorization: Bearer $API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/organizations/{org_id}/workspaces?page_size=10&page_token=TOKEN"
```

## Filtering

Many list endpoints support filtering with the `filter` query parameter, following the [AIP-160](https://google.aip.dev/160) standard:

```bash
# Filter automations by display name
?filter=display_name="Invoice Processing"

# Filter runs by state
?filter=state.completed!=null
```

### User Filtering

You can filter user lists by **display name**, **email**, or both. Filters use OR semantics, so a user is returned if either field matches.

```bash
# Search users by display name or email
?filter=display_name="Jane" OR email="jane@acme.com"
```

## Current User Permissions

You can retrieve the permissions for the currently authenticated user with the **CurrentUserPermissions** endpoint. This is useful for building interfaces or tools that adapt based on what the current user can access.

{% tabs %}
{% tab title="Request" %}

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.us-1.kognitos.com/api/v1/me/permissions?organization_id={org_id}&workspace_id={workspace_id}"
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "permissions": [
    "automations.view",
    "automations.invoke",
    "runs.view",
    "exceptions.view"
  ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The permissions returned reflect the authenticated user's effective permissions for the specified organization and workspace, based on their assigned roles.
{% endhint %}

## Errors

The API returns standard HTTP status codes:

| Code  | Meaning                                   |
| ----- | ----------------------------------------- |
| `200` | Success                                   |
| `400` | Bad request (invalid parameters)          |
| `401` | Unauthorized (missing or invalid API key) |
| `403` | Forbidden (insufficient permissions)      |
| `404` | Resource not found                        |
| `429` | Rate limited                              |
| `500` | Internal server error                     |


---

# 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/guides/api-reference/api-reference.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.