# 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](https://docs.kognitos.com/guides/api-reference/api-keys) for setup instructions.

## Quick Start

### Prerequisites

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

### 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"
```

## 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                     |