Overview

Build integrations and automate workflows with the Kognitos REST API.

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

All API paths in this documentation are relative to the base URL above.

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 for setup instructions.

Quick Start

Prerequisites

• A Kognitos account with at least one published automation

• An API Key

1. Verify Your Key

Test your API key by listing your organizations:

Request

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

Response

{
  "user_organizations": [
    {
      "name": "organizations/abc123def456",
      "title": "Acme Corp",
      "owner_display_name": "Jane Smith",
      "owner_email": "[e-mail]",
      "create_time": "2025-01-15T10:30:00Z"
    }
  ]
}

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:

Request

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

Response

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

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

3. Invoke an Automation

Start a run of your automation:

Request

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"
  }'

Response

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

Use AUTOMATION_STAGE_PUBLISHED for production runs. Use AUTOMATION_STAGE_DRAFT to test a draft version.

4. Check Run Status

Monitor your run until it completes:

Request

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}"

Response

{
  "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"
}

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:

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"

The endpoint returns a standard success response on completion.

Archived runs are hidden from the default run list but remain accessible through filtered queries. Archiving does not delete the run or its data.

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:

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

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

# Search users by display name or email
?filter=display_name="Jane" OR email="[e-mail]"

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.

Request

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}"

Response

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

The permissions returned reflect the authenticated user's effective permissions for the specified organization and workspace, based on their assigned roles.

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